AWS::ApiGateway::Stage
The AWS::ApiGateway::Stage
resource creates a stage for a deployment.
Syntax
To declare this entity in your AWS CloudFormation template, use the following syntax:
JSON
{ "Type" : "AWS::ApiGateway::Stage", "Properties" : { "AccessLogSetting" :
AccessLogSetting
, "CacheClusterEnabled" :Boolean
, "CacheClusterSize" :String
, "CanarySetting" :CanarySetting
, "ClientCertificateId" :String
, "DeploymentId" :String
, "Description" :String
, "DocumentationVersion" :String
, "MethodSettings" :[ MethodSetting, ... ]
, "RestApiId" :String
, "StageName" :String
, "Tags" :[ Tag, ... ]
, "TracingEnabled" :Boolean
, "Variables" :{
} }Key
:Value
, ...}
YAML
Type: AWS::ApiGateway::Stage Properties: AccessLogSetting:
AccessLogSetting
CacheClusterEnabled:Boolean
CacheClusterSize:String
CanarySetting:CanarySetting
ClientCertificateId:String
DeploymentId:String
Description:String
DocumentationVersion:String
MethodSettings:- MethodSetting
RestApiId:String
StageName:String
Tags:- Tag
TracingEnabled:Boolean
Variables:
Key
:Value
Properties
AccessLogSetting
-
Access log settings, including the access log format and access log destination ARN.
Required: No
Type: AccessLogSetting
Update requires: No interruption
CacheClusterEnabled
-
Specifies whether a cache cluster is enabled for the stage. To activate a method-level cache, set
CachingEnabled
totrue
for a method.Required: No
Type: Boolean
Update requires: No interruption
CacheClusterSize
-
The stage's cache capacity in GB. For more information about choosing a cache size, see Enabling API caching to enhance responsiveness.
Required: No
Type: String
Allowed values:
0.5 | 1.6 | 6.1 | 13.5 | 28.4 | 58.2 | 118 | 237
Update requires: No interruption
CanarySetting
-
Settings for the canary deployment in this stage.
Required: No
Type: CanarySetting
Update requires: No interruption
ClientCertificateId
-
The identifier of a client certificate for an API stage.
Required: No
Type: String
Update requires: No interruption
DeploymentId
-
The identifier of the Deployment that the stage points to.
Required: No
Type: String
Update requires: No interruption
Description
-
The stage's description.
Required: No
Type: String
Update requires: No interruption
DocumentationVersion
-
The version of the associated API documentation.
Required: No
Type: String
Update requires: No interruption
MethodSettings
-
A map that defines the method settings for a Stage resource. Keys (designated as
/{method_setting_key
below) are method paths defined as{resource_path}/{http_method}
for an individual method override, or/\*/\*
for overriding all methods in the stage.Required: No
Type: Array of MethodSetting
Update requires: No interruption
RestApiId
-
The string identifier of the associated RestApi.
Required: Yes
Type: String
Update requires: Replacement
StageName
-
The name of the stage is the first path segment in the Uniform Resource Identifier (URI) of a call to API Gateway. Stage names can only contain alphanumeric characters, hyphens, and underscores. Maximum length is 128 characters.
Required: No
Type: String
Update requires: Replacement
-
The collection of tags. Each tag element is associated with a given resource.
Required: No
Type: Array of Tag
Update requires: No interruption
TracingEnabled
-
Specifies whether active tracing with X-ray is enabled for the Stage.
Required: No
Type: Boolean
Update requires: No interruption
Variables
-
A map (string-to-string map) that defines the stage variables, where the variable name is the key and the variable value is the value. Variable names are limited to alphanumeric characters. Values must match the following regular expression:
[A-Za-z0-9-._~:/?#&=,]+
.Required: No
Type: Object of String
Pattern:
[a-zA-Z0-9]+
Update requires: No interruption
Return values
Ref
When you pass the logical ID of this resource to the intrinsic Ref
function, Ref
returns the name of the stage, such as MyTestStage
.
For more information about using the Ref
function, see Ref
.
Examples
Create stage
The following example creates a stage for the TestDeployment
deployment. The stage also specifies method settings for the MyRestApi
API.
JSON
{ "Resources": { "Prod": { "Type": "AWS::ApiGateway::Stage", "Properties": { "StageName": "Prod", "Description": "Prod Stage", "RestApiId": { "Ref": "MyRestApi" }, "DeploymentId": { "Ref": "TestDeployment" }, "DocumentationVersion": { "Ref": "MyDocumentationVersion" }, "ClientCertificateId": { "Ref": "ClientCertificate" }, "Variables": { "Stack": "Prod" }, "MethodSettings": [ { "ResourcePath": "/", "HttpMethod": "GET", "MetricsEnabled": "true", "DataTraceEnabled": "false" }, { "ResourcePath": "/stack", "HttpMethod": "POST", "MetricsEnabled": "true", "DataTraceEnabled": "false", "ThrottlingBurstLimit": "999" }, { "ResourcePath": "/stack", "HttpMethod": "GET", "MetricsEnabled": "true", "DataTraceEnabled": "false", "ThrottlingBurstLimit": "555" } ] } } } }
YAML
Resources: Prod: Type: AWS::ApiGateway::Stage Properties: StageName: Prod Description: Prod Stage RestApiId: !Ref MyRestApi DeploymentId: !Ref TestDeployment DocumentationVersion: !Ref MyDocumentationVersion ClientCertificateId: !Ref ClientCertificate Variables: Stack: Prod MethodSettings: - ResourcePath: / HttpMethod: GET MetricsEnabled: 'true' DataTraceEnabled: 'false' - ResourcePath: /stack HttpMethod: POST MetricsEnabled: 'true' DataTraceEnabled: 'false' ThrottlingBurstLimit: '999' - ResourcePath: /stack HttpMethod: GET MetricsEnabled: 'true' DataTraceEnabled: 'false' ThrottlingBurstLimit: '555'
See also
-
stage:create in the Amazon API Gateway REST API Reference