APIGateway / Client / create_stage

create_stage#

APIGateway.Client.create_stage(**kwargs)#

Creates a new Stage resource that references a pre-existing Deployment for the API.

Request Syntax

response = client.create_stage(
    restApiId='string',
    stageName='string',
    deploymentId='string',
    description='string',
    cacheClusterEnabled=True|False,
    cacheClusterSize='0.5'|'1.6'|'6.1'|'13.5'|'28.4'|'58.2'|'118'|'237',
    variables={
        'string': 'string'
    },
    documentationVersion='string',
    canarySettings={
        'percentTraffic': 123.0,
        'deploymentId': 'string',
        'stageVariableOverrides': {
            'string': 'string'
        },
        'useStageCache': True|False
    },
    tracingEnabled=True|False,
    tags={
        'string': 'string'
    }
)

Parameters:

restApiId (string) –
[REQUIRED]

The string identifier of the associated RestApi.
stageName (string) –
[REQUIRED]

The name for the Stage resource. Stage names can only contain alphanumeric characters, hyphens, and underscores. Maximum length is 128 characters.
deploymentId (string) –
[REQUIRED]

The identifier of the Deployment resource for the Stage resource.
description (string) – The description of the Stage resource.
cacheClusterEnabled (boolean) – Whether cache clustering is enabled for the stage.
cacheClusterSize (string) – The stage’s cache capacity in GB. For more information about choosing a cache size, see Enabling API caching to enhance responsiveness.
variables (dict) –
A map that defines the stage variables for the new Stage resource. Variable names can have alphanumeric and underscore characters, and the values must match [A-Za-z0-9-._~:/?#&=,]+.
- (string) –
  - (string) –
documentationVersion (string) – The version of the associated API documentation.
canarySettings (dict) –
The canary deployment settings of this stage.
- percentTraffic (float) –
  
  The percent (0-100) of traffic diverted to a canary deployment.
- deploymentId (string) –
  
  The ID of the canary deployment.
- stageVariableOverrides (dict) –
  
  Stage variables overridden for a canary release deployment, including new stage variables introduced in the canary. These stage variables are represented as a string-to-string map between stage variable names and their values.
  - (string) –
    - (string) –
- useStageCache (boolean) –
  
  A Boolean flag to indicate whether the canary deployment uses the stage cache or not.
tracingEnabled (boolean) – Specifies whether active tracing with X-ray is enabled for the Stage.
tags (dict) –
The key-value map of strings. The valid character set is [a-zA-Z+-=._:/]. The tag key can be up to 128 characters and must not start with aws:. The tag value can be up to 256 characters.
- (string) –
  - (string) –

Return type:

dict

Returns:

Response Syntax

{
    'deploymentId': 'string',
    'clientCertificateId': 'string',
    'stageName': 'string',
    'description': 'string',
    'cacheClusterEnabled': True|False,
    'cacheClusterSize': '0.5'|'1.6'|'6.1'|'13.5'|'28.4'|'58.2'|'118'|'237',
    'cacheClusterStatus': 'CREATE_IN_PROGRESS'|'AVAILABLE'|'DELETE_IN_PROGRESS'|'NOT_AVAILABLE'|'FLUSH_IN_PROGRESS',
    'methodSettings': {
        'string': {
            'metricsEnabled': True|False,
            'loggingLevel': 'string',
            'dataTraceEnabled': True|False,
            'throttlingBurstLimit': 123,
            'throttlingRateLimit': 123.0,
            'cachingEnabled': True|False,
            'cacheTtlInSeconds': 123,
            'cacheDataEncrypted': True|False,
            'requireAuthorizationForCacheControl': True|False,
            'unauthorizedCacheControlHeaderStrategy': 'FAIL_WITH_403'|'SUCCEED_WITH_RESPONSE_HEADER'|'SUCCEED_WITHOUT_RESPONSE_HEADER'
        }
    },
    'variables': {
        'string': 'string'
    },
    'documentationVersion': 'string',
    'accessLogSettings': {
        'format': 'string',
        'destinationArn': 'string'
    },
    'canarySettings': {
        'percentTraffic': 123.0,
        'deploymentId': 'string',
        'stageVariableOverrides': {
            'string': 'string'
        },
        'useStageCache': True|False
    },
    'tracingEnabled': True|False,
    'webAclArn': 'string',
    'tags': {
        'string': 'string'
    },
    'createdDate': datetime(2015, 1, 1),
    'lastUpdatedDate': datetime(2015, 1, 1)
}

Response Structure

(dict) –

Represents a unique identifier for a version of a deployed RestApi that is callable by users.
- deploymentId (string) –
  
  The identifier of the Deployment that the stage points to.
- clientCertificateId (string) –
  
  The identifier of a client certificate for an API stage.
- stageName (string) –
  
  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.
- description (string) –
  
  The stage’s description.
- cacheClusterEnabled (boolean) –
  
  Specifies whether a cache cluster is enabled for the stage.
- cacheClusterSize (string) –
  
  The stage’s cache capacity in GB. For more information about choosing a cache size, see Enabling API caching to enhance responsiveness.
- cacheClusterStatus (string) –
  
  The status of the cache cluster for the stage, if enabled.
- methodSettings (dict) –
  
  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.
  - (string) –
    - (dict) –
      
      Specifies the method setting properties.
      - metricsEnabled (boolean) –
        
        Specifies whether Amazon CloudWatch metrics are enabled for this method.
      - loggingLevel (string) –
        
        Specifies the logging level for this method, which affects the log entries pushed to Amazon CloudWatch Logs. Valid values are OFF, ERROR, and INFO. Choose ERROR to write only error-level entries to CloudWatch Logs, or choose INFO to include all ERROR events as well as extra informational events.
      - dataTraceEnabled (boolean) –
        
        Specifies whether data trace logging is enabled for this method, which affects the log entries pushed to Amazon CloudWatch Logs.
      - throttlingBurstLimit (integer) –
        
        Specifies the throttling burst limit.
      - throttlingRateLimit (float) –
        
        Specifies the throttling rate limit.
      - cachingEnabled (boolean) –
        
        Specifies whether responses should be cached and returned for requests. A cache cluster must be enabled on the stage for responses to be cached.
      - cacheTtlInSeconds (integer) –
        
        Specifies the time to live (TTL), in seconds, for cached responses. The higher the TTL, the longer the response will be cached.
      - cacheDataEncrypted (boolean) –
        
        Specifies whether the cached responses are encrypted.
      - requireAuthorizationForCacheControl (boolean) –
        
        Specifies whether authorization is required for a cache invalidation request.
      - unauthorizedCacheControlHeaderStrategy (string) –
        
        Specifies how to handle unauthorized requests for cache invalidation.
- variables (dict) –
  
  A map that defines the stage variables for a Stage resource. Variable names can have alphanumeric and underscore characters, and the values must match [A-Za-z0-9-._~:/?#&=,]+.
  - (string) –
    - (string) –
- documentationVersion (string) –
  
  The version of the associated API documentation.
- accessLogSettings (dict) –
  
  Settings for logging access in this stage.
  - format (string) –
    
    A single line format of the access logs of data, as specified by selected $context variables. The format must include at least $context.requestId.
  - destinationArn (string) –
    
    The Amazon Resource Name (ARN) of the CloudWatch Logs log group or Kinesis Data Firehose delivery stream to receive access logs. If you specify a Kinesis Data Firehose delivery stream, the stream name must begin with amazon-apigateway-.
- canarySettings (dict) –
  
  Settings for the canary deployment in this stage.
  - percentTraffic (float) –
    
    The percent (0-100) of traffic diverted to a canary deployment.
  - deploymentId (string) –
    
    The ID of the canary deployment.
  - stageVariableOverrides (dict) –
    
    Stage variables overridden for a canary release deployment, including new stage variables introduced in the canary. These stage variables are represented as a string-to-string map between stage variable names and their values.
    - (string) –
      - (string) –
  - useStageCache (boolean) –
    
    A Boolean flag to indicate whether the canary deployment uses the stage cache or not.
- tracingEnabled (boolean) –
  
  Specifies whether active tracing with X-ray is enabled for the Stage.
- webAclArn (string) –
  
  The ARN of the WebAcl associated with the Stage.
- tags (dict) –
  
  The collection of tags. Each tag element is associated with a given resource.
  - (string) –
    - (string) –
- createdDate (datetime) –
  
  The timestamp when the stage was created.
- lastUpdatedDate (datetime) –
  
  The timestamp when the stage last updated.

create_stage#

Request Syntax

Response Syntax

Response Structure

Exceptions