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 AWS Serverless Application Model (AWS SAM) template, use the following syntax.
YAML
CreateUsagePlan:
String
Description:String
Quota:QuotaSettings
Tags:List
Throttle:ThrottleSettings
UsagePlanName:String
Properties
-
CreateUsagePlan
-
Determines how this usage plan is configured. Valid values are
PER_API
,SHARED
, andNONE
.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
, and<api-logical-id>
ApiKey
, respectively.<api-logical-id>
UsagePlanKeySHARED
creates AWS::ApiGateway::UsagePlan, AWS::ApiGateway::ApiKey, and AWS::ApiGateway::UsagePlanKey resources that are shared across any API that also hasCreateUsagePlan: SHARED
in the same AWS SAM template. These resources have logical IDs ofServerlessUsagePlan
,ServerlessApiKey
, andServerlessUsagePlanKey
, 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 ifSHARED
orPER_API
is specified in the Globals section of the AWS SAM template.Valid values:
PER_API
,SHARED
, andNONE
Type: String
Required: Yes
AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.
-
Description
-
A description of the usage plan.
Type: String
Required: No
AWS CloudFormation compatibility: This property is passed directly to the
Description
property of anAWS::ApiGateway::UsagePlan
resource. -
Quota
-
Configures the number of requests that users can make within a given interval.
Type: QuotaSettings
Required: No
AWS CloudFormation compatibility: This property is passed directly to the
Quota
property of anAWS::ApiGateway::UsagePlan
resource. -
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
AWS CloudFormation compatibility: This property is passed directly to the
Tags
property of anAWS::ApiGateway::UsagePlan
resource. -
Throttle
-
Configures the overall request rate (average requests per second) and burst capacity.
Type: ThrottleSettings
Required: No
AWS CloudFormation compatibility: This property is passed directly to the
Throttle
property of anAWS::ApiGateway::UsagePlan
resource. -
UsagePlanName
-
A name for the usage plan.
Type: String
Required: No
AWS CloudFormation compatibility: This property is passed directly to the
UsagePlanName
property of anAWS::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