使用API閘道CLI和建立、設定和測試使用計劃 REST API - Amazon API 网关
遷移到預設用量計劃建立用量計劃使用管理使用量計劃 AWS CLI測試用量計劃

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

使用API閘道CLI和建立、設定和測試使用計劃 REST API

在設定使用方案之前，您必須已經完成下列動作：設定選取的方法以需API要API金鑰、部署或重新部署API到階段，以及建立或匯入一或多個API金鑰。如需詳細資訊，請參閱 使用API閘道設定API金鑰 REST API。

若要使用API閘道設定用量計劃 RESTAPI，請使用下列指示 (假設您已建立要新增APIs至使用計劃的)。

遷移到預設用量計劃

第一次建立使用量計劃時，您可以呼叫account:update下列主體，將與所選API索引鍵相關聯的現有API階段移轉至使用量計劃：

{
  "patchOperations" : [ {
    "op" : "add",
    "path" : "/features",
    "value" : "UsagePlans"
  } ]
}

如需移轉與API金鑰相關API階段的詳細資訊，請參閱移轉至API閘道主控台中的預設使用方案。

建立用量計劃

下列程序說明如何建立用量計劃。

若要建立使用量計劃 REST API

  1. 呼叫 usageplan:create 來建立用量計劃。在承載中，指定計劃的名稱和說明、相關API階段、速率限制和配額。

    記下產生的用量計劃識別符。下一個步驟需要此值。

  2. 執行以下任意一項：

    1. 呼叫usageplankey:create以將API金鑰新增至使用方案。在承載中指定 keyId 和 keyType。

      若要在使用方案中新增更多API金鑰，請一API次重複上一個電話。

    2. 呼叫apikey:import將一個或多個API金鑰直接新增至指定的使用方案。要求承載應包含索API引鍵值、相關聯的使用計劃識別碼、用來指示已針對使用方案啟用索引鍵的 Boolean 旗標，以及可能的索API引鍵名稱和說明。

      下列apikey:import要求範例會將三個索API引鍵 (由keyname、和所識別description) 新增至一個使用計劃 (如所識別usageplanIds)：

      POST /apikeys?mode=import&format=csv&failonwarnings=fase HTTP/1.1
Host: apigateway.us-east-1.amazonaws.com
Content-Type: text/csv
Authorization: ...

key,name, description, enabled, usageplanIds
abcdef1234ghijklmnop8901234567, importedKey_1, firstone,  tRuE, n371pt 
abcdef1234ghijklmnop0123456789, importedKey_2, secondone, TRUE, n371pt
abcdef1234ghijklmnop9012345678, importedKey_3,          , true, n371pt

      因此，會在 UsagePlanKey 中建立和新增三項 UsagePlan 資源。

      您還可以通過這種方式將API密鑰添加到多個使用計劃中。若要這樣做，請將每個 usageplanIds 欄值變更成包含所選用量計劃識別符的逗號分隔字串，以一對引號 ("n371pt,m282qs" 或 'n371pt,m282qs') 括住。

      注意

      一個API金鑰可以與多個使用方案相關聯。用量計劃可以關聯到多個階段。不過，針對您的每個階段，指定的API金鑰只能與一個使用方案產生關聯API。

使用管理使用量計劃 AWS CLI

以下程式碼範例說明如何透過呼叫 update-usage-plan 命令來在用量計劃中新增、移除或修改方法層級調節設定。

注意

請務必變更us-east-1為適當的 [區域] 值API。

若要為調節個別的資源和方法新增或取代速率限制：

aws apigateway --region us-east-1 update-usage-plan --usage-plan-id <planId> --patch-operations 
                        op="replace",path="/apiStages/<apiId>:<stage>/throttle/<resourcePath>/<httpMethod>/rateLimit",value="0.1"

若要為調節個別的資源和方法新增或取代爆量限制：

aws apigateway --region us-east-1 update-usage-plan --usage-plan-id <planId> --patch-operations op="replace",path="/apiStages/<apiId>:<stage>/throttle/<resourcePath>/<httpMethod>/burstLimit",value="1"

若要為個別的資源和方法移除方法層級調節設定：

aws apigateway --region us-east-1 update-usage-plan --usage-plan-id <planId> --patch-operations op="remove",path="/apiStages/<apiId>:<stage>/throttle/<resourcePath>/<httpMethod>",value=""

若要移除下列項目的所有方法層級節流設定：API

aws apigateway --region us-east-1 update-usage-plan --usage-plan-id <planId> --patch-operations op="remove",path="/apiStages/<apiId>:<stage>/throttle ",value=""

以下是使用寵物店示例的示例API：

aws apigateway --region us-east-1 update-usage-plan --usage-plan-id <planId> --patch-operations 
                op="replace",path="/apiStages/<apiId>:<stage>/throttle",value='"{\"/pets/GET\":{\"rateLimit\":1.0,\"burstLimit\":1},\"//GET\":{\"rateLimit\":1.0,\"burstLimit\":1}}"'

測試用量計劃

作為一個例子，讓我們使 PetStore API用在中創建的教學課程：匯入範例來建立 REST API。假設設定API為使用的API金鑰Hiorr45VR...c4GJc。下列步驟說明如何測試用量計劃。

測試您的用量計劃

  • 使用使用計劃中 (例如/pets) 的?type=...&page=...查詢參數，在 Pets 資源 API (xbvxlpijch) 上GET提出請求：

    GET /testStage/pets?type=dog&page=1 HTTP/1.1
x-api-key: Hiorr45VR...c4GJc
Content-Type: application/x-www-form-urlencoded
Host: xbvxlpijch.execute-api.ap-southeast-1.amazonaws.com
X-Amz-Date: 20160803T001845Z
Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20160803/ap-southeast-1/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-api-key, Signature={sigv4_hash}
    注意

    您必須將此要求提交至 API Gateway 的execute-api元件，並在必要的x-api-key標頭中提供必要的API金鑰 (例如，Hiorr45VR...c4GJc)。

    成功的回應會傳回 200 OK 狀態碼和包含後端請求結果的承載。如果您忘記設定 x-api-key 標頭或以錯誤的金鑰設定它，您會收到 403 Forbidden 回應。不過，如果您未將方法設定為需要API金鑰，則無論您是否正確設定x-api-key標頭，都可能會收到200 OK回應，而且會略過使用方案的節流和配額限制。

    有時候，當 API Gateway 無法針對要求強制執行使用計劃節流限制或配額時發生內部錯誤時，APIGateway 會在不套用使用量計劃中指定的節流限制或配額的情況下提供要求。但是，它會記錄Usage Plan check failed due to an internal error中的錯誤消息 CloudWatch。您可以忽略這類偶發的錯誤。