Ingesting data using the Amazon IoT SiteWise API - Amazon IoT SiteWise
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).

Ingesting data using the Amazon IoT SiteWise API

Use the Amazon IoT SiteWise API to send timestamped industrial data to your assets' attribute and measurement properties. The API accepts a payload that contains timestamp-quality-value (TQV) structures.

Use the BatchPutAssetPropertyValue operation to upload your data. With this operation, you can upload multiple data entries at a time to collect data from several devices and send it all in a single request.

Important

The BatchPutAssetPropertyValue operation is subject to the following quotas:

  • Up to 10 entries per request.

  • Up to 10 property values (TQV data points) per entry.

  • Amazon IoT SiteWise rejects any data with a timestamp dated to more than 7 days in the past or more than 10 minutes in the future.

For more information about these quotas, see BatchPutAssetPropertyValue in the Amazon IoT SiteWise API Reference.

To identify an asset property, specify one of the following:

  • The assetId and propertyId of the asset property that data is sent to.

  • The propertyAlias, which is a data stream alias (for example, /company/windfarm/3/turbine/7/temperature). To use this option, you must first set your asset property's alias. To set property aliases, see Mapping industrial data streams to asset properties.

The following example demonstrates how to send a wind turbine's temperature and rotations per minute (RPM) readings from a payload stored in a JSON file.

aws iotsitewise batch-put-asset-property-value --cli-input-json file://batch-put-payload.json

The example payload in batch-put-payload.json contains the following content.

{
  "entries": [
    {
      "entryId": "unique entry ID",
      "propertyAlias": "/company/windfarm/3/turbine/7/temperature",
      "propertyValues": [
        {
          "value": {
            "integerValue": 38
          },
          "timestamp": {
            "timeInSeconds": 1575691200
          }
        }
      ]
    },
    {
      "entryId": "unique entry ID",
      "propertyAlias": "/company/windfarm/3/turbine/7/rpm",
      "propertyValues": [
        {
          "value": {
            "doubleValue": 15.09
          },
          "timestamp": {
            "timeInSeconds": 1575691200
          },
          "quality": "GOOD"
        }
      ]
    }
  ]
}

Each entry in the payload contains an entryId that you can define as any unique string. If any request entries fail, each error will contain the entryId of the corresponding request so that you know which requests to retry.

Each structure in the list of propertyValues is a timestamp-quality-value (TQV) structure that contains a value, a timestamp, and optionally a quality.

  • value – A structure that contains one of the following fields, depending on the type of the property being set:

    • booleanValue

    • doubleValue

    • integerValue

    • stringValue

  • timestamp – A structure that contains the current Unix epoch time in seconds, timeInSeconds. You can also set the offsetInNanos key in the timestamp structure if you have temporally precise data. Amazon IoT SiteWise rejects any data points with timestamps older than 7 days in the past or newer than 10 minutes in the future.

  • quality – (Optional) One of the following quality strings:

    • GOOD – (Default) The data isn't affected by any issues.

    • BAD – The data is affected by an issue such as sensor failure.

    • UNCERTAIN – The data is affected by an issue such as sensor inaccuracy.

    For more information about how Amazon IoT SiteWise handles data quality in computations, see Data quality in formula expressions.