Working with HTTP topic rule destinations - Amazon IoT Core
HTTP topic rule destination overviewCreating HTTP topic rule destinationsConfirming HTTP topic rule destinationsSending a new confirmation requestDisabling and deleting a topic rule destination
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Working with HTTP topic rule destinations

An HTTP topic rule destination is a web service to which the rules engine can route data from a topic rule. An Amazon IoT Core resource describes the web service for Amazon IoT. Topic rule destination resources can be shared by different rules.

Before Amazon IoT Core can send data to another web service, it must confirm that it can access the service's endpoint.

HTTP topic rule destination overview

An HTTP topic rule destination refers to a web service that supports a confirmation URL and one or more data collection URLs. The HTTP topic rule destination resource contains the confirmation URL of your web service. When you configure an HTTP topic rule action, you specify the actual URL of the endpoint that should receive the data along with the web service's confirmation URL. After your destination is confirmed, the topic rule sends the result of the SQL statement to the HTTPS endpoint (and not to the confirmation URL).

An HTTP topic rule destination can be in one of the following states:

ENABLED

The destination has been confirmed and can be used by a rule action. A destination must be in the ENABLED state for it to be used in a rule. You can only enable a destination that's in DISABLED status.

DISABLED

The destination has been confirmed but it can't be used by a rule action. This is useful if you want to temporarily prevent traffic to your endpoint without having to go through the confirmation process again. You can only disable a destination that's in ENABLED status.

IN_PROGRESS

Confirmation of the destination is in progress.

ERROR

Destination confirmation timed out.

After an HTTP topic rule destination has been confirmed and enabled, it can be used with any rule in your account.

The following sections describe common actions on HTTP topic rule destinations.

Creating HTTP topic rule destinations

You create an HTTP topic rule destination by calling the CreateTopicRuleDestination operation or by using the Amazon IoT console.

After you create a destination, Amazon IoT sends a confirmation request to the confirmation URL. The confirmation request has the following format:

HTTP POST {confirmationUrl}/?confirmationToken={confirmationToken}
Headers:
x-amz-rules-engine-message-type: DestinationConfirmation
x-amz-rules-engine-destination-arn:"arn:aws:iot:us-east-1:123456789012:ruledestination/http/7a280e37-b9c6-47a2-a751-0703693f46e4"
Content-Type: application/json
Body:
{
    "arn":"arn:aws:iot:us-east-1:123456789012:ruledestination/http/7a280e37-b9c6-47a2-a751-0703693f46e4",  
    "confirmationToken": "AYADeMXLrPrNY2wqJAKsFNn-…NBJndA",
    "enableUrl": "https://iot.us-east-1.amazonaws.com/confirmdestination/AYADeMXLrPrNY2wqJAKsFNn-…NBJndA",
    "messageType": "DestinationConfirmation"
}

The content of the confirmation request includes the following information:

arn

The Amazon Resource Name (ARN) for the topic rule destination to confirm.

confirmationToken

The confirmation token sent by Amazon IoT Core. The token in the example is truncated. Your token will be longer. You'll need this token to confirm your destination with Amazon IoT Core.

enableUrl

The URL to which you browse to confirm a topic rule destination.

messageType

The type of message.

Confirming HTTP topic rule destinations

To complete the endpoint confirmation process, if you're using the Amazon CLI, you must perform the following steps after your confirmation URL receives the confirmation request.

  1. Confirm that the destination is willing to receive messages

    To confirm that the topic rule destination is willing to receive IoT messages, either call the enableUrl in the confirmation request, or perform the ConfirmTopicRuleDestination API operation and pass the confirmationToken from the confirmation request.

  2. Set topic rule status to enabled

    After you've confirmed that the destination can receive messages, you must perform the UpdateTopicRuleDestination API operation to set the status of the topic rule to ENABLED.

If you're using the Amazon IoT console, copy the confirmationToken and paste it into the destination's confirmation dialog in the Amazon IoT console. You can then enable the topic rule.

Sending a new confirmation request

To activate a new confirmation message for a destination, call UpdateTopicRuleDestination and set the topic rule destination's status to IN_PROGRESS.

Repeat the confirmation process after you send a new confirmation request.

Disabling and deleting a topic rule destination

To disable a destination, call UpdateTopicRuleDestination and set the topic rule destination's status to DISABLED. A topic rule in the DISABLED state can be enabled again without the need to send a new confirmation request.

To delete a topic rule destination, call DeleteTopicRuleDestination.