本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
使用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
-
呼叫
usageplan:create
來建立用量計劃。在承載中,指定計劃的名稱和說明、相關API階段、速率限制和配額。記下產生的用量計劃識別符。下一個步驟需要此值。
-
執行以下任意一項:
-
呼叫
usageplankey:create
以將API金鑰新增至使用方案。在承載中指定keyId
和keyType
。若要在使用方案中新增更多API金鑰,請一API次重複上一個電話。
-
呼叫
apikey:import
將一個或多個API金鑰直接新增至指定的使用方案。要求承載應包含索API引鍵值、相關聯的使用計劃識別碼、用來指示已針對使用方案啟用索引鍵的 Boolean 旗標,以及可能的索API引鍵名稱和說明。下列
apikey:import
要求範例會將三個索API引鍵 (由key
name
、和所識別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。您可以忽略這類偶發的錯誤。