Amazon IoT Analytics examples using Amazon CLI

To send a message to a channel

The following batch-put-message example sends a message to the specified channel.

aws iotanalytics batch-put-message \
    --cli-binary-format raw-in-base64-out \
    --cli-input-json file://batch-put-message.json

Contents of batch-put-message.json:

{
    "channelName": "mychannel",
    "messages": [
        {
            "messageId": "0001",
            "payload": "eyAidGVtcGVyYXR1cmUiOiAyMCB9"
        }
    ]
}

Output:

{
    "batchPutMessageErrorEntries": []
}

For more information, see BatchPutMessage in the Amazon IoT Analytics API Reference.

To cancel the reprocessing of data through a pipeline

The following cancel-pipeline-reprocessing example cancels the reprocessing of data through the specified pipeline.

aws iotanalytics cancel-pipeline-reprocessing \
    --pipeline-name mypipeline \
    --reprocessing-id "6ad2764f-fb13-4de3-b101-4e74af03b043"

This command produces no output.

For more information, see CancelPipelineReprocessing in the Amazon IoT Analytics API Reference.

To create a channel

The following create-channel example creates a channel with the specified configuration. A channel collects data from an MQTT topic and archives the raw, unprocessed messages before publishing the data to a pipeline.

aws iotanalytics create-channel \
    --cli-input-json file://create-channel.json

Contents of create-channel.json:

{
    "channelName": "mychannel",
    "retentionPeriod": {
        "unlimited": true
    },
    "tags": [
        {
            "key": "Environment",
            "value": "Production"
        }
    ]
}

Output:

{
    "channelArn": "arn:aws:iotanalytics:us-west-2:123456789012:channel/mychannel",
    "channelName": "mychannel",
    "retentionPeriod": {
        "unlimited": true
    }
}

For more information, see CreateChannel in the Amazon IoT Analytics API Reference.

To create the content of a dataset

The following create-dataset-content example creates the content of the specified dataset by applying a queryAction (an SQL query) or a containerAction (executing a containerized application).

aws iotanalytics create-dataset-content \
    --dataset-name mydataset

Output:

{
    "versionId": "d494b416-9850-4670-b885-ca22f1e89d62"
}

For more information, see CreateDatasetContent in the Amazon IoT Analytics API Reference.

To create a dataset

The following create-dataset example creates a dataset. A dataset stores data retrieved from a data store by applying a queryAction (a SQL query) or a containerAction (executing a containerized application). This operation creates the skeleton of a dataset. You can populate the dataset manually by calling CreateDatasetContent or automatically according to a trigger you specify.

aws iotanalytics create-dataset \
    --cli-input-json file://create-dataset.json

Contents of create-dataset.json:

{
    "datasetName": "mydataset",
    "actions": [
        {
            "actionName": "myDatasetAction",
            "queryAction": {
                "sqlQuery": "SELECT * FROM mydatastore"
            }
        }
    ],
    "retentionPeriod": {
        "unlimited": true
    },
    "tags": [
        {
            "key": "Environment",
            "value": "Production"
        }
    ]
}

Output:

{
    "datasetName": "mydataset",
    "retentionPeriod": {
        "unlimited": true
    },
    "datasetArn": "arn:aws:iotanalytics:us-west-2:123456789012:dataset/mydataset"
}

For more information, see CreateDataset in the Amazon IoT Analytics API Reference.

To create a data store

The following create-datastore example creates a data store, which is a repository for messages.

aws iotanalytics create-datastore \
    --cli-input-json file://create-datastore.json

Contents of create-datastore.json:

{
    "datastoreName": "mydatastore",
    "retentionPeriod": {
        "numberOfDays": 90
    },
    "tags": [
        {
            "key": "Environment",
            "value": "Production"
        }
    ]
}

Output:

{
    "datastoreName": "mydatastore",
    "datastoreArn": "arn:aws:iotanalytics:us-west-2:123456789012:datastore/mydatastore",
    "retentionPeriod": {
        "numberOfDays": 90,
        "unlimited": false
    }
}

For more information, see CreateDatastore in the Amazon IoT Analytics API Reference.

Create an IoT Analytics Pipeline

The following create-pipeline example creates a pipeline. A pipeline consumes messages from a channel and allows you to process the messages before storing them in a data store. You must specify both a channel and a data store activity and, optionally, as many as 23 additional activities in the pipelineActivities array.

aws iotanalytics create-pipeline \
    --cli-input-json file://create-pipeline.json

Contents of create-pipeline.json:

{
    "pipelineName": "mypipeline",
    "pipelineActivities": [
        {
            "channel": {
                "name": "myChannelActivity",
                "channelName": "mychannel",
                "next": "myMathActivity"
            }
        },
        {
            "datastore": {
                "name": "myDatastoreActivity",
                "datastoreName": "mydatastore"
            }
        },
        {
            "math": {
                "name": "myMathActivity",
                "math": "((temp - 32) * 5.0) / 9.0",
                "attribute": "tempC",
                "next": "myDatastoreActivity"
            }
        }
    ],
    "tags": [
        {
            "key": "Environment",
            "value": "Beta"
        }
    ]
}

Output:

{
    "pipelineArn": "arn:aws:iotanalytics:us-west-2:123456789012:pipeline/mypipeline",
    "pipelineName": "mypipeline"
}

For more information, see CreatePipeline in the Amazon IoT Analytics API Reference.

Delete an IoT Analytics Channel

The following delete-channel example deletes the specified channel.

aws iotanalytics delete-channel \
    --channel-name mychannel

This command produces no output.

For more information, see DeleteChannel in the Amazon IoT Analytics API Reference.

To delete dataset content

The following delete-dataset-content example deletes the content of the specified dataset.

aws iotanalytics delete-dataset-content \
    --dataset-name mydataset

This command produces no output.

For more information, see DeleteDatasetContent in the Amazon IoT Analytics API Reference.

To delete a dataset

The following delete-dataset example deletes the specified dataset. You don't have to delete the content of the dataset before you perform this operation.

aws iotanalytics delete-dataset \
    --dataset-name mydataset

This command produces no output.

For more information, see DeleteDataset in the Amazon IoT Analytics API Reference.

To delete a data store

The following delete-datastore example deletes the specified data store.

aws iotanalytics delete-datastore \
    --datastore-name mydatastore

This command produces no output.

For more information, see DeleteDatastore in the Amazon IoT Analytics API Reference.

To delete a pipeline

The following delete-pipeline example deletes the specified pipeline.

aws iotanalytics delete-pipeline \
    --pipeline-name mypipeline

This command produces no output.

For more information, see DeletePipeline in the Amazon IoT Analytics API Reference.

To retrieve information about a channel

The following describe-channel example displays details, including statistics, for the specified channel.

aws iotanalytics describe-channel \
    --channel-name mychannel \
    --include-statistics

Output:

{
    "statistics": {
        "size": {
            "estimatedSizeInBytes": 402.0,
            "estimatedOn": 1561504380.0
        }
    },
    "channel": {
        "status": "ACTIVE",
        "name": "mychannel",
        "lastUpdateTime": 1557860351.001,
        "creationTime": 1557860351.001,
        "retentionPeriod": {
            "unlimited": true
        },
        "arn": "arn:aws:iotanalytics:us-west-2:123456789012:channel/mychannel"
    }
}

For more information, see DescribeChannel in the Amazon IoT Analytics API Reference.

To retrieve information about a dataset

The following describe-dataset example displays details for the specified dataset.

aws iotanalytics describe-dataset \
    --dataset-name mydataset

Output:

{
    "dataset": {
        "status": "ACTIVE",
        "contentDeliveryRules": [],
        "name": "mydataset",
        "lastUpdateTime": 1557859240.658,
        "triggers": [],
        "creationTime": 1557859240.658,
        "actions": [
            {
                "actionName": "query_32",
                "queryAction": {
                    "sqlQuery": "SELECT * FROM mydatastore",
                    "filters": []
                }
            }
        ],
        "retentionPeriod": {
            "numberOfDays": 90,
            "unlimited": false
        },
        "arn": "arn:aws:iotanalytics:us-west-2:123456789012:dataset/mydataset"
    }
}

For more information, see DescribeDataset in the Amazon IoT Analytics API Reference.

To retrieve information about a data store

The following describe-datastore example displays details, including statistics, for the specified data store.

aws iotanalytics describe-datastore \
    --datastore-name mydatastore \
    --include-statistics

Output:

{
    "datastore": {
        "status": "ACTIVE",
        "name": "mydatastore",
        "lastUpdateTime": 1557858971.02,
        "creationTime": 1557858971.02,
        "retentionPeriod": {
            "unlimited": true
        },
        "arn": "arn:aws:iotanalytics:us-west-2:123456789012:datastore/mydatastore"
    },
    "statistics": {
        "size": {
            "estimatedSizeInBytes": 397.0,
            "estimatedOn": 1561592040.0
        }
    }
}

For more information, see DescribeDatastore in the Amazon IoT Analytics API Reference.

To retrieve the current logging options

The following describe-logging-options example displays the current Amazon IoT Analytics logging options.

aws iotanalytics describe-logging-options

This command produces no output. Output:

{
    "loggingOptions": {
        "roleArn": "arn:aws:iam::123456789012:role/service-role/myIoTAnalyticsRole",
        "enabled": true,
        "level": "ERROR"
    }
}

For more information, see DescribeLoggingOptions in the Amazon IoT Analytics API Reference.

To retrieve information about a pipeline

The following describe-pipeline example displays details for the specified pipeline.

aws iotanalytics describe-pipeline \
    --pipeline-name mypipeline

Output:

{
    "pipeline": {
        "activities": [
            {
                "channel": {
                    "channelName": "mychannel",
                    "name": "mychannel_28",
                    "next": "mydatastore_29"
                }
            },
            {
                "datastore": {
                    "datastoreName": "mydatastore",
                    "name": "mydatastore_29"
                }
            }
        ],
        "name": "mypipeline",
        "lastUpdateTime": 1561676362.515,
        "creationTime": 1557859124.432,
        "reprocessingSummaries": [
            {
                "status": "SUCCEEDED",
                "creationTime": 1561676362.189,
                "id": "6ad2764f-fb13-4de3-b101-4e74af03b043"
            }
        ],
        "arn": "arn:aws:iotanalytics:us-west-2:123456789012:pipeline/mypipeline"
    }
}

For more information, see DescribePipeline in the Amazon IoT Analytics API Reference.

To retrieve the contents of a dataset

The following get-dataset-content example retrieves the contents of a dataset as presigned URIs.

aws iotanalytics get-dataset-content --dataset-name mydataset

Output:

{
    "status": {
        "state": "SUCCEEDED"
    },
    "timestamp": 1557863215.995,
    "entries": [
        {
            "dataURI": "https://aws-radiant-dataset-12345678-1234-1234-1234-123456789012.s3.us-west-2.amazonaws.com/results/12345678-e8b3-46ba-b2dd-efe8d86cf385.csv?X-Amz-Security-Token=...-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20190628T173437Z&X-Amz-SignedHeaders=host&X-Amz-Expires=7200&X-Amz-Credential=...F20190628%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Signature=..."
        }
    ]
}

For more information, see GetDatasetContent in the guide.

To retrieve a list of channels

The following list-channels example displays summary information for the available channels.

aws iotanalytics list-channels

Output:

{
    "channelSummaries": [
        {
            "status": "ACTIVE",
            "channelName": "mychannel",
            "creationTime": 1557860351.001,
            "lastUpdateTime": 1557860351.001
        }
    ]
}

For more information, see ListChannels in the Amazon IoT Analytics API Reference.

To list information about dataset contents

The following list-dataset-contents example lists information about dataset contents that have been created.

aws iotanalytics list-dataset-contents \
    --dataset-name mydataset

Output:

{
    "datasetContentSummaries": [
        {
            "status": {
                "state": "SUCCEEDED"
            },
            "scheduleTime": 1557863215.995,
            "version": "b10ea2a9-66c1-4d99-8d1f-518113b738d0",
            "creationTime": 1557863215.995
        }
    ]
}

For more information, see ListDatasetContents in the Amazon IoT Analytics API Reference.

To retrieve information about datasets

The following list-datasets example lists summary information about available datasets.

aws iotanalytics list-datasets

Output:

{
    "datasetSummaries": [
        {
            "status": "ACTIVE",
            "datasetName": "mydataset",
            "lastUpdateTime": 1557859240.658,
            "triggers": [],
            "creationTime": 1557859240.658,
            "actions": [
                {
                    "actionName": "query_32",
                    "actionType": "QUERY"
                }
            ]
        }
    ]
}

For more information, see ListDatasets in the Amazon IoT Analytics API Reference.

To retrieve a list of data stores

The following list-datastores example displays summary information about the available data stores.

aws iotanalytics list-datastores

Output:

{
    "datastoreSummaries": [
        {
            "status": "ACTIVE",
            "datastoreName": "mydatastore",
            "creationTime": 1557858971.02,
            "lastUpdateTime": 1557858971.02
        }
    ]
}

For more information, see ListDatastores in the Amazon IoT Analytics API Reference.

To retrieve a list of pipelines

The following list-pipelines example displays a list of available pipelines.

aws iotanalytics list-pipelines

Output:

{
    "pipelineSummaries": [
        {
            "pipelineName": "mypipeline",
            "creationTime": 1557859124.432,
            "lastUpdateTime": 1557859124.432,
            "reprocessingSummaries": []
        }
    ]
}

For more information, see ListPipelines in the Amazon IoT Analytics API Reference.

To list tags for a resource

The following list-tags-for-resource example Lists the tags that you have attached to the specified resource.

aws iotanalytics list-tags-for-resource \
    --resource-arn "arn:aws:iotanalytics:us-west-2:123456789012:channel/mychannel"

Output:

{
    "tags": [
        {
            "value": "bar",
            "key": "foo"
        }
    ]
}

For more information, see ListTagsForResource in the Amazon IoT Analytics API Reference.

To set or update logging options

The following put-logging-options example sets or updates the Amazon IoT Analytics logging options. If you update the value of any loggingOptions field, it can take up to one minute for the change to take effect. Also, if you change the policy attached to the role you specified in the "roleArn" field (for example, to correct an invalid policy) it can take up to five minutes for that change to take effect.

aws iotanalytics put-logging-options \
    --cli-input-json file://put-logging-options.json

Contents of put-logging-options.json:

{
    "loggingOptions": {
        "roleArn": "arn:aws:iam::123456789012:role/service-role/myIoTAnalyticsRole",
        "level": "ERROR",
        "enabled": true
    }
}

This command produces no output.

For more information, see PutLoggingOptions in the Amazon IoT Analytics API Reference.

To simulate a pipeline activity

The following run-pipeline-activity example simulates the results of running a pipeline activity on a message payload.

aws iotanalytics run-pipeline-activity \
    --pipeline-activity file://maths.json \
    --payloads file://payloads.json

Contents of maths.json:

{
    "math": {
        "name": "MyMathActivity",
        "math": "((temp - 32) * 5.0) / 9.0",
        "attribute": "tempC"
    }
}

Contents of payloads.json:

[
    "{\"humidity\": 52, \"temp\": 68 }",
    "{\"humidity\": 52, \"temp\": 32 }"
]

Output:

{
    "logResult": "",
    "payloads": [
        "eyJodW1pZGl0eSI6NTIsInRlbXAiOjY4LCJ0ZW1wQyI6MjB9",
        "eyJodW1pZGl0eSI6NTIsInRlbXAiOjMyLCJ0ZW1wQyI6MH0="
    ]
}

For more information, see RunPipelineActivity in the Amazon IoT Analytics API Reference.

To retrieve sample messages from a channel

The following sample-channel-data example retrieves a sample of messages from the specified channel ingested during the specified timeframe. You can retrieve up to 10 messages.

aws iotanalytics sample-channel-data \
    --channel-name mychannel

Output:

{
    "payloads": [
        "eyAidGVtcGVyYXR1cmUiOiAyMCB9",
        "eyAiZm9vIjogImJhciIgfQ=="
    ]
}

For more information, see SampleChannelData in the Amazon IoT Analytics API Reference.

To start pipeline reprocessing

The following start-pipeline-reprocessing example starts the reprocessing of raw message data through the specified pipeline.

aws iotanalytics start-pipeline-reprocessing \
    --pipeline-name mypipeline

Output:

{
    "reprocessingId": "6ad2764f-fb13-4de3-b101-4e74af03b043"
}

For more information, see StartPipelineReprocessing in the Amazon IoT Analytics API Reference.

To add or modify tags for a resource

The following tag-resource example adds to or modifies the tags attached to the specified resource.

aws iotanalytics tag-resource \
    --resource-arn "arn:aws:iotanalytics:us-west-2:123456789012:channel/mychannel" \
    --tags "[{\"key\": \"Environment\", \"value\": \"Production\"}]"

This command produces no output.

For more information, see TagResource in the Amazon IoT Analytics API Reference.

To remove tags from a resource

The following untag-resource example removes the tags with the specified key names from the specified resource.

aws iotanalytics untag-resource \
    --resource-arn "arn:aws:iotanalytics:us-west-2:123456789012:channel/mychannel" \
    --tag-keys "[\"Environment\"]"

This command produces no output.

For more information, see UntagResource <https://docs.aws.amazon.com/iotanalytics/latest/APIReference/API_UntagResource.html > in the Amazon IoT Analytics API Reference.

To modify a channel

The following update-channel example modifies the settings for the specified channel.

aws iotanalytics update-channel \
    --cli-input-json file://update-channel.json

Contents of update-channel.json:

{
    "channelName": "mychannel",
    "retentionPeriod": {
        "numberOfDays": 92
    }
}

This command produces no output.

For more information, see UpdateChannel in the Amazon IoT Analytics API Reference.

To update a dataset

The following update-dataset example modifies the settings of the specified dataset.

aws iotanalytics update-dataset \
    --cli-input-json file://update-dataset.json

Contents of update-dataset.json:

{
    "datasetName": "mydataset",
    "actions": [
        {
            "actionName": "myDatasetUpdateAction",
            "queryAction": {
                "sqlQuery": "SELECT * FROM mydatastore"
            }
        }
    ],
    "retentionPeriod": {
        "numberOfDays": 92
    }
}

This command produces no output.

For more information, see UpdateDataset <https://docs.aws.amazon.com/iotanalytics/latest/APIReference/API_UpdateDataset.html > in the Amazon IoT Analytics API Reference.

To update a data store

The following update-datastore example modifies the settings of the specified data store.

aws iotanalytics update-datastore \
    --cli-input-json file://update-datastore.json

Contents of update-datastore.json:

{
    "datastoreName": "mydatastore",
    "retentionPeriod": {
        "numberOfDays": 93
    }
}

This command produces no output.

For more information, see UpdateDatastore in the Amazon IoT Analytics API Reference.

To update a pipeline

The following update-pipeline example modifies the settings of the specified pipeline. You must specify both a channel and a data store activity and, optionally, as many as 23 additional activities, in the pipelineActivities array.

aws iotanalytics update-pipeline \
    --cli-input-json file://update-pipeline.json

Contents of update-pipeline.json:

{
    "pipelineName": "mypipeline",
    "pipelineActivities": [
        {
            "channel": {
                "name": "myChannelActivity",
                "channelName": "mychannel",
                "next": "myMathActivity"
            }
        },
        {
            "datastore": {
                "name": "myDatastoreActivity",
                "datastoreName": "mydatastore"
            }
        },
        {
            "math": {
                "name": "myMathActivity",
                "math": "(((temp - 32) * 5.0) / 9.0) + 273.15",
                "attribute": "tempK",
                "next": "myDatastoreActivity"
            }
        }
    ]
}

This command produces no output.

For more information, see UpdatePipeline in the Amazon IoT Analytics API Reference.