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).

Preparing fleet indexing

With Amazon IoT fleet indexing, you can search and aggregate data by using the reserved named shadow ($package). You can also group Amazon IoT things by querying the Reserved named shadow and dynamic thing groups. For example, you can find information about which Amazon IoT things use a specific package version, don't have a specific package version installed, or don’t have any package version installed. You can gain further insight by combining attributes. For example, identifying things that have a specific version and are of a specific thing type (such as version 1.0.0 and thing type of pump_sensor). For more information, see Fleet indexing.

Setting the $package shadow as a data source

To use fleet indexing with Software Package Catalog, you must enable fleet indexing, set the named shadow as the data source, and define $package as the named shadow filter. If you haven’t enabled fleet indexing, you can enable it within this process. From Amazon IoT Core in the console, open Settings, choose Manage indexing, then Add named shadows, Add device software packages and versions, and Update. For more information, see Manage thing indexing.

Alternately, you can enable fleet indexing when you create your first package. When the Enable dependencies for package management dialog box appears, choose the option to add device software packages and versions as data sources to fleet indexing. By selecting this option, you also enable fleet indexing.

Metrics displayed in the console

On the Amazon IoT console software package details page, the Discovery panel displays standard metrics ingested through the $package shadow.

For another method to gain insight into collecting package version distribution, see Collecting package version distribution through getBucketsAggregation.

Query patterns

Fleet indexing with Software Package Catalog uses most of the supported features (for example, terms and phrases and search fields) that are standard for fleet indexing. The exception is that the comparison and range queries aren't available for the reserved named shadow ($package) version key. However, these queries are available for the attributes key. For more information, see Query syntax.

Example data

Note: for information about the reserved named shadow and its structure, see Reserved named shadow.

In this example, a first device is named AnyThing and has the following packages installed:

The shadow looks as follows:

{
    "state": {
        "reported": {
            "SamplePackage": {
                "version": "1.0.0",
                "attributes": {
                    "s3UrlForSamplePackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile1",
                    "packageID": "1111"
                    }
            }
        }
    }
}

A second device is named AnotherThing and has the following package installed:

The shadow looks as follows:

{
    "state": {
        "reported": {
            "SamplePackage": {
                "version": "1.0.0",
                "attributes": {
                    "s3UrlForSamplePackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile1",
                    "packageID": "1111"
                }
            },
            "OtherPackage": {
                "version": "1.2.5",
                "attributes": {
                    "s3UrlForOtherPackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile2",
                    "packageID": "2222"
                    }
            },
        }
    }
}

Sample queries

The following table lists sample queries based on the example device shadows for AnyThing and AnotherThing. For more information, see Example thing queries.

Collecting package version distribution through getBucketsAggregation

In addition to the Discovery panel within the Amazon IoT console, you can also get package version distribution information by using the GetBucketsAggregation API operation. To get the package version distribution information, you must do the following:

For more information, see the Custom fields section in Amazon IoT fleet indexing.