本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
使用影子 IPC 服務與裝置上的本機影子互動。您選擇與之互動的裝置可以是您的核心裝置或連線的用戶端裝置。
若要使用這些 IPC 操作,請在您的自訂元件中包含影子管理員元件做為相依性。然後,您可以在自訂元件中使用 IPC 操作,透過影子管理員與裝置上的本機影子互動。若要讓自訂元件對本機影子狀態的變更做出反應,您也可以使用發佈/訂閱 IPC 服務來訂閱影子事件。如需使用發佈/訂閱服務的詳細資訊,請參閱 發佈/訂閱本機訊息。
注意
若要讓核心裝置與用戶端裝置影子互動,您還必須設定和部署 MQTT 橋接元件。如需詳細資訊,請參閱啟用影子管理員以與用戶端裝置通訊。
最低 SDK 版本
下表列出 AWS IoT Device SDK 您必須用來與本機影子互動的 最低版本。
SDK | 最低版本 |
---|---|
1.4.0 版 |
|
v1.6.0 |
|
1.17.0 版 |
|
v1.12.0 |
授權
若要在自訂元件中使用影子 IPC 服務,您必須定義授權政策,以允許元件與影子互動。如需定義授權政策的資訊,請參閱 授權元件來執行 IPC 操作。
陰影互動的授權政策具有下列屬性。
IPC 服務識別符: aws.greengrass.ShadowManager
作業 | 描述 | 資源 |
---|---|---|
|
允許元件擷取物件的陰影。 |
下列其中一個字串:
|
|
允許元件更新物件的陰影。 |
下列其中一個字串:
|
|
允許元件刪除物件的陰影。 |
下列其中一個字串:
|
|
允許元件擷取物件的具名影子清單。 |
物件名稱字串,允許存取物件以列出其影子。 使用 |
IPC 服務識別符: aws.greengrass.ipc.pubsub
作業 | 描述 | 資源 |
---|---|---|
|
允許元件訂閱您指定主題的訊息。 |
下列其中一個主題字串:
主題字首的值
使用 在 Greengrass nucleus 2.6.0 版及更新版本中,您可以訂閱包含 MQTT 主題萬用字元 ( |
本機影子授權政策中的配方變數
如果您使用 Greengrass 核的 v2.6.0 或更新版本,並將 Greengrass 核的 interpolateComponentConfiguration 組態選項設定為 true
,您可以在授權政策中使用{iot:thingName}
配方變數。此功能可讓您為一組核心裝置設定單一授權政策,其中每個核心裝置只能存取自己的影子。例如,您可以允許元件存取下列資源以進行陰影 IPC 操作。
$aws/things/{iot:thingName}/shadow/
授權政策範例
您可以參考下列授權政策範例,協助您設定元件的授權政策。
範例:允許一組核心裝置與本機影子互動
重要
此範例使用適用於 Greengrass 核元件 v2.6.0 和更新版本的功能。Greengrass nucleus 2.6.0 版在元件組態中新增了對大多數配方變數的支援{iot:thingName}
,例如 。若要啟用此功能,請將 Greengrass nucleus 的 interpolateComponentConfiguration 組態選項設定為 true
。如需適用於所有 Greengrass 核版本的範例,請參閱單一核心裝置的範例授權政策。
下列範例授權政策允許 元件與傳統裝置影子和執行元件myNamedShadow
之核心裝置的具名影子com.example.MyShadowInteractionComponent
互動。此政策也允許此元件接收有關這些影子之本機主題的訊息。
{
"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 nucleus 2.6.0 版或更新版本、影子管理員 2.2.0 版或更新版本,以及 MQTT 橋接器 2.2.0 版或更新版本。您必須設定 MQTT 橋接器,讓影子管理員能夠與用戶端裝置通訊。
下列範例授權政策允許 元件與名稱開頭為 的用戶端裝置的所有裝置影子com.example.MyShadowInteractionComponent
互動MyClientDevice
。
注意
若要讓核心裝置與用戶端裝置影子互動,您還必須設定和部署 MQTT 橋接元件。如需詳細資訊,請參閱啟用影子管理員以與用戶端裝置通訊。
{
"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*"
]
}
}
}
}
範例:允許單一核心裝置與本機影子互動
下列範例授權政策允許 元件與傳統裝置影子和裝置 myNamedShadow
的具名影子com.example.MyShadowInteractionComponent
互動MyThingName
。此政策也允許此元件接收有關這些影子之本機主題的訊息。
{
"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"
]
}
}
}
}
範例:允許一組核心裝置對本機陰影狀態變更做出反應
重要
此範例使用適用於 Greengrass 核元件 v2.6.0 和更新版本的功能。Greengrass nucleus 2.6.0 版在元件組態中新增了對大多數配方變數的支援{iot:thingName}
,例如 。若要啟用此功能,請將 Greengrass nucleus 的 interpolateComponentConfiguration 組態選項設定為 true
。如需適用於所有 Greengrass 核版本的範例,請參閱單一核心裝置的範例授權政策。
下列範例存取控制政策允許自訂com.example.MyShadowReactiveComponent
接收傳統裝置影子/update/delta
主題的訊息,以及執行元件myNamedShadow
之每個核心裝置上的具名影子。
{
"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
。
{
"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
(Python:thing_name
)-
物件名稱。
類型:
string
shadowName
(Python:shadow_name
)-
影子的名稱。若要指定物件的傳統陰影,請將此參數設定為空字串 (
""
)。警告
AWS IoT Greengrass 服務使用
AWSManagedGreengrassV2Deployment
具名影子來管理以個別核心裝置為目標的部署。此具名影子會保留供 AWS IoT Greengrass 服務使用。請勿更新或刪除此具名影子。類型:
string
回應
此操作的回應包含下列資訊:
payload
-
回應狀態文件做為 Blob。
類型:
object
包含下列資訊:state
-
狀態資訊。
此物件包含下列資訊。
desired
-
在裝置中請求更新的狀態屬性和值。
類型:鍵值對
map
的 reported
-
裝置報告的狀態屬性和值。
類型:鍵值對
map
的 delta
-
所需和報告的狀態屬性和值之間的差異。此屬性只有在
desired
和reported
狀態不同時才存在。類型:鍵值對
map
的
metadata
-
desired
和reported
區段中每個屬性的時間戳記,以便您可以判斷狀態的更新時間。類型:
string
timestamp
-
產生回應的 epoch 日期和時間。
類型:
integer
clientToken
(Python:clientToken
)-
用於比對請求和對應回應的字符
類型:
string
version
-
本機影子文件的版本。
類型:
integer
錯誤
此操作可能會傳回下列錯誤。
InvalidArgumentsError
-
本機影子服務無法驗證請求參數。如果請求包含格式不正確的 JSON 或不支援的字元,就可能發生這種情況。
ResourceNotFoundError
-
找不到請求的本機影子文件。
ServiceError
-
發生內部服務錯誤,或對 IPC 服務的請求數量超過影子管理員元件中
maxLocalRequestsPerSecondPerThing
和maxTotalLocalRequestsRate
組態參數中指定的限制。 -
元件的授權政策不包含此操作所需的許可。
範例
下列範例示範如何在自訂元件程式碼中呼叫此操作。
範例:取得物件陰影
注意
此範例使用 IPCUtils
類別來建立與 AWS IoT Greengrass Core IPC 服務的連線。如需詳細資訊,請參閱連線至 AWS IoT Greengrass Core 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());
}
}
UpdateThingShadow
更新指定物件的影子。如果影子不存在,則會建立一個影子。
請求
此操作的請求具有下列參數:
thingName
(Python:thing_name
)-
物件名稱。
類型:
string
shadowName
(Python:shadow_name
)-
影子的名稱。若要指定物件的傳統陰影,請將此參數設定為空字串 (
""
)。警告
AWS IoT Greengrass 服務使用
AWSManagedGreengrassV2Deployment
具名影子來管理以個別核心裝置為目標的部署。此具名影子會保留供 AWS IoT Greengrass 服務使用。請勿更新或刪除此具名影子。類型:
string
payload
-
請求狀態文件做為 Blob。
類型:
object
包含下列資訊:state
-
要更新的狀態資訊。此 IPC 操作只會影響指定的欄位。
此物件包含下列資訊。一般而言,您會使用
desired
屬性或reported
屬性,但不會同時用於相同的請求。desired
-
在裝置中請求更新的狀態屬性和值。
類型:鍵值對
map
的 reported
-
裝置報告的狀態屬性和值。
類型:鍵值對
map
的
clientToken
(Python:client_token
)-
(選用) 用於比對請求和用戶端字符對應回應的字符。
類型:
string
version
-
(選用) 要更新的本機影子文件版本。只有當指定的版本符合其擁有的最新版本時,陰影服務才會處理更新。
類型:
integer
回應
此操作的回應具有下列資訊:
payload
-
回應狀態文件做為 Blob。
類型:
object
包含下列資訊:state
-
狀態資訊。
此物件包含下列資訊。
desired
-
在裝置中請求更新的狀態屬性和值。
類型:鍵值對
map
的 reported
-
裝置報告的狀態屬性和值。
類型:鍵值對
map
的 delta
-
裝置報告的狀態屬性和值。
類型:鍵值對
map
的
metadata
-
desired
和reported
區段中每個屬性的時間戳記,以便您可以判斷狀態的更新時間。類型:
string
timestamp
-
產生回應的 epoch 日期和時間。
類型:
integer
clientToken
(Python:client_token
)-
用於比對請求和對應回應的字符。
類型:
string
version
-
更新完成後的本機影子文件版本。
類型:
integer
錯誤
此操作可能會傳回下列錯誤。
ConflictError
-
本機影子服務在更新操作期間遇到版本衝突。當請求承載中的版本與最新可用本機影子文件中的版本不相符時,就會發生這種情況。
InvalidArgumentsError
-
本機影子服務無法驗證請求參數。如果請求包含格式不正確的 JSON 或不支援的字元,就可能發生這種情況。
有效的
payload
具有下列屬性:-
state
節點存在,且 是包含desired
或reported
狀態資訊的物件。 -
desired
和reported
節點是物件或 null。這些物件中至少有一個必須包含有效的狀態資訊。 -
desired
和reported
物件的深度不能超過八個節點。 -
clientToken
值的長度不能超過 64 個字元。 -
version
值必須為1
或更高。
-
ServiceError
-
發生內部服務錯誤,或對 IPC 服務的請求數量超過影子管理員元件中
maxLocalRequestsPerSecondPerThing
和maxTotalLocalRequestsRate
組態參數中指定的限制。 -
元件的授權政策不包含此操作所需的許可。
範例
下列範例示範如何在自訂元件程式碼中呼叫此操作。
範例:更新物件影子
注意
此範例使用 IPCUtils
類別來建立與 AWS IoT Greengrass Core IPC 服務的連線。如需詳細資訊,請參閱連線至 AWS IoT Greengrass Core 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());
}
}
DeleteThingShadow
刪除特定物件的影子。
從影子管理員 2.0.4 版開始,刪除影子會增加版本編號。例如,當您刪除第 1 MyThingShadow
版的影子時,已刪除影子的版本為 2。如果您接著重新建立名稱為 的影子MyThingShadow
,則該影子的版本為 3。
請求
此操作的請求具有下列參數:
thingName
(Python:thing_name
)-
物件名稱。
類型:
string
shadowName
(Python:shadow_name
)-
影子的名稱。若要指定物件的傳統陰影,請將此參數設定為空字串 (
""
)。警告
AWS IoT Greengrass 服務使用
AWSManagedGreengrassV2Deployment
具名影子來管理以個別核心裝置為目標的部署。此具名影子會保留供 AWS IoT Greengrass 服務使用。請勿更新或刪除此具名影子。類型:
string
回應
此操作的回應具有下列資訊:
payload
-
空的回應狀態文件。
錯誤
此操作可能會傳回下列錯誤。
InvalidArgumentsError
-
本機影子服務無法驗證請求參數。如果請求包含格式不正確的 JSON 或不支援的字元,就可能發生這種情況。
ResourceNotFoundError
-
找不到請求的本機影子文件。
ServiceError
-
發生內部服務錯誤,或對 IPC 服務的請求數量超過影子管理員元件中
maxLocalRequestsPerSecondPerThing
和maxTotalLocalRequestsRate
組態參數中指定的限制。 -
元件的授權政策不包含此操作所需的許可。
範例
下列範例示範如何在自訂元件程式碼中呼叫此操作。
範例:刪除物件影子
注意
此範例使用 IPCUtils
類別來建立與 AWS IoT Greengrass Core IPC 服務的連線。如需詳細資訊,請參閱連線至 AWS IoT Greengrass Core 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());
}
}
ListNamedShadowsForThing
列出指定物件的命名影子。
請求
此操作的請求具有下列參數:
thingName
(Python:thing_name
)-
物件名稱。
類型:
string
pageSize
(Python:page_size
)-
(選用) 每次呼叫中要傳回的陰影名稱數量。
類型:
integer
預設:25
上限:100
nextToken
(Python:next_token
)-
(選用) 擷取下一組結果的字符。此值會在分頁結果上傳回,並在傳回下一頁的呼叫中使用。
類型:
string
回應
此操作的回應包含下列資訊:
results
-
陰影名稱清單。
類型:
array
timestamp
-
(選用) 產生回應的日期和時間。
類型:
integer
nextToken
(Python:next_token
)-
(選用) 在分頁請求中使用的字符值,用於擷取序列中的下一頁。當不再傳回陰影名稱時,此權杖不存在。
類型:
string
注意
如果請求的頁面大小完全符合回應中的陰影名稱數量,則此字符存在;但是,使用時,它會傳回空清單。
錯誤
此操作可能會傳回下列錯誤。
InvalidArgumentsError
-
本機影子服務無法驗證請求參數。如果請求包含格式不正確的 JSON 或不支援的字元,就可能發生這種情況。
ResourceNotFoundError
-
找不到請求的本機影子文件。
ServiceError
-
發生內部服務錯誤,或對 IPC 服務的請求數量超過陰影管理員元件中
maxLocalRequestsPerSecondPerThing
和maxTotalLocalRequestsRate
組態參數中指定的限制。 -
元件的授權政策不包含此操作所需的許可。
範例
下列範例示範如何在自訂元件程式碼中呼叫此操作。
範例:列出物件的命名影子
注意
此範例使用 IPCUtils
類別來建立與 AWS IoT Greengrass Core IPC 服務的連線。如需詳細資訊,請參閱連線至 AWS IoT Greengrass Core 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());
}
}