# Sidewalk 資源的事件通知
<a name="iot-sidewalk-events"></a>

您可以使用 AWS 管理主控台 或 AWS IoT Wireless API 操作，通知自己有關 Sidewalk 裝置和合作夥伴帳戶的事件。如需事件通知以及如何啟用事件通知的相關資訊，請參閱 [AWS IoT Wireless 事件通知](iot-wireless-events.md) 和 [為無線資源啟用事件](iot-wireless-control-events.md)。

## Sideside 資源的事件類型
<a name="iot-sidewalk-event-types"></a>

您可以為 Sidewalk 資源啟用的事件包括：
+ 裝置事件：通知您 Sidewalk 裝置狀態發生變更，例如裝置已註冊且可供使用。
+ 接近事件：在 AWS IoT Wireless 接收來自 Amazon Sidewalk 的通知，指出發現或遺失信標時通知您的事件。

以下部分包含有關 Sidewalk 資源事件的更多資訊：

**Topics**
+ [Sideside 資源的事件類型](#iot-sidewalk-event-types)
+ [裝置註冊狀態事件](iot-sidewalk-device-events.md)
+ [接近事件](iot-sidewalk-proximity-events.md)

# 裝置註冊狀態事件
<a name="iot-sidewalk-device-events"></a>

裝置註冊狀態事件會在裝置註冊狀態發生變更時發佈事件通知，例如已佈建或註冊 Sidewalk 裝置時。這些事件會提供關於裝置從佈建到註冊時所經歷的不同狀態資訊。

## 裝置註冊狀態事件如何運作
<a name="iot-sidewalk-device-events-work"></a>

在使用 Amazon Sidewalk 和 AWS IoT Wireless 加入 Sidewalk 裝置時，AWS IoT Wireless 會執行 `create` 操作，並將 Sidewalk 裝置新增至 AWS 帳戶。然後裝置會進入已佈建狀態，而 `eventType` 會變成 `provisioned`。如需加入裝置的相關資訊，請參閱 [適用於 AWS IoT Core 的 Amazon Sidewalk 入門](sidewalk-getting-started.md)。

裝置已完成 `provisioned` 之後，Amazon Sidewalk 會執行 `register` 操作，透過 AWS IoT Wireless 註冊 Sidewalk 裝置。註冊程序會啟動，其中加密和工作階段金鑰設定為 AWS IoT。註冊裝置後，`eventType` 會變成 `registered`，裝置即可供使用。

裝置 `registered` 後，Sidewalk 可以傳送請求以 `deregister` 您的裝置。AWS IoT Wireless 會完成該請求，並將裝置狀態改回 `provisioned`。如需裝置狀態的詳細資訊，請參閱 [DeviceState](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_SidewalkDeviceMetadata.html#iotwireless-Type-SidewalkDeviceMetadata-DeviceState)。

## 啟用裝置註冊狀態事件通知
<a name="iot-sidewalk-device-events-enable"></a>

在裝置註冊狀態預留主題的訂閱者可以接收訊息之前，您必須先從 AWS 管理主控台 或透過使用 API 或 CLI 啟用事件通知。您可以為 AWS 帳戶 中的所有 Sidewalk 資源或選定資源啟用這些事件。如需如何啟用這些事件的詳細資訊，請參閱 [為無線資源啟用事件](iot-wireless-control-events.md)。

## 裝置註冊狀態事件的 MQTT 主題格式
<a name="iot-sidewalk-device-events-mqtt"></a>

若要通知裝置註冊狀態事件，您可以訂閱以美元 (\$1) 符號開頭的 MQTT 預留主題。如需詳細資訊，請參閱《AWS IoT 開發人員指南》**中的 [MQTT 主題](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html)。

Sidewalk 裝置註冊狀態事件的預留 MQTT 主題使用以下格式：
+ 對於資源層級主題：

  `$aws/iotwireless/events/{eventName}/{eventType}/sidewalk/wireless_devices`
+ 對於識別符主題：

  `$aws/iotwireless/events/{eventName}/{eventType}/sidewalk/{resourceType}/{resourceID}/{id}`

其中：

**\$1eventName\$1**  
\$1eventName\$1 必須是 `device_registation_state`。

**\$1eventType\$1**  
\$1eventType\$1 可以是 `provisioned` 或 `registered`。

**\$1resourceType\$1**  
\$1resourceType\$1 可以是 `sidewalk_accounts` 或 `wireless_devices`。

**\$1resourceID\$1**  
\$1resourceID\$1 在 `sidewalk_accounts` 的 \$1resourceType\$1 為 `amazon_id`，在 `wireless_devices` 的 \$1resourceType\$1 為 `wireless_device_id`。

您也可以使用 `+` 萬用字元同時訂閱多個主題。此 `+` 萬用字元會比對包含該字元的層級中的任何字串。例如，如果您想要收到所有可能事件類型 (`provisioned` 和 `registered`) 的通知，以及註冊到特定 Amazon ID 的所有裝置的通知，您可以使用下列主題篩選條件：

`$aws/iotwireless/events/device_registration_state/+/sidewalk/sidewalk_accounts/amazon_id/+`

**注意**  
您不能使用萬用字元 `#` 訂閱預留主題。如需有關主題篩選器的詳細資訊，請參閱《AWS IoT 開發人員指南》**中的 [MQTT 主題篩選器](https://docs.aws.amazon.com/iot/latest/developerguide/topicfilters.html)。

## 裝置註冊狀態事件的訊息承載
<a name="iot-sidewalk-device-events-json"></a>

啟用裝置註冊狀態事件通知之後，事件通知會透過具 JSON 承載的 MQTT 發佈。這些事件包含下方的範例承載：

```
{    
    "eventId": "string", 
    "eventType": "provisioned|registered", 
    "WirelessDeviceId": "string",
    "timestamp": "timestamp",

    // Event-specific fields
    "operation": "create|deregister|register", 
    "Sidewalk": {
        "AmazonId": "string",
        "SidewalkManufacturingSn": "string"
    }
}
```

承載包含以下屬性：

**eventId**  
獨特的事件 ID (字串)。

**eventType**  
發生的事件類型。可以是 `provisioned` 或 `registered`。

**wirelessDeviceId**  
無線裝置的識別符。

**timestamp**  
事件發生時的 Unix 時間戳記。

**操作**  
觸發事件的操作。有效值為 `create`、`register` 和 `deregister`。

**sidewalk**  
要接收事件通知的 Sidewalk Amazon ID 或 `SidewalkManufacturingSn`。

# 接近事件
<a name="iot-sidewalk-proximity-events"></a>

接近事件會在 AWS IoT 從 Sidewalk 裝置接收信標時發佈事件通知。當 Sidewalk 裝置接近 Amazon Sidewalk 時，Amazon Sidewalk 會定期篩選從裝置傳送的信標，並由 AWS IoT Wireless 接收。AWS IoT Wireless 會在收到信標時通知您這些事件。

## 接近事件的運作方式
<a name="iot-sidewalk-proximity-events-work"></a>

接近事件會在 AWS IoT 接收到信標時發出通知，Sidewalk 裝置可以隨時發出信標。當裝置位於 Amazon Sidewalk 附近時，Sidewalk 會收到信標並會按固定的時間間隔將信標轉送到 AWS IoT Wireless。Amazon Sidewalk 已將此時間間隔設定為 10 分鐘。在 AWS IoT Wireless 接收來自 Sidewalk 的信標時，您會收到事件的通知。

當發現信標或信標遺失時，接近事件會通知您。您可以設定接收接近事件通知的間隔。

## 啟用接近事件的通知
<a name="iot-sidewalk-proximity-events-enable"></a>

在 Sidewalk 接近預留主題的訂閱者可以接收訊息之前，您必須先從 AWS 管理主控台 或透過使用 API 或 CLI 啟用事件通知。您可以為 AWS 帳戶 中的所有 Sidewalk 資源或選定資源啟用這些事件。如需如何啟用這些事件的詳細資訊，請參閱 [為無線資源啟用事件](iot-wireless-control-events.md)。

## 接近事件的 MQTT 主題格式
<a name="iot-sidewalk-proximity-events-mqtt"></a>

若要通知自己接近事件，您可以訂閱以美元 (\$1) 符號開頭的 MQTT 預留主題。如需詳細資訊，請參閱《AWS IoT 開發人員指南》**中的 [MQTT 主題](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html)。

Sidewalk 接近事件的預留 MQTT 主題使用以下格式：
+ 對於資源層級主題：

  `$aws/iotwireless/events/{eventName}/{eventType}/sidewalk/wireless_devices`
+ 對於識別符主題：

  `$aws/iotwireless/events/{eventName}/{eventType}/sidewalk/{resourceType}/{resourceID}/{id}`

其中：

**\$1eventName\$1**  
\$1eventName\$1 必須是 `proximity`。

**\$1eventType\$1**  
\$1eventType\$1 可以是 `beacon_discovered` 或 `beacon_lost`。

**\$1resourceType\$1**  
\$1resourceType\$1 可以是 `sidewalk_accounts` 或 `wireless_devices`。

**\$1resourceID\$1**  
\$1resourceID\$1 在 `sidewalk_accounts` 的 \$1resourceType\$1 為 `amazon_id`，在 `wireless_devices` 的 \$1resourceType\$1 為 `wireless_device_id`。

您也可以使用 `+` 萬用字元同時訂閱多個主題。此 `+` 萬用字元會比對包含該字元的層級中的任何字串。例如，如果您想要收到所有可能事件類型 (`beacon_discovered` 和 `beacon_lost`) 的通知，以及註冊到特定 Amazon ID 的所有裝置的通知，您可以使用下列主題篩選條件：

`$aws/iotwireless/events/proximity/+/sidewalk/sidewalk_accounts/amazon_id/+`

**注意**  
您不能使用萬用字元 `#` 訂閱預留主題。如需有關主題篩選器的詳細資訊，請參閱《AWS IoT 開發人員指南》**中的 [MQTT 主題篩選器](https://docs.aws.amazon.com/iot/latest/developerguide/topicfilters.html)。

## 接近事件的訊息承載
<a name="iot-sidewalk-proximity-events-json"></a>

啟用接近事件通知之後，事件訊息會透過具 JSON 承載的 MQTT 發佈。這些事件包含下方的範例承載：

```
{    
    "eventId": "string", 
    "eventType": "beacon_discovered|beacon_lost",
    "WirelessDeviceId": "string",
    "timestamp": "1234567890123",

    // Event-specific fields
    "Sidewalk": {
        "AmazonId": "string",
        "SidewalkManufacturingSn": "string"        
    }
}
```

承載包含以下屬性：

**eventId**  
唯一的事件 ID，這是一個字串。

**eventType**  
發生的事件類型。可以是 `beacon_discovered` 或 `beacon_lost`。

**WirelessDeviceId**  
無線裝置的識別符。

**timestamp**  
事件發生時的 Unix 時間戳記。

**sidewalk**  
要接收事件通知的 Sidewalk Amazon ID 或 `SidewalkManufacturingSn`。