ApiUsagePlan - Amazon Serverless Application Model
SyntaxPropertiesExamples
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

ApiUsagePlan

Configures a usage plan for an API Gateway API. For more information about usage plans, see Create and Use Usage Plans with API Keys in the API Gateway Developer Guide.

Syntax

To declare this entity in your Amazon Serverless Application Model (Amazon SAM) template, use the following syntax.

Properties

CreateUsagePlan

Determines how this usage plan is configured. Valid values are PER_API, SHARED, and NONE.

PER_API creates AWS::ApiGateway::UsagePlan, AWS::ApiGateway::ApiKey, and AWS::ApiGateway::UsagePlanKey resources that are specific to this API. These resources have logical IDs of <api-logical-id>UsagePlan, <api-logical-id>ApiKey, and <api-logical-id>UsagePlanKey, respectively.

SHARED creates AWS::ApiGateway::UsagePlan, AWS::ApiGateway::ApiKey, and AWS::ApiGateway::UsagePlanKey resources that are shared across any API that also has CreateUsagePlan: SHARED in the same Amazon SAM template. These resources have logical IDs of ServerlessUsagePlan, ServerlessApiKey, and ServerlessUsagePlanKey, respectively. If you use this option, we recommend that you add additional configuration for this usage plan on only one API resource to avoid conflicting definitions and an uncertain state.

NONE disables the creation or association of a usage plan with this API. This is only necessary if SHARED or PER_API is specified in the Globals section of the Amazon SAM template.

Valid values: PER_API, SHARED, and NONE

Type: String

Required: Yes

Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn't have an Amazon CloudFormation equivalent.

Description

A description of the usage plan.

Type: String

Required: No

Amazon CloudFormation compatibility: This property is passed directly to the Description property of an AWS::ApiGateway::UsagePlan resource.

Quota

Configures the number of requests that users can make within a given interval.

Type: QuotaSettings

Required: No

Amazon CloudFormation compatibility: This property is passed directly to the Quota property of an AWS::ApiGateway::UsagePlan resource.

Tags

An array of arbitrary tags (key-value pairs) to associate with the usage plan.

This property uses the CloudFormation Tag Type.

Type: List

Required: No

Amazon CloudFormation compatibility: This property is passed directly to the Tags property of an AWS::ApiGateway::UsagePlan resource.

Throttle

Configures the overall request rate (average requests per second) and burst capacity.

Type: ThrottleSettings

Required: No

Amazon CloudFormation compatibility: This property is passed directly to the Throttle property of an AWS::ApiGateway::UsagePlan resource.

UsagePlanName

A name for the usage plan.

Type: String

Required: No

Amazon CloudFormation compatibility: This property is passed directly to the UsagePlanName property of an AWS::ApiGateway::UsagePlan resource.

Examples

UsagePlan

The following is a usage plan example.

YAML

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