topic_rules

Creates, updates, deletes, gets or lists a topic_rules resource.

Overview

Name	topic_rules
Type	Resource
Id	aws.iot.topic_rules

Fields

The following fields are returned by SELECT queries:

get_topic_rule

Name	Datatype	Description
rule	object	The rule.
rule_arn	string	The rule ARN.

list_topic_rules

Name	Datatype	Description
created_at	string (date-time)	The date and time the rule was created.
rule_arn	string	The rule ARN.
rule_disabled	boolean	Specifies whether the rule is disabled.
rule_name	string	The name of the rule. (pattern: <code>^[a-zA-Z0-9_]+$</code>)
topic_pattern	string	The pattern for the topic names that apply.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_topic_rule	select	rule_name, region		Gets information about the rule. Requires permission to access the GetTopicRule action.
list_topic_rules	select	region	topic, maxResults, nextToken, ruleDisabled	Lists the rules for the specific topic. Requires permission to access the ListTopicRules action.
create_topic_rule	insert	rule_name, region, topicRulePayload	x-amz-tagging	Creates a rule. Creating rules is an administrator-level action. Any user who has permission to create rules will be able to access data processed by the rule. Requires permission to access the CreateTopicRule action.
replace_topic_rule	replace	rule_name, region, topicRulePayload		Replaces the rule. You must specify all parameters for the new rule. Creating rules is an administrator-level action. Any user who has permission to create rules will be able to access data processed by the rule. Requires permission to access the ReplaceTopicRule action.
delete_topic_rule	delete	rule_name, region		Deletes the rule. Requires permission to access the DeleteTopicRule action.
confirm_topic_rule_destination	exec	confirmation_token, region		Confirms a topic rule destination. When you create a rule requiring a destination, IoT sends a confirmation message to the endpoint or base address you specify. The message includes a token which you pass back when calling ConfirmTopicRuleDestination to confirm that you own or have access to the endpoint. Requires permission to access the ConfirmTopicRuleDestination action.

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
confirmation_token	string	The token used to confirm ownership or access to the topic rule confirmation URL.
region	string	AWS region (default: us-east-1)
rule_name	string	The name of the rule.
maxResults	integer	The maximum number of results to return.
nextToken	string	To retrieve the next set of results, the nextToken value from a previous response; otherwise null to receive the first set of results.
ruleDisabled	boolean	Specifies whether the rule is disabled.
topic	string	The topic.
x-amz-tagging	string	Metadata which can be used to manage the topic rule. For URI Request parameters use format: ...key1=value1&key2=value2... For the CLI command-line parameter use format: --tags "key1=value1&key2=value2..." For the cli-input-json file use format: "tags": "key1=value1&key2=value2..."

SELECT examples

get_topic_rule

Gets information about the rule. Requires permission to access the GetTopicRule action.

SELECT
rule,
rule_arn
FROM aws.iot.topic_rules
WHERE rule_name = '{{ rule_name }}' -- required
AND region = '{{ region }}' -- required
;

list_topic_rules

Lists the rules for the specific topic. Requires permission to access the ListTopicRules action.

SELECT
created_at,
rule_arn,
rule_disabled,
rule_name,
topic_pattern
FROM aws.iot.topic_rules
WHERE region = '{{ region }}' -- required
AND topic = '{{ topic }}'
AND maxResults = '{{ maxResults }}'
AND nextToken = '{{ nextToken }}'
AND ruleDisabled = '{{ ruleDisabled }}'
;

INSERT examples

create_topic_rule

Creates a rule. Creating rules is an administrator-level action. Any user who has permission to create rules will be able to access data processed by the rule. Requires permission to access the CreateTopicRule action.

INSERT INTO aws.iot.topic_rules (
topicRulePayload,
rule_name,
region,
`x-amz-tagging`
)
SELECT 
'{{ topicRulePayload }}' /* required */,
'{{ rule_name }}',
'{{ region }}',
'{{ x-amz-tagging }}'
;

Manifest

# Description fields are for documentation purposes
- name: topic_rules
props:
  - name: rule_name
    value: "{{ rule_name }}"
    description: Required parameter for the topic_rules resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the topic_rules resource.
  - name: topicRulePayload
    description: |
      Describes a rule.
    value:
      sql: "{{ sql }}"
      description: "{{ description }}"
      actions:
        - dynamoDB:
            tableName: "{{ tableName }}"
            roleArn: "{{ roleArn }}"
            operation: "{{ operation }}"
            hashKeyField: "{{ hashKeyField }}"
            hashKeyValue: "{{ hashKeyValue }}"
            hashKeyType: "{{ hashKeyType }}"
            rangeKeyField: "{{ rangeKeyField }}"
            rangeKeyValue: "{{ rangeKeyValue }}"
            rangeKeyType: "{{ rangeKeyType }}"
            payloadField: "{{ payloadField }}"
          dynamoDBv2:
            roleArn: "{{ roleArn }}"
            putItem:
              tableName: "{{ tableName }}"
          lambda:
            functionArn: "{{ functionArn }}"
          sns:
            targetArn: "{{ targetArn }}"
            roleArn: "{{ roleArn }}"
            messageFormat: "{{ messageFormat }}"
          sqs:
            roleArn: "{{ roleArn }}"
            queueUrl: "{{ queueUrl }}"
            useBase64: {{ useBase64 }}
          kinesis:
            roleArn: "{{ roleArn }}"
            streamName: "{{ streamName }}"
            partitionKey: "{{ partitionKey }}"
          republish:
            roleArn: "{{ roleArn }}"
            topic: "{{ topic }}"
            qos: {{ qos }}
            headers:
              payloadFormatIndicator: "{{ payloadFormatIndicator }}"
              contentType: "{{ contentType }}"
              responseTopic: "{{ responseTopic }}"
              correlationData: "{{ correlationData }}"
              messageExpiry: "{{ messageExpiry }}"
              userProperties:
                - key: "{{ key }}"
                  value: "{{ value }}"
          s3:
            roleArn: "{{ roleArn }}"
            bucketName: "{{ bucketName }}"
            key: "{{ key }}"
            cannedAcl: "{{ cannedAcl }}"
          firehose:
            roleArn: "{{ roleArn }}"
            deliveryStreamName: "{{ deliveryStreamName }}"
            separator: "{{ separator }}"
            batchMode: {{ batchMode }}
          cloudwatchMetric:
            roleArn: "{{ roleArn }}"
            metricNamespace: "{{ metricNamespace }}"
            metricName: "{{ metricName }}"
            metricValue: "{{ metricValue }}"
            metricUnit: "{{ metricUnit }}"
            metricTimestamp: "{{ metricTimestamp }}"
          cloudwatchAlarm:
            roleArn: "{{ roleArn }}"
            alarmName: "{{ alarmName }}"
            stateReason: "{{ stateReason }}"
            stateValue: "{{ stateValue }}"
          cloudwatchLogs:
            roleArn: "{{ roleArn }}"
            logGroupName: "{{ logGroupName }}"
            batchMode: {{ batchMode }}
          elasticsearch:
            roleArn: "{{ roleArn }}"
            endpoint: "{{ endpoint }}"
            index: "{{ index }}"
            type_: "{{ type_ }}"
            id: "{{ id }}"
          salesforce:
            token: "{{ token }}"
            url: "{{ url }}"
          iotAnalytics:
            channelArn: "{{ channelArn }}"
            channelName: "{{ channelName }}"
            batchMode: {{ batchMode }}
            roleArn: "{{ roleArn }}"
          iotEvents:
            inputName: "{{ inputName }}"
            messageId: "{{ messageId }}"
            batchMode: {{ batchMode }}
            roleArn: "{{ roleArn }}"
          iotSiteWise:
            putAssetPropertyValueEntries:
              - entryId: "{{ entryId }}"
                assetId: "{{ assetId }}"
                propertyId: "{{ propertyId }}"
                propertyAlias: "{{ propertyAlias }}"
                propertyValues: "{{ propertyValues }}"
            roleArn: "{{ roleArn }}"
          stepFunctions:
            executionNamePrefix: "{{ executionNamePrefix }}"
            stateMachineName: "{{ stateMachineName }}"
            roleArn: "{{ roleArn }}"
          timestream:
            roleArn: "{{ roleArn }}"
            databaseName: "{{ databaseName }}"
            tableName: "{{ tableName }}"
            dimensions:
              - name: "{{ name }}"
                value: "{{ value }}"
            timestamp:
              value: "{{ value }}"
              unit: "{{ unit }}"
          http:
            url: "{{ url }}"
            confirmationUrl: "{{ confirmationUrl }}"
            headers:
              - key: "{{ key }}"
                value: "{{ value }}"
            auth:
              sigv4:
                signingRegion: "{{ signingRegion }}"
                serviceName: "{{ serviceName }}"
                roleArn: "{{ roleArn }}"
            enableBatching: {{ enableBatching }}
            batchConfig:
              maxBatchOpenMs: {{ maxBatchOpenMs }}
              maxBatchSize: {{ maxBatchSize }}
              maxBatchSizeBytes: {{ maxBatchSizeBytes }}
              batchAcrossTopics: {{ batchAcrossTopics }}
          kafka:
            destinationArn: "{{ destinationArn }}"
            topic: "{{ topic }}"
            key: "{{ key }}"
            partition: "{{ partition }}"
            clientProperties: "{{ clientProperties }}"
            headers:
              - key: "{{ key }}"
                value: "{{ value }}"
          openSearch:
            roleArn: "{{ roleArn }}"
            endpoint: "{{ endpoint }}"
            index: "{{ index }}"
            type_: "{{ type_ }}"
            id: "{{ id }}"
          location:
            roleArn: "{{ roleArn }}"
            trackerName: "{{ trackerName }}"
            deviceId: "{{ deviceId }}"
            timestamp:
              value: "{{ value }}"
              unit: "{{ unit }}"
            latitude: "{{ latitude }}"
            longitude: "{{ longitude }}"
      ruleDisabled: {{ ruleDisabled }}
      awsIotSqlVersion: "{{ awsIotSqlVersion }}"
      errorAction:
        dynamoDB:
          tableName: "{{ tableName }}"
          roleArn: "{{ roleArn }}"
          operation: "{{ operation }}"
          hashKeyField: "{{ hashKeyField }}"
          hashKeyValue: "{{ hashKeyValue }}"
          hashKeyType: "{{ hashKeyType }}"
          rangeKeyField: "{{ rangeKeyField }}"
          rangeKeyValue: "{{ rangeKeyValue }}"
          rangeKeyType: "{{ rangeKeyType }}"
          payloadField: "{{ payloadField }}"
        dynamoDBv2:
          roleArn: "{{ roleArn }}"
          putItem:
            tableName: "{{ tableName }}"
        lambda:
          functionArn: "{{ functionArn }}"
        sns:
          targetArn: "{{ targetArn }}"
          roleArn: "{{ roleArn }}"
          messageFormat: "{{ messageFormat }}"
        sqs:
          roleArn: "{{ roleArn }}"
          queueUrl: "{{ queueUrl }}"
          useBase64: {{ useBase64 }}
        kinesis:
          roleArn: "{{ roleArn }}"
          streamName: "{{ streamName }}"
          partitionKey: "{{ partitionKey }}"
        republish:
          roleArn: "{{ roleArn }}"
          topic: "{{ topic }}"
          qos: {{ qos }}
          headers:
            payloadFormatIndicator: "{{ payloadFormatIndicator }}"
            contentType: "{{ contentType }}"
            responseTopic: "{{ responseTopic }}"
            correlationData: "{{ correlationData }}"
            messageExpiry: "{{ messageExpiry }}"
            userProperties:
              - key: "{{ key }}"
                value: "{{ value }}"
        s3:
          roleArn: "{{ roleArn }}"
          bucketName: "{{ bucketName }}"
          key: "{{ key }}"
          cannedAcl: "{{ cannedAcl }}"
        firehose:
          roleArn: "{{ roleArn }}"
          deliveryStreamName: "{{ deliveryStreamName }}"
          separator: "{{ separator }}"
          batchMode: {{ batchMode }}
        cloudwatchMetric:
          roleArn: "{{ roleArn }}"
          metricNamespace: "{{ metricNamespace }}"
          metricName: "{{ metricName }}"
          metricValue: "{{ metricValue }}"
          metricUnit: "{{ metricUnit }}"
          metricTimestamp: "{{ metricTimestamp }}"
        cloudwatchAlarm:
          roleArn: "{{ roleArn }}"
          alarmName: "{{ alarmName }}"
          stateReason: "{{ stateReason }}"
          stateValue: "{{ stateValue }}"
        cloudwatchLogs:
          roleArn: "{{ roleArn }}"
          logGroupName: "{{ logGroupName }}"
          batchMode: {{ batchMode }}
        elasticsearch:
          roleArn: "{{ roleArn }}"
          endpoint: "{{ endpoint }}"
          index: "{{ index }}"
          type_: "{{ type_ }}"
          id: "{{ id }}"
        salesforce:
          token: "{{ token }}"
          url: "{{ url }}"
        iotAnalytics:
          channelArn: "{{ channelArn }}"
          channelName: "{{ channelName }}"
          batchMode: {{ batchMode }}
          roleArn: "{{ roleArn }}"
        iotEvents:
          inputName: "{{ inputName }}"
          messageId: "{{ messageId }}"
          batchMode: {{ batchMode }}
          roleArn: "{{ roleArn }}"
        iotSiteWise:
          putAssetPropertyValueEntries:
            - entryId: "{{ entryId }}"
              assetId: "{{ assetId }}"
              propertyId: "{{ propertyId }}"
              propertyAlias: "{{ propertyAlias }}"
              propertyValues: "{{ propertyValues }}"
          roleArn: "{{ roleArn }}"
        stepFunctions:
          executionNamePrefix: "{{ executionNamePrefix }}"
          stateMachineName: "{{ stateMachineName }}"
          roleArn: "{{ roleArn }}"
        timestream:
          roleArn: "{{ roleArn }}"
          databaseName: "{{ databaseName }}"
          tableName: "{{ tableName }}"
          dimensions:
            - name: "{{ name }}"
              value: "{{ value }}"
          timestamp:
            value: "{{ value }}"
            unit: "{{ unit }}"
        http:
          url: "{{ url }}"
          confirmationUrl: "{{ confirmationUrl }}"
          headers:
            - key: "{{ key }}"
              value: "{{ value }}"
          auth:
            sigv4:
              signingRegion: "{{ signingRegion }}"
              serviceName: "{{ serviceName }}"
              roleArn: "{{ roleArn }}"
          enableBatching: {{ enableBatching }}
          batchConfig:
            maxBatchOpenMs: {{ maxBatchOpenMs }}
            maxBatchSize: {{ maxBatchSize }}
            maxBatchSizeBytes: {{ maxBatchSizeBytes }}
            batchAcrossTopics: {{ batchAcrossTopics }}
        kafka:
          destinationArn: "{{ destinationArn }}"
          topic: "{{ topic }}"
          key: "{{ key }}"
          partition: "{{ partition }}"
          clientProperties: "{{ clientProperties }}"
          headers:
            - key: "{{ key }}"
              value: "{{ value }}"
        openSearch:
          roleArn: "{{ roleArn }}"
          endpoint: "{{ endpoint }}"
          index: "{{ index }}"
          type_: "{{ type_ }}"
          id: "{{ id }}"
        location:
          roleArn: "{{ roleArn }}"
          trackerName: "{{ trackerName }}"
          deviceId: "{{ deviceId }}"
          timestamp:
            value: "{{ value }}"
            unit: "{{ unit }}"
          latitude: "{{ latitude }}"
          longitude: "{{ longitude }}"
  - name: x-amz-tagging
    value: "{{ x-amz-tagging }}"
    description: Metadata which can be used to manage the topic rule. For URI Request parameters use format: ...key1=value1&key2=value2... For the CLI command-line parameter use format: --tags "key1=value1&key2=value2..." For the cli-input-json file use format: "tags": "key1=value1&key2=value2..."
    description: Metadata which can be used to manage the topic rule. For URI Request parameters use format: ...key1=value1&key2=value2... For the CLI command-line parameter use format: --tags "key1=value1&key2=value2..." For the cli-input-json file use format: "tags": "key1=value1&key2=value2..."

REPLACE examples

replace_topic_rule

Replaces the rule. You must specify all parameters for the new rule. Creating rules is an administrator-level action. Any user who has permission to create rules will be able to access data processed by the rule. Requires permission to access the ReplaceTopicRule action.

REPLACE aws.iot.topic_rules
SET 
topicRulePayload = '{{ topicRulePayload }}'
WHERE 
rule_name = '{{ rule_name }}' --required
AND region = '{{ region }}' --required
AND topicRulePayload = '{{ topicRulePayload }}' --required;

DELETE examples

delete_topic_rule

Deletes the rule. Requires permission to access the DeleteTopicRule action.

DELETE FROM aws.iot.topic_rules
WHERE rule_name = '{{ rule_name }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

confirm_topic_rule_destination

Confirms a topic rule destination. When you create a rule requiring a destination, IoT sends a confirmation message to the endpoint or base address you specify. The message includes a token which you pass back when calling ConfirmTopicRuleDestination to confirm that you own or have access to the endpoint. Requires permission to access the ConfirmTopicRuleDestination action.

EXEC aws.iot.topic_rules.confirm_topic_rule_destination 
@confirmation_token='{{ confirmation_token }}' --required, 
@region='{{ region }}' --required
;