usage_plans

Creates, updates, deletes or gets an usage_plan resource or lists usage_plans in a region

Overview

Name	usage_plans
Type	Resource
Description	The ``AWS::ApiGateway::UsagePlan`` resource creates a usage plan for deployed APIs. A usage plan sets a target for the throttling and quota limits on individual client API keys. For more information, see [Creating and Using API Usage Plans in Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-usage-plans.html) in the *API Gateway Developer Guide*. In some cases clients can exceed the targets that you set. Don’t rely on usage plans to control costs. Consider using [](https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) to monitor costs and [](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) to manage API requests.
Id	awscc.apigateway.usage_plans

Fields

get (all properties)

Name	Datatype	Description
id	string
▶api_stages	array
description	string
▶quota	object	&#96;&#96;QuotaSettings&#96;&#96; is a property of the &#91;AWS::ApiGateway::UsagePlan&#93;(https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html) resource that specifies a target for the maximum number of requests users can make to your REST APIs.<br />In some cases clients can exceed the targets that you set. Don’t rely on usage plans to control costs. Consider using &#91;&#93;(https://docs.aws.amazon.com/cost-management/latest/userguide/budgets-managing-costs.html) to monitor costs and &#91;&#93;(https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) to manage API requests.
▶tags	array
▶throttle	object	&#96;&#96;ThrottleSettings&#96;&#96; is a property of the &#91;AWS::ApiGateway::UsagePlan&#93;(https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-usageplan.html) resource that specifies the overall request rate (average requests per second) and burst capacity when users call your REST APIs.
usage_plan_name	string
region	string	AWS region.

list (identifiers only)

Name	Datatype	Description
id	string
region	string	AWS region.

For more information, see AWS::ApiGateway::UsagePlan.

Methods

Name	Resource	Accessible by	Required Params
create_resource	usage_plans	INSERT	region
delete_resource	usage_plans	DELETE	Identifier, region
update_resource	usage_plans	UPDATE	Identifier, PatchDocument, region
list_resources	usage_plans_list_only	SELECT	region
get_resource	usage_plans	SELECT	Identifier, region

SELECT examples

get (all properties)

Gets all properties from an individual usage_plan.

SELECT
  region,
  id,
  api_stages,
  description,
  quota,
  tags,
  throttle,
  usage_plan_name
FROM awscc.apigateway.usage_plans
WHERE
  region = 'us-east-1' AND
  Identifier = '{{ id }}';

list (identifiers only)

Lists all usage_plans in a region.

SELECT
  region,
  id
FROM awscc.apigateway.usage_plans_list_only
WHERE
  region = 'us-east-1';

INSERT example

Use the following StackQL query and manifest file to create a new usage_plan resource, using stack-deploy.

Required Properties

/*+ create */
INSERT INTO awscc.apigateway.usage_plans (
  ApiStages,
  Description,
  Quota,
  Tags,
  Throttle,
  UsagePlanName,
  region
)
SELECT
  '{{ api_stages }}',
  '{{ description }}',
  '{{ quota }}',
  '{{ tags }}',
  '{{ throttle }}',
  '{{ usage_plan_name }}',
  '{{ region }}';

All Properties

/*+ create */
INSERT INTO awscc.apigateway.usage_plans (
  ApiStages,
  Description,
  Quota,
  Tags,
  Throttle,
  UsagePlanName,
  region
)
SELECT
  '{{ api_stages }}',
  '{{ description }}',
  '{{ quota }}',
  '{{ tags }}',
  '{{ throttle }}',
  '{{ usage_plan_name }}',
  '{{ region }}';

Manifest

version: 1
name: stack name
description: stack description
providers:
  - aws
globals:
  - name: region
    value: '{{ vars.AWS_REGION }}'
resources:
  - name: usage_plan
    props:
      - name: api_stages
        value:
          - api_id: '{{ api_id }}'
            stage: '{{ stage }}'
            throttle: {}
      - name: description
        value: '{{ description }}'
      - name: quota
        value:
          limit: '{{ limit }}'
          offset: '{{ offset }}'
          period: '{{ period }}'
      - name: tags
        value:
          - value: '{{ value }}'
            key: '{{ key }}'
      - name: throttle
        value:
          burst_limit: '{{ burst_limit }}'
          rate_limit: null
      - name: usage_plan_name
        value: '{{ usage_plan_name }}'

UPDATE example

Use the following StackQL query and manifest file to update a usage_plan resource, using stack-deploy.

/*+ update */
UPDATE awscc.apigateway.usage_plans
SET PatchDocument = string('{{ {
    "ApiStages": api_stages,
    "Description": description,
    "Quota": quota,
    "Tags": tags,
    "Throttle": throttle,
    "UsagePlanName": usage_plan_name
} | generate_patch_document }}')
WHERE
  region = '{{ region }}' AND
  Identifier = '{{ id }}';

DELETE example

/*+ delete */
DELETE FROM awscc.apigateway.usage_plans
WHERE
  Identifier = '{{ id }}' AND
  region = 'us-east-1';

Permissions

To operate on the usage_plans resource, the following permissions are required:

Create

apigateway:POST,
apigateway:GET,
apigateway:PUT

Read

apigateway:GET

Update

apigateway:GET,
apigateway:DELETE,
apigateway:PATCH,
apigateway:PUT

Delete

apigateway:DELETE,
apigateway:GET,
apigateway:PATCH

List

apigateway:GET