# 為您的 Sidewalk 終端裝置新增目的地
使用 AWS IoT 規則來處理資料和裝置訊息，並將其路由至其他服務。您還可定義規則來處理從裝置接收的二進位訊息，並將訊息轉換為其他格式，讓其他服務可輕鬆加以使用。目的地會將您的 Sidewalk 終端裝置與規則建立關聯，而此規則會處理裝置資料以傳送至其他 AWS 服務。
## 如何建立和使用目的地
1. 建立目的地的 AWS IoT 規則 和 IAM 角色。AWS IoT 規則指定將處理裝置資料並將其路由以供其他 AWS 服務 和您應用程式使用的規則。IAM 角色授予存取規則的權限。
1. 使用 `CreateDestination` API 操作，建立您 Sidewalk 裝置的目的地。指定目的地名稱、規則名稱、角色名稱和任何選用的參數。API 會傳回目的地的唯一識別碼，您可於將終端裝置新增至適用於 Amazon Sidewalk 的 AWS IoT Core 時加以指定。
下列展示如何建立目的地，及目的地的 AWS IoT 規則和 IAM 角色。
**Topics**
+ [如何建立和使用目的地](#iot-sidewalk-destination-how)
+ [建立您 Sidewalk 裝置的目的地](iot-sidewalk-destination-create.md)
+ [為您的目的地建立 IAM 角色和 IoT 規則](sidewalk-destination-rule-role.md)
# 建立您 Sidewalk 裝置的目的地
您可從使用[目的地中樞](https://console.aws.amazon.com/iot/home#/wireless/destinations)或使用 `CreateDestination`，將目的地新增至您的適用於 Amazon Sidewalk 的 AWS IoT Core 帳戶。建立目的地時，請指定：
+ 一個用於您 Sidewalk 終端裝置之目的地的唯一名稱。
**注意**
若您已使用目的地名稱新增裝置，則在建立目的地時必須使用該名稱。如需詳細資訊，請參閱[步驟 2：新增您的 Sidewalk 裝置](iot-sidewalk-add-device.md#iot-sidewalk-device-create)。
+ 將要處理裝置資料的 AWS IoT 規則名稱，及訊息將要發佈的主題。
+ 授予裝置資料存取規則權限的 IAM 角色。
下列章節說明如何建立您目的地的 AWS IoT 規則和 IAM 角色。
## 建立目的地 (主控台)
如要使用 AWS IoT 主控台建立目的地，請移至[目的地中樞](https://console.aws.amazon.com/iot/home#/wireless/destinations)，並選擇**新增目的地**。
![\[alt text not found\]](http://docs.aws.amazon.com/zh_tw/iot-wireless/latest/developerguide/images/iot-sidewalk-add-destination.PNG)
如要處理裝置的資料，請在建立目的地時指定下列欄位，然後選擇**新增目的地**。
+
**目的地詳細資訊**
為您的目的地輸入 **Destination name** (目的地名稱) 和選用描述。
+
**規則名稱**
AWS IoT 規則被設定為評估裝置傳送的訊息並處理裝置的資料。規則名稱會映射至目的地。目的地需要規則來處理接收到的訊息。您可以選擇透過叫用 AWS IoT 規則或發佈至 AWS IoT 訊息代理程式的方式來處理訊息。
+ 如果選擇 **Enter a rule name** (輸入規則名稱)，請輸入名稱然後選擇 **Copy** (複製)，來複製您在建立 AWS IoT 規則時將輸入的規則名稱。您可以選擇 **Create rule** (建立規則) 來立即建立規則，或導覽至 AWS IoT 主控台的[規則](https://console.aws.amazon.com/iot/home#/create/rule)中樞，並使用該名稱建立規則。
您也可以輸入規則，再使用 **Advanced** (進階) 設定來指定主題名稱。主題名稱會在規則叫用期間提供，而且可以使用規則中的 `topic` 運算式存取。如需有關 AWS IoT 規則的更多資訊，請參閱 [AWS IoT 規則](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html)。
+ 若您選擇**發佈至 AWS IoT 訊息代理程式**，請輸入主題名稱。然後您可以複製 MQTT 主題名稱，多位訂閱者可以訂閱此主題，以接收發佈至該主題的訊息。如需更多詳細資訊，請參閱 [MQTT 主題](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html)。
如需有關目的地之 AWS IoT 規則的詳細資訊，請參閱[建立規則來處理 LoRaWAN 裝置訊息](https://docs.aws.amazon.com/iot/latest/developerguide/connect-iot-lorawan-destination-rules.html)。
+
**角色名稱**
授予裝置資料許可，以存取在 **Rule name** (規則名稱) 中命名之規則的 IAM 角色。您可以在主控台中建立新的服務角色，或選取現有的服務角色。如果正在建立新的服務角色，您可以輸入角色名稱 (例如 **SidewalkDestinationRole**)，或為 AWS IoT Core for LoRaWAN 保留為空白以產生新的角色名稱。AWS IoT Core for LoRaWAN 會代表您自動建立具有適當許可的 IAM 角色。
## 建立目的地 (CLI)
如要建立一個目的地，請使用 [https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_CreateDestination.html](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_CreateDestination.html) API 操作或 [https://docs.aws.amazon.com/cli/latest/reference/create-destination.html](https://docs.aws.amazon.com/cli/latest/reference/create-destination.html) CLI 命令。例如，下列命令會建立一個 Sidewalk 終端裝置的目的地。
```
aws iotwireless create-destination --name SidewalkDestination \
--expression-type RuleName --expression SidewalkRule \
--role-arn arn:aws:iam::123456789012:role/SidewalkRole
```
執行此命令會傳回目的地詳細資訊，此包括 Amazon Resource Name (ARN) 和目的地名稱。
```
{
"Arn": "arn:aws:iotwireless:us-east-1:123456789012:Destination/SidewalkDestination",
"Name": "SidewalkDestination"
}
```
如需有關建立目的地的詳細資訊，請參閱[建立規則來處理 LoRaWAN 裝置訊息](https://docs.aws.amazon.com/iot/latest/developerguide/connect-iot-lorawan-destination-rules.html)。
# 為您的目的地建立 IAM 角色和 IoT 規則
AWS IoT 規則會將裝置訊息傳送至其他服務。AWS IoT 規則還可處理從 Sidewalk 終端裝置接收的二進位訊息，以供其他服務使用。適用於 Amazon Sidewalk 的 AWS IoT Core 目的地會將無線裝置與規則建立關聯，而此規則會處理裝置訊息資料以傳送至其他服務。一旦適用於 Amazon Sidewalk 的 AWS IoT Core 收到裝置資料，該規則就會對裝置資料採取行動。對於將其資料傳送至相同服務的所有裝置，您可建立可供所有裝置共用的目的地。您還需建立 IAM 角色，授與將資料傳送至規則的權限。
## 為您的目的地建立 IAM 角色
建立 IAM 角色，將傳送資料至 AWS IoT 規則的許可授予適用於 Amazon Sidewalk 的 AWS IoT Core。如要建立該角色，請使用 [https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateRole.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateRole.html) API 操作或 [https://docs.aws.amazon.com/cli/latest/reference/iam/create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role) CLI 命令。您可將該角色命名為 *`SidewalkRole`*。
```
aws iam create-role --role-name SidewalkRole \
--assume-role-policy-document '{"Version": "2012-10-17","Statement": [{ "Effect": "Allow", "Principal": {"Service": "lambda.amazonaws.com"}, "Action": "sts:AssumeRole"}]}'
```
您也可使用 JSON 檔案來定義角色的信任政策。
```
aws iam create-role --role-name SidewalkRole \
--assume-role-policy-document file://trust-policy.json
```
下列顯示 JSON 檔案的內容。
**trust-policy.json 的內容**
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
## 為您的目的地建立規則
請使用 AWS IoT Core API 操作 [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRule.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRule.html)，或 AWS CLI 命令 [https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html) 來建立一個規則。您的目的地將使用主題規則，將從 Sidewalk 終端裝置接收的資料路由至其他 AWS 服務。例如，您可建立一個將訊息傳送至 Lambda 函數的規則動作。您可以定義 Lambda 函數，使其從您的裝置接收應用程式資料，並使用 base64 解碼承載資料，則其他應用程式可以使用該函數。
下列步驟顯示如何建立 Lambda 函數，接著建立將訊息傳送至此函數的主題規則。
1.
**建立執行角色和原則**
建立一個 IAM 角色，授予您函數存取 AWS 資源的權限。您也可使用 JSON 檔案來定義角色的信任政策。
```
aws iam create-role --role-name lambda-ex \
--assume-role-policy-document file://lambda-trust-policy.json
```
下列顯示 JSON 檔案的內容。
**lambda-trust-policy.json 的內容**
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
1.
**建立並測試 Lambda 函數**
執行下列步驟來建立 base64 解碼承載資料的 AWS Lambda 函數。
1. 撰寫用於解碼負載資料的程式碼。例如，您可使用下列 Python 程式碼範例。指定指令碼的名稱，例如 *`base64_decode.py`*。
**base64\$1decode.py 的內容**
```
// -----------------------------------------------------------
// ----- Python script to decode incoming binary payload -----
// -----------------------------------------------------------
import json
import base64
def lambda_handler(event, context):
message = json.dumps(event)
print (message)
payload_data = base64.b64decode(event["PayloadData"])
print(payload_data)
print(int(payload_data,16))
```
1. 將部署套件建立為一個包含 Python 檔案的 zip 檔案，並將其命名為 `base64_decode.zip`。使用 `CreateFunction` API 或 `create-function` CLI 命令，為範例程式碼 *`base64_decode.py`* 建立 Lambda 函數。
1.
```
aws lambda create-function --function-name my-function \
--zip-file fileb://base64_decode.zip --handler index.handler \
--runtime python3.9 --role arn:aws:iam::123456789012:role/lambda-ex
```
您應該會看到下列輸出。建立主題規則時，您將會使用輸出 `FunctionArn` 中的 Amazon Resource Name (ARN) 值。
```
{
"FunctionName": "my-function",
"FunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:my-function",
"Runtime": "python3.9",
"Role": "arn:aws:iam::123456789012:role/lambda-ex",
"Handler": "index.handler",
"CodeSha256": "FpFMvUhayLkOoVBpNuNiIVML/tuGv2iJQ7t0yWVTU8c=",
"Version": "$LATEST",
"TracingConfig": {
"Mode": "PassThrough"
},
"RevisionId": "88ebe1e1-bfdf-4dc3-84de-3017268fa1ff",
...
}
```
1. 如要從命令列取得某次調用的日誌，請使用具有 `invoke` 命令的 `--log-type` 選項。該回應包括 LogResult 欄位，其內含該次調用的 base64 編碼日誌 (最大達 4 KB)。
```
aws lambda invoke --function-name my-function out --log-type Tail
```
您應該會收到 `StatusCode` 為 200 的回應。如需有關從 AWS CLI 建立並使用 Lambda 函數的詳細資訊，請參閱 [Lambda 與 AWS CLI 搭配使用](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-awscli.html)。
1. 建立主題規則
使用 `CreateTopicRule` API 或 `create-topic-rule` CLI 命令，建立將訊息傳送至此 Lambda 函數的主題規則。您還可新增一個重新發佈至 AWS IoT 主題的第二個規則動作。將此主題規則命名為 `Sidewalkrule`。
```
aws iot create-topic-rule --rule-name Sidewalkrule \
--topic-rule-payload file://myrule.json
```
您可使用 `myrule.json` 檔案，來指定有關規則的更多詳細資訊。例如，下列 JSON 檔案顯示如何重新發佈至 AWS IoT 主題，及如何將訊息傳送至 Lambda 函數。
```
{
"sql": "SELECT * ",
"actions": [
{
// You obtained this functionArn when creating the Lambda function using the
// create-function command.
"lambda": {
"functionArn": "arn:aws:lambda:us-east-1:123456789012:function:my-function"
}
},
{
// This topic can be used to observe messages exchanged between the device and
// AWS IoT Core for Amazon Sidewalk after the device is connected.
"republish": {
"roleArn": "arn:aws:iam::123456789012:role/service-role/SidewalkRepublishRole",
"topic": "project/sensor/observed"
}
}
],
}
```