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

# ApiUsagePlan
<a name="sam-property-api-apiusageplan"></a>

設定 API Gateway API 的用量計劃。如需用量計劃的詳細資訊，請參閱《 [API Gateway 開發人員指南》中的使用 API 金鑰建立和使用用量計劃](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html)。 **

## 語法
<a name="sam-property-api-apiusageplan-syntax"></a>

若要在 AWS Serverless Application Model (AWS SAM) 範本中宣告此實體，請使用下列語法。

### YAML
<a name="sam-property-api-apiusageplan-syntax.yaml"></a>

```
  [CreateUsagePlan](#sam-api-apiusageplan-createusageplan): String
  [Description](#sam-api-apiusageplan-description): String
  [Quota](#sam-api-apiusageplan-quota): [QuotaSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-quota)
  [Tags](#sam-api-apiusageplan-tags): List
  [Throttle](#sam-api-apiusageplan-throttle): [ThrottleSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-throttle)
  [UsagePlanName](#sam-api-apiusageplan-usageplanname): String
```

## Properties
<a name="sam-property-api-apiusageplan-properties"></a>

 `CreateUsagePlan`   <a name="sam-api-apiusageplan-createusageplan"></a>
決定此用量計劃的設定方式。有效值為 `PER_API`、`SHARED` 和 `NONE`。  
`PER_API` 會建立此 API 特有的 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html)、 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html)和 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplankey.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplankey.html) 資源。這些資源的邏輯 IDs `<api-logical-id>UsagePlanKey`分別為 `<api-logical-id>UsagePlan`、 `<api-logical-id>ApiKey`和 。  
`SHARED` 會建立 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html)、 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-apikey.html)和 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplankey.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplankey.html) 資源，這些資源在相同 AWS SAM 範本`CreateUsagePlan: SHARED`中也有 的任何 API 之間共用。這些資源的邏輯 IDs `ServerlessUsagePlanKey`分別為 `ServerlessUsagePlan`、 `ServerlessApiKey`和 。如果您使用此選項，建議您僅針對一個 API 資源新增此用量計劃的其他組態，以避免衝突的定義和不確定狀態。  
`NONE` 會停用與此 API 建立或關聯用量計劃。只有在 中指定 `PER_API` `SHARED`或 時，才需要這樣做[AWS SAM 範本的全域區段](sam-specification-template-anatomy-globals.md)。  
*有效值*：`PER_API`、`SHARED` 與 `NONE`  
*類型：*字串  
*必要*：是  
*CloudFormation 相容性*：此屬性對 是唯一的 AWS SAM ，並且沒有 CloudFormation 同等屬性。

 `Description`   <a name="sam-api-apiusageplan-description"></a>
用量計劃的描述。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGateway::UsagePlan` 資源的 `[Description](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-description)` 屬性。

 `Quota`   <a name="sam-api-apiusageplan-quota"></a>
設定使用者可在指定間隔內發出的請求數。  
*類型*：[QuotaSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-quota)  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGateway::UsagePlan` 資源的 `[Quota](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-quota)` 屬性。

 `Tags`   <a name="sam-api-apiusageplan-tags"></a>
要與用量計劃關聯的任意標籤陣列 (金鑰值對)。  
此屬性使用 [CloudFormation 標籤類型](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html)。  
*類型：*清單  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGateway::UsagePlan` 資源的 `[Tags](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-tags)` 屬性。

 `Throttle`   <a name="sam-api-apiusageplan-throttle"></a>
設定整體請求速率 (每秒平均請求數) 和高載容量。  
*類型*：[ThrottleSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-throttle)  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGateway::UsagePlan` 資源的 `[Throttle](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-throttle)` 屬性。

 `UsagePlanName`   <a name="sam-api-apiusageplan-usageplanname"></a>
用量計劃的名稱。  
*類型：*字串  
*必要*：否  
*CloudFormation 相容性*：此屬性會直接傳遞至 `AWS::ApiGateway::UsagePlan` 資源的 `[UsagePlanName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html#cfn-apigateway-usageplan-usageplanname)` 屬性。

## 範例
<a name="sam-property-api-apiusageplan--examples"></a>

### UsagePlan
<a name="sam-property-api-apiusageplan--examples--usageplan"></a>

以下是用量計劃範例。

#### YAML
<a name="sam-property-api-apiusageplan--examples--usageplan--yaml"></a>

```
Auth:
  UsagePlan:
    CreateUsagePlan: PER_API
    Description: Usage plan for this API
    Quota:
      Limit: 500
      Period: MONTH
    Throttle:
      BurstLimit: 100
      RateLimit: 50
    Tags:
      - Key: TagName
        Value: TagValue
```