本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 整合 API 型 AI 代理器產品 ## API 型 AI 代理器產品準則 AWS Marketplace 提供所有軟體即服務 (SaaS) API 型 AI 代理器產品的指導方針。這些準則可確保為客戶提供安全且值得信賴的體驗。 **Topics** + [產品審核程序](#product-review-process) + [維持合規](#maintaining-compliance) ### 產品審核程序 當您提交產品時， 會 AWS Marketplace 檢閱產品及其中繼資料，以確認其符合目前的準則。我們會定期更新這些準則，以因應不斷變化的安全需求。 ### 維持合規 AWS Marketplace 會持續監控產品以驗證合規性。如果您的產品不符合目前的準則： + 在您解決問題之前，您的產品可能無法供新訂閱用戶使用 + 您必須更新產品以符合新的需求 | Category | 指導方針 | | --- | --- | | API 和代理程式功能 | 所有 APIs都應正常運作並適當回應。如果您要列出 代理程式，解決方案必須透過在沒有明確外部命令或常式人工輸入的情況下操作來示範自主功能。 | | API 存取和身分驗證 | 客戶應該能夠訂閱您的清單並擷取 API 金鑰，或依照步驟產生 OAuth 權杖。 | | 架構準則 | [如需詳細資訊，請遵循架構準則。](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-guidelines.html#saas-architecture) | | 客戶資訊要求 | [如需詳細資訊，請遵循客戶資訊需求。](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-guidelines.html#saas-customer-information) | | 金鑰管理 | 供應商應讓客戶能夠使金鑰失效/輪換。一旦客戶取消訂閱清單，廠商也應該有使金鑰失效的機制。 | | MCP 伺服器需求 （如適用） | 對於 MCP Server，廠商應該提供遠端 MCP 組態詳細資訊，以及要設定的任何先決條件或環境變數。 | | 產品設定 | [如需詳細資訊，請遵循產品設定準則。](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-guidelines.html#saas-guidelines-setup) | | 產品用量 | [如需詳細資訊，請遵循產品使用準則。](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-guidelines.html#saas-product-usage) | | 使用說明 | 使用說明應清楚說明先決條件、身分驗證設定、支援的端點、請求/回應結構描述、工具描述、錯誤碼和其他資源。 | ## 整合 API 型 AI 代理器產品 ### 根據產品定價進行整合 將您的產品與 整合， AWS Marketplace 是列出 API 型 AI 代理器產品的一個步驟。若要將 API 型 AI 代理器產品與 整合 AWS Marketplace，您必須撰寫程式碼，並示範它可以成功回應數個客戶案例。 如需根據不同定價模型整合產品的相關資訊，請參閱下列主題： + 如需訂閱型產品的相關資訊，請參閱 [將您的 SaaS 訂閱或Pay-As-You-Go產品與 整合 AWS Marketplace](saas-integrate-subscription.md)。 + 如需有關以合約為基礎的產品的資訊，請參閱 [將您的 SaaS 合約產品與 整合 AWS Marketplace](saas-integrate-contract.md)。 + 如需與pay-as-you-go產品簽訂合約的相關資訊，請參閱 [將您的 SaaS 合約型產品與 整合 AWS Marketplace](saas-integrate-contract-with-pay.md)。 ### 客戶加入 #### 重新導向至網站履行 當客戶透過 訂閱您的產品時 AWS Marketplace，他們會存取您 AWS 環境中的產品。訂閱後，我們會引導客戶前往您的產品網站，註冊其帳戶並設定產品。 + 了解如何在 中使用重新導向至網站履行來加入客戶[透過 將客戶加入您的 SaaS 產品 AWS Marketplace](saas-product-customer-setup.md)。 #### QuickLaunch 履行 客戶透過 訂閱您的產品時 AWS Marketplace，會收到 API 金鑰或 OAuth 登入資料，以呼叫您的 API 端點或 MCP 伺服器。程序的運作方式如下： + 客戶訂閱產品。 + 客戶在您的網站上註冊或登入 帳戶。 + 您可以使用 **PutDeploymentParameter** API，將 API 金鑰或 OAuth 登入資料存放在客戶的 AWS Secrets Manager 中。 + 如果您在 API 金鑰的情況下存放一個參數，請呼叫 `secretString` 參數為字串的 `PutDeploymentParameter` API。如果您在 OAuth 登入資料的情況下存放多個參數，請在 `secretString` 參數中提供 JSON 字串，其中包含索引鍵/值對，如下所示： ``` { "Client Id": "{{12345}}", "Client Secret": "{{12345}}", "Discovery URL" : "{{https://auth.example.com/.well-known/openid-configuration}}" } ``` 進一步了解這些資源中的 QuickLaunch 履行： + 了解部署 API 中的 **PutDeploymentParameter** API [AWS Marketplace](https://docs.aws.amazon.com/marketplace/latest/APIReference/API_Operations_AWS_Marketplace_Deployment_Service.html) + 在 中尋找客戶加入指示 [透過 將客戶加入您的 SaaS 產品 AWS Marketplace](saas-product-customer-setup.md) ### 存取 AWS Marketplace APIs 下一節概述了與 AWS Marketplace Metering Service 或 AWS Marketplace Entitlement Service 整合的程序，用於確保您產品的帳單和客戶用量報告的準確性。 + 若要進一步了解存取 AWS Marketplace APIs，請參閱 [存取 AWS Marketplace 計量和權利服務 APIs](saas-integration-metering-and-entitlement-apis.md)。 ### SNS 通知 訂閱 Amazon Simple Notification Service (Amazon SNS) 主題，以接收有關產品的客戶訂閱變更和合約權利的通知。 會在產品建立期間 AWS Marketplace 提供這些主題，協助您管理客戶存取權。 下列 Amazon SNS 主題適用於 SaaS API 型產品： + [Amazon SNS 主題： `aws-mp-entitlement-notification`](saas-notification.md#saas-sns-message-body) – 在客戶建立、升級或續約合約時，或合約過期時通知您。這僅適用於定價模型包含合約的產品。 + [Amazon SNS 主題： `aws-mp-subscription-notification`](saas-notification.md#saas-sns-subscription-message-body) – 當客戶訂閱或取消訂閱您的產品時通知您，並包含`offer-identifier`適用於私有優惠的 和適用於 SaaS 免費試用的免費試用旗標。這適用於所有定價模式，包括合約和訂閱。 ## 使用說明範本 ### MCP 伺服器使用說明範本 下列範例示範 MCP 伺服器的使用說明，包括工具描述、先決條件、身分驗證設定、熱門用戶端的組態、速率限制和其他資源： ``` To get started using the remove MCP server, follow the instructions below: **Availble Tools** This MCP server support the following tools: - Search - Performs a web search - Summarize Website - Summarizes a webpage **Prerequisites** - Install **Node.js** and **npm** **Authentication** Replace `YOUR_API_KEY` with your actual key below. **Claude Desktop** Edit the configuration file at: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json Add the below code: ``` { "mcpServers": { "demo-example": { "command": "npx", "args": [ "mcp-remote", "https://remote.mcp.server/sse", "--header", "Authorization: Bearer " ] }, } } ``` **Cline** Cline stores MCP server configurations in a JSON file that can be modified. In the "Installed" tab, click "Configure MCP Servers" to access the settings file. Add the following: ``` { "mcpServers": { "demoServer": { "url": "https://remote.mcp.server/sse", "disabled": false, "autoApprove": ["searchWeb", "summarizeWebsite"], "timeout": 30 } } } ``` **Rate Limits** - 60 requests per minute per API key. - Exceeding returns HTTP 429 Too Many Requests. - Use retry and exponential backoff to handle limits. **Learn More** MCP Docs: https://mcp.search.demoproduct.com ``` ### AI Agent 和 Agent & Tools 使用說明範本 下列範例示範客服人員或客服人員工具的使用說明，包括先決條件、身分驗證設定、支援的端點、請求/回應結構描述、錯誤碼和其他資源： ``` To get started follow the instructions below: **Authentication** All API requests require this HTTP header: Authorization: Bearer `YOUR_API_KEY` Replace `YOUR_API_KEY` with your actual key. **Search Endpoint** **Endpoint:** `GET /web/search` Performs a web search. **Query Parameters:** | Param | Type | Description | |------------|--------|-------------------------------------| | `q` | string | Your search query (required) | | `count` | int | Number of results (default: 10) | | `offset` | int | Offset for pagination | | `country` | string | Country code (e.g. `us`, `de`) | | `safesearch` | string | `off`, `moderate`, or `strict` | **Example Request:** ```bash curl -X GET "https://api.search.demo.com/res/v1/web/search?q=searchtool" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Response Schema:** ``` { "results": [{ "title": "string", "url": "string", "description": "string" }], "query" :"string", "total" :"number" } ``` **Example Response:** ``` { "results": [ { "title": "DemoProductAPI", "url": "https://demo.com", "description": "Demo Product API is a search tool for..." } ], "query": "searchtool", "total": 1 } ``` **Additional Search Types** DemoProduct also supports: - `GET /news/search – News articles` - `GET /images/search – Image results` - `GET /videos/search – Video results` These endpoints follow the same format as /web/search. **Summarize Endpoint** **Endpoint:** `POST /summarize` Summarizes a webpage **Request Headers:** Content Type: application/json **Request Body:** ``` { "input": "string" // URL or plain text } ``` **Example Request:** ``` { "input": "https://example.com/article" } ``` **Response Schema** ``` { "summary": "string" } ``` **Example Response** ``` { "summary": "This article explains our commitment to user privacy." } ``` **Error Codes** | Status | Meaning | | ------ | ------------------------------ | | `401` | Unauthorized (check your key) | | `429` | Too many requests (rate limit) | | `500` | Server error | All error responses follow this structure: ``` { "error": { "code": 401, "message": "Unauthorized" } } ``` **Rate Limits** - 60 requests per minute per API key. - Exceeding returns HTTP 429 Too Many Requests. - Use retry and exponential backoff to handle limits. **Learn More** API Docs: https://api.search.demoproduct.com ```