本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
与局部阴影交互
使用阴影 IPC 服务与设备上的本地阴影进行交互。您选择与之交互的设备可以是您的核心设备或连接的客户端设备。
加入影子管理器组件作为您的自定义组件中的依赖项。然后，您可以在自定义组件中使用 IPC 操作，通过卷影管理器与设备上的本地阴影进行交互。若要使自定义组件能够响应本地阴影状态的更改，还可以使用发布/订阅 IPC 服务订阅卷影事件。有关使用发布/订阅服务的更多信息，请参阅发布/订阅本地消息。
主题
最低开发工具包版本
下表列出了最低版本的 Amazon IoT Device SDK ，您必须使用它与局部阴影进行交互。
| 开发工具包 | 最低版本 |
|---|---|
|
v1.4.0 |
|
|
v1.6.0 |
Authorization
要在自定义组件中使用影子 IPC 服务，必须定义允许组件与阴影交互的授权策略。有关定义授权策略的信息，请参阅授权组件执行 IPC 操作。
卷影交互的授权策略具有以下属性。
IPC 服务标识符： aws.greengrass.ShadowManager
| 操作 | 说明 | 资源 |
|---|---|---|
|
|
允许组件检索事物的阴影。 |
下列字符串之一：
|
|
|
允许组件更新事物的阴影。 |
下列字符串之一：
|
|
|
允许组件删除事物的阴影。 |
下列字符串之一：
|
|
|
允许组件为事物检索命名的阴影的列表。 |
一个事物名称字符串，允许访问该事物以列出其阴影。 使用 |
IPC 服务标识符： aws.greengrass.ipc.pubsub
| 操作 | 说明 | 资源 |
|---|---|---|
|
|
允许组件订阅您指定主题的消息。 |
下列主题字符串之一：
主题前缀的值
使用 |
例 授权策略示例
以下示例授权策略允许com.example.MyShadowInteractionComponent与经典设备阴影和命名阴影进行交互myNamedShadow对于设备MyThingName。此策略还允许此组件接收有关这些阴影的本地主题的消息。
GetThingShadow
获取指定事物的影子。
Request
此操作的请求包含以下参数：
thingName-
要获取影子的事物的名称。
类型：
string shadowName-
（可选）要获取的影子的名称。仅命名的影子需要使用该参数。
类型：
string
Response
该操作的响应包含以下信息：
payload-
响应状态文档作为 Blob。
类型：
object包含以下信息：state-
状态信息。
此对象包含以下信息。
desired-
请求在设备中更新的状态属性和值。
类型：
map键/值对的情况 reported-
设备报告的状态属性和值。
类型：
map键/值对的情况 delta-
所需状态和报告状态属性和值之间的差异。仅当使用该属性时，才存在该属性。
desired和reported状态是不同的。类型：
map键/值对的情况
metadata-
每个属性的时间戳
desired和reported部分，因此，您可以确定状态的更新时间。类型：
string timestamp-
生成响应时的 Epoch 日期和时间。
类型：
integer clientToken-
用于匹配请求和相应的响应的令牌
类型：
string version-
本地影子文档的版本。
类型：
integer
Errors
此操作可能会返回以下错误。
Examples
以下示例演示如何在自定义组件代码中调用该操作。
UpdateThingShadow
更新指定事物的影子。
Request
此操作的请求包含以下参数：
thingName-
要更新影子的事物的名称。
类型：
string shadowName-
（可选）要更新的影子的名称。仅命名的影子需要使用该参数。
类型：
string payload-
请求状态文档作为 Blob。
类型：
object包含以下信息：state-
要更新的状态信息。此 IPC 操作仅影响指定字段。
此对象包含以下信息。通常情况下，您将使用
desired属性或reported属性，但不能在同一请求中同时使用这两个属性。desired-
请求在设备中更新的状态属性和值。
类型：
map键/值对的情况 reported-
设备报告的状态属性和值。
类型：
map键/值对的情况
clientToken-
（可选）用于通过客户端令牌匹配请求和相应的响应的令牌。
类型：
string version-
（可选）要更新的本地影子文档的版本。仅当指定的版本与 Shadow 服务拥有的最新版本相符时，该服务才会处理更新。
类型：
integer
Response
该操作的响应包含以下信息：
payload-
响应状态文档作为 Blob。
类型：
object包含以下信息：state-
状态信息。
此对象包含以下信息。
desired-
请求在设备中更新的状态属性和值。
类型：
map键/值对的情况 reported-
设备报告的状态属性和值。
类型：
map键/值对的情况 delta-
设备报告的状态属性和值。
类型：
map键/值对的情况
metadata-
每个属性的时间戳
desired和reported部分，因此，您可以确定状态的更新时间。类型：
string timestamp-
生成响应时的 Epoch 日期和时间。
类型：
integer clientToken-
用于匹配请求和相应的响应的令牌。
类型：
string version-
更新完成后的本地影子文档的版本。
类型：
integer
Errors
此操作可能会返回以下错误。
ConflictError-
本地影子服务在更新操作期间遇到版本冲突。当请求有效负载中的版本与最新的可用本地影子文档中的版本不匹配时，会发生这种情况。
InvalidArgumentsError-
本地影子服务无法验证请求参数。如果请求包含格式错误的 JSON 或不支持的字符，则会发生这种情况。
有效的操作
payload具有以下属性：-
这些区域有：
state节点存在，并且是一个包含desired或者reported状态信息。 -
这些区域有：
desired和reported节点是对象或空值。其中至少有一个对象必须包含有效的状态信息。 -
的深度
desired和reported对象不能超过八个节点。 -
的长度
clientToken值不得超过 64 个字符。 -
这些区域有：
version值必须为。1或更高版本。
-
ServiceError-
发生内部服务错误，或者对 IPC 服务的请求数超过
maxLocalRequestsPerSecondPerThing和maxTotalLocalRequestsRate配置参数。 UnauthorizedError-
组件的授权策略不包括此操作所需的权限。
Examples
以下示例演示如何在自定义组件代码中调用该操作。
DeleteThingShadow
删除指定事物的影子。
Request
该操作的请求包含以下参数：
thingName-
要删除影子的事物的名称。
类型：
string shadowName-
（可选）要删除的影子的名称。仅命名的影子需要使用该参数。
类型：
string
Response
该操作的响应包含以下信息：
payload-
空的响应状态文档。
Errors
此操作可能会返回以下错误。
Examples
以下示例演示如何在自定义组件代码中调用该操作。
ListNamedShadowsForThing
列出指定事物的命名影子。
Request
该操作的请求包含以下参数：
thingName-
要列出命名的影子的事物的名称。
类型：
string pageSize-
（可选）在每个调用中返回的影子名称的数量。
类型：
integer默认值：25
最大值：100
nextToken-
（可选）用于检索下一组结果的令牌。该值在分页结果中返回，并在返回下一页的调用中使用。
类型：
string
Response
该操作的响应包含以下信息：
results-
影子名称列表。
类型：
array timestamp-
（可选）生成响应时的日期和时间。
类型：
integer nextToken-
（可选）在用于检索序列中的下一页的分页请求中使用的令牌值。当没有其他要返回的影子名称时，该令牌不存在。
类型：
string注意 如果请求的页面大小与响应中的影子名称数量完全匹配，则此标记存在；但是，使用时，它会返回一个空列表。
Errors
此操作可能会返回以下错误。
Examples
以下示例演示如何在自定义组件代码中调用该操作。