api_destinations

Creates, updates, deletes, gets or lists an api_destinations resource.

Overview

Name	api_destinations
Type	Resource
Id	aws.events.api_destinations

Fields

The following fields are returned by SELECT queries:

describe_api_destination

Name	Datatype	Description
api_destination_arn	string	The ARN of the API destination retrieved. (pattern: <code>^arn:aws([a-z]|-):events:([a-z]|\d|-):([0-9]{12})?:api-destination/[.-_A-Za-z0-9]+/[-A-Za-z0-9]+$</code>)
api_destination_state	string	The state of the API destination retrieved. (ACTIVE, INACTIVE)
connection_arn	string	The ARN of the connection specified for the API destination retrieved. (pattern: <code>^arn:aws([a-z]|-):events:([a-z]|\d|-):([0-9]{12})?:connection/[.-_A-Za-z0-9]+/[-A-Za-z0-9]+$</code>)
creation_time	string (date-time)	A time stamp for the time that the API destination was created.
description	string	The description for the API destination retrieved. (pattern: <code>.*</code>)
http_method	string	The method to use to connect to the HTTP endpoint. (POST, GET, HEAD, OPTIONS, PUT, PATCH, DELETE)
invocation_endpoint	string	The URL to use to connect to the HTTP endpoint. (pattern: <code>^((%[0-9A-Fa-f]{2}|[-()_.!~*';/?:@\x26=+$,A-Za-z0-9])+)([).!';/?:,])?$</code>)
invocation_rate_limit_per_second	integer	The maximum number of invocations per second to specified for the API destination. Note that if you set the invocation rate maximum to a value lower the rate necessary to send all events received on to the destination HTTP endpoint, some events may not be delivered within the 24-hour retry window. If you plan to set the rate lower than the rate necessary to deliver all events, consider using a dead-letter queue to catch events that are not delivered within 24 hours.
last_modified_time	string (date-time)	A time stamp for the time that the API destination was last modified.
name	string	The name of the API destination retrieved. (pattern: <code>[.-_A-Za-z0-9]+</code>)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_api_destination	select	region		Retrieves details about an API destination.
create_api_destination	insert	region, ConnectionArn, InvocationEndpoint, HttpMethod		Creates an API destination, which is an HTTP invocation endpoint configured as a target for events. API destinations do not support private destinations, such as interface VPC endpoints. For more information, see API destinations in the EventBridge User Guide.
update_api_destination	update	region		Updates an API destination.
delete_api_destination	delete	region		Deletes the specified API destination.
list_api_destinations	exec	region		Retrieves a list of API destination in the account in the current Region.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

describe_api_destination

Retrieves details about an API destination.

SELECT
api_destination_arn,
api_destination_state,
connection_arn,
creation_time,
description,
http_method,
invocation_endpoint,
invocation_rate_limit_per_second,
last_modified_time,
name
FROM aws.events.api_destinations
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_api_destination

Creates an API destination, which is an HTTP invocation endpoint configured as a target for events. API destinations do not support private destinations, such as interface VPC endpoints. For more information, see API destinations in the EventBridge User Guide.

INSERT INTO aws.events.api_destinations (
Name,
Description,
ConnectionArn,
InvocationEndpoint,
HttpMethod,
InvocationRateLimitPerSecond,
region
)
SELECT 
'{{ Name }}',
'{{ Description }}',
'{{ ConnectionArn }}' /* required */,
'{{ InvocationEndpoint }}' /* required */,
'{{ HttpMethod }}' /* required */,
{{ InvocationRateLimitPerSecond }},
'{{ region }}'
RETURNING
api_destination_arn,
api_destination_state,
creation_time,
last_modified_time
;

Manifest

# Description fields are for documentation purposes
- name: api_destinations
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the api_destinations resource.
  - name: Name
    value: "{{ Name }}"
    description: |
      The name for the API destination to create.
  - name: Description
    value: "{{ Description }}"
    description: |
      A description for the API destination to create.
  - name: ConnectionArn
    value: "{{ ConnectionArn }}"
    description: |
      The ARN of the connection to use for the API destination. The destination endpoint must support the authorization type specified for the connection.
  - name: InvocationEndpoint
    value: "{{ InvocationEndpoint }}"
    description: |
      The URL to the HTTP invocation endpoint for the API destination.
  - name: HttpMethod
    value: "{{ HttpMethod }}"
    description: |
      The method to use for the request to the HTTP invocation endpoint.
    valid_values: ['POST', 'GET', 'HEAD', 'OPTIONS', 'PUT', 'PATCH', 'DELETE']
  - name: InvocationRateLimitPerSecond
    value: {{ InvocationRateLimitPerSecond }}
    description: |
      The maximum number of requests per second to send to the HTTP invocation endpoint.

UPDATE examples

update_api_destination

Updates an API destination.

UPDATE aws.events.api_destinations
SET 
Name = '{{ Name }}',
Description = '{{ Description }}',
ConnectionArn = '{{ ConnectionArn }}',
InvocationEndpoint = '{{ InvocationEndpoint }}',
HttpMethod = '{{ HttpMethod }}',
InvocationRateLimitPerSecond = {{ InvocationRateLimitPerSecond }}
WHERE 
region = '{{ region }}' --required
RETURNING
api_destination_arn,
api_destination_state,
creation_time,
last_modified_time;

DELETE examples

delete_api_destination

Deletes the specified API destination.

DELETE FROM aws.events.api_destinations
WHERE region = '{{ region }}' --required
;

Lifecycle Methods

list_api_destinations

Retrieves a list of API destination in the account in the current Region.

EXEC aws.events.api_destinations.list_api_destinations 
@region='{{ region }}' --required 
@@json=
'{
"NamePrefix": "{{ NamePrefix }}", 
"ConnectionArn": "{{ ConnectionArn }}", 
"NextToken": "{{ NextToken }}", 
"Limit": {{ Limit }}
}'
;