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

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

与局部阴影互动

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

要使用这些 IPC 操作,请包括影子管理器组件作为自定义组件中的依赖项。然后,您可以在自定义组件中使用 IPC 操作,通过影子管理器与设备上的本地阴影进行交互。要使自定义组件能够对本地影子状态的变化做出反应,您还可以使用发布/订阅 IPC 服务订阅影子事件。有关使用发布/订阅服务的更多信息,请参阅发布/订阅本地消息.

注意

要使核心设备能够与客户端设备影子交互,您还必须配置和部署 MQTT 桥接组件。有关更多信息,请参阅 。启用影子管理器与客户端设备通信.

最低 SDK 版本

下表列出了Amazon IoT Device SDK你必须用它来与局部阴影互动。

Authorization

要在自定义组件中使用 shadow 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

使用*以允许访问所有主题。

Greengrass 核v2.6.0 及更高版本,您可以订阅包含 MQTT 主题通配符的主题 (#+)。此主题字符串支持 MQTT 主题通配符作为文字字符。例如,如果组件的授权策略授予对的访问权限test/topic/#,该组件可以订阅test/topic/#,但它无法订阅test/topic/filter.

本地影子授权策略中的配方变量

如果你使用 v2.6.0 或更高版本的Greengrass 核,然后你设置了 Greengrass NucleusinterpolateComponentConfiguration配置选项至true,您可以使用{iot:thingName} 配方变量在授权策略中。此功能使您可以为一组核心设备配置单一授权策略,其中每个核心设备只能访问自己的影子。例如,您可以允许组件访问以下资源以进行影子 IPC 操作。

$aws/things/{iot:thingName}/shadow/

授权策略示例

您可以参考以下授权策略示例来帮助您为组件配置授权策略。

例 示例:允许一组核心设备与本地阴影交互

重要

此示例使用了可用于 v2.6.0 及更高版本的功能Greengrass 核组件. Greengrass nucleus v2.6.0 增加了对大多数人的支持配方变量,例如{iot:thingName},在组件配置中。要启用此功能,请设置Greengrass 核interpolateComponentConfiguration配置选项至true. 有关适用于所有版本的 Greengrass 原子核的示例,请参阅单核设备的授权策略示例.

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

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

例 示例:允许一组核心设备与客户端设备影子交互

重要

此功能需要Greengrass 核v1.2.0 或更高版本,影子经理v2.2.0 或更高版本,以及MQTT 桥v2.2.0 或更高版本。您必须将 MQTT 网桥配置为启用影子管理器与客户端设备通信.

以下示例授权策略允许组件com.example.MyShadowInteractionComponent与名称以开头的客户端设备的所有设备影子进行交互MyClientDevice.

注意

要使核心设备能够与客户端设备影子交互,您还必须配置和部署 MQTT 桥接组件。有关更多信息,请参阅 。启用影子管理器与客户端设备通信.

JSON
{ "accessControl": { "aws.greengrass.ShadowManager": { "com.example.MyShadowInteractionComponent:shadow:1": { "policyDescription": "Allows access to shadows", "operations": [ "aws.greengrass#GetThingShadow", "aws.greengrass#UpdateThingShadow", "aws.greengrass#DeleteThingShadow" ], "resources": [ "$aws/things/MyClientDevice*/shadow", "$aws/things/MyClientDevice*/shadow/name/*" ] }, "com.example.MyShadowInteractionComponent:shadow:2": { "policyDescription": "Allows access to things with shadows", "operations": [ "aws.greengrass#ListNamedShadowsForThing" ], "resources": [ "MyClientDevice*" ] } } } }
YAML
accessControl: aws.greengrass.ShadowManager: 'com.example.MyShadowInteractionComponent:shadow:1': policyDescription: 'Allows access to shadows' operations: - 'aws.greengrass#GetThingShadow' - 'aws.greengrass#UpdateThingShadow' - 'aws.greengrass#DeleteThingShadow' resources: - $aws/things/MyClientDevice*/shadow - $aws/things/MyClientDevice*/shadow/name/* 'com.example.MyShadowInteractionComponent:shadow:2': policyDescription: 'Allows access to things with shadows' operations: - 'aws.greengrass#ListNamedShadowsForThing' resources: - MyClientDevice*

例 示例:允许单核设备与本地阴影交互

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

JSON
{ "accessControl": { "aws.greengrass.ShadowManager": { "com.example.MyShadowInteractionComponent:shadow:1": { "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" ] }, "com.example.MyShadowInteractionComponent:shadow:2": { "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: 'com.example.MyShadowInteractionComponent:shadow:1': 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 'com.example.MyShadowInteractionComponent:shadow:2': 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

例 示例:允许一组核心设备对本地影子状态变化做出反应

重要

此示例使用了可用于 v2.6.0 及更高版本的功能Greengrass 核组件. Greengrass nucleus v2.6.0 增加了对大多数人的支持配方变量,例如{iot:thingName},在组件配置中。要启用此功能,请设置Greengrass 核interpolateComponentConfiguration配置选项至true. 有关适用于所有版本的 Greengrass 原子核的示例,请参阅单核设备的授权策略示例.

以下示例访问控制策略允许自定义com.example.MyShadowReactiveComponent在上接收消息/update/delta经典设备影子和命名影子的主题myNamedShadow在运行该组件的每台核心设备上。

JSON
{ "accessControl": { "aws.greengrass.ipc.pubsub": { "com.example.MyShadowReactiveComponent:pubsub:1": { "policyDescription": "Allows access to shadow pubsub topics", "operations": [ "aws.greengrass#SubscribeToTopic" ], "resources": [ "$aws/things/{iot:thingName}/shadow/update/delta", "$aws/things/{iot:thingName}/shadow/name/myNamedShadow/update/delta" ] } } } }
YAML
accessControl: aws.greengrass.ipc.pubsub: "com.example.MyShadowReactiveComponent:pubsub:1": policyDescription: Allows access to shadow pubsub topics operations: - 'aws.greengrass#SubscribeToTopic' resources: - $aws/things/{iot:thingName}/shadow/update/delta - $aws/things/{iot:thingName}/shadow/name/myNamedShadow/update/delta

例 示例:允许单核设备对本地影子状态变化做出反应

以下示例访问控制策略允许自定义com.example.MyShadowReactiveComponent在上接收消息/update/delta经典设备影子和命名影子的主题myNamedShadow用于此设备MyThingName.

JSON
{ "accessControl": { "aws.greengrass.ipc.pubsub": { "com.example.MyShadowReactiveComponent:pubsub:1": { "policyDescription": "Allows access to shadow pubsub topics", "operations": [ "aws.greengrass#SubscribeToTopic" ], "resources": [ "$aws/things/MyThingName/shadow/update/delta", "$aws/things/MyThingName/shadow/name/myNamedShadow/update/delta" ] } } } }
YAML
accessControl: aws.greengrass.ipc.pubsub: "com.example.MyShadowReactiveComponent:pubsub:1": policyDescription: Allows access to shadow pubsub topics operations: - 'aws.greengrass#SubscribeToTopic' resources: - $aws/things/MyThingName/shadow/update/delta - $aws/things/MyThingName/shadow/name/myNamedShadow/update/delta

GetThingShadow

获取指定事物的影子。

请求

该操作的请求具有以下参数:

thingName(Pyon:thing_name)

事物的名称。

类型:string

shadowName(Pyon:shadow_name)

影子的名称。要指定事物的经典阴影,请将此参数设置为空字符串 ("")。

警告

这些区域有:Amazon IoT Greengrass服务使用AWSManagedGreengrassV2Deployment命名为 shadow,用于管理针对单个核心设备的部署。这个命名的阴影是留待使用的Amazon IoT Greengrass服务。不要更新或删除这个命名的影子。

类型:string

响应

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

payload

响应状态文档为 blob。

Type:object它包含以下信息:

state

状态信息。

该对象包含以下信息。

desired

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

Type:map的键值对

reported

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

Type:map的键值对

delta

所需状态属性和报告的状态属性和值之间的差异。此属性仅在以下情况下存在desiredreported各州是不同的。

Type:map的键值对

metadata

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

类型:string

timestamp

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

类型:integer

clientToken(Pyon:clientToken)

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

类型:string

version

本地影子文档的版本。

类型:integer

错误

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

InvalidArgumentsError

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

ResourceNotFoundError

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

ServiceError

发生了内部服务错误,或者对 IPC 服务的请求数量超过了中指定的限制maxLocalRequestsPerSecondPerThingmaxTotalLocalRequestsRate影子管理器组件中的配置参数。

UnauthorizedError

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

示例

以下示例将说明如何在自定义组件代码中调用函数。

Java (IPC client V1)

例 示例:找个东西影子

注意

此示例使用 1IPCUtilsclass 要创建到Amazon IoT Greengrass核心 IPC 服务。有关更多信息,请参阅 Connect 到Amazon IoT Greengrass核心 IPC 服务

package com.aws.greengrass.docs.samples.ipc; import com.aws.greengrass.docs.samples.ipc.util.IPCUtils; import software.amazon.awssdk.aws.greengrass.GetThingShadowResponseHandler; import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient; import software.amazon.awssdk.aws.greengrass.model.GetThingShadowRequest; import software.amazon.awssdk.aws.greengrass.model.GetThingShadowResponse; import software.amazon.awssdk.aws.greengrass.model.ResourceNotFoundError; import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError; import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection; import java.nio.charset.StandardCharsets; import java.util.Optional; import java.util.concurrent.CompletableFuture; import java.util.concurrent.ExecutionException; import java.util.concurrent.TimeUnit; import java.util.concurrent.TimeoutException; public class GetThingShadow { public static final int TIMEOUT_SECONDS = 10; public static void main(String[] args) { // Use the current core device's name if thing name isn't set. String thingName = args[0].isEmpty() ? System.getenv("AWS_IOT_THING_NAME") : args[0]; String shadowName = args[1]; try (EventStreamRPCConnection eventStreamRPCConnection = IPCUtils.getEventStreamRpcConnection()) { GreengrassCoreIPCClient ipcClient = new GreengrassCoreIPCClient(eventStreamRPCConnection); GetThingShadowResponseHandler responseHandler = GetThingShadow.getThingShadow(ipcClient, thingName, shadowName); CompletableFuture<GetThingShadowResponse> futureResponse = responseHandler.getResponse(); try { GetThingShadowResponse response = futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS); String shadowPayload = new String(response.getPayload(), StandardCharsets.UTF_8); System.out.printf("Successfully got shadow %s/%s: %s%n", thingName, shadowName, shadowPayload); } catch (TimeoutException e) { System.err.printf("Timeout occurred while getting shadow: %s/%s%n", thingName, shadowName); } catch (ExecutionException e) { if (e.getCause() instanceof UnauthorizedError) { System.err.printf("Unauthorized error while getting shadow: %s/%s%n", thingName, shadowName); } else if (e.getCause() instanceof ResourceNotFoundError) { System.err.printf("Unable to find shadow to get: %s/%s%n", thingName, shadowName); } else { throw e; } } } catch (InterruptedException e) { System.out.println("IPC interrupted."); } catch (ExecutionException e) { System.err.println("Exception occurred when using IPC."); e.printStackTrace(); System.exit(1); } } public static GetThingShadowResponseHandler getThingShadow(GreengrassCoreIPCClient greengrassCoreIPCClient, String thingName, String shadowName) { GetThingShadowRequest getThingShadowRequest = new GetThingShadowRequest(); getThingShadowRequest.setThingName(thingName); getThingShadowRequest.setShadowName(shadowName); return greengrassCoreIPCClient.getThingShadow(getThingShadowRequest, Optional.empty()); } }
Python (IPC client V1)

例 示例:找个东西影子

import awsiot.greengrasscoreipc import awsiot.greengrasscoreipc.client as client from awsiot.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

为指定事物更新影子。

请求

该操作的请求具有以下参数:

thingName(Pyon:thing_name)

事物的名称。

类型:string

shadowName(Pyon:shadow_name)

影子的名称。要指定事物的经典阴影,请将此参数设置为空字符串 ("")。

警告

这些区域有:Amazon IoT Greengrass服务使用AWSManagedGreengrassV2Deployment命名为 shadow,用于管理针对单个核心设备的部署。这个命名的阴影是留待使用的Amazon IoT Greengrass服务。不要更新或删除这个命名的影子。

类型:string

payload

请求状态文档为 blob。

Type:object它包含以下信息:

state

要更新的状态信息。此 IPC 操作仅影响指定的字段。

该对象包含以下信息。通常,你会使用desiredPropert 或reported属性,但不能在同一个请求中同时使用。

desired

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

Type:map的键值对

reported

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

Type:map的键值对

clientToken(Pyon:client_token)

(可选)用于匹配请求和客户端令牌的相应响应的令牌。

类型:string

version

(可选)要更新的本地影子文档的版本。只有当指定的版本与其拥有的最新版本相匹配时,影子服务才会处理更新。

类型:integer

响应

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

payload

响应状态文档为 blob。

Type:object它包含以下信息:

state

状态信息。

该对象包含以下信息。

desired

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

Type:map的键值对

reported

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

Type:map的键值对

delta

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

Type:map的键值对

metadata

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

类型:string

timestamp

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

类型:integer

clientToken(Pyon:client_token)

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

类型:string

version

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

类型:integer

错误

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

ConflictError

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

InvalidArgumentsError

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

有效的payload具有以下属性:

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

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

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

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

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

ServiceError

发生了内部服务错误,或者对 IPC 服务的请求数量超过了中指定的限制maxLocalRequestsPerSecondPerThingmaxTotalLocalRequestsRate影子管理器组件中的配置参数。

UnauthorizedError

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

示例

以下示例将说明如何在自定义组件代码中调用函数。

Java (IPC client V1)

例 示例:更新事物影子

注意

此示例使用 1IPCUtilsclass 要创建到Amazon IoT Greengrass核心 IPC 服务。有关更多信息,请参阅 Connect 到Amazon IoT Greengrass核心 IPC 服务

package com.aws.greengrass.docs.samples.ipc; import com.aws.greengrass.docs.samples.ipc.util.IPCUtils; import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient; import software.amazon.awssdk.aws.greengrass.UpdateThingShadowResponseHandler; import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError; import software.amazon.awssdk.aws.greengrass.model.UpdateThingShadowRequest; import software.amazon.awssdk.aws.greengrass.model.UpdateThingShadowResponse; import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection; import java.nio.charset.StandardCharsets; import java.util.Optional; import java.util.concurrent.CompletableFuture; import java.util.concurrent.ExecutionException; import java.util.concurrent.TimeUnit; import java.util.concurrent.TimeoutException; public class UpdateThingShadow { public static final int TIMEOUT_SECONDS = 10; public static void main(String[] args) { // Use the current core device's name if thing name isn't set. String thingName = args[0].isEmpty() ? System.getenv("AWS_IOT_THING_NAME") : args[0]; String shadowName = args[1]; byte[] shadowPayload = args[2].getBytes(StandardCharsets.UTF_8); try (EventStreamRPCConnection eventStreamRPCConnection = IPCUtils.getEventStreamRpcConnection()) { GreengrassCoreIPCClient ipcClient = new GreengrassCoreIPCClient(eventStreamRPCConnection); UpdateThingShadowResponseHandler responseHandler = UpdateThingShadow.updateThingShadow(ipcClient, thingName, shadowName, shadowPayload); CompletableFuture<UpdateThingShadowResponse> futureResponse = responseHandler.getResponse(); try { futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS); System.out.printf("Successfully updated shadow: %s/%s%n", thingName, shadowName); } catch (TimeoutException e) { System.err.printf("Timeout occurred while updating shadow: %s/%s%n", thingName, shadowName); } catch (ExecutionException e) { if (e.getCause() instanceof UnauthorizedError) { System.err.printf("Unauthorized error while updating shadow: %s/%s%n", thingName, shadowName); } else { throw e; } } } catch (InterruptedException e) { System.out.println("IPC interrupted."); } catch (ExecutionException e) { System.err.println("Exception occurred when using IPC."); e.printStackTrace(); System.exit(1); } } public static UpdateThingShadowResponseHandler updateThingShadow(GreengrassCoreIPCClient greengrassCoreIPCClient, String thingName, String shadowName, byte[] shadowPayload) { UpdateThingShadowRequest updateThingShadowRequest = new UpdateThingShadowRequest(); updateThingShadowRequest.setThingName(thingName); updateThingShadowRequest.setShadowName(shadowName); updateThingShadowRequest.setPayload(shadowPayload); return greengrassCoreIPCClient.updateThingShadow(updateThingShadowRequest, Optional.empty()); } }
Python (IPC client V1)

例 示例:更新事物影子

import awsiot.greengrasscoreipc import awsiot.greengrasscoreipc.client as client from awsiot.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

删除指定事物的影子。

从 shadow Manager v2.0.4 开始,删除阴影会增加版本号。例如,当您删除阴影时MyThingShadow在版本 1 中,已删除影子的版本为 2。如果你随后用这个名字重新创建一个阴影MyThingShadow,那个阴影的版本是 3。

请求

该操作的请求具有以下参数:

thingName(Pyon:thing_name)

事物的名称。

类型:string

shadowName(Pyon:shadow_name)

影子的名称。要指定事物的经典阴影,请将此参数设置为空字符串 ("")。

警告

这些区域有:Amazon IoT Greengrass服务使用AWSManagedGreengrassV2Deployment命名为 shadow,用于管理针对单个核心设备的部署。这个命名的阴影是留待使用的Amazon IoT Greengrass服务。不要更新或删除这个命名的影子。

类型:string

响应

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

payload

一个空的响应状态文档。

错误

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

InvalidArgumentsError

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

ResourceNotFoundError

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

ServiceError

发生了内部服务错误,或者对 IPC 服务的请求数量超过了中指定的限制maxLocalRequestsPerSecondPerThingmaxTotalLocalRequestsRate影子管理器组件中的配置参数。

UnauthorizedError

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

示例

以下示例将说明如何在自定义组件代码中调用函数。

Java (IPC client V1)

例 示例:删除事物影子

注意

此示例使用 1IPCUtilsclass 要创建到Amazon IoT Greengrass核心 IPC 服务。有关更多信息,请参阅 Connect 到Amazon IoT Greengrass核心 IPC 服务

package com.aws.greengrass.docs.samples.ipc; import com.aws.greengrass.docs.samples.ipc.util.IPCUtils; import software.amazon.awssdk.aws.greengrass.DeleteThingShadowResponseHandler; import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient; import software.amazon.awssdk.aws.greengrass.model.DeleteThingShadowRequest; import software.amazon.awssdk.aws.greengrass.model.DeleteThingShadowResponse; import software.amazon.awssdk.aws.greengrass.model.ResourceNotFoundError; import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError; import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection; import java.util.Optional; import java.util.concurrent.CompletableFuture; import java.util.concurrent.ExecutionException; import java.util.concurrent.TimeUnit; import java.util.concurrent.TimeoutException; public class DeleteThingShadow { public static final int TIMEOUT_SECONDS = 10; public static void main(String[] args) { // Use the current core device's name if thing name isn't set. String thingName = args[0].isEmpty() ? System.getenv("AWS_IOT_THING_NAME") : args[0]; String shadowName = args[1]; try (EventStreamRPCConnection eventStreamRPCConnection = IPCUtils.getEventStreamRpcConnection()) { GreengrassCoreIPCClient ipcClient = new GreengrassCoreIPCClient(eventStreamRPCConnection); DeleteThingShadowResponseHandler responseHandler = DeleteThingShadow.deleteThingShadow(ipcClient, thingName, shadowName); CompletableFuture<DeleteThingShadowResponse> futureResponse = responseHandler.getResponse(); try { futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS); System.out.printf("Successfully deleted shadow: %s/%s%n", thingName, shadowName); } catch (TimeoutException e) { System.err.printf("Timeout occurred while deleting shadow: %s/%s%n", thingName, shadowName); } catch (ExecutionException e) { if (e.getCause() instanceof UnauthorizedError) { System.err.printf("Unauthorized error while deleting shadow: %s/%s%n", thingName, shadowName); } else if (e.getCause() instanceof ResourceNotFoundError) { System.err.printf("Unable to find shadow to delete: %s/%s%n", thingName, shadowName); } else { throw e; } } } catch (InterruptedException e) { System.out.println("IPC interrupted."); } catch (ExecutionException e) { System.err.println("Exception occurred when using IPC."); e.printStackTrace(); System.exit(1); } } public static DeleteThingShadowResponseHandler deleteThingShadow(GreengrassCoreIPCClient greengrassCoreIPCClient, String thingName, String shadowName) { DeleteThingShadowRequest deleteThingShadowRequest = new DeleteThingShadowRequest(); deleteThingShadowRequest.setThingName(thingName); deleteThingShadowRequest.setShadowName(shadowName); return greengrassCoreIPCClient.deleteThingShadow(deleteThingShadowRequest, Optional.empty()); } }
Python (IPC client V1)

例 示例:删除事物影子

import awsiot.greengrasscoreipc import awsiot.greengrasscoreipc.client as client from awsiot.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

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

请求

该操作的请求具有以下参数:

thingName(Pyon:thing_name)

事物的名称。

类型:string

pageSize(Pyon:page_size)

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

类型:integer

默认值:25

最大值:100

nextToken(Pyon:next_token)

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

类型:string

响应

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

results

影子名称列表。

类型:array

timestamp

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

类型:integer

nextToken(Pyon:next_token)

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

类型:string

注意

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

错误

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

InvalidArgumentsError

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

ResourceNotFoundError

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

ServiceError

发生了内部服务错误,或者对 IPC 服务的请求数量超过了中指定的限制maxLocalRequestsPerSecondPerThingmaxTotalLocalRequestsRate影子管理器组件中的配置参数。

UnauthorizedError

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

示例

以下示例将说明如何在自定义组件代码中调用函数。

Java (IPC client V1)

例 示例:列出事物的命名阴影

注意

此示例使用 1IPCUtilsclass 要创建到Amazon IoT Greengrass核心 IPC 服务。有关更多信息,请参阅 Connect 到Amazon IoT Greengrass核心 IPC 服务

package com.aws.greengrass.docs.samples.ipc; import com.aws.greengrass.docs.samples.ipc.util.IPCUtils; import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient; import software.amazon.awssdk.aws.greengrass.ListNamedShadowsForThingResponseHandler; import software.amazon.awssdk.aws.greengrass.model.ListNamedShadowsForThingRequest; import software.amazon.awssdk.aws.greengrass.model.ListNamedShadowsForThingResponse; import software.amazon.awssdk.aws.greengrass.model.ResourceNotFoundError; import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError; import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection; import java.util.ArrayList; import java.util.List; import java.util.Optional; import java.util.concurrent.CompletableFuture; import java.util.concurrent.ExecutionException; import java.util.concurrent.TimeUnit; import java.util.concurrent.TimeoutException; public class ListNamedShadowsForThing { public static final int TIMEOUT_SECONDS = 10; public static void main(String[] args) { // Use the current core device's name if thing name isn't set. String thingName = args[0].isEmpty() ? System.getenv("AWS_IOT_THING_NAME") : args[0]; try (EventStreamRPCConnection eventStreamRPCConnection = IPCUtils.getEventStreamRpcConnection()) { GreengrassCoreIPCClient ipcClient = new GreengrassCoreIPCClient(eventStreamRPCConnection); List<String> namedShadows = new ArrayList<>(); String nextToken = null; try { // Send additional requests until there's no pagination token in the response. do { ListNamedShadowsForThingResponseHandler responseHandler = ListNamedShadowsForThing.listNamedShadowsForThing(ipcClient, thingName, nextToken, 25); CompletableFuture<ListNamedShadowsForThingResponse> futureResponse = responseHandler.getResponse(); ListNamedShadowsForThingResponse response = futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS); List<String> responseNamedShadows = response.getResults(); namedShadows.addAll(responseNamedShadows); nextToken = response.getNextToken(); } while (nextToken != null); System.out.printf("Successfully got named shadows for thing %s: %s%n", thingName, String.join(",", namedShadows)); } catch (TimeoutException e) { System.err.println("Timeout occurred while listing named shadows for thing: " + thingName); } catch (ExecutionException e) { if (e.getCause() instanceof UnauthorizedError) { System.err.println("Unauthorized error while listing named shadows for " + "thing: " + thingName); } else if (e.getCause() instanceof ResourceNotFoundError) { System.err.println("Unable to find thing to list named shadows: " + thingName); } else { throw e; } } } catch (InterruptedException e) { System.out.println("IPC interrupted."); } catch (ExecutionException e) { System.err.println("Exception occurred when using IPC."); e.printStackTrace(); System.exit(1); } } public static ListNamedShadowsForThingResponseHandler listNamedShadowsForThing(GreengrassCoreIPCClient greengrassCoreIPCClient, String thingName, String nextToken, int pageSize) { ListNamedShadowsForThingRequest listNamedShadowsForThingRequest = new ListNamedShadowsForThingRequest(); listNamedShadowsForThingRequest.setThingName(thingName); listNamedShadowsForThingRequest.setNextToken(nextToken); listNamedShadowsForThingRequest.setPageSize(pageSize); return greengrassCoreIPCClient.listNamedShadowsForThing(listNamedShadowsForThingRequest, Optional.empty()); } }
Python (IPC client V1)

例 示例:列出事物的命名阴影

import awsiot.greengrasscoreipc import awsiot.greengrasscoreipc.client as client from awsiot.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