本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 准备实例集索引
使用 AWS IoT 队列索引，您可以使用名为 shadow (`$package`) 的预留名称来搜索和聚合数据。您还可以通过查询[预留命名影子](preparing-to-use-software-package-catalog.md#reserved-named-shadow)和[动态 AWS IoT 事物组对事物进行分组](https://docs.aws.amazon.com/iot/latest/developerguide/dynamic-thing-groups.html)。例如，您可以找到有关哪些 AWS IoT 内容使用特定的软件包版本、未安装特定的软件包版本或未安装任何软件包版本的信息。您可以通过组合属性来获得进一步的见解。例如，识别具有特定版本且属于特定事物类型的事物（例如版本 1.0.0 和事物类型 pump\$1sensor）。有关更多信息，请参阅[实例集索引](https://docs.aws.amazon.com/iot/latest/developerguide/iot-indexing.html)。
## 将 `$package` 影子设置为数据来源
要在软件包目录中使用实例集索引，必须启用实例集索引，将命名影子设置为数据来源，并将 `$package` 定义为命名影子筛选条件。如果您尚未启用实例集索引，则可以在此过程中将其启用。从控制台中的 [AWS IoT Core](https://console.aws.amazon.com/iot/home)，打开**设置**，选择**管理索引**，然后依次选择**添加命名影子**、**添加设备软件包和版本**和**更新**。有关更多信息，请参阅[管理事物索引](https://docs.aws.amazon.com/iot/latest/developerguide/managing-fleet-index.html#thing-index)。
或者，您可以在创建第一个软件包时启用实例集索引。出现**为软件包管理启用依赖项**对话框时，选择将设备软件包和版本作为数据来源添加到实例集索引的选项。通过选择此选项，还可以启用实例集索引。
**注意**
为软件包目录启用实例集索引会产生标准服务成本。有关更多信息，请参阅 [AWS IoT Device Management定价](https://aws.amazon.com/iot-device-management/pricing/)。
## 控制台中显示的指标
![\[标准指标图\]](http://docs.aws.amazon.com/zh_cn/iot/latest/developerguide/images/package-catalog-discovery-metrics.png)
在 AWS IoT 控制台软件包详细信息页面上，**Discovery** 面板显示通过`$package`阴影获取的标准指标。
+ **当前版本分布**图显示了与该软件包关联的所有设备中与某 AWS IoT 件事物关联的 10 个最新软件包版本的设备数量和百分比。**注意：**如果软件包的程序包版本多于图表中标注的版本，则可以发现它们分组在**其它**中。
+ **历史图表**显示指定时间段内与所选程序包版本关联的设备数量。该图表最初为空，直至您选择多达 5 个程序包版本并定义日期范围和时间间隔。要选择图表的参数，请选择**设置**。**历史图表**中显示的数据可能与**当前版本分发**图不同，这是因为它们显示的程序包版本数量不同，也因为您可以在**历史图表**中选择要分析的程序包版本。**注意：**当您选择要可视化的程序包版本时，它将计入实例集指标的最大数量限制。有关更多信息，请参阅[实例集索引限制和限额](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#fleet-indexing-limits)。
有关深入了解收集程序包版本分发的另一种方法，请参阅[通过 `getBucketsAggregation` 收集程序包版本分发](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-fleet-indexing.html#package-version-distribution)。
## 查询模式
使用软件包目录的实例集索引支持大多数标准功能（例如术语、短语和搜索字段）。但是，比较运算符（例如小于 `<` 和大于 `>`）和 `range` 查询不适用于保留的命名影子 (`$package`) `version` 键。这些查询可用于 `attributes` 键。有关更多信息，请参阅[查询语法](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html)。
### 示例数据
**注意：**有关预留命名影子及其结构的信息，请参阅[预留命名影子](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-to-use-software-package-catalog.html#reserved-named-shadow)。
在此示例中，第一台设备命名为 `AnyThing` 并安装了以下软件包：
+ 软件包：`SamplePackage`
程序包版本：`1.0.0`
软件包 ID：`1111`
影子如下所示：
```
{
"state": {
"reported": {
"SamplePackage": {
"version": "1.0.0",
"attributes": {
"s3UrlForSamplePackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile1",
"packageID": "1111"
}
}
}
}
}
```
第二台设备命名为 `AnotherThing` 并安装了以下软件包：
+ 软件包：`SamplePackage`
程序包版本：`1.0.0`
软件包 ID：`1111`
+ 软件包：`OtherPackage`
程序包版本：`1.2.5`
软件包 ID：`2222`
影子如下所示：
```
{
"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"
}
},
}
}
}
```
### 查询示例
下表根据 `AnyThing` 和 `AnotherThing` 的示例设备影子列出了查询示例。有关更多信息，请参阅[示例事物查询](https://docs.aws.amazon.com/iot/latest/developerguide/example-queries.html)。
**AWS IoT Device Tester 适用于 FreeRTOS 的最新版本**
| **所请求的信息** | **查询** | **结果** |
| --- | --- | --- |
| 安装了特定程序包版本的事物 | `shadow.name.$package.reported.SamplePackage.version:1.0.0` | `AnyThing`, `OtherThing` |
| 未安装特定程序包版本的事物 | `NOT shadow.name.$package.reported.OtherPackage.version:1.2.5` | `AnyThing` |
| 使用软件包 ID 大于 1500 的程序包版本的任何设备 | `shadow.name.$package.reported.*.attributes.packageID>1500"` | `OtherThing` |
| 安装了特定软件包和安装了多个软件包的事物 | `shadow.name.$package.reported.SamplePackage.version:1.0.0 AND shadow.name.$package.reported.totalCount:2` | `OtherThing` |
## 通过 `getBucketsAggregation` 收集程序包版本分发
除了 AWS IoT 控制台中的**发现**面板外，您还可以使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_GetBucketsAggregation.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetBucketsAggregation.html)API 操作获取软件包版本分发信息。要获取程序包版本分发信息，必须执行以下操作：
+ 在实例集索引中为每个软件包定义一个自定义字段。**注意：**创建自定义字段会计入 [AWS IoT 实例集索引服务限额](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#fleet-indexing-limits)。
+ 按如下方式格式化自定义字段：
`shadow.name.$package.reported..version`
有关更多信息，请参阅 AWS IoT 舰队索引中的 “[自定义字段](https://docs.aws.amazon.com/iot/latest/developerguide/managing-fleet-index.html#custom-field)” 部分。