本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 生命週期事件
<a name="life-cycle-events"></a>

AWS IoT 可以在 MQTT 主題上發佈生命週期事件。預設情況下，這些事件可用且無法停用。

**注意**  
生命週期的訊息可能不會按照順序傳送。您可能會收到重複的訊息。  
`thingName` 只有在用戶端使用[獨家物件](exclusive-thing.md)功能連線時，才會包含 。

**Topics**
+ [連線/中斷連線事件](#connect-disconnect)
+ [連線嘗試失敗事件](#connect-authfailure-event)
+ [訂閱/取消訂閱事件](#subscribe-unsubscribe-events)

## 連線/中斷連線事件
<a name="connect-disconnect"></a>

**注意**  
使用 AWS IoT Device Management 機群索引，您可以搜尋物件、執行彙總查詢，並根據物件連線/中斷連線事件建立動態群組。如需詳細資訊，請參閱[機群索引](https://docs.aws.amazon.com//iot/latest/developerguide/iot-indexing.html)。

AWS IoT 當用戶端連線或中斷連線時， 會將訊息發佈至下列 MQTT 主題：
+ `$aws/events/presence/connected/{{clientId}}`：用戶端已連接到訊息代理程式。
+ `$aws/events/presence/disconnected/{{clientId}}`：用戶端已與訊息代理程式中斷連線。

以下為發佈至 `$aws/events/presence/connected/{{clientId}}` 主題之連線/中斷連線訊息所包含的 JSON 元素。

**clientId**  
連線或中斷連線之用戶端的用戶端 ID。  
包含 \# 或 \+ 的用戶端 ID 不會收到生命週期事件。

**thingName**  
您的 IoT 物件名稱。只有在用戶端使用[獨家物件](exclusive-thing.md)功能進行連線時，`thingName`才會包含 。

**clientInitiatedDisconnect**  
如果用戶端已啟動中斷連線，則為 True。否則為 false。僅在中斷連線訊息中發現。

**disconnectReason**  
用戶端中斷連線的原因。僅在中斷連線訊息中發現。下表包含有效值，以及代理程式是否會在連線中斷時傳送 [Last Will and Testament (LWT) 訊息](mqtt.md#mqtt-lwt)。      
[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/iot/latest/developerguide/life-cycle-events.html)
1如果裝置在收到此錯誤之前有作用中的連線。  
2若要防止 Last Will and Testament (LWT) 訊息，請將 `preventWillMessage=true` 設定為覆寫 `DeleteConnection` API 的預設 LWT 傳送行為。

**eventType**  
事件的類型。有效值為 `connected` 或 `disconnected`。

**ipAddress**  
連線用戶端的 IP 地址。這可以是 IPv4 或 IPv6 格式。僅在連線訊息中發現。

**principalIdentifier**  
用於身分驗證的憑證。對於 TLS 交互身分驗證憑證，此為憑證 ID。對於其他連線，此為 IAM 憑證。

**sessionIdentifier**  
在工作階段生命週期內 AWS IoT 存在於 中的全域唯一識別符。

**timestamp**  
事件發生的約略時間。

**versionNumber**  
生命週期事件的版本號碼。這是每個用戶端 ID 連線的依序遞增長整數值。訂閱者戶可以使用版本號碼來推斷生命週期事件的順序。  
用戶端連線的連線和中斷連線訊息具有相同的版本號碼。  
版本號碼可能會略過值，並且每個事件並不保證會以 1 為值持續增加。  
如果用戶端約一小時未連線，則版本號碼將重設為 0。若為持久工作階段，當用戶端中斷連線時間超過為持久工作階段所設的存留時間 (TTL) 後，版本號碼將重設為 0。

連線訊息具有以下結構。

```
{
    "clientId": "186b5",
    "thingName": "exampleThing",
    "timestamp": 1573002230757,
    "eventType": "connected",
    "sessionIdentifier": "00000000-0000-0000-0000-000000000000",
    "principalIdentifier": "12345678901234567890123456789012",
    "ipAddress": "192.0.2.0",
    "versionNumber": 0
}
```

中斷連線訊息具有以下結構。

```
{
    "clientId": "186b5",
    "thingName": "exampleThing",
    "timestamp": 1573002340451,
    "eventType": "disconnected",
    "sessionIdentifier": "00000000-0000-0000-0000-000000000000",
    "principalIdentifier": "12345678901234567890123456789012",
    "clientInitiatedDisconnect": true,
    "disconnectReason": "CLIENT_INITIATED_DISCONNECT",
    "versionNumber": 0
}
```

### 處理用戶端中斷連線
<a name="reconnect"></a>

最佳實務是一律為生命週期事件實作等待狀態，包括 [Last Will and Testament (LWT) 訊息](mqtt.md)。收到中斷連線的訊息時，您的程式碼會等待一段時間並驗證裝置是否仍然離線，才採取動作。使用 [SQS 延遲佇列](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-delay-queues.html)是執行此操作的其中一種方法。當用戶端收到 LWT 或生命週期事件時，您可以將訊息加入佇列 (例如，5 秒鐘)。當該訊息變為可用並由 Lambda 或其他服務進行處理時，您可以在進行下一個動作前，先檢查該裝置是否仍處於離線狀態。

## 連線嘗試失敗事件
<a name="connect-authfailure-event"></a>

AWS IoT 當用戶端未獲授權進行連線或設定最後一個遺囑和見證，且用戶端未獲授權發佈至最後一個遺囑主題時， 會將訊息發佈至下列 MQTT 主題。

```
$aws/events/presence/connect_failed/{{clientId}}
```

以下是發佈至`$aws/events/presence/connect_failed/{{clientId}}`主題的連線授權訊息中包含的 JSON 元素清單。

**clientId**  
嘗試連線且無法連線之用戶端的用戶端 ID。  
包含 \# 或 \+ 的用戶端 ID 不會收到生命週期事件。

**thingName**  
您的 IoT 物件名稱。只有在用戶端使用[獨家物件](exclusive-thing.md)功能進行連線時，`thingName`才會包含 。

**timestamp**  
事件發生的約略時間。

**eventType**  
事件的類型。有效值為 `connect_failed`。

**connectFailureReason**  
連線失敗的原因。有效值為 `AUTHORIZATION_FAILED`。

**principalIdentifier**  
用於身分驗證的憑證。對於 TLS 交互身分驗證憑證，此為憑證 ID。對於其他連線，此為 IAM 憑證。

**sessionIdentifier**  
在工作階段生命週期內 AWS IoT 存在於 中的全域唯一識別符。

**ipAddress**  
連線用戶端的 IP 地址。這可以是 IPv4 或 IPv6 格式。僅在連線訊息中發現。

連線失敗訊息具有下列結構。

```
{
    "clientId": "186b5",
    "thingName": "exampleThing",
    "timestamp": 1460065214626,
    "eventType": "connect_failed",
    "connectFailureReason": "AUTHORIZATION_FAILED",
    "principalIdentifier": "12345678901234567890123456789012",
    "sessionIdentifier": "00000000-0000-0000-0000-000000000000",
    "ipAddress" : "192.0.2.0"
}
```

## 訂閱/取消訂閱事件
<a name="subscribe-unsubscribe-events"></a>

AWS IoT 當用戶端訂閱或取消訂閱 MQTT 主題時， 會將訊息發佈至下列 MQTT 主題：

```
$aws/events/subscriptions/subscribed/{{clientId}}
```

 或 

```
$aws/events/subscriptions/unsubscribed/{{clientId}}
```

其中 `clientId` 是連線至 AWS IoT 訊息代理程式的 MQTT 用戶端 ID。

發佈至此主題的訊息具有以下結構：

```
{
    "clientId": "186b5",
    "thingName": "exampleThing",
    "timestamp": 1460065214626,
    "eventType": "subscribed" | "unsubscribed",
    "sessionIdentifier": "00000000-0000-0000-0000-000000000000",
    "principalIdentifier": "12345678901234567890123456789012",
    "topics" : ["foo/bar","device/data","dog/cat"]
}
```

以下為發佈至 `$aws/events/subscriptions/subscribed/{{clientId}}` 和 `$aws/events/subscriptions/unsubscribed/{{clientId}}` 主題之訂閱與取消訂閱訊息所包含的 JSON 元素。

clientId  
訂閱或取消訂閱之用戶端的用戶端 ID。  
包含 \# 或 \+ 的用戶端 ID 不會收到生命週期事件。

thingName  
您的 IoT 物件名稱。只有在用戶端使用[獨家物件](exclusive-thing.md)功能進行連線時，`thingName`才會包含 。

eventType  
事件的類型。有效值為 `subscribed` 或 `unsubscribed`。

principalIdentifier  
用於身分驗證的憑證。對於 TLS 交互身分驗證憑證，此為憑證 ID。對於其他連線，此為 IAM 憑證。

sessionIdentifier  
在工作階段生命週期內 AWS IoT 存在於 中的全域唯一識別符。

timestamp  
事件發生的約略時間。

topics  
用戶端已訂閱的一系列 MQTT 主題。

**注意**  
生命週期的訊息可能不會按照順序傳送。您可能會收到重複的訊息。