与局部阴影交互 - Amazon IoT Greengrass
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

与局部阴影交互

使用阴影 IPC 服务与设备上的本地阴影进行交互。您选择与之交互的设备可以是您的核心设备或连接的客户端设备。

加入影子管理器组件作为您的自定义组件中的依赖项。然后,您可以在自定义组件中使用 IPC 操作,通过卷影管理器与设备上的本地阴影进行交互。若要使自定义组件能够响应本地阴影状态的更改,还可以使用发布/订阅 IPC 服务订阅卷影事件。有关使用发布/订阅服务的更多信息,请参阅发布/订阅本地消息

最低开发工具包版本

下表列出了最低版本的 Amazon IoT Device SDK ,您必须使用它与局部阴影进行交互。

Authorization

要在自定义组件中使用影子 IPC 服务,必须定义允许组件与阴影交互的授权策略。有关定义授权策略的信息,请参阅授权组件执行 IPC 操作

卷影交互的授权策略具有以下属性。

IPC 服务标识符: aws.greengrass.ShadowManager

操作 说明 资源

aws.greengrass#GetThingShadow

允许组件检索事物的阴影。

下列字符串之一:

  • $aws/things/thingName/shadow/,以允许访问经典设备阴影

  • $aws/things/thingName/shadow/name/shadowName,以允许访问命名阴影

  • *,以允许访问所有主题。

aws.greengrass#UpdateThingShadow

允许组件更新事物的阴影。

下列字符串之一:

  • $aws/things/thingName/shadow/,以允许访问经典设备阴影

  • $aws/things/thingName/shadow/name/shadowName,以允许访问命名阴影

  • *,以允许访问所有主题。

aws.greengrass#DeleteThingShadow

允许组件删除事物的阴影。

下列字符串之一:

  • $aws/things/thingName/shadow/,以允许访问经典设备阴影

  • $aws/things/thingName/shadow/name/shadowName,以允许访问命名阴影

  • *,以允许访问所有主题。

aws.greengrass#ListNamedShadowsForThing

允许组件为事物检索命名的阴影的列表。

一个事物名称字符串,允许访问该事物以列出其阴影。

使用*允许访问事物。

IPC 服务标识符: aws.greengrass.ipc.pubsub

操作 说明 资源

aws.greengrass#SubscribeToTopic

允许组件订阅您指定主题的消息。

下列主题字符串之一:

  • shadowTopicPrefix/get/accepted

  • shadowTopicPrefix/get/rejected

  • shadowTopicPrefix/delete/accepted

  • shadowTopicPrefix/delete/rejected

  • shadowTopicPrefix>/update/accepted

  • shadowTopicPrefix/update/delta

  • shadowTopicPrefix/update/rejected

主题前缀的值shadowTopicPrefix取决于影子的类型:

  • 经典影子:$aws/things/thingName/shadow

  • 命名的影子:$aws/things/thingName/shadow/name/shadowName

使用*以允许访问所有主题。此主题字符串不支持 MQTT 主题通配符 (#+)。

例 授权策略示例

以下示例授权策略允许com.example.MyShadowInteractionComponent与经典设备阴影和命名阴影进行交互myNamedShadow对于设备MyThingName。此策略还允许此组件接收有关这些阴影的本地主题的消息。

JSON
{ "accessControl": { "aws.greengrass.ShadowManager": { "policyId1": { "policyDescription": "Allows access to shadows", "operations": [ "aws.greengrass#GetThingShadow", "aws.greengrass#UpdateThingShadow", "aws.greengrass#DeleteThingShadow" ], "resources": [ "$aws/things/MyThingName/shadow", "$aws/things/MyThingName/shadow/name/myNamedShadow" ] }, "policyId2": { "policyDescription": "Allows access to things with shadows", "operations": [ "aws.greengrass#ListNamedShadowsForThing" ], "resources": [ "MyThingName" ] } }, "aws.greengrass.ipc.pubsub": { "com.example.MyShadowInteractionComponent:pubsub:1": { "policyDescription": "Allows access to shadow pubsub topics", "operations": [ "aws.greengrass#SubscribeToTopic" ], "resources": [ "$aws/things/MyThingName/shadow/get/accepted", "$aws/things/MyThingName/shadow/name/myNamedShadow/get/accepted" ] } } } }
YAML
accessControl: aws.greengrass.ShadowManager: policyId1: policyDescription: 'Allows access to shadows' operations: - 'aws.greengrass#GetThingShadow' - 'aws.greengrass#UpdateThingShadow' - 'aws.greengrass#DeleteThingShadow' resources: - $aws/things/MyThingName/shadow - $aws/things/MyThingName/shadow/name/myNamedShadow policyId2: policyDescription: 'Allows access to things with shadows' operations: - 'aws.greengrass#ListNamedShadowsForThing' resources: - MyThingName aws.greengrass.ipc.pubsub: 'com.example.MyShadowInteractionComponent:pubsub:1': policyDescription: 'Allows access to shadow pubsub topics' operations: - 'aws.greengrass#SubscribeToTopic' resources: - $aws/things/MyThingName/shadow/get/accepted - $aws/things/MyThingName/shadow/name/myNamedShadow/get/accepted

GetThingShadow

获取指定事物的影子。

Request

此操作的请求包含以下参数:

thingName

要获取影子的事物的名称。

类型:string

shadowName

(可选)要获取的影子的名称。仅命名的影子需要使用该参数。

类型:string

Response

该操作的响应包含以下信息:

payload

响应状态文档作为 Blob。

类型:object包含以下信息:

state

状态信息。

此对象包含以下信息。

desired

请求在设备中更新的状态属性和值。

类型:map键/值对的情况

reported

设备报告的状态属性和值。

类型:map键/值对的情况

delta

所需状态和报告状态属性和值之间的差异。仅当使用该属性时,才存在该属性。desiredreported状态是不同的。

类型:map键/值对的情况

metadata

每个属性的时间戳desiredreported部分,因此,您可以确定状态的更新时间。

类型:string

timestamp

生成响应时的 Epoch 日期和时间。

类型:integer

clientToken

用于匹配请求和相应的响应的令牌

类型:string

version

本地影子文档的版本。

类型:integer

Errors

此操作可能会返回以下错误。

InvalidArgumentsError

本地影子服务无法验证请求参数。如果请求包含格式错误的 JSON 或不支持的字符,则会发生这种情况。

ResourceNotFoundError

找不到请求的本地影子文档。

ServiceError

发生内部服务错误,或者对 IPC 服务的请求数超过maxLocalRequestsPerSecondPerThingmaxTotalLocalRequestsRate配置参数。

UnauthorizedError

组件的授权策略不包括此操作所需的权限。

Examples

以下示例演示如何在自定义组件代码中调用该操作。

Java
byte[] sampleGetThingShadowRequest(String thingName, String shadowName) { try { // set up IPC client to connect to the IPC server EventStreamRPCConnection eventStreamRpcConnection = IPCUtils.getEventStreamRpcConnection(); GreengrassCoreIPCClient greengrassCoreIPCClient = new GreengrassCoreIPCClient(eventStreamRpcConnection); // create the GetThingShadow request GetThingShadowRequest getThingShadowRequest = new GetThingShadowRequest(); getThingShadowRequest.setThingName(thingName); getThingShadowRequest.setShadowName(shadowName); // retrieve the GetThingShadow response after sending the request to the IPC server GetThingShadowResponse getThingShadowResponse = greengrassCoreIPCClient.getThingShadow(getThingShadowRequest, Optional.empty()) .getResponse() .get(); byte[] payload = getThingShadowResponse.getPayload(); return payload; catch (ExecutionException e) { if (e.getCause() instanceof InvalidArgumentsError) { // add error handling } ... // catch ResourceNotFoundError | UnauthorizedError | ServiceError } }
Python
import awsiot.greengrasscoreipc import awsiot.greengrasscoreipc.client as client from aws.iot.greengrasscoreipc.model import GetThingShadowRequest TIMEOUT = 10 def sample_get_thing_shadow_request(thingName, shadowName): try: # set up IPC client to connect to the IPC server ipc_client = awsiot.greengrasscoreipc.connect() # create the GetThingShadow request get_thing_shadow_request = GetThingShadowRequest() get_thing_shadow_request.thing_name = thingName get_thing_shadow_request.shadow_name = shadowName # retrieve the GetThingShadow response after sending the request to the IPC server op = ipc_client.new_get_thing_shadow() op.activate(get_thing_shadow_request) fut = op.get_response() result = fut.result(TIMEOUT) return result.payload except InvalidArgumentsError as e: # add error handling ... # except ResourceNotFoundError | UnauthorizedError | ServiceError

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

每个属性的时间戳desiredreported部分,因此,您可以确定状态的更新时间。

类型:string

timestamp

生成响应时的 Epoch 日期和时间。

类型:integer

clientToken

用于匹配请求和相应的响应的令牌。

类型:string

version

更新完成后的本地影子文档的版本。

类型:integer

Errors

此操作可能会返回以下错误。

ConflictError

本地影子服务在更新操作期间遇到版本冲突。当请求有效负载中的版本与最新的可用本地影子文档中的版本不匹配时,会发生这种情况。

InvalidArgumentsError

本地影子服务无法验证请求参数。如果请求包含格式错误的 JSON 或不支持的字符,则会发生这种情况。

有效的操作payload具有以下属性:

  • 这些区域有:state节点存在,并且是一个包含desired或者reported状态信息。

  • 这些区域有:desiredreported节点是对象或空值。其中至少有一个对象必须包含有效的状态信息。

  • 的深度desiredreported对象不能超过八个节点。

  • 的长度clientToken值不得超过 64 个字符。

  • 这些区域有:version值必须为。1或更高版本。

ServiceError

发生内部服务错误,或者对 IPC 服务的请求数超过maxLocalRequestsPerSecondPerThingmaxTotalLocalRequestsRate配置参数。

UnauthorizedError

组件的授权策略不包括此操作所需的权限。

Examples

以下示例演示如何在自定义组件代码中调用该操作。

Java
byte[] sampleUpdateThingShadowRequest(String thingName, String shadowName, byte[] updateDocument) { try { // set up IPC client to connect to the IPC server EventStreamRPCConnection eventStreamRpcConnection = IPCUtils.getEventStreamRpcConnection(); GreengrassCoreIPCClient greengrassCoreIPCClient = new GreengrassCoreIPCClient(eventStreamRpcConnection); // create the UpdateThingShadow request UpdateThingShadowRequest updateThingShadowRequest = new UpdateThingShadowRequest(); updateThingShadowRequest.setThingName(thingName); updateThingShadowRequest.setShadowName(shadowName); updateThingShadowRequest.setPayload(updateDocument); // retrieve the UpdateThingShadow response after sending the request to the IPC server UpdateThingShadowRespone updateThingShadowResponse = greengrassCoreIPCClient.updateThingShadow(updateThingShadowRequest, Optional.empty()) .getResponse() .get(); byte[] payload = updateThingShadowResponse.getPayload(); return payload; catch (ExecutionException e) { if (e.getCause() instanceof InvalidArgumentsError) { // add error handling } ... // catch ConflictError | UnauthorizedError | ServiceError } }
Python
import awsiot.greengrasscoreipc import awsiot.greengrasscoreipc.client as client from aws.iot.greengrasscoreipc.model import UpdateThingShadowRequest TIMEOUT = 10 def sample_update_thing_shadow_request(thingName, shadowName, payload): try: # set up IPC client to connect to the IPC server ipc_client = awsiot.greengrasscoreipc.connect() # create the UpdateThingShadow request update_thing_shadow_request = UpdateThingShadowRequest() update_thing_shadow_request.thing_name = thingName update_thing_shadow_request.shadow_name = shadowName update_thing_shadow_request.payload = payload # retrieve the UpdateThingShadow response after sending the request to the IPC server op = ipc_client.new_update_thing_shadow() op.activate(update_thing_shadow_request) fut = op.get_response() result = fut.result(TIMEOUT) return result.payload except InvalidArgumentsError as e: # add error handling ... # except ConflictError | UnauthorizedError | ServiceError

DeleteThingShadow

删除指定事物的影子。

Request

该操作的请求包含以下参数:

thingName

要删除影子的事物的名称。

类型:string

shadowName

(可选)要删除的影子的名称。仅命名的影子需要使用该参数。

类型:string

Response

该操作的响应包含以下信息:

payload

空的响应状态文档。

Errors

此操作可能会返回以下错误。

InvalidArgumentsError

本地影子服务无法验证请求参数。如果请求包含格式错误的 JSON 或不支持的字符,则会发生这种情况。

ResourceNotFoundError

找不到请求的本地影子文档。

ServiceError

发生内部服务错误,或者对 IPC 服务的请求数超过maxLocalRequestsPerSecondPerThingmaxTotalLocalRequestsRate配置参数。

UnauthorizedError

组件的授权策略不包括此操作所需的权限。

Examples

以下示例演示如何在自定义组件代码中调用该操作。

Java
byte[] sampleDeleteThingShadowRequest(String thingName, String shadowName) { try { // set up IPC client to connect to the IPC server EventStreamRPCConnection eventStreamRpcConnection = IPCUtils.getEventStreamRpcConnection(); GreengrassCoreIPCClient greengrassCoreIPCClient = new GreengrassCoreIPCClient(eventStreamRpcConnection); // create the DeleteThingShadow request DeleteThingShadowRequest deleteThingShadowRequest = new DeleteThingShadowRequest(); deleteThingShadowRequest.setThingName(thingName); deleteThingShadowRequest.setShadowName(shadowName); // retrieve the DeleteThingShadow response after sending the request to the IPC server DeleteThingShadowResponse deleteThingShadowResponse = greengrassCoreIPCClient.deleteThingShadow(deleteThingShadowRequest, Optional.empty()) .getResponse() .get(); byte[] payload = deleteThingShadowResponse.getPayload(); return payload; catch (ExecutionException e) { if (e.getCause() instanceof InvalidArgumentsError) { // add error handling } ... // catch ResourceNotFoundError | UnauthorizedError | ServiceError } }
Python
import awsiot.greengrasscoreipc import awsiot.greengrasscoreipc.client as client from aws.iot.greengrasscoreipc.model import DeleteThingShadowRequest TIMEOUT = 10 def sample_delete_thing_shadow_request(thingName, shadowName): try: # set up IPC client to connect to the IPC server ipc_client = awsiot.greengrasscoreipc.connect() # create the DeleteThingShadow request delete_thing_shadow_request = DeleteThingShadowRequest() delete_thing_shadow_request.thing_name = thingName delete_thing_shadow_request.shadow_name = shadowName # retrieve the DeleteThingShadow response after sending the request to the IPC server op = ipc_client.new_delete_thing_shadow() op.activate(delete_thing_shadow_request) fut = op.get_response() result = fut.result(TIMEOUT) return result.payload except InvalidArgumentsError as e: # add error handling ... # except ResourceNotFoundError | UnauthorizedError | ServiceError

ListNamedShadowsForThing

列出指定事物的命名影子。

Request

该操作的请求包含以下参数:

thingName

要列出命名的影子的事物的名称。

类型:string

pageSize

(可选)在每个调用中返回的影子名称的数量。

类型:integer

默认值:25

最大值:100

nextToken

(可选)用于检索下一组结果的令牌。该值在分页结果中返回,并在返回下一页的调用中使用。

类型:string

Response

该操作的响应包含以下信息:

results

影子名称列表。

类型:array

timestamp

(可选)生成响应时的日期和时间。

类型:integer

nextToken

(可选)在用于检索序列中的下一页的分页请求中使用的令牌值。当没有其他要返回的影子名称时,该令牌不存在。

类型:string

注意

如果请求的页面大小与响应中的影子名称数量完全匹配,则此标记存在;但是,使用时,它会返回一个空列表。

Errors

此操作可能会返回以下错误。

InvalidArgumentsError

本地影子服务无法验证请求参数。如果请求包含格式错误的 JSON 或不支持的字符,则会发生这种情况。

ResourceNotFoundError

找不到请求的本地影子文档。

ServiceError

发生内部服务错误,或者对 IPC 服务的请求数超过maxLocalRequestsPerSecondPerThingmaxTotalLocalRequestsRate配置参数。

UnauthorizedError

组件的授权策略不包括此操作所需的权限。

Examples

以下示例演示如何在自定义组件代码中调用该操作。

Java
List<String> sampleListNamedShadowsForThingRequest(String thingName, String nextToken, int pageSize) { try { // set up IPC client to connect to the IPC server EventStreamRPCConnection eventStreamRpcConnection = IPCUtils.getEventStreamRpcConnection(); GreengrassCoreIPCClient greengrassCoreIPCClient = new GreengrassCoreIPCClient(eventStreamRpcConnection); // create the ListNamedShadowsForThing request ListNamedShadowsForThingRequest request = new ListNamedShadowsForThingRequest(); request.setThingName(thingName); request.setNextToken(nextToken); request.setPageSize(pageSize); // retrieve the ListNamedShadowsForThing response after sending the request to the IPC server ListThingShadowsForThingResponse response = greengrassCoreIPCClient.listNamedShadowsForThing(request, Optional.empty()) .getResponse() .get(); List<String> listOfNamedShadows = response.getResults().get() // pagination token used to get next set of data // null indicates that all named shadows were received String tokenForNextQuery = response.getNextToken().get() return listOfNamedShadows; catch (ExecutionException e) { if (e.getCause() instanceof InvalidArgumentsError) { // add error handling } ... // catch ResourceNotFoundError | UnauthorizedError | ServiceError } }
Python
import awsiot.greengrasscoreipc import awsiot.greengrasscoreipc.client as client from aws.iot.greengrasscoreipc.model import ListNamedShadowsForThingRequest TIMEOUT = 10 def sample_list_named_shadows_for_thing_request(thingName, nextToken, pageSize): try: # set up IPC client to connect to the IPC server ipc_client = awsiot.greengrasscoreipc.connect() # create the ListNamedShadowsForThingRequest request list_named_shadows_for_thing_request = ListNamedShadowsForThingRequest() list_named_shadows_for_thing_request.thing_name = thingName list_named_shadows_for_thing_request.next_token = nextToken list_named_shadows_for_thing_request.page_size = pageSize # retrieve the ListNamedShadowsForThingRequest response after sending the request to the IPC server op = ipc_client.new_list_named_shadows_for_thing() op.activate(list_named_shadows_for_thing_request) fut = op.get_response() list_result = fut.result(TIMEOUT) # additional returned fields timestamp = list_result.timestamp next_token = result.next_token named_shadow_list = list_result.results return named_shadow_list, next_token, timestamp except InvalidArgumentsError as e: # add error handling ... # except ResourceNotFoundError | UnauthorizedError | ServiceError