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.greengrass#UpdateThingShadow
|
允许组件更新事物的阴影。
|
下列情况之一:
|
aws.greengrass#DeleteThingShadow
|
允许组件删除事物的阴影。
|
下列情况之一:
|
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 取决于影子的类型:
使用* 以允许访问所有主题。此主题字符串不支持 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
-
所需状态和报告状态属性和值之间的差异。此属性仅在desired
和reported
状态是不同的。
类型:map
键值对的
metadata
-
每个属性的时间戳desired
和reported
部分,以便确定状态的更新时间。
类型:string
timestamp
-
生成响应时的 Epow 日期和时间。
类型:integer
clientToken
-
用于匹配请求和相应的响应的令牌
类型:string
version
-
本地影子文档的版本。
类型:integer
Errors
此操作可能会返回以下错误。
InvalidArgumentsError
-
本地影子服务无法验证请求参数。如果请求包含格式错误的 JSON 或不支持的字符,则会发生这种情况。
ResourceNotFoundError
-
找不到请求的本地影子文档。
ServiceError
-
发生内部服务错误,或者对 IPC 服务的请求数超过maxLocalRequestsPerSecondPerThing
和maxTotalLocalRequestsRate
配置参数。
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 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
更新指定事物的影子。
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
-
生成响应时的 Epow 日期和时间。
类型: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
以下示例演示如何在自定义组件代码中调用此操作。
- 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 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
删除指定事物的影子。
Request
该操作的请求包含以下参数:
thingName
-
要删除影子的事物的名称。
类型:string
shadowName
-
(可选)要删除的影子的名称。仅命名的影子需要使用该参数。
类型:string
Response
该操作的响应包含以下信息:
Errors
此操作可能会返回以下错误。
InvalidArgumentsError
-
本地影子服务无法验证请求参数。如果请求包含格式错误的 JSON 或不支持的字符,则会发生这种情况。
ResourceNotFoundError
-
找不到请求的本地影子文档。
ServiceError
-
发生内部服务错误,或者对 IPC 服务的请求数超过maxLocalRequestsPerSecondPerThing
和maxTotalLocalRequestsRate
配置参数。
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 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
列出指定事物的命名影子。
Request
此操作的请求包含以下参数:
thingName
-
要列出命名的影子的事物的名称。
类型:string
pageSize
-
(可选)在每个调用中返回的影子名称的数量。
类型:integer
默认值:25
最大值:100
nextToken
-
(可选)用于检索下一组结果的令牌。该值在分页结果中返回,并在返回下一页的调用中使用。
类型:string
Response
该操作的响应包含以下信息:
results
-
影子名称列表。
类型:array
timestamp
-
(可选)生成响应时的日期和时间。
类型:integer
nextToken
-
(可选)在用于检索序列中的下一页的分页请求中使用的令牌值。当没有其他要返回的影子名称时,该令牌不存在。
类型:string
如果请求的页面大小与响应中的影子名称数量完全匹配,则此标记存在;但是,使用时,它会返回一个空列表。
Errors
此操作可能会返回以下错误。
InvalidArgumentsError
-
本地影子服务无法验证请求参数。如果请求包含格式错误的 JSON 或不支持的字符,则会发生这种情况。
ResourceNotFoundError
-
找不到请求的本地影子文档。
ServiceError
-
发生内部服务错误,或者对 IPC 服务的请求数超过maxLocalRequestsPerSecondPerThing
和maxTotalLocalRequestsRate
配置参数。
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 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