AWS IoT Analytics examples using AWS CLI - AWS SDK Code Examples
Actions

There are more AWS SDK examples available in the AWS Doc SDK Examples GitHub repo.

AWS IoT Analytics examples using AWS CLI

The following code examples show you how to perform actions and implement common scenarios by using the AWS Command Line Interface with AWS IoT Analytics.

Actions are code excerpts from larger programs and must be run in context. While actions show you how to call individual service functions, you can see actions in context in their related scenarios.

Each example includes a link to the complete source code, where you can find instructions on how to set up and run the code in context.

Topics

Actions

The following code example shows how to use batch-put-message.

AWS 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 AWS IoT Analytics API Reference.

The following code example shows how to use cancel-pipeline-reprocessing.

AWS CLI

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 AWS IoT Analytics API Reference.

The following code example shows how to use create-channel.

AWS CLI

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 AWS IoT Analytics API Reference.

  • For API details, see CreateChannel in AWS CLI Command Reference.

The following code example shows how to use create-dataset-content.

AWS CLI

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 AWS IoT Analytics API Reference.

The following code example shows how to use create-dataset.

AWS CLI

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 AWS IoT Analytics API Reference.

  • For API details, see CreateDataset in AWS CLI Command Reference.

The following code example shows how to use create-datastore.

AWS CLI

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 AWS IoT Analytics API Reference.

The following code example shows how to use create-pipeline.

AWS CLI

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 AWS IoT Analytics API Reference.

The following code example shows how to use delete-channel.

AWS CLI

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 AWS IoT Analytics API Reference.

  • For API details, see DeleteChannel in AWS CLI Command Reference.

The following code example shows how to use delete-dataset-content.

AWS CLI

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 AWS IoT Analytics API Reference.

The following code example shows how to use delete-dataset.

AWS CLI

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 AWS IoT Analytics API Reference.

  • For API details, see DeleteDataset in AWS CLI Command Reference.

The following code example shows how to use delete-datastore.

AWS CLI

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 AWS IoT Analytics API Reference.

The following code example shows how to use delete-pipeline.

AWS CLI

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 AWS IoT Analytics API Reference.

The following code example shows how to use describe-channel.

AWS CLI

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 AWS IoT Analytics API Reference.

The following code example shows how to use describe-dataset.

AWS CLI

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 AWS IoT Analytics API Reference.

The following code example shows how to use describe-datastore.

AWS CLI

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 AWS IoT Analytics API Reference.

The following code example shows how to use describe-logging-options.

AWS CLI

To retrieve the current logging options

The following describe-logging-options example displays the current AWS 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 AWS IoT Analytics API Reference.

The following code example shows how to use describe-pipeline.

AWS CLI

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 AWS IoT Analytics API Reference.

The following code example shows how to use get-dataset-content.

AWS CLI

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.

The following code example shows how to use list-channels.

AWS CLI

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 AWS IoT Analytics API Reference.

  • For API details, see ListChannels in AWS CLI Command Reference.

The following code example shows how to use list-dataset-contents.

AWS CLI

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 AWS IoT Analytics API Reference.

The following code example shows how to use list-datasets.

AWS CLI

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 AWS IoT Analytics API Reference.

  • For API details, see ListDatasets in AWS CLI Command Reference.

The following code example shows how to use list-datastores.

AWS CLI

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 AWS IoT Analytics API Reference.

The following code example shows how to use list-pipelines.

AWS CLI

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 AWS IoT Analytics API Reference.

  • For API details, see ListPipelines in AWS CLI Command Reference.

The following code example shows how to use list-tags-for-resource.

AWS CLI

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 AWS IoT Analytics API Reference.

The following code example shows how to use put-logging-options.

AWS CLI

To set or update logging options

The following put-logging-options example sets or updates the AWS 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 AWS IoT Analytics API Reference.

The following code example shows how to use run-pipeline-activity.

AWS CLI

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 AWS IoT Analytics API Reference.

The following code example shows how to use sample-channel-data.

AWS CLI

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 AWS IoT Analytics API Reference.

The following code example shows how to use start-pipeline-reprocessing.

AWS CLI

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 AWS IoT Analytics API Reference.

The following code example shows how to use tag-resource.

AWS CLI

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 AWS IoT Analytics API Reference.

  • For API details, see TagResource in AWS CLI Command Reference.

The following code example shows how to use untag-resource.

AWS CLI

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 AWS IoT Analytics API Reference.

  • For API details, see UntagResource in AWS CLI Command Reference.

The following code example shows how to use update-channel.

AWS CLI

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 AWS IoT Analytics API Reference.

  • For API details, see UpdateChannel in AWS CLI Command Reference.

The following code example shows how to use update-dataset.

AWS CLI

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 AWS IoT Analytics API Reference.

  • For API details, see UpdateDataset in AWS CLI Command Reference.

The following code example shows how to use update-datastore.

AWS CLI

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 AWS IoT Analytics API Reference.

The following code example shows how to use update-pipeline.

AWS CLI

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 AWS IoT Analytics API Reference.