透過 AWS Marketplace 銷售您的 API Gateway API - Amazon API Gateway
初始化 AWS Marketplace 與 API Gateway 的整合處理客戶的用量計劃訂閱

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

透過 AWS Marketplace 銷售您的 API Gateway API

建置、測試及部署 API 之後，您可以將 API 封裝在 API Gateway 用量計畫中，並將此計畫當做軟體即服務 (SaaS) 產品透過 AWS Marketplace 銷售。AWS Marketplace 會根據對用量計劃提出的請求數目，向訂閱您產品供應項目的 API 買方收取費用。

若要在 AWS Marketplace 上銷售您的 API，您必須設定銷售管道來整合 AWS Marketplace 與 API Gateway。一般來說，這包括在 AWS Marketplace 上列出您的產品、使用適當的政策設定 IAM 角色來允許 API Gateway 傳送用量指標至 AWS Marketplace、將 AWS Marketplace 產品與 API Gateway 用量計畫相關聯，以及將 AWS Marketplace 買方與 API Gateway API 金鑰相關聯。下列各節將會詳細討論。

如需在 AWS Marketplace 上將 API 當做 SaaS 產品銷售的詳細資訊，請參閱 AWS Marketplace SaaS 訂閱 - 使用者指南。

初始化 AWS Marketplace 與 API Gateway 的整合

下列任務適用於 AWS Marketplace 與 API Gateway 整合的一次性初始化，讓您可以將 API 當做 SaaS 產品銷售。

在 AWS Marketplace 上列出產品

若要將您的用量計劃列為 SaaS 產品，請透過 AWS Marketplace 提交產品載入表單。產品必須包含 requests 類型的維度 apigateway。此維度會定義每個請求的價格，且 API Gateway 會使用它來測量傳送至您 API 的請求。

建立計量角色

您可以使用下列執行政策與信任政策來建立名為 ApiGatewayMarketplaceMeteringRole 的 IAM 角色。此角色可讓 API Gateway 代替您傳送用量指標至 AWS Marketplace。

計量角色的執行政策

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "aws-marketplace:BatchMeterUsage",
        "aws-marketplace:ResolveCustomer"
      ],
      "Resource": "*",
      "Effect": "Allow"
    }
  ]
}

計量角色的信任關係政策

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "apigateway.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

將用量計劃與 AWS Marketplace 產品相關聯

當您在 AWS Marketplace 上列出產品時，您會收到 AWS Marketplace 產品代碼。若要整合 API Gateway 與 AWS Marketplace，請將您的用量計畫與 AWS Marketplace 產品代碼相關聯。使用 API Gateway 主控台、API Gateway REST API、適用於 API Gateway 的 AWS CLI 或適用於 API Gateway 的 AWS 開發套件，將 API Gateway UsagePlan 的 productCode 欄位設定為您的 AWS Marketplace 產品代碼，即可建立關聯。下列程式碼範例會使用 API Gateway REST API：

PATCH /usageplans/USAGE_PLAN_ID
Host: apigateway.region.amazonaws.com
Authorization: ...

{
    "patchOperations" : [{
        "path" : "/productCode",
        "value" : "MARKETPLACE_PRODUCT_CODE",
        "op" : "replace"
    }]
}

處理客戶的用量計劃訂閱

下列作業是由開發人員入口網站應用程式所處理。

當客戶透過 AWS Marketplace 訂閱您的產品，AWS Marketplace 會轉送 POST 請求至 SaaS 訂閱 URL (也就是在 AWS Marketplace 上列出您的產品時所註冊的 URL)。POST 請求會隨附於 x-amzn-marketplace-token 參數，其中包含買方資訊。請遵循 SaaS 客戶上線中的指示，在開發人員入口網站應用程式中處理此重新導向。

AWS Marketplace 回應客戶的訂閱請求，並傳送 subscribe-success 通知到您可以訂閱的 Amazon SNS 主題。(請參閱 SaaS 客戶上線)。若要接受客戶訂閱請求，您可以透過建立或擷取客戶的 API Gateway API 金鑰、將客戶之 AWS Marketplace 佈建的 customerId 與 API 金鑰相關聯，然後將 API 金鑰新增至您的用量計畫，來處理 subscribe-success 通知。

當客戶的訂閱請求完成時，開發人員入口網站應用程式應該將相關聯的 API 金鑰提供給客戶，並通知客戶必須在 API 請求的 x-api-key 標頭中包含此 API 金鑰。

當客戶取消訂閱用量計劃時，AWS Marketplace 會傳送 unsubscribe-success 通知至 SNS 主題。若要完成將客戶取消訂閱的程序，您可以從用量計劃中移除客戶的 API 金鑰，來處理 unsubscribe-success 通知。

授權客戶存取用量計劃

若要授權指定客戶存取您的用量計劃，請使用 API Gateway API 為客戶擷取或建立 API 金鑰，然後將 API 金鑰新增至用量計劃。

下列範例示範如何呼叫 API Gateway REST API，以使用特定 AWS Marketplace customerId 值 (MARKETPLACE_CUSTOMER_ID) 來建立新的 API 金鑰。

POST apikeys HTTP/1.1
Host: apigateway.region.amazonaws.com
Authorization: ...

{
  "name" : "my_api_key",
  "description" : "My API key",
  "enabled" : "false",
  "stageKeys" : [ {
    "restApiId" : "uycll6xg9a",
    "stageName" : "prod"
  } ],
  "customerId" : "MARKETPLACE_CUSTOMER_ID"
}

下列範例示範如何使用特定 AWS Marketplace customerId 值 (MARKETPLACE_CUSTOMER_ID) 來取得 API 金鑰。

GET apikeys?customerId=MARKETPLACE_CUSTOMER_ID HTTP/1.1
Host: apigateway.region.amazonaws.com
Authorization: ...

若要將 API 金鑰新增至用量計劃，請使用相關用量計劃的 API 金鑰來建立 UsagePlanKey。下列範例示範如何使用 API Gateway REST API 來完成此作業，其中 n371pt 是用量計劃 ID，而 q5ugs7qjjh 是前述範例所傳回的範例 API keyId。

POST /usageplans/n371pt/keys HTTP/1.1
Host: apigateway.region.amazonaws.com
Authorization: ...

{
    "keyId": "q5ugs7qjjh",
    "keyType": "API_KEY"
}

將客戶與 API 金鑰相關聯

您必須將ApiKey的 customerId 欄位更新為客戶的 AWS Marketplace 客戶 ID。這會將 API 金鑰與 AWS Marketplace 客戶相關聯，以啟用買方的計量與計費。下列程式碼範例會呼叫 API Gateway REST API 來執行這項操作。

PATCH /apikeys/q5ugs7qjjh
Host: apigateway.region.amazonaws.com
Authorization: ...
        
{
    "patchOperations" : [{
        "path" : "/customerId",
        "value" : "MARKETPLACE_CUSTOMER_ID",
        "op" : "replace"
    }]
}