文件 AWS 開發套件範例 GitHub 儲存庫中有更多可用的 [AWS SDK 範例](https://github.com/awsdocs/aws-doc-sdk-examples)。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# AWS IoT data 使用 AWS SDKs的基本範例
下列程式碼範例示範如何 AWS IoT data 搭配 AWS SDKs 使用 的基本概念。
**Contents**
+ [動作](iot-data-plane_code_examples_actions.md)
+ [`GetThingShadow`](iot-data-plane_example_iot-data-plane_GetThingShadow_section.md)
+ [`UpdateThingShadow`](iot-data-plane_example_iot-data-plane_UpdateThingShadow_section.md)
# AWS IoT data 使用 AWS SDKs的動作
下列程式碼範例示範如何使用 AWS SDKs執行個別 AWS IoT data 動作。每個範例均包含 GitHub 的連結，您可以在連結中找到設定和執行程式碼的相關說明。
下列範例僅包含最常使用的動作。如需完整清單，請參閱《[AWS IoT data API 參考](https://docs.aws.amazon.com/iot/latest/apireference/Welcome.html)》。
**Topics**
+ [`GetThingShadow`](iot-data-plane_example_iot-data-plane_GetThingShadow_section.md)
+ [`UpdateThingShadow`](iot-data-plane_example_iot-data-plane_UpdateThingShadow_section.md)
# `GetThingShadow` 搭配 AWS SDK 或 CLI 使用
下列程式碼範例示範如何使用 `GetThingShadow`。
------
#### [ .NET ]
**適用於 .NET 的 SDK (v4)**
GitHub 上提供更多範例。尋找完整範例，並了解如何在 [AWS 程式碼範例儲存庫](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv4/IoT#code-examples)中設定和執行。
```
///
/// Gets the Thing's shadow information.
///
/// The name of the Thing.
/// The shadow data as a string, or null if retrieval failed.
public async Task GetThingShadowAsync(string thingName)
{
try
{
var request = new GetThingShadowRequest
{
ThingName = thingName
};
var response = await _amazonIotData.GetThingShadowAsync(request);
using var reader = new StreamReader(response.Payload);
var shadowData = await reader.ReadToEndAsync();
_logger.LogInformation($"Retrieved shadow for Thing {thingName}");
return shadowData;
}
catch (Amazon.IotData.Model.ResourceNotFoundException ex)
{
_logger.LogError($"Cannot get Thing shadow - resource not found: {ex.Message}");
return null;
}
catch (Exception ex)
{
_logger.LogError($"Couldn't get Thing shadow. Here's why: {ex.Message}");
return null;
}
}
```
+ 如需 API 詳細資訊，請參閱《適用於 .NET 的 AWS SDK API 參考》**中的 [GetThingShadow](https://docs.aws.amazon.com/goto/DotNetSDKV4/iot-data-2015-05-28/GetThingShadow)。
------
#### [ C\$1\$1 ]
**適用於 C\$1\$1 的 SDK**
GitHub 上提供更多範例。尋找完整範例，並了解如何在 [AWS 程式碼範例儲存庫](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/iot#code-examples)中設定和執行。
```
//! Get the shadow of an AWS IoT thing.
/*!
\param thingName: The name for the thing.
\param documentResult: String to receive the state information, in JSON format.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool AwsDoc::IoT::getThingShadow(const Aws::String &thingName,
Aws::String &documentResult,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::IoTDataPlane::IoTDataPlaneClient iotClient(clientConfiguration);
Aws::IoTDataPlane::Model::GetThingShadowRequest request;
request.SetThingName(thingName);
auto outcome = iotClient.GetThingShadow(request);
if (outcome.IsSuccess()) {
std::stringstream ss;
ss << outcome.GetResult().GetPayload().rdbuf();
documentResult = ss.str();
}
else {
std::cerr << "Error getting thing shadow: " <<
outcome.GetError().GetMessage() << std::endl;
}
return outcome.IsSuccess();
}
```
+ 如需 API 詳細資訊，請參閱《適用於 C\$1\$1 的 AWS SDK API 參考》**中的 [GetThingShadow](https://docs.aws.amazon.com/goto/SdkForCpp/iot-data-2015-05-28/GetThingShadow)。
------
#### [ CLI ]
**AWS CLI**
**取得物件影子文件**
下列 `get-thing-shadow` 範例會取得指定 IoT 物件的物件影子文件。
```
aws iot-data get-thing-shadow \
--thing-name MyRPi \
output.txt
```
此命令不會在顯示器上產生輸出，但以下會顯示 `output.txt` 的內容：
```
{
"state":{
"reported":{
"moisture":"low"
}
},
"metadata":{
"reported":{
"moisture":{
"timestamp":1560269319
}
}
},
"version":1,"timestamp":1560269405
}
```
如需詳細資訊，請參閱《AWS IoT 開發人員指南》**中的[裝置影子服務資料流程](https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-data-flow.html)。
+ 如需 API 詳細資訊，請參閱《AWS CLI 命令參考》**中的 [GetThingShadow](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot-data/get-thing-shadow.html)。
------
#### [ Java ]
**SDK for Java 2.x**
GitHub 上提供更多範例。尋找完整範例，並了解如何在 [AWS 程式碼範例儲存庫](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/iot#code-examples)中設定和執行。
```
/**
* Retrieves the payload of a Thing's shadow asynchronously.
*
* @param thingName The name of the IoT Thing.
*
* This method initiates an asynchronous request to get the payload of a Thing's shadow.
* If the request is successful, it prints the shadow data.
* If an exception occurs, it prints the error message.
*/
public void getPayload(String thingName) {
GetThingShadowRequest getThingShadowRequest = GetThingShadowRequest.builder()
.thingName(thingName)
.build();
CompletableFuture future = getAsyncDataPlaneClient().getThingShadow(getThingShadowRequest);
future.whenComplete((getThingShadowResponse, ex) -> {
if (getThingShadowResponse != null) {
// Extracting payload from response.
SdkBytes payload = getThingShadowResponse.payload();
String payloadString = payload.asUtf8String();
System.out.println("Received Shadow Data: " + payloadString);
} else {
Throwable cause = ex != null ? ex.getCause() : null;
if (cause instanceof IotException) {
System.err.println(((IotException) cause).awsErrorDetails().errorMessage());
} else if (cause != null) {
System.err.println("Unexpected error: " + cause.getMessage());
} else {
System.err.println("Failed to get Thing Shadow payload.");
}
}
});
future.join();
}
```
+ 如需 API 詳細資訊，請參閱《AWS SDK for Java 2.x API 參考》**中的 [GetThingShadow](https://docs.aws.amazon.com/goto/SdkForJavaV2/iot-data-2015-05-28/GetThingShadow)。
------
#### [ Kotlin ]
**適用於 Kotlin 的 SDK**
GitHub 上提供更多範例。尋找完整範例，並了解如何在 [AWS 程式碼範例儲存庫](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/iot#code-examples)中設定和執行。
```
suspend fun getPayload(thingNameVal: String?) {
val getThingShadowRequest =
GetThingShadowRequest {
thingName = thingNameVal
}
IotDataPlaneClient.fromEnvironment { region = "us-east-1" }.use { iotPlaneClient ->
val getThingShadowResponse = iotPlaneClient.getThingShadow(getThingShadowRequest)
val payload = getThingShadowResponse.payload
val payloadString = payload?.let { java.lang.String(it, Charsets.UTF_8) }
println("Received shadow data: $payloadString")
}
}
```
+ 如需 API 詳細資訊，請參閱《適用於 Kotlin 的AWS SDK API 參考》**中的 [GetThingShadow](https://sdk.amazonaws.com/kotlin/api/latest/index.html)。
------
#### [ Python ]
**適用於 Python 的 SDK (Boto3)**
GitHub 上提供更多範例。尋找完整範例，並了解如何在 [AWS 程式碼範例儲存庫](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/iot#code-examples)中設定和執行。
```
class IoTWrapper:
"""Encapsulates AWS IoT actions."""
def __init__(self, iot_client, iot_data_client=None):
"""
:param iot_client: A Boto3 AWS IoT client.
:param iot_data_client: A Boto3 AWS IoT Data Plane client.
"""
self.iot_client = iot_client
self.iot_data_client = iot_data_client
@classmethod
def from_client(cls):
iot_client = boto3.client("iot")
iot_data_client = boto3.client("iot-data")
return cls(iot_client, iot_data_client)
def get_thing_shadow(self, thing_name):
"""
Gets the shadow for an AWS IoT thing.
:param thing_name: The name of the thing.
:return: The shadow state as a dictionary.
"""
import json
try:
response = self.iot_data_client.get_thing_shadow(thingName=thing_name)
shadow = json.loads(response["payload"].read())
logger.info("Retrieved shadow for thing %s.", thing_name)
except ClientError as err:
if err.response["Error"]["Code"] == "ResourceNotFoundException":
logger.error("Cannot get thing shadow. Resource not found.")
return None
logger.error(
"Couldn't get thing shadow. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return shadow
```
+ 如需 API 詳細資訊，請參閱《適用於 *AWS Python (Boto3) 的 SDK API 參考*》中的 [GetThingShadow](https://docs.aws.amazon.com/goto/boto3/iot-data-2015-05-28/GetThingShadow)。
------
# `UpdateThingShadow` 搭配 AWS SDK 或 CLI 使用
下列程式碼範例示範如何使用 `UpdateThingShadow`。
------
#### [ .NET ]
**適用於 .NET 的 SDK (v4)**
GitHub 上提供更多範例。尋找完整範例，並了解如何在 [AWS 程式碼範例儲存庫](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv4/IoT#code-examples)中設定和執行。
```
///
/// Updates the Thing's shadow with new state information.
///
/// The name of the Thing.
/// The shadow payload in JSON format.
/// True if successful, false otherwise.
public async Task UpdateThingShadowAsync(string thingName, string shadowPayload)
{
try
{
var request = new UpdateThingShadowRequest
{
ThingName = thingName,
Payload = new MemoryStream(System.Text.Encoding.UTF8.GetBytes(shadowPayload))
};
await _amazonIotData.UpdateThingShadowAsync(request);
_logger.LogInformation($"Updated shadow for Thing {thingName}");
return true;
}
catch (Amazon.IotData.Model.ResourceNotFoundException ex)
{
_logger.LogError($"Cannot update Thing shadow - resource not found: {ex.Message}");
return false;
}
catch (Exception ex)
{
_logger.LogError($"Couldn't update Thing shadow. Here's why: {ex.Message}");
return false;
}
}
```
+ 如需 API 詳細資訊，請參閱《適用於 .NET 的 AWS SDK API 參考》**中的 [UpdateThingShadow](https://docs.aws.amazon.com/goto/DotNetSDKV4/iot-data-2015-05-28/UpdateThingShadow)。
------
#### [ C\$1\$1 ]
**適用於 C\$1\$1 的 SDK**
GitHub 上提供更多範例。尋找完整範例，並了解如何在 [AWS 程式碼範例儲存庫](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/iot#code-examples)中設定和執行。
```
//! Update the shadow of an AWS IoT thing.
/*!
\param thingName: The name for the thing.
\param document: The state information, in JSON format.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool AwsDoc::IoT::updateThingShadow(const Aws::String &thingName,
const Aws::String &document,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::IoTDataPlane::IoTDataPlaneClient iotDataPlaneClient(clientConfiguration);
Aws::IoTDataPlane::Model::UpdateThingShadowRequest updateThingShadowRequest;
updateThingShadowRequest.SetThingName(thingName);
std::shared_ptr streamBuf = std::make_shared(
document);
updateThingShadowRequest.SetBody(streamBuf);
Aws::IoTDataPlane::Model::UpdateThingShadowOutcome outcome = iotDataPlaneClient.UpdateThingShadow(
updateThingShadowRequest);
if (outcome.IsSuccess()) {
std::cout << "Successfully updated thing shadow." << std::endl;
}
else {
std::cerr << "Error while updating thing shadow."
<< outcome.GetError().GetMessage() << std::endl;
}
return outcome.IsSuccess();
}
```
+ 如需 API 詳細資訊，請參閱《適用於 C\$1\$1 的 AWS SDK API 參考》**中的 [UpdateThingShadow](https://docs.aws.amazon.com/goto/SdkForCpp/iot-data-2015-05-28/UpdateThingShadow)。
------
#### [ CLI ]
**AWS CLI**
**更新物件影子**
下列 `update-thing-shadow` 範例會修改指定物件之裝置影子的目前狀態，並將其儲存至檔案 `output.txt`。
```
aws iot-data update-thing-shadow \
--thing-name MyRPi \
--payload "{"state":{"reported":{"moisture":"okay"}}}" \
"output.txt"
```
此命令不會在顯示器上產生輸出，但以下會顯示 `output.txt` 的內容：
```
{
"state": {
"reported": {
"moisture": "okay"
}
},
"metadata": {
"reported": {
"moisture": {
"timestamp": 1560270036
}
}
},
"version": 2,
"timestamp": 1560270036
}
```
如需詳細資訊，請參閱《AWS IoT 開發人員指南》**中的[裝置影子服務資料流程](https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-data-flow.html)。
+ 如需 API 詳細資訊，請參閱《AWS CLI 命令參考》**中的 [UpdateThingShadow](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot-data/update-thing-shadow.html)。
------
#### [ Java ]
**SDK for Java 2.x**
GitHub 上提供更多範例。尋找完整範例，並了解如何在 [AWS 程式碼範例儲存庫](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/iot#code-examples)中設定和執行。
```
/**
* Updates the shadow of an IoT Thing asynchronously.
*
* @param thingName The name of the IoT Thing.
*
* This method initiates an asynchronous request to update the shadow of an IoT Thing.
* If the request is successful, it prints a confirmation message.
* If an exception occurs, it prints the error message.
*/
public void updateShadowThing(String thingName) {
// Create Thing Shadow State Document.
String stateDocument = "{\"state\":{\"reported\":{\"temperature\":25, \"humidity\":50}}}";
SdkBytes data = SdkBytes.fromString(stateDocument, StandardCharsets.UTF_8);
UpdateThingShadowRequest updateThingShadowRequest = UpdateThingShadowRequest.builder()
.thingName(thingName)
.payload(data)
.build();
CompletableFuture future = getAsyncDataPlaneClient().updateThingShadow(updateThingShadowRequest);
future.whenComplete((updateResponse, ex) -> {
if (updateResponse != null) {
System.out.println("Thing Shadow updated successfully.");
} else {
Throwable cause = ex != null ? ex.getCause() : null;
if (cause instanceof IotException) {
System.err.println(((IotException) cause).awsErrorDetails().errorMessage());
} else if (cause != null) {
System.err.println("Unexpected error: " + cause.getMessage());
} else {
System.err.println("Failed to update Thing Shadow.");
}
}
});
future.join();
}
```
+ 如需 API 詳細資訊，請參閱《AWS SDK for Java 2.x API 參考》**中的 [UpdateThingShadow](https://docs.aws.amazon.com/goto/SdkForJavaV2/iot-data-2015-05-28/UpdateThingShadow)。
------
#### [ Kotlin ]
**適用於 Kotlin 的 SDK**
GitHub 上提供更多範例。尋找完整範例，並了解如何在 [AWS 程式碼範例儲存庫](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/iot#code-examples)中設定和執行。
```
suspend fun updateShawdowThing(thingNameVal: String?) {
// Create the thing shadow state document.
val stateDocument = "{\"state\":{\"reported\":{\"temperature\":25, \"humidity\":50}}}"
val byteStream: ByteStream = ByteStream.fromString(stateDocument)
val byteArray: ByteArray = byteStream.toByteArray()
val updateThingShadowRequest =
UpdateThingShadowRequest {
thingName = thingNameVal
payload = byteArray
}
IotDataPlaneClient.fromEnvironment { region = "us-east-1" }.use { iotPlaneClient ->
iotPlaneClient.updateThingShadow(updateThingShadowRequest)
println("The thing shadow was updated successfully.")
}
}
```
+ 如需 API 詳細資訊，請參閱《適用於 Kotlin 的AWS SDK API 參考》**中的 [UpdateThingShadow](https://sdk.amazonaws.com/kotlin/api/latest/index.html)。
------
#### [ Python ]
**適用於 Python 的 SDK (Boto3)**
GitHub 上提供更多範例。尋找完整範例，並了解如何在 [AWS 程式碼範例儲存庫](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/iot#code-examples)中設定和執行。
```
class IoTWrapper:
"""Encapsulates AWS IoT actions."""
def __init__(self, iot_client, iot_data_client=None):
"""
:param iot_client: A Boto3 AWS IoT client.
:param iot_data_client: A Boto3 AWS IoT Data Plane client.
"""
self.iot_client = iot_client
self.iot_data_client = iot_data_client
@classmethod
def from_client(cls):
iot_client = boto3.client("iot")
iot_data_client = boto3.client("iot-data")
return cls(iot_client, iot_data_client)
def update_thing_shadow(self, thing_name, shadow_state):
"""
Updates the shadow for an AWS IoT thing.
:param thing_name: The name of the thing.
:param shadow_state: The shadow state as a dictionary.
"""
import json
try:
self.iot_data_client.update_thing_shadow(
thingName=thing_name, payload=json.dumps(shadow_state)
)
logger.info("Updated shadow for thing %s.", thing_name)
except ClientError as err:
if err.response["Error"]["Code"] == "ResourceNotFoundException":
logger.error("Cannot update thing shadow. Resource not found.")
return
logger.error(
"Couldn't update thing shadow. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ 如需 API 詳細資訊，請參閱《適用於 *AWS Python (Boto3) 的 SDK API 參考*》中的 [UpdateThingShadow](https://docs.aws.amazon.com/goto/boto3/iot-data-2015-05-28/UpdateThingShadow)。
------