本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 Amazon Chime SDK 訊息
您可以使用 Amazon Chime SDK 開發人員指南的本節，協助建立在 Amazon Chime SDK 服務上執行的訊息應用程式。此 SDK 提供建立基本訊息應用程式所需的概念和實用資訊。
**Topics**
+ [
# 遷移至 Amazon Chime SDK 身分命名空間
](identity-namespace-migration.md)
+ [
# 遷移至 Amazon Chime SDK 訊息命名空間
](messaging-namespace-migration.md)
+ [
# 了解 Amazon Chime SDK 訊息的先決條件
](messaging-prerequisites.md)
+ [
# 了解 Amazon Chime SDK 傳訊概念
](messaging-concepts.md)
+ [
# 了解 Amazon Chime SDK 訊息架構
](messaging-architecture.md)
+ [
# 了解 Amazon Chime SDK 訊息類型
](msg-types.md)
+ [
# Amazon Chime SDK 訊息入門
](getting-started.md)
+ [
# 了解 Amazon Chime SDK 訊息的系統訊息
](system-messages.md)
+ [
# Amazon Chime SDK 訊息的範例 IAM 角色
](iam-roles.md)
+ [
# 了解角色的授權
](auth-by-role.md)
+ [
# 在 Amazon Chime SDK 訊息中串流訊息資料
](streaming-export.md)
+ [
# 使用彈性管道在 Amazon Chime SDK 會議中託管即時事件
](elastic-channels.md)
+ [
# 使用 Amazon Chime SDK 訊息的行動推播通知來接收訊息
](using-push-notifications.md)
+ [
# 針對 Amazon Chime SDK 訊息使用服務連結角色
](using-roles.md)
+ [
# 使用頻道流程來處理 Amazon Chime SDK 訊息
](using-channel-flows.md)
+ [
# 使用 AppInstanceBots 做為 Amazon Chime SDK 訊息的智慧型頻道代理程式
](appinstance-bots.md)
+ [
# 管理 Amazon Chime SDK 訊息的訊息保留
](manage-retention.md)
+ [
# Amazon Chime SDK 訊息的使用者介面元件
](ui-components.md)
+ [
# 將 Amazon Chime SDK 訊息與用戶端程式庫整合
](integrate-client-library.md)
+ [
# 搭配 JavaScript 使用 Amazon Chime SDK 訊息
](use-javascript.md)
# 遷移至 Amazon Chime SDK 身分命名空間
[Amazon Chime SDK Identity](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Identity.html) 命名空間是用於建立和管理 Amazon Chime SDK 身分資源APIs 的專用位置，包括 AppInstances 和 AppInstanceUsers。您可以使用 命名空間來處理任何可用 AWS 區域中的 Amazon Chime SDK 身分 API 端點。如果您剛開始使用 Amazon Chime SDK，請使用此命名空間。如需區域的詳細資訊，請參閱本指南[Amazon Chime SDK 的可用 AWS 區域](sdk-available-regions.md)中的 。
使用 [Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空間的現有應用程式應計劃遷移到專用命名空間。
**Topics**
+ [
## 遷移原因
](#identity-migration-reasons)
+ [
## 遷移之前
](#id-before-migrating)
+ [
## 命名空間之間的差異
](#id-namespace-differences)
## 遷移原因
基於下列原因，建議您遷移至 [Amazon Chime SDK Identity](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Identity.html) 命名空間：
**API 端點的選擇**
Amazon Chime SDK Identity 命名空間是唯一可在任何[區域中使用 API 端點的 API ](https://docs.aws.amazon.com/chime-sdk/latest/dg/sdk-available-regions.html)命名空間。如果您想要使用 以外的 API 端點`us-east-1`，則必須使用 Amazon Chime SDK Identity 命名空間。如需目前端點的詳細資訊，請參閱本指南[API 映射](migrate-from-chm-namespace.md#name-end-map)中的 。
**已更新和新的訊息 APIs**
我們只在 Amazon Chime SDK Identity 命名空間中新增或更新身分 APIs。
## 遷移之前
遷移之前，請注意命名空間之間的差異。下表列出並說明它們。
| | Amazon Chime SDK Identity 命名空間 | Amazon Chime 命名空間 |
| --- | --- | --- |
| AWS SDK 命名空間 | ChimeSDKIdentity | Chime |
| 區域 | 多個 | 僅限 us-east-1 |
| 服務主體 | https://identity.chime.amazonaws.com | https://chime.amazonaws.com |
| API | 只有用於身分APIs | Amazon Chime 身分和其他部分的 APIs |
| 使用者過期 | 可用性 | 無 |
| 機器人 | 可用性 | 無 |
## 命名空間之間的差異
下列各節說明 `Chime`和 `ChimeSDKIdentity`命名空間之間的差異。
**AWS SDK 命名空間**
Amazon Chime SDK 命名空間使用`Chime`正式名稱。Amazon Chime SDK Identity 命名空間使用`ChimeSDKIdentity`正式名稱。名稱的精確格式因平台而異。
例如，如果您使用 Node.js 中的 AWS SDK 來建立身分，您可以使用一行程式碼來定址命名空間。
```
const chimeIdentity = AWS.Chime();
```
若要遷移至`ChimeSDKIdentity`命名空間，請使用新的命名空間和端點區域更新這行程式碼。
```
const chimeIdentity = AWS.ChimeSDKIdentity({ region: "eu-central-1" });
```
**區域**
[Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空間只能處理 `us-east-1` 區域中的 API 端點。[Amazon Chime SDK Identity](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Identity.html) 命名空間可以在任何可用區域中處理 Amazon Chime SDK Identity API 端點。如需最新的端點區域清單，請參閱本指南[Amazon Chime SDK 的可用 AWS 區域](sdk-available-regions.md)中的 。
**端點**
[Amazon Chime SDK Identity](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Identity.html) 命名空間使用與 [Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空間不同的 API 端點。
只有用來建立身分資源的端點才能用來更新。這表示透過 中的端點建立的 AppInstance `eu-central-1` 只能透過 修改`eu-central-1`。這也表示您無法在 中使用 ChimeSDKIdentity 命名空間處理透過 Chime 命名空間建立的 AppInstance`us-east-1`，或在建立 AppInstance 和 AppInstanceUser 成員的區域以外的區域中建立頻道。如需目前端點的詳細資訊，請參閱本指南[API 映射](migrate-from-chm-namespace.md#name-end-map)中的 。
**服務主體**
[Amazon Chime SDK Identity](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Messaging.html) 命名空間使用新的服務主體：`Identity.chime.amazonaws.com`。如果您有授予服務存取權的 SQS、SNS 或其他 IAM 存取政策，則需要更新這些政策，以授予新服務主體存取權。
**API**
[Amazon Chime SDK Identity](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Identity.html) 命名空間僅包含用於建立和管理訊息資源的 APIs，以及用於傳送和接收訊息的 API。[Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空間包含 Amazon Chime 服務其他部分的 APIs 以及訊息。
**使用者過期**
建立 AppInstanceUsers 時的過期設定可讓您建立臨時使用者。例如，您可以建立只在大型廣播期間存在的聊天使用者。只有 Identity 命名空間支援 AppInstanceUsers 的過期設定。
**機器人**
您可以使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_AppInstanceBot.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_AppInstanceBot.html) API 將 Amazon Lex V2 支援的聊天機器人新增至您的應用程式。您只能在 Identity 命名空間中使用 AppInstanceBots。如需機器人的詳細資訊，請參閱本指南[使用 AppInstanceBots 做為 Amazon Chime SDK 訊息的智慧型頻道代理程式](appinstance-bots.md)中的 。
**其他 APIs**
Identity 命名空間有越來越多的 Chime 命名空間沒有的其他 APIs 清單。如果您開始使用 Amazon Chime SDK，請使用 Identity 命名空間來存取所有最新功能。如需目前 APIs的詳細資訊，請參閱《[Amazon Chime SDK API 參考](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Identity.html)*》中的 Amazon Chime SDK* Identity。
# 遷移至 Amazon Chime SDK 訊息命名空間
[Amazon Chime SDK Messaging](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Messaging.html) 命名空間是建立和管理 Amazon Chime SDK 訊息資源APIs 的專用位置。您可以使用 命名空間來處理任何可用 AWS 區域中的 Amazon Chime SDK 訊息 API 端點。如果您才剛開始使用 Amazon Chime SDK，請使用此命名空間。如需區域的詳細資訊，請參閱本指南[Amazon Chime SDK 的可用 AWS 區域](sdk-available-regions.md)中的 。
使用 [Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空間的現有應用程式應計劃遷移至專用命名空間。
**Topics**
+ [
## 移轉原因
](#migration-reasons)
+ [
## 遷移之前
](#before-migrating)
+ [
## 命名空間之間的差異
](#namespace-differences)
## 移轉原因
基於下列原因，建議您遷移至 [Amazon Chime SDK Messaging](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Messaging.html) 命名空間：
**API 端點的選擇**
Amazon Chime SDK Messaging 命名空間是唯一可在任何[區域中使用 API 端點的 API ](https://docs.aws.amazon.com/chime-sdk/latest/dg/sdk-available-regions.html)命名空間。如果您想要使用美國東部 （維吉尼亞北部） 以外的 API 端點，您必須使用 Amazon Chime SDK Messaging 命名空間。
如需 Amazon Chime SDK 訊息如何使用 AWS 區域的詳細資訊，請參閱本指南中的[可用區域](https://docs.aws.amazon.com/chime-sdk/latest/dg/available-regions.html)。
**更新和新的訊息 APIs**
我們只在 Amazon Chime SDK 訊息命名空間中新增或更新訊息 APIs。
## 遷移之前
遷移之前，請注意命名空間之間的差異。下表列出並說明它們。
| | Amazon Chime SDK Messaging 命名空間 | Amazon Chime 命名空間 |
| --- | --- | --- |
| AWS SDK 命名空間 | ChimeSDKMessaging | Chime |
| 區域 | 多個 | 僅限美國東部 （維吉尼亞北部） |
| API | 僅限用於傳訊APIs | 用於傳訊和 Amazon Chime 其他部分的 APIs |
| 流程 | Available | 不適用 |
| 彈性頻道 | Available | 不適用 |
## 命名空間之間的差異
下列各節說明 `Amazon Chime`和 `Amazon Chime SDK Messaging`命名空間之間的差異。
**AWS SDK 命名空間**
Amazon Chime SDK 命名空間使用`Chime`正式名稱。Amazon Chime SDK Messaging 命名空間使用`ChimeSDKMessaging`正式名稱。名稱的精確格式因平台而異。
例如，如果您使用 Node.js 中的 AWS SDK 來建立訊息，您可以使用一行程式碼來定址命名空間。
```
const chimeMessaging = AWS.Chime();
```
若要遷移至 Amazon Chime Messaging SDK，請使用新的命名空間和端點區域更新此行程式碼。
```
const chimeMessaging = AWS.ChimeSDKMessaging({ region: "Europe (Frankfurt)" });
```
**大區 (Regions)**
[Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空間只能處理`US East (N. Virginia)`區域中的 API 端點。[Amazon Chime SDK 訊息](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Messaging.html)命名空間可以在任何可用區域中處理 Amazon Chime SDK 訊息 API 端點。如需最新訊息區域的清單，請參閱本指南[Amazon Chime SDK 的可用 AWS 區域](sdk-available-regions.md)中的 。
**端點**
[Amazon Chime SDK Messaging](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Messaging.html) 命名空間使用與 [Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空間不同的 API 端點。
只有用來建立傳訊資源的端點才能用來修改它。這表示透過 中的端點建立的訊息資源`Europe (Frankfurt)`只能透過 修改`Europe (Frankfurt)`。這表示透過歐洲 （法蘭克福） 端點建立的頻道只能透過歐洲 （法蘭克福） 進行修改。這也表示您無法將透過`Chime`命名空間建立的頻道定址為美國東部 （維吉尼亞北部） 的`ChimeSDKMessaging`命名空間。如需目前端點的詳細資訊，請參閱本指南[API 映射](migrate-from-chm-namespace.md#name-end-map)中的 。
**服務主體**
[Amazon Chime SDK Messaging](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Messaging.html) 命名空間使用新的服務主體：`messaging.chime.amazonaws.com`。如果您有授予服務存取權的 SQS、SNS 或其他 IAM 存取政策，則需要更新這些政策，以授予新服務主體存取權。
**API**
[Amazon Chime SDK Messaging](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Messaging.html) 命名空間僅包含用於建立和管理訊息資源，以及用於傳送和接收訊息的 APIs。[Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) 命名空間包含 Amazon Chime 服務其他部分的 APIs 以及簡訊。
**頻道流程**
頻道流程可讓開發人員在傳輸中的訊息上執行商業邏輯，再交付給訊息頻道的成員。例如，您可以建立流程，在訊息傳遞前從訊息中移除敏感資料，例如政府 ID 號碼、電話號碼或褻瀆資料。這有助於實作公司通訊政策或其他通訊指導方針。
您也可以使用頻道流程來執行函數，例如在將結果傳回給參與者之前彙總輪詢的回應，或透過 SMS 傳送訊息。
頻道流程僅適用於 `ChimeSDKMessaging` 命名空間。如需有關它們的詳細資訊，請參閱本指南[使用頻道流程來處理 Amazon Chime SDK 訊息](using-channel-flows.md)中的 。
**彈性頻道**
彈性管道支援大規模聊天體驗，最多可有 100 萬聊天使用者在定義的子通道數量之間自動平衡。彈性頻道只能在`ChimeSDKMessaging`端點中使用。如需彈性頻道的詳細資訊，請參閱本指南[使用彈性管道在 Amazon Chime SDK 會議中託管即時事件](elastic-channels.md)中的 。
**其他 APIs**
訊息命名空間有不斷增長的 APIs 清單，而`Chime`命名空間沒有這些 API。如果您開始使用 Amazon Chime SDK，請使用簡訊命名空間來存取所有最新功能。如需目前 APIs的詳細資訊，請參閱《[Amazon Chime SDK API 參考](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Messaging.html)*》中的 Amazon Chime SDK* 訊息。
# 了解 Amazon Chime SDK 訊息的先決條件
您需要下列項目才能使用 Amazon Chime SDK 訊息。
+ 編寫程式的能力。
+ AWS 帳戶。
+ 使用 Amazon Chime SDK 訊息為應用程式設定 IAM 角色的許可。
對於大多數情況，您也需要：
+ **用戶端應用程式** – 顯示訊息 UI、使用 Amazon Chime SDKs連線至 Web 通訊端、管理狀態。
+ **伺服器應用程式** – 管理身分和使用者。
# 了解 Amazon Chime SDK 傳訊概念
若要有效使用 Amazon Chime SDK 訊息，您必須了解下列術語和概念。
**AppInstance**
若要使用 Amazon Chime SDK 訊息，您必須先建立 AppInstance。AppInstance 包含 AppInstanceUsers 和頻道。一般而言，您會為應用程式建立單一 AppInstance。 AWS 帳戶可以有多個 AppInstances。您可以在 AppInstance 層級進行應用程式層級設定，例如訊息保留和串流組態。AppInstances 由此格式的唯一 ARN 識別：`arn:aws:chime:region:aws_account_id:app-instance/app_instance_id`。
**AppInstanceUser**
AppInstanceUsers 是傳送訊息、建立頻道、聯結頻道等的實體。一般而言，您會建立 one-to-one映射。 `AppInstanceUser`您也可以建立 `AppInstanceUser` 來連線至後端服務，讓使用者識別來自後端服務的訊息。由 ARN 識別的 AppInstanceUsers，例如 `arn:aws:chime:region:aws_account_id:app-instance/app_instance_id/user/app_instance_user_id`。您可以控制 `app_instance_user_id`，而作為最佳實務，請重複使用應用程式已有IDs。
**Channel**
當您將 `AppInstanceUser`新增至頻道時，該使用者會成為成員並可以傳送和接收訊息。頻道可以是公有的，它允許任何使用者將自己新增為成員，也可以是私有的，只允許頻道主持人新增成員。您也可以隱藏頻道成員。隱藏成員可以觀察對話，但不傳送訊息，而且不會新增至頻道成員資格。
**SubChannel**
彈性頻道的成員會分為名為 SubChannels 的邏輯容器。當您將 AppInstanceUser 新增至彈性頻道時，使用者會成為SubChannel的成員，並可以傳送和接收該特定SubChannel的訊息。頻道成員資格和訊息位於 SubChannel 層級，表示某個 SubChannel 中的成員傳送的訊息不會由另一個 SubChannel 中的成員接收。成員會轉移到不同的 SubChannels以支援頻道的彈性本質並提升參與度。
**UserMessage**
`AppInstanceUser` 屬於頻道的 可以傳送和接收使用者訊息。`AppInstanceUser` 可以傳送 `STANDARD`或 `CONTROL` 訊息。 `STANDARD` 訊息可以包含 4KB 的資料和 1KB 中繼資料。 `CONTROL` 訊息只能包含 30 個位元組的資料。訊息可以是 `PERSISTENT`或 `NON_PERSISTENT`。您可以從頻道歷史記錄擷取`PERSISTENT`訊息。只有目前連線至 Amazon Chime SDK 訊息的頻道成員可以看到`NON_PERSISTENT`訊息。
**系統訊息**
Amazon Chime SDK 會產生系統訊息以回應事件，例如成員加入或離開頻道。
# 了解 Amazon Chime SDK 訊息架構
您可以使用 Amazon Chime SDK 訊息作為伺服器端和用戶端 SDK。伺服器端 APIs 會建立 `AppInstance`和 `AppInstanceUser`。您可以使用各種勾點和組態來新增應用程式特定的商業邏輯和驗證。如需執行此作業的詳細資訊，請參閱 [在 Amazon Chime SDK 訊息中串流訊息資料](streaming-export.md)。此外，伺服器端程序可以代表 呼叫 APIs`AppInstanceUser`，或控制代表後端程序`AppInstanceUser`的專用 。
表示為 的用戶端應用程式`AppInstanceUser`可以直接呼叫 Amazon Chime SDK 訊息 APIs。用戶端應用程式使用 WebSocket 通訊協定，在上線時連線至簡訊 SDK。連線時，他們會從他們所屬的任何頻道接收即時訊息。中斷連線時， `AppInstanceUser`仍然屬於新增至其中的頻道，而且可以使用 SDK 的 HTTP APIs載入這些頻道的訊息歷史記錄。
用戶端應用程式具有以單一 進行 API 呼叫的許可`AppInstanceUser`。若要將 IAM 憑證範圍限定為單一 `AppInstanceUser`，用戶端應用程式會透過 AWS Cognito 身分集區或小型自我託管後端 API 擔任參數化 IAM 角色。如需身分驗證的相關詳細資訊，請參閱 [驗證 Amazon Chime SDK 訊息的最終使用者用戶端應用程式](auth-client-apps.md)。相反地，伺服器端應用程式通常具有與單一應用程式執行個體使用者繫結的許可，例如具有管理許可的使用者，或具有代表所有應用程式執行個體使用者進行 API 呼叫的許可。
# 了解 Amazon Chime SDK 訊息類型
您可以透過管道傳送訊息。您可以傳送 `STANDARD`、 `CONTROL`或 `SYSTEM` 訊息。
+ `STANDARD` 訊息的大小上限為 4KB，且包含中繼資料。中繼資料是任意的，您可以透過各種方式使用，例如包含附件的連結。
+ `CONTROL` 訊息限制為 30 個位元組，且不包含中繼資料。
+ `STANDARD` 和 `CONTROL` 訊息可以是持久性或非持久性。持久性訊息會保留在頻道的歷史記錄中，並使用 `ListChannelMessages` API 呼叫檢視。非持久性訊息會傳送至透過 WebSocket `AppInstanceUser`連線的每個 。
+ Amazon Chime SDK 會傳送事件的自動`SYSTEM`訊息，例如加入或離開頻道的成員。
# Amazon Chime SDK 訊息入門
本節中的主題說明如何開始建置 Amazon Chime SDK 訊息應用程式。
**Topics**
+ [
# 建立 AppInstance Amazon Chime SDK 訊息
](create-app-instance.md)
+ [
# 從後端服務對 Amazon Chime SDK 訊息進行 SDK 呼叫
](call-from-backend.md)
+ [
# 驗證 Amazon Chime SDK 訊息的最終使用者用戶端應用程式
](auth-client-apps.md)
+ [
# 建立 Amazon Chime SDK 訊息的頻道
](creating-channels.md)
+ [
# 在 Amazon Chime SDK 訊息中傳送訊息
](send-messages.md)
+ [
# 在 Amazon Chime SDK 訊息中使用 ExpirationSettings
](expiration.md)
+ [
# 使用 WebSockets Amazon Chime SDK 訊息中接收訊息
](websockets.md)
+ [
# 在 Amazon Chime SDK 訊息中設定附件
](configure-attachments.md)
# 建立 AppInstance Amazon Chime SDK 訊息
若要使用 Amazon Chime SDK 訊息，您必須先`AppInstance`在 AWS 帳戶中建立 Amazon Chime SDK。
**Topics**
+ [
## 建置 AppInstance
](#app-instance-steps)
+ [
## 建立 AppInstanceUser
](#create-app-instance-user)
## 建置 AppInstance
**建立 `AppInstance`用於傳訊**
1. 在 CLI 中，執行 `aws chime-sdk-identity create-app-instance --name NameOfAppInstance.`
1. 在建立回應中，記下 `AppInstanceArn`。 `arn:aws:chime:region: aws_account_id:app-instance/app_instance_id`
## 建立 AppInstanceUser
建立 後`AppInstance`，您可以在該 `AppInstanceUser`中建立 `AppInstance`。您通常會在使用者第一次註冊或登入您的應用程式時執行此操作。您也可以建立 `AppInstanceUser`來代表後端服務。
下列範例示範如何建立後端 `AppInstanceUser`：
```
aws chime-sdk-identity create-app-instance-user \
--app-instance-arn "app_instance_arn" \
--app-instance-user-id "back-end-worker" \
--name "back-end-worker"
```
在建立回應中，記下 `AppInstanceUserArn`。它採用此表單：`arn:aws:chime:region: aws_account_id:app-instance/app_instance_id/user/app_instance_user_id`。在此範例中， `app_instance_user_id`是「back-end-worker」。
**注意**
最佳實務是，`AppInstanceUser`為用戶端應用程式建立 時，請讓 `AppInstanceUserId` 符合該使用者的現有唯一 ID，例如身分提供者`sub`的 。名稱是連接到某些 API 實體的選用預留位置，例如訊息寄件者。它可讓您在一個位置控制使用者的顯示名稱，然後需要從 `AppInstanceUser` ARN 進行查詢，該 ARN 也會附加為訊息的寄件者。
# 從後端服務對 Amazon Chime SDK 訊息進行 SDK 呼叫
建立使用者以代表您的後端服務後，您可以建立頻道、傳送訊息至該頻道，以及從該頻道讀取訊息。
執行下列 CLI 命令來建立公有頻道。
```
aws chime-sdk-messaging create-channel \
--chime-bearer "app_instance_user_arn" \
--app-instance-arn "app_instance_arn" \
--name "firstChannel"
```
命令會產生此格式的 ARN： `arn:aws:chime:region:aws_account_id:app-instance/app_instance_id/channel/channel_id.`
**Topics**
+ [
## IAM 授權如何用於後端服務
](#how-iam-works)
+ [
## 了解隱含 API 授權
](#api-implicit-auth)
+ [
## 傳送和列出頻道訊息
](#send-list-msgs)
## IAM 授權如何用於後端服務
在上一節的 CLI 命令中，記下 `chime-bearer` 參數。它可識別建立或與管道和訊息等資源互動的使用者。幾乎所有 Amazon Chime SDK 訊息 APIs都採用 `chime-bearer` 參數，但 APIs API 只能由開發人員呼叫，例如 `CreateAppInstance`。
Amazon Chime SDK 訊息 APIs 的 IAM 許可需要`app-instance-user-arn `符合 `chime-bearer` 參數的 。根據 API，可能需要其他 ARNs，通常是頻道 ARNs。對於如上述範例的後端服務，這會導致類似下列範例的 IAM 政策：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": [
"chime:SendChannelMessage",
"chime:ListChannelMessages",
"chime:CreateChannelMembership",
"chime:ListChannelMemberships",
"chime:DeleteChannelMembership",
"chime:CreateChannel",
"chime:ListChannels",
"chime:DeleteChannel"
],
"Resource": [
"arn:aws:chime:us-east-1:123456789012:app-instance/app_instance_id/user/back-end-worker",
"arn:aws:chime:us-east-1:123456789012:app-instance/app_instance_id/channel/*"
]
}
}
```
------
請注意 `Resource`區段中的 `AppInstanceUser` ARN 和頻道 ARN。此 IAM 政策範例授予後端服務許可，以 ID 為「back-end-worker」的使用者身分進行 API 呼叫。如果您希望後端服務能夠呼叫使用您應用程式的人員，請將 變更為 `app_instance_user_arn` `arn:aws:chime:region:aws_account_id:app-instance/app_instance_id/user/*`。
## 了解隱含 API 授權
除了 IAM 政策之外，Amazon Chime SDK 訊息 APIs 還具有隱含許可。例如， `AppInstanceUser`只能在使用者所屬的頻道中傳送訊息或列出頻道成員資格。其中一個例外是提升為 `AppInstanceUser`的 `AppInstanceAdmin`。根據預設，管理員具有應用程式中所有頻道的許可。對於大多數使用案例，對於包含重要商業邏輯的後端服務，您只需要此項目。
下列 CLI 命令會將後端使用者提升為 管理員。
```
aws chime-sdk-identity create-app-instance-admin \
--app-instance-admin-arn "app_instance_user_arn" \
--app-instance-arn "app_instance_arn"
```
## 傳送和列出頻道訊息
下列 CLI 命令會傳送頻道訊息。
```
aws chime-sdk-messaging send-channel-message \
--chime-bearer "app_instance_user_arn" \
--channel-arn "channel_arn" \
--content "hello world" \
--type STANDARD \
--persistence PERSISTENT
```
下列 CLI 命令會依反向時間順序列出頻道訊息。
+ `aws chime list-channel-messages`
+ `aws chime-sdk-messaging list-channel-messages`
```
aws chime-sdk-messaging list-channel-messages \
--chime-bearer "app_instance_user_arn" \
--channel-arn "channel_arn"
```
# 驗證 Amazon Chime SDK 訊息的最終使用者用戶端應用程式
您也可以從最終使用者用戶端應用程式執行 Amazon Chime SDK 訊息。 [從後端服務對 Amazon Chime SDK 訊息進行 SDK 呼叫](call-from-backend.md) 說明如何進行 API 呼叫，例如 create-channel、send-channel-message 和 list-channel-messages。瀏覽器和行動應用程式等最終使用者用戶端應用程式會進行這些相同的 API 呼叫。用戶端應用程式也可以透過 WebSocket 連線，以接收其所屬頻道的訊息和事件即時更新。本節說明如何將 IAM 登入資料提供給範圍為特定應用程式執行個體使用者的用戶端應用程式。一旦最終使用者擁有這些登入資料，他們可以進行 中顯示的 API 呼叫[從後端服務對 Amazon Chime SDK 訊息進行 SDK 呼叫](call-from-backend.md)。若要查看用戶端應用程式的完整示範，請參閱 [ https：//https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/chat](https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/chat)。如需從用戶端應用程式所屬頻道接收即時訊息的詳細資訊，請參閱 [使用 WebSockets Amazon Chime SDK 訊息中接收訊息](websockets.md)。
## 提供 IAM 登入資料給最終使用者
Amazon Chime SDK 訊息原生與 AWS Identity and Access Management (IAM) 政策整合，以驗證傳入的請求。IAM 政策定義個別使用者可以執行的操作。您可以製作 IAM 政策，為您的使用案例提供縮小範圍的有限憑證。如需為 Amazon Chime SDK 訊息使用者建立政策的詳細資訊，請參閱 [Amazon Chime SDK 訊息的範例 IAM 角色](iam-roles.md)。
如果您有現有的身分提供者，您有下列選項可將現有的身分與 Amazon Chime SDK 訊息整合。
+ 您可以使用現有的身分提供者來驗證使用者，然後將身分驗證服務與 AWS Security Token Service (STS) 整合，為用戶端建立自己的憑證販賣服務。STS 提供用於擔任 IAM 角色的 APIs。
+ 如果您已經有 SAML 或 OpenID 相容身分提供者，建議您使用 Amazon [Cognito 身分集區](https://docs.aws.amazon.com/cognito/latest/developerguide/identity-pools.html)，這會抽象化對 AWS STS [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html)和 的呼叫[https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)。Amazon Cognito 與 OpenID、SAML 和公有身分提供者整合，例如 Facebook、Login with Amazon、Google 和 Sign in with Apple。
如果您沒有身分提供者，您可以開始使用 Amazon Cognito 使用者集區。如需如何搭配 Amazon Chime SDK 訊息功能使用 Amazon Cognito 的範例，請參閱[使用 Amazon Chime SDK 訊息在您的應用程式中建置聊天功能](https://aws.amazon.com/blogs/business-productivity/build-chat-features-into-your-application-with-amazon-chime-sdk-messaging/)。
或者，您可以使用 [AWS STS](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html)來建立自己的登入資料販賣服務，或建置自己的身分提供者。
**使用 STS 提供登入資料**
如果您已經有 ActiveDirectory LDAP 等 IDP，而且想要實作自訂憑證販賣服務，或授予未驗證會議出席者聊天的存取權，您可以使用 [AWS STS AssumeRole API](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。若要這樣做，請先建立 Amazon Chime SDK 訊息 SDK 角色。如需建立該角色的詳細資訊，請參閱[建立角色以將許可委派給 IAM 使用者。 ](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html)
IAM 角色將具有應用程式將使用之 Amazon Chime SDK 訊息動作的許可，如下所示：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"chime:GetMessagingSessionEndpoint"
],
"Resource": [
"*"
]
},
{
"Effect": "Allow",
"Action": [
"chime:SendChannelMessage",
"chime:ListChannelMessages",
"chime:CreateChannelMembership",
"chime:ListChannelMemberships",
"chime:DeleteChannelMembership",
"chime:CreateChannelModerator",
"chime:ListChannelModerators",
"chime:DescribeChannelModerator",
"chime:CreateChannel",
"chime:DescribeChannel",
"chime:ListChannels",
"chime:DeleteChannel",
"chime:RedactChannelMessage",
"chime:UpdateChannelMessage",
"chime:Connect",
"chime:ListChannelBans",
"chime:CreateChannelBan",
"chime:DeleteChannelBan",
"chime:ListChannelMembershipsForAppInstanceUser",
"chime:AssociateChannelFlow",
"chime:DisassociateChannelFlow",
"chime:GetChannelMessageStatus"
],
"Resource": [
"arn:aws:chime:us-east-1:123456789012:app-instance/app_instance_id/user/my_applications_user_id",
"arn:aws:chime:us-east-1:123456789012:app-instance/app_instance_id/channel/*"
]
}
]
}
```
------
在此範例中，將此角色稱為 *ChimeMessagingSampleAppUserRole*。
請注意使用者 ARN 資源中 *ChimeMessagingSampleAppUserRole* 政策`${my_application_user_id}`中的工作階段標籤。此工作階段標籤會在 [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) API 呼叫中參數化，以將傳回的登入資料限制為單一使用者的許可。
[https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) 和 [https://docs.aws.amazon.com/STS/latest/APIReference/API_TagSesstion.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_TagSesstion.html) APIs 會使用已登入的 IAM 實體呼叫，例如 IAM 使用者。APIs 也可以由不同的 IAM 角色呼叫，例如[AWS Lambda 執行角色](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html)。該 IAM 身分必須具有在 *ChimeMessagingSampleAppUserRole* `TagSession` 上呼叫 `AssumeRole`和 的許可。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"sts:AssumeRole",
"sts:TagSession"
],
"Resource": "arn:aws:iam::123456789012:role/ChimeMessagingSampleAppUserRole"
}
]
}
```
------
在此範例中，將此角色稱為 *ChimeSampleAppServerRole*。
您需要`ChimeMessagingSampleAppUserRole`使用允許 `ChimeMessagingSampleAppServerRole`呼叫 [STS AssumeRole API](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) 的信任政策來設定 。如需搭配 IAM 角色使用信任政策的詳細資訊，請參閱[如何搭配 IAM 角色使用信任政策。 ](https://aws.amazon.com/blogs/security/how-to-use-trust-policies-with-iam-roles/)您可以使用 AWS IAM 角色主控台將此政策新增至 `ChimeMessagingSampleAppUserRole`。下列範例顯示典型的信任關係。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:role/ChimeMessagingSampleAppServerRole"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
在範例部署中， AWS Lambda 會使用 啟動 [Amazon EC2](https://aws.amazon.com/ec2/) 執行個體或 `ChimeMessagingSampleAppServerRole`。然後伺服器：
1. 對用戶端接收憑證的請求執行任何應用程式特定授權。
1. 在 `AssumeRole`上呼叫 STS`ChimeMessagingSampleAppUserRole`，標籤會參數化 `${aws:PrincipalTag/my_applications_user_id}`。
1. 將`AssumeRole`通話中傳回的登入資料轉送給使用者。
下列範例顯示針對步驟 2 擔任角色的 CLI 命令：
`aws sts assume-role --role-arn arn:aws:iam::my_aws_account_id:role/ChimeMessagingSampleAppUserRole --role-session-name demo --tags Key=my_applications_user_id,Value=123456789 `
# 建立 Amazon Chime SDK 訊息的頻道
您和您的最終使用者可以建立頻道。建立之後，您或您的最終使用者也需要將成員新增至頻道。用於建立頻道的範例程式碼可在 [ GitHub 上的範例應用程式中](https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/chat)取得。
如需建立頻道和新增成員的詳細資訊，請參閱：
+ [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html)
+ [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html)
# 在 Amazon Chime SDK 訊息中傳送訊息
使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html) API 傳送訊息。範例程式碼可在 [ GitHub 上的範例應用程式中](https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/chat)取得。
# 在 Amazon Chime SDK 訊息中使用 ExpirationSettings
當您建立 `AppInstanceUser`或 時`Channel`，您可以使用 `ExpirationSettings` 來設定這些資源以進行自動刪除。 `ExpirationSettings`有助於降低儲存成本，並防止resource-limit-exceeded的問題。例如，您可以在 7 天後刪除未使用的頻道，或刪除僅用於測試目的`AppInstanceUser`的 。
對於 `AppInstanceUser`，您可以根據使用者建立時間指定過期期間。對於 `Channel`，您可以根據頻道的建立時間或上次訊息時間指定過期期間。後者可讓您使用訊息活動來自訂自動刪除。
**重要**
在資源過期後不久， 會`ExpirationSettings`啟動背景程序來刪除該資源。程序通常需要 6 小時，但時間可能會有所不同。
已過期`AppInstanceUsers`且尚未刪除`Channels`的 仍會顯示為有效且作用中。您可以更新或移除其過期設定，且系統會遵守您的變更。
**Topics**
+ [
## 設定 ExpirationSettings
](#create-expiration)
+ [
## 過期資源刪除的AWS CloudTrail 事件
](#ct-events)
## 設定 ExpirationSettings
下列各節說明如何設定 `AppInstanceUser`或 `ExpirationSettings`的 `Channel`。
### 在建立資源ExpirationSettings時設定
您可以在執行 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateAppInstanceUser.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateAppInstanceUser.html)或 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html) APIs`ExpirationSettings`時設定 。如果您設定 `ExpirationSettings` 參數，則必須授予下列 IAM 許可：
+ `chime:PutAppInstanceUserExpirationSettings` 建立 時 `AppInstanceUser`
+ `chime:PutChannelExpirationSettings` 建立 時`Channel`。
下列範例使用 AWS CLI 來建立在一天後過期`AppInstanceUser`的 。
```
aws chime-sdk-identity create-app-instance-user \
--app-instance-arn "app_instance_arn" \
--app-instance-user-id "backend-worker" \
--name "backend-worker" \
--expiration-settings '{
"ExpirationDays": 1,
"ExpirationCriterion": "CREATED_TIMESTAMP"
}'
```
下列範例使用 AWS CLI 來建立`Channel`在最後收到訊息一天後過期的 。
```
aws chime-sdk-messaging create-channel \
--chime-bearer "app_instance_user_arn" \
--app-instance-arn "app_instance_arn" \
--name "firstChannel" \
--expiration-settings '{
"ExpirationDays": 1,
"ExpirationCriterion": "LAST_MESSAGE_TIMESTAMP"
}'
```
### 使用 Put APIs設定 ExpirationSettings
您也可以使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_PutAppInstanceUserExpirationSettings.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_PutAppInstanceUserExpirationSettings.html)和 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelExpirationSettings.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelExpirationSettings.html) APIs 來建立、更新和刪除 `ExpirationSettings`。
下列範例顯示您使用 AWS CLI 來更新 `AppInstanceUser`的 `ExpirationSettings`。
```
aws chime-sdk-identity put-app-instance-user-expiration-settings \
--app-instance-user-arn "app_instance_user_arn" \
--expiration-settings '{
"ExpirationDays": 30,
"ExpirationCriterion": "CREATED_TIMESTAMP"
}'
```
下列範例顯示使用 AWS CLI 刪除頻道的 `ExpirationSettings`。
```
aws chime-sdk-messaging put-channel-expiration-settings \
--chime-bearer "app_instance_user_arn" \
--channel-arn "channel_arn"
```
## 過期資源刪除的AWS CloudTrail 事件
系統刪除過期的資源後，會將 `ExpireAppInstanceUser`或 `ExpireChannel`事件傳送至 AWS CloudTrail。事件的類型取決於已刪除資產的類型。
下列範例顯示 `AppInstanceUser`事件。
```
{
"eventVersion": "1.08",
"userIdentity": {
"accountId": "123456789012",
"invokedBy": "chime.amazonaws.com"
},
"eventTime": "2023-03-15T00:00:00Z",
"eventSource": "chime.amazonaws.com",
"eventName": "ExpireAppInstanceUser",
"awsRegion": "us-east-1",
"sourceIPAddress": "chime.amazonaws.com",
"userAgent": "chime.amazonaws.com",
"requestParameters": null,
"responseElements": null,
"eventID": "12345678-1234-1234-1234-123456789012",
"readOnly": false,
"resources": [
{
"accountId": "123456789012",
"type": "AWS::Chime::AppInstanceUser",
"ARN": "arn:aws:chime:us-east-1:123456789012:app-instance/app-instance-id/user/user-id"
}
],
"eventType": "AwsServiceEvent",
"managementEvent": true,
"recipientAccountId": "123456789012",
"serviceEventDetails": {
"reason": "AppInstanceUser deleted due to expiration settings."
},
"eventCategory": "Management"
}
```
# 使用 WebSockets Amazon Chime SDK 訊息中接收訊息
您可以使用 [Amazon Chime JS SDK](https://github.com/aws/amazon-chime-sdk-js) 來使用 WebSockets 接收訊息，也可以使用您選擇的 WebSocket 用戶端程式庫。
依照列出的順序遵循這些主題，以開始使用 WebSockets：
**Topics**
+ [
## 定義 IAM 政策
](#define-iam-policy)
+ [
## 擷取端點
](#retrieve-endpoint)
+ [
## 建立連線
](#connect-api)
+ [
## 使用預先擷取來交付頻道詳細資訊
](#prefetch)
+ [
## 處理事件
](#process-events)
## 定義 IAM 政策
若要開始，請定義可讓您建立 WebSocket 連線的 IAM 政策。下列範例政策提供建立 WebSocket 連線的`AppInstanceUser`許可。
```
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action: [
"chime:Connect"
],
"Resource": [
"arn:aws:chime:region:{aws_account_id}:app-instance/{app_instance_id}/user/{app_instance_user_id}"
]
},
{
"Effect": "Allow",
"Action: [
"chime:GetMessagingSessionEndpoint"
],
"Resource": [
"*"
]
}
]
}
```
## 擷取端點
下列步驟說明如何擷取 WebSocket 連線中使用的端點。
1. 使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html) API 擷取 WebSocket 端點。
1. 使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html) API 傳回的 URL 來建構簽章第 4 版簽署的 WebSocket URL。如果您需要協助執行此操作，您可以遵循 中的指示[建立連線](#connect-api)。
**注意**
WebSocket URLs的格式如下： `id.region.ws-messaging.chime.aws`
## 建立連線
擷取端點之後，您可以使用連線 API 建立與 Amazon Chime SDK 後端伺服器的 WebSocket 連線，並接收 的訊息`AppInstanceUser`。您必須使用 AWS Signature 第 4 版來簽署請求。如需簽署請求的詳細資訊，請參閱[使用 Signature 第 4 版簽署 AWS 請求](https://docs.aws.amazon.com/general/latest/gr/Signature Version 4_signing.html)。
**注意**
若要擷取端點，您可以叫用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html) API。您可以使用您選擇的 WebSocket 用戶端程式庫來連線至端點。
**請求語法**
```
GET /connect
?X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=AKIARALLEXAMPLE%2F20201214%2Fregion%2Fchime%2Faws4_request
&X-Amz-Date=20201214T171359Z
&X-Amz-Expires=10
&X-Amz-SignedHeaders=host
&sessionId={sessionId}
&userArn={appInstanceUserArn}
&X-Amz-Signature=db75397d79583EXAMPLE
```
**URI 請求參數**
所有 URI 請求查詢參數都必須以 URL 編碼。
**X-Amz-Algorithm**
識別 AWS Signature 的版本，以及您用來計算簽章的演算法。Amazon Chime SDK 僅支援 AWS Signature 第 4 版身分驗證，因此此值為 `AWS4-HMAC-SHA256`。
**X-Amz-Credential**
除了您的存取金鑰 ID 之外，此參數還提供 AWS 區域和服務，也就是簽章有效的範圍。此值必須符合您在簽章計算中使用的範圍。此參數值的一般格式為：
`////aws4_request`
例如：
`AKIAIOSFODNN7EXAMPLE/20201214/us-east-1/chime/aws4_request`
**X-Amz-Date**
日期和時間格式必須遵循 ISO 8601 標準，而且您必須將其格式化為 `yyyyMMddTHHmmssZ`。例如，您必須將 **08/01/2020 15：32：41.982-700** 轉換為國際標準時間 (UTC)，並以 提交`20200801T083241Z`。
**X-Amz-Signed-Headers**
列出您用來計算簽章的標頭。簽章計算中需要下列標頭：
+ HTTP 主機標頭。
+ 您計劃新增至請求的任何 x-amz-\$1 標頭。
**注意**
為了提高安全性，請簽署您計劃包含在請求中的所有請求標頭。
**X-Amz-Signatures**
提供簽章以驗證您的請求。此簽章必須符合 Amazon Chime SDK 計算的簽章。如果沒有，Amazon Chime SDK 會拒絕請求。例如 `733255ef022bec3f2a8701cd61d4b371f3f28c9f19EXAMPLEd48d5193d7`。
**X-Amz-Security-Token**
如果使用來自 Security Token Service 的登入資料，則為選用登入資料參數。如需 服務的詳細資訊，請參閱 https：//[https://docs.aws.amazon.com/STS/latest/APIReference/](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html)。
**SessionId**
指出要建立之 WebSocket 連線的唯一 ID。
**UserArn**
指出`AppInstanceUser`嘗試建立連線的 身分。值應該是 的 ARN`AppInstanceUser`。例如 `arn:aws:chime:us%2Deast%2D1:123456789012:app%2Dinstance/694d2099%2Dcb1e%2D463e%2D9d64%2D697ff5b8950e/user/johndoe`
## 使用預先擷取來交付頻道詳細資訊
當您建立 WebSocket 連線時，您可以在查詢參數`prefetch-on=connect`中指定 來傳遞`CHANNEL_DETAILS`事件。預先擷取功能隨附於連線 API，而 功能可讓使用者查看豐富的聊天檢視，而無需額外的 API 呼叫。使用者可以：
+ 查看最後一個頻道訊息的預覽，以及其時間戳記。
+ 查看頻道的成員。
+ 查看頻道的未讀取標記。
使用者連線到指定的預先擷取參數後，使用者會收到工作階段建立的事件，這表示已建立連線。然後，使用者會收到最多 50 個`CHANNEL_DETAILS`事件。如果使用者的頻道少於 50 個，連線 API 會透過`CHANNEL_DETAILS`事件預先擷取所有頻道。如果使用者有超過 50 個頻道，API 會預先擷取前 50 個包含未讀取訊息和最新`LastMessageTimestamp`值的頻道。`CHANNEL_DETAILS` 事件以隨機順序到達，您會收到所有 50 個頻道的事件。
此外，預先擷取會傳回 `ChannelMessages`和 的下列項目`ChannelMemberships`：
+ **ChannelMessages** – [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html) 物件清單，`CreatedTimestamp`依遞減順序排序。僅包含使用者可看到的最新 20 則訊息。如果頻道中有目前使用者看不到的目標訊息，則可能會傳回少於 20 則訊息。`ChannelMessagesHasMore` 布林值將設定為 true，表示有更多訊息。軟性限制，可在 AWS 帳戶層級調整。
+ **ChannelMemberships** – [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html) 物件的清單。包含最多 30 個頻道成員。軟性限制，可在 AWS 帳戶層級調整。
此範例示範如何使用 `prefetch-on=connect`。
```
GET /connect
?X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=AKIARALLEXAMPLE%2F20201214%2Fregion%2Fchime%2Faws4_request
&X-Amz-Date=20201214T171359Z
&X-Amz-Expires=10
&X-Amz-SignedHeaders=host
&sessionId=sessionId
&prefetch-on=connect
&userArn=appInstanceUserArn
&X-Amz-Signature=db75397d79583EXAMPLE
```
此範例顯示一個頻道的回應。您將會收到所有 50 個頻道的回應。
```
{
"Headers": {
"x-amz-chime-event-type": "CHANNEL_DETAILS",
"x-amz-chime-message-type": "SYSTEM"
},
"Payload": JSON.stringify"({
Channel: [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelSummary.html)
ChannelMessages: List of [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html)
ChannelMemberships: List of [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html ](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html )
ReadMarkerTimestamp: Timestamp
ChannelMessagesHasMore: Boolean
})
}
```
## 處理事件
若要`AppInstanceUser`讓 在訊息建立連線後接收訊息，您必須將其新增至頻道。若要這樣做，請使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html) API。
**注意**
`AppInstanceUser` 一律會接收其所屬之所有頻道的訊息。當`AppInstance`使用者中斷連線時，訊息會停止。
`AppInstanceAdmin` 和 `ChannelModerator`不會在頻道上接收訊息，除非您使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html) API 明確新增。
下列主題說明如何處理事件。
**Topics**
+ [
### 了解訊息結構
](#message-structures)
+ [
### 處理中斷連線
](#handle-disconnects)
### 了解訊息結構
您收到的每個 WebSocket 訊息都遵循此格式：
```
{
"Headers": {"key": "value"},
"Payload": "{\"key\": \"value\"}"
}
```
**標頭**
Amazon Chime SDK 訊息使用以下標頭索引鍵：
+ `x-amz-chime-event-type`
+ `x-amz-chime-message-type`
+ `x-amz-chime-event-reason`
下一節會列出並描述標頭的可能值和承載。
**酬載**
Websocket 訊息會傳回 JSON 字串。JSON 字串的結構取決於`x-amz-event-type`標頭。下表列出可能`x-amz-chime-event-type`的值和承載：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/websockets.html)
**x-amz-chime-message-type**
下表列出`x-amz-chime-message-type`訊息類型 。
| 訊息類型 | Description |
| --- | --- |
| `STANDARD` | 當 Websocket 收到 STANDARD 頻道訊息時傳送。 |
| `CONTROL` | 當 WebSocket 收到 CONTROL 頻道訊息時傳送。 |
| `SYSTEM` | Amazon Chime SDK Messaging 傳送的所有其他 Websocket 訊息。 |
**x-amz-chime-event-reason**
這是特定使用案例支援的選用標頭。標頭提供有關為何收到特定事件的資訊。
| 事件原因 | Description |
| --- | --- |
| subchannel\$1DELETED | `DELETE_CHANNEL_MEMBERSHIP` 彈性頻道主持人收到的事件。只有在成員資格平衡之後，主持人才會看到 會刪除其所屬的子頻道。 |
### 處理中斷連線
Websocket 可能因網路連線變更或憑證過期而中斷連線。開啟 WebSocket 之後，Amazon Chime SDK 會將一般 ping 傳送至訊息用戶端，以確保其仍保持連線。如果連線關閉，用戶端會收到 WebSocket 關閉程式碼。用戶端可以嘗試重新連線，也可以不重新連線，具體取決於關閉程式碼。下表顯示用戶端可用來重新連線的關閉代碼。
對於 1000 到 4000 關閉碼，請僅針對下列訊息重新連線：
| 關閉代碼 | 可以重新連線 | Reason |
| --- | --- | --- |
| 1001 | 是 | 正常關閉 |
| 1006 | 是 | 異常關閉 |
| 1011 | 是 | 內部伺服器錯誤 |
| 1012 | 是 | 服務重新啟動 |
| 1013 | 是 | 稍後再試一次 |
| 1014 | 是 | 伺服器做為閘道或代理，並從上游伺服器收到無效的回應。這類似於 502 HTTP 狀態碼。 |
對於 4XXX 代碼，除了下列訊息*之外*，一律重新連線：
| 關閉代碼 | 可以重新連線 | Reason |
| --- | --- | --- |
| 4002 | 否 | 用戶端已啟動 |
| 4003 | 否 | 禁止 |
| 4401 | 否 | 未獲授權 |
當應用程式使用關閉程式碼重新連線時，應用程式應該：
1. 再次呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html) API 以取得新的基本 URL。
1. 如果 IAM 登入資料已過期，請重新整理。
1. 透過 WebSocket 連線。
如果您使用 amazon-chime-sdk-js 程式庫，如果您實作 [needsRefresh()](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html#needsRefresh-property) 屬性和 [refresh()](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html#refresh-property) 方法，則會為您處理。如需工作範例，請參閱 https：//[https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/AuthProvider.jsx\$1L93-L101](https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/AuthProvider.jsx#L93-L101)。
# 在 Amazon Chime SDK 訊息中設定附件
Amazon Chime SDK 可讓您將自己的儲存體用於訊息附件，並將其包含為訊息中繼資料。Amazon Simple Storage Service (S3) 是開始使用附件的最簡單方法。
**使用 S3 連接**
1. 建立 S3 儲存貯體以存放附件。
1. 為儲存貯體建立 IAM 政策，允許 Amazon Chime SDK 使用者從您的 S3 儲存貯體上傳、下載和刪除附件。
1. 建立 IAM 角色供身分提供者使用，以將登入資料提供給使用者進行連接。
[範例應用程式](https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/chat)提供如何使用 Amazon S3、Amazon Cognito 和 Amazon Chime SDK 執行此操作的範例。
# 了解 Amazon Chime SDK 訊息的系統訊息
Amazon Chime SDK 會針對在頻道中發生的事件，將系統訊息傳送至所有連線的用戶端。事件包括：
+ `UPDATE_CHANNEL` – 此事件表示對頻道詳細資訊所做的任何更新，例如名稱或中繼資料。
+ `DELETE_CHANNEL` – 此事件表示將刪除頻道及其所有資料，包括訊息、成員資格、主持人和禁止。
+ `CREATE_CHANNEL_MEMBERSHIP` – 此事件表示特定 `AppInstanceUser` 已新增為頻道的成員。事件也包含新 的詳細資訊`AppInstanceUser`。
+ `DELETE_CHANNEL_MEMBERSHIP` – 此事件表示 `AppInstanceUser` 已從頻道中移除。事件也包含已移除`AppInstanceUser`的詳細資訊。
+ `UPDATE_CHANNEL_MEMBERSHIP` – 此事件僅適用於彈性頻道。事件表示成員資格平衡將 `AppInstanceUser`從一個子通道轉移到另一個子通道。事件也包含`AppInstanceUser`詳細資訊，以及 `AppInstanceUser` 所傳輸之子通道的相關資訊。
# Amazon Chime SDK 訊息的範例 IAM 角色
若要讓使用者存取 Amazon Chime SDK 訊息功能，您必須定義 IAM 角色和政策，以便在使用者登入時提供登入資料。IAM 政策定義使用者可以存取的資源。
本節中的範例提供基本政策，您可以根據需求進行調整。如需政策運作方式的詳細資訊，請參閱 [從後端服務對 Amazon Chime SDK 訊息進行 SDK 呼叫](call-from-backend.md)。
此範例顯示開發人員使用 Amazon Chime SDK 訊息建置應用程式的政策。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"chime:CreateAppInstance",
"chime:DescribeAppInstance",
"chime:ListAppInstances",
"chime:UpdateAppInstance",
"chime:DeleteAppInstance",
"chime:CreateAppInstanceUser",
"chime:DeleteAppInstanceUser",
"chime:ListAppInstanceUsers",
"chime:UpdateAppInstanceUser",
"chime:DescribeAppInstanceUser",
"chime:CreateAppInstanceAdmin",
"chime:DescribeAppInstanceAdmin",
"chime:ListAppInstanceAdmins",
"chime:DeleteAppInstanceAdmin",
"chime:PutAppInstanceRetentionSettings",
"chime:GetAppInstanceRetentionSettings",
"chime:PutAppInstanceStreamingConfigurations",
"chime:GetAppInstanceStreamingConfigurations",
"chime:DeleteAppInstanceStreamingConfigurations",
"chime:TagResource",
"chime:UntagResource",
"chime:ListTagsForResource",
"chime:CreateChannelFlow",
"chime:UpdateChannelFlow",
"chime:DescribeChannelFlow",
"chime:DeleteChannelFlow",
"chime:ListChannelFlows",
"chime:ListChannelsAssociatedWithChannelFlow",
"chime:ChannelFlowCallback"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
```
------
此範例顯示允許使用者存取 Amazon Chime SDK 使用者動作的政策。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": "chime:GetMessagingSessionEndpoint",
"Effect": "Allow",
"Resource": "*"
},
{
"Action": [
"chime:CreateChannel",
"chime:DescribeChannel",
"chime:DeleteChannel",
"chime:UpdateChannel",
"chime:ListChannels",
"chime:Listsubchannels",
"chime:ListChannelMembershipsForAppInstanceUser",
"chime:DescribeChannelMembershipForAppInstanceUser",
"chime:ListChannelsModeratedByAppInstanceUser",
"chime:DescribeChannelModeratedByAppInstanceUser",
"chime:UpdateChannelReadMarker",
"chime:CreateChannelModerator",
"chime:DescribeChannelModerator",
"chime:ListChannelModerators",
"chime:DeleteChannelModerator",
"chime:SendChannelMessage",
"chime:GetChannelMessage",
"chime:DeleteChannelMessage",
"chime:UpdateChannelMessage",
"chime:RedactChannelMessage",
"chime:ListChannelMessages",
"chime:CreateChannelMembership",
"chime:DescribeChannelMembership",
"chime:DeleteChannelMembership",
"chime:ListChannelMemberships",
"chime:CreateChannelBan",
"chime:DeleteChannelBan",
"chime:ListChannelBans",
"chime:DescribeChannelBan",
"chime:Connect",
"chime:AssociateChannelFlow",
"chime:DisassociateChannelFlow",
"chime:GetChannelMessageStatus"
],
"Effect": "Allow",
"Resource": [
"arn:aws:chime:us-east-1:123456789012:app-instance/app_instance_id/user/app_instance_user_id",
"arn:aws:chime:us-east-1:123456789012:app-instance/app_instance_id/channel/*"
]
}
]
}
```
------
此範例顯示的政策可讓使用者對 Amazon Chime SDK 使用者動作的存取權降到最低。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": "chime:GetMessagingSessionEndpoint",
"Effect": "Allow",
"Resource": "*"
},
{
"Action": [
"chime:ListChannels",
"chime:DescribeChannel",
"chime:ListChannelMembershipsForAppInstanceUser",
"chime:DescribeChannelMembershipForAppInstanceUser",
"chime:ListChannelsModeratedByAppInstanceUser",
"chime:DescribeChannelModeratedByAppInstanceUser",
"chime:SendChannelMessage",
"chime:GetChannelMessage",
"chime:ListChannelMessages",
"chime:Connect"
],
"Effect": "Allow",
"Resource": [
"arn:aws:chime:us-east-1:123456789012:app-instance/app_instance_id/user/app_instance_user_id",
"arn:aws:chime:us-east-1:123456789012:app-instance/app_instance_id/channel/*"
]
}
]
}
```
------
此範例顯示為 建立 WebSocket 連線的政策`AppInstanceUser`。如需 WebSocket 連線的詳細資訊，請參閱 [使用 WebSockets Amazon Chime SDK 訊息中接收訊息](websockets.md)。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"chime:Connect"
],
"Resource": [
"arn:aws:chime:us-east-1:123456789012:app-instance/app_instance_id/user/app_instance_user_id"
]
}
]
}
```
------
# 了解角色的授權
本主題中的資料表列出應用程式執行個體使用者可以執行的動作，視其角色而定。
**圖例**
+ **允許** – 如果在 IAM 政策中指定正確的動作/資源內容，則可以成功執行。
+ **允許有限制** – 如果在 IAM 政策中指定了正確的動作/資源內容，則必須符合特定條件才能成功執行動作。
+ **拒絕** – 即使 IAM 政策中指定了正確的動作/資源內容，後端仍會封鎖它。
**Topics**
+ [
## AppInstanceAdmin
](#appinstanceadmin)
+ [
## ChannelModerator
](#channelmoderator)
+ [
## 成員
](#member)
+ [
## 非成員
](#non-member)
## AppInstanceAdmin
應用程式執行個體管理員可以在其為管理員的應用程式執行個體內的頻道上執行動作。
| API 名稱 | 允許或拒絕 | 備註 |
| --- | --- | --- |
| `UpdateChannel` | 允許，但有限制 | 設定後無法更新 ElasticChannelConfiguration |
| `DeleteChannel` | 已允許 | |
| `DescribeChannel` | 已允許 | |
| `ListChannel` | 已允許 | |
| `ListChannelMembershipsForAppInstanceUser` | 允許 | 您也可以[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax)將另一個 填入 `AppInstanceUser`。 |
| `DescribeChannelMembershipForAppInstanceUser` | 允許 | 您也可以[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax)填入另一個 `AppInstanceUser`。 |
| `ListChannelsModeratedByAppInstanceUser` | 允許 | 您也可以[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax)填入另一個 AppInstanceUser。 |
| `DescribeChannelModeratedByAppInstanceUser` | 允許 | 您也可以[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax)填入另一個 `ppInstanceUser`A。彈性頻道不允許。 |
| `CreateChannelMembership` | 已允許 | |
| `DescribeChannelMembership` | 已允許 | |
| `ListChannelMembership` | 已允許 | |
| `DeleteChannelMembership` | 允許 | |
| `SendChannelMessage` | 允許，但有限制 | 首先，您需要使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateChannelMembership.html) 來建立自己的成員資格，然後呼叫 API。 |
| `GetChannelMessage` | 已允許 | |
| `ListChannelMessage` | 已允許 | |
| `DeleteChannelMessage` | 已允許 | |
| `RedactChannelMessage` | 允許 | |
| `UpdateChannelMessage` | 允許，但有限制 | 您只能編輯自己的訊息。 |
| `CreateChannelModerator` | 已允許 | |
| `DeleteChannelModerator` | 已允許 | |
| `DescribeChannelModerator` | 已允許 | |
| `ListChannelModerator` | 允許 | |
| `CreateChannelBan` | 允許，但有限制 | 您禁止`AppInstanceUser`的 不能是該頻道的 `AppInstanceAdmin`或 主持人。 |
| `DeleteChannelBan` | 允許，但有限制 | |
| `DescribeChannelBan` | 已允許 | |
| `ListChannelBan` | 允許 | |
| `UpdateChannelReadMarker` | 允許，但有限制 | 對於非彈性管道，您需要先使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html) API 為自己建立成員資格，然後呼叫 API。 不允許用於彈性頻道。 |
| `GetChannelMessage` | 允許限制 | 僅允許傳送的訊息。除非您是訊息寄件者，否則不允許透過頻道流程處理的訊息。 |
| `ListChannelMessages` | 允許 | |
| `DeleteChannelMessage` | 允許限制 | 僅允許傳送的訊息。 |
| `RedactChannelMessage` | 允許限制 | 僅允許傳送的訊息。 |
| `UpdateChannelMessage` | 允許限制 | 您只能編輯自己的已傳送訊息。 |
| `AssociateChannelFlow` | 已允許 | |
| `DisassociateChannelFlow` | 允許 | |
| `GetChannelMessageStatus` | 允許限制 | 您只能取得自己訊息的訊息狀態。 |
| `ListSubChannels` | 允許 | |
## ChannelModerator
頻道主持人只能在他們具有主持人角色的頻道上執行動作。
**注意**
身為 的主持人`AppInstanceAdmin`可以對該角色允許的頻道執行動作。
| API 名稱 | 允許或拒絕 | 備註 |
| --- | --- | --- |
| `UpdateChannel` | 允許 | 設定後無法更新 ElasticChannelConfiguration |
| `DeleteChannel` | 允許 | |
| `DescribeChannel` | 允許，但有限制 | 您只能取得公有頻道的詳細資訊。 |
| `ListChannel` | 允許，但有限制 | 您只能取得公有頻道的詳細資訊。 |
| `ListChannelMembershipsForAppInstanceUser` | 允許，但有限制 | 您只能使用 ARN 做為 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax)值。 |
| `DescribeChannelMembershipForAppInstanceUser` | 允許，但有限制 | 您只能使用 ARN 做為 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax)值。 |
| `ListChannelsModeratedByAppInstanceUser` | 允許，但有限制 | 您只能使用 ARN 做為 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax)值。 |
| `DescribeChannelModeratedByAppInstanceUser` | 允許，但有限制 | 您也可以[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax)使用另一個 AppInstanceUser 填入 。 |
| `CreateChannelMembership` | 已允許 | |
| `DescribeChannelMembership` | 已允許 | |
| `ListChannelMembership` | 已允許 | |
| `DeleteChannelMembership` | 允許 | |
| `SendChannelMessage` | 允許，但有限制 | 您需要先使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html) API 為自己建立成員資格，然後呼叫 `SendChannelMessage` API。 |
| `GetChannelMessage` | 已允許 | |
| `ListChannelMessage` | 允許 | |
| `DeleteChannelMessage` | 已拒絕 | |
| `RedactChannelMessage` | 允許 | |
| `UpdateChannelMessage` | 允許，但有限制 | 您只能更新自己的訊息。 |
| `CreateChannelModerator` | 允許 | 您需要先使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html) API 為自己建立成員資格，然後呼叫 `CreateChannelModerator` API。 |
| `DeleteChannelModerator` | 已允許 | |
| `DescribeChannelModerator` | 已允許 | |
| `ListChannelModerator` | 允許 | |
| `CreateChannelBan` | 允許，但有限制 | `AppInstanceUser` 您禁止的 不能是該頻道的 `AppInstanceAdmin`或 主持人。 |
| `DeleteChannelBan` | 允許，但有限制 | |
| `DescribeChannelBan` | 已允許 | |
| `ListChannelBan` | 允許 | |
| `UpdateChannelReadMarker` | 允許，但有限制 | 對於非彈性管道，您需要先使用 為自己[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html)建立成員資格，然後呼叫 `UpdateChannelReadMarker` API。 不允許用於彈性頻道。 |
| `GetChannelMessage` | 允許限制 | 僅允許傳送的訊息。除非您是訊息寄件者，否則不允許透過頻道流程處理的訊息。 |
| `ListChannelMessages` | 允許 | |
| `DeleteChannelMessage` | 已拒絕 | |
| `RedactChannelMessage` | 允許限制 | 僅允許傳送的訊息。 |
| `UpdateChannelMessage` | 允許限制 | 您只能編輯自己的已傳送訊息。 |
| `AssociateChannelFlow` | 已允許 | |
| `DisassociateChannelFlow` | 允許 | |
| `GetChannelMessageStatus` | 允許限制 | 您只能取得自己訊息的訊息狀態。 |
| `ListSubChannels` | 允許 | |
## 成員
如果頻道是透過 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html) API 新增至頻道，則 `AppInstanceUser`會成為頻道的成員。
成員只能在其所屬的頻道上執行動作。
**注意**
屬於 `AppInstanceAdmin`或 的成員，`ChannelModerator`可以在這兩個角色允許的頻道上執行動作。
| API 名稱 | 允許或拒絕 | 備註 |
| --- | --- | --- |
| `UpdateChannel` | 已拒絕 | |
| `DeleteChannel` | 已拒絕 | |
| `DescribeChannel` | 允許，但有限制 | 您只能取得公有頻道的詳細資訊。 |
| `ListChannel` | 允許，但有限制 | 您只能取得公有頻道的詳細資訊。 |
| `ListChannelMembershipsForAppInstanceUser` | 允許，但有限制 | 您只能使用 ARN 做為 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax)值。 |
| `DescribeChannelMembershipForAppInstanceUser` | 允許，但有限制 | 您只能使用 ARN 做為 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax)值。 |
| `ListChannelsModeratedByAppInstanceUser` | 允許，但有限制 | 您只能使用 ARN 做為 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax)值。 |
| `DescribeChannelModeratedByAppInstanceUser` | 允許，但有限制 | 您也可以[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax)使用另一個 AppInstanceUser 填入 。 不允許用於彈性頻道。 |
| `CreateChannelMembership` | 允許，但有限制 | 您只能為[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html#chime-CreateChannel-request-Mode](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html#chime-CreateChannel-request-Mode)頻道新增其他成員。 |
| `DescribeChannelMembership` | 已允許 | |
| `ListChannelMembership` | 已允許 | |
| `DeleteChannelMembership` | 已允許 | |
| `SendChannelMessage` | 已允許 | |
| `GetChannelMessage` | 已允許 | |
| `ListChannelMessage` | 允許 | |
| `DeleteChannelMessage` | 已拒絕 | |
| `RedactChannelMessage` | 允許，但有限制 | 您只能編輯自己的訊息。 |
| `UpdateChannelMessage` | 允許，但有限制 | 您只能更新自己的訊息。 |
| `CreateChannelModerator` | 已拒絕 | |
| `DeleteChannelModerator` | 已拒絕 | |
| `DescribeChannelModerator` | 已拒絕 | |
| `ListChannelModerator` | 已拒絕 | |
| `CreateChannelBan` | 已拒絕 | |
| `DeleteChannelBan` | 已拒絕 | |
| `DescribeChannelBan` | 已拒絕 | |
| `ListChannelBan` | 已拒絕 | |
| `UpdateChannelReadMarker` | 允許，但有限制 | 不允許用於彈性頻道。 |
| `GetChannelMessage` | 允許限制 | 僅允許傳送的訊息。除非您是訊息寄件者，否則不允許透過頻道流程處理的訊息。 |
| `ListChannelMessages` | 允許 | |
| `DeleteChannelMessage` | 允許限制 | 僅允許傳送的訊息。 |
| `RedactChannelMessage` | 允許限制 | 僅允許傳送的訊息。 |
| `UpdateChannelMessage` | 允許限制 | 您只能編輯自己的已傳送訊息。 |
| `AssociateChannelFlow` | 已拒絕 | |
| `DisassociateChannelFlow` | 已拒絕 | |
| `GetChannelMessageStatus` | 允許限制 | 您只能取得自己訊息的訊息狀態。 |
| `Listsubchannels` | 已拒絕 | |
## 非成員
非成員是一般的`AppInstanceUser`，除非您使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html) API 新增，否則無法執行任何頻道相關動作。
**注意**
非成員，其為 `AppInstanceAdmin`或 `ChannelModerator`可以執行這兩個角色允許的頻道相關動作。
| API 名稱 | 允許或拒絕 | 備註 |
| --- | --- | --- |
| `UpdateChannel` | 已拒絕 | |
| `DeleteChannel` | 已拒絕 | |
| `DescribeChannel` | 允許，但有限制 | 您只能取得公有頻道的詳細資訊。 |
| `ListChannel` | 允許，但有限制 | 您只能取得公有頻道的詳細資訊。 |
| `ListChannelMembershipsForAppInstanceUser` | 允許，但有限制 | 您只能使用 ARN 做為 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax)值。 |
| `DescribeChannelMembershipForAppInstanceUser` | 允許，但有限制 | 您也可以[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_DescribeChannelModeratedByAppInstanceUser.html#API_DescribeChannelModeratedByAppInstanceUser_RequestSyntax)將另一個 填入 `AppInstanceUser`。 不允許用於彈性頻道。 |
| `ListChannelsModeratedByAppInstanceUser` | 允許，但有限制 | 您只能使用 ARN 做為 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax)值。 |
| `DescribeChannelModeratedByAppInstanceUser` | 允許，但有限制 | 您只能使用 ARN 做為 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_ListChannelMembershipsForAppInstanceUser.html#API_ListChannelMembershipsForAppInstanceUser_RequestSyntax)值。 |
| `CreateChannelMembership` | 已拒絕 | |
| `DescribeChannelMembership` | 允許，但有限制 | 您只能取得公有頻道的詳細資訊。 |
| `ListChannelMembership` | 允許，但有限制 | 您只能取得公有頻道的詳細資訊。 |
| `DeleteChannelMembership` | 已拒絕 | |
| `SendChannelMessage` | 已拒絕 | |
| `GetChannelMessage` | 允許，但有限制 | 您只能取得公有頻道的詳細資訊。 |
| `ListChannelMessage` | 允許，但有限制 | 您只能取得公有頻道的詳細資訊。 |
| `DeleteChannelMessage` | 已拒絕 | |
| `RedactChannelMessage` | 已拒絕 | |
| `UpdateChannelMessage` | 已拒絕 | |
| `CreateChannelModerator` | 已拒絕 | |
| `DeleteChannelModerator` | 已拒絕 | |
| `DescribeChannelModerator` | 已拒絕 | |
| `ListChannelModerator` | 已拒絕 | |
| `CreateChannelBan` | 已拒絕 | |
| `DeleteChannelBan` | 已拒絕 | |
| `DescribeChannelBan` | 已拒絕 | |
| `ListChannelBan` | 已拒絕 | |
| `UpdateChannelReadMarker` | 已拒絕 | |
| `GetChannelMessage` | 允許限制 | 僅允許傳送的訊息。除非您是訊息寄件者，否則不允許透過頻道流程處理的訊息。 |
| `ListChannelMessages` | 允許限制 | |
| `DeleteChannelMessage` | 已拒絕 | 已拒絕 |
| `RedactChannelMessage` | 已拒絕 | |
| `UpdateChannelMessage` | 已拒絕 | |
| `AssociateChannelFlow` | 已拒絕 | |
| `DisassociateChannelFlow` | 已拒絕 | |
| `GetChannelMessageStatus` | 允許限制 | 您只能取得自己訊息的訊息狀態。 |
# 在 Amazon Chime SDK 訊息中串流訊息資料
您可以設定 `AppInstance` 以串流的形式接收資料，例如訊息和頻道事件。然後，您可以即時回應該資料。目前，Amazon Chime SDK 訊息僅接受 Kinesis 串流做為串流目的地。您必須具備這些先決條件，才能使用 Kinesis 串流與此功能：
+ Kinesis 串流必須與 位於相同的 AWS 帳戶中`AppInstance`。
+ 串流必須與 位於相同的區域`AppInstance`。
+ 串流名稱的字首開頭為 `chime-messaging-`。
+ 您必須設定至少兩個碎片。每個碎片每秒最多可接收 1MB 的資料，因此請相應地擴展串流。
+ 您必須啟用伺服器端加密 (SSE)。
**設定 Kinesis 串流**
1. 使用上一節的先決條件建立一或多個 Kinesis 串流，然後取得 ARN。確保發起人除了 Amazon Chime 許可外還有 Kinesis 許可。
下列範例示範如何使用 AWS CLI 建立具有兩個碎片的 Kinesis 串流，以及如何啟用 SSE。
`aws kinesis create-stream --stream-name chime-messaging-unique-name --shard-count 2`
`aws kinesis start-stream-encryption --stream-name chime-messaging-unique-name --encryption-type KMS --key-id "alias/aws/kinesis"`
1. 呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutMessagingStreamingConfigurations.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutMessagingStreamingConfigurations.html) API 來設定串流。
您可以設定兩種資料類型中的一種或兩種，並且可以為它們選擇相同的串流或單獨的串流。
下列範例示範如何使用 AWS CLI 來設定 `appinstance`以串流 `ChannelMessage`和 `Channel`資料類型。
```
aws chime-sdk-messaging put-messaging-streaming-configurations --app-instance-arn app_instance_arn \
--streaming-configurations DataType=ChannelMessage,ResourceArn=kinesis_data_stream_arn
```
```
aws chime-sdk-messaging put-messaging-streaming-configurations --app-instance-arn app_instance_arn \
--streaming-configurations DataType=Channel,ResourceArn=kinesis_data_stream_arn
```
資料類型的範圍如下：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/streaming-export.html)
1. 開始從設定的 Kinesis 串流讀取資料。
**注意**
在您設定串流之前傳送的任何事件都不會傳送到您的 Kinesis 串流。
**資料格式**
Kinesis 會使用下列欄位以 JSON 格式輸出記錄： `EventType`和 `Payload`。承載格式取決於 `EventType`。下表列出事件類型及其對應的承載格式。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/streaming-export.html)
# 使用彈性管道在 Amazon Chime SDK 會議中託管即時事件
彈性管道支援最多 100 萬名成員的大規模聊天體驗。典型用途包括觀看體育賽事或政治賽事。您只能在美國東部 （維吉尼亞北部） 區域使用彈性頻道。
彈性頻道包含具有常見組態的單一頻道，以及不同或*彈性*的子頻道數量。組態也包含子頻道中成員的最小和最大閾值。
例如，假設您建立具有 100 個子頻道的彈性頻道，而對於子頻道，您設定了 500 個成員的低閾值和 10，000 個成員的高閾值。當使用者加入此範例頻道時，系統會自動將其指派給單一子頻道，直到成員計數超過 10，000。此時，系統會建立新的子通道，並在該處新增任何新成員。當使用者離開時，系統會刪除子通道，並將成員分配到剩餘的子通道。
跨子頻道分割受眾可讓參與者更輕鬆地進行對話。主持人也減少了工作負載，因為他們只需要監看一些子頻道。此外，主持人可以使用彈性頻道提供的內建工具。例如，主持人可以從頻道[中禁止使用者](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelBan.html)、[建立主持人](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelModerator.html)，並使用[頻道流程](https://docs.aws.amazon.com/chime-sdk/latest/dg/using-channel-flows.html)自動調節頻道中的所有訊息。
如需 Amazon Chime SDK 訊息配額的詳細資訊，請參閱《*Amazon Chime SDK 一般參考*》中的 [Messaging Quotas](https://docs.aws.amazon.com/general/latest/gr/chime-sdk.html)。
**Topics**
+ [
## 先決條件
](#elastic-prereqs)
+ [
## 彈性管道概念
](#elastic-concepts)
+ [
## 其他支援的功能
](#additional-features)
+ [
# 為 Amazon Chime SDK 會議建立彈性管道
](create-elastic-channel.md)
+ [
# 管理 Amazon Chime SDK 會議的彈性管道成員
](manage-elastic-members.md)
+ [
# 在 Amazon Chime SDK 會議中傳送彈性管道訊息
](send-messages-elastic.md)
+ [
# 了解 Amazon Chime SDK 會議彈性管道中的 WebSocket 系統訊息
](websocket-messages-elastic.md)
+ [
# 使用 Kinesis 串流接收 Amazon Chime SDK 會議的系統訊息
](elastic-onboard-streams.md)
+ [
# 在我們的示範應用程式中測試 Amazon Chime SDK 會議的彈性管道
](elastic-testing.md)
## 先決條件
您必須具有下列項目才能使用彈性頻道。
+ 了解 Amazon Chime SDK 傳訊功能，例如管理頻道，以及傳送和接收訊息。
+ 調用 Amazon Chime SDK 訊息 APIs的功能。
## 彈性管道概念
若要有效使用彈性管道，您必須了解這些概念。
**子頻道**
彈性頻道會將成員分成稱為子頻道的邏輯容器。當您將 `AppInstanceUser`新增至彈性頻道時，使用者會成為子頻道的成員。該使用者可以傳送和接收訊息，但只能與該子頻道的其他成員一起傳送和接收訊息。系統絕不允許來自一個子頻道的訊息出現在其他子頻道中。
**擴展**
若要支援使用者參與，每個子頻道都必須符合最低成員資格要求。您在建立彈性頻道時提供該值。當使用者加入或離開事件時，系統會將成員轉移到不同的子頻道，讓整體頻道變成「彈性」。子通道會執行下列擴展動作。
+ **SCALE\$1OUT** – 當新的彈性通道成員資格請求進入且所有子通道都已滿時，系統會透過建立新的子通道，然後將成員資格從現有子通道轉移到新的子通道來向外擴展。
+ **SCALE\$1IN** – 當子通道成員資格計數低於最低需求，且另一個子通道具有容納第一個子通道所有成員的容量時，`SCALE_IN`事件會轉移這些成員資格，然後刪除子通道和所有訊息。
如果您需要從已刪除的頻道存取訊息，您必須先開啟訊息串流。如需詳細資訊，請參閱 [在 Amazon Chime SDK 訊息中串流訊息資料](streaming-export.md)。
**成員轉移**
當成員資格平衡`AppInstanceUser`將 從一個子通道移動 到另一個子通道時，就會發生這種情況。轉移後， `AppInstanceUser`仍屬於彈性頻道。不過，新的子頻道包含不同的成員資格和訊息，因此 傳輸`AppInstanceUser`後傳送的訊息會傳送至這些不同的成員。成員資格平衡不會影響主持人成員資格。
**注意**
彈性管道不支援隱藏的成員資格、成員資格偏好設定和讀取訊息時間戳記。
## 其他支援的功能
彈性管道也支援這些傳訊功能。
+ [預先擷取](websockets.md#prefetch)
+ [頻道流程](using-channel-flows.md)
# 為 Amazon Chime SDK 會議建立彈性管道
您可以使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html) API 中的 `ElasticChannelConfiguration` 欄位來建立彈性頻道。建立彈性頻道後，即可建立頻道成員資格。
**注意**
對於非彈性頻道，建立頻道`AppInstanceUser`的 會自動以成員和主持人身分新增至該頻道。對於彈性頻道，頻道建立者只會新增為主持人。
您無法更新`ElasticChannelConfiguration`一次設定。
您無法將頻道從彈性更新為非彈性，反之亦然。
您無法在 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html) API 請求中包含成員 ARNs的清單。不過，您可以包含主持人 ARNs的清單。
您無法建立`UNRESTRICTED`類型彈性頻道。
# 管理 Amazon Chime SDK 會議的彈性管道成員
若要管理彈性頻道中的成員，請使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html)、 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelModerator.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelModerator.html)和 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelBan.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelBan.html) APIs。以下資訊說明如何使用它們。
**頻道成員資格**
`CreateChannelMembership` API 會在子頻道層級建立成員資格。子頻道可以包含主持人和一般成員。
+ **主持人** – 您可以將主持人新增至多個子頻道。這可讓主持人在其所屬的每個子頻道上傳送訊息。當您將主持人新增至子頻道時，您必須提供 `SubChannelId`。
如果您想要自動將主持人指派給新的子頻道，您可以[啟用訊息串流](streaming-export.md)、接聽子頻道建立事件，然後建立主持人成員資格以回應這些事件。
最後，您可以從特定子頻道或所有子頻道刪除主持人。在這兩種情況下，您都使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_DeleteChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_DeleteChannelMembership.html) API。若要從特定子頻道刪除主持人，請提供 `SubChannelId`。如果您未提供子頻道的 ID，系統會從所有子頻道中移除主持人。最後，您可以使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ListSubChannels](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ListSubChannels) API 列出每個子頻道中的成員數量。
+ **一般成員** – 這些構成大部分的頻道成員資格。您只能將一般成員新增至一個子頻道。此外，您無法在建立或刪除頻道成員資格`SubChannelId`時傳遞 ，因為系統控制在哪個子頻道中建立成員資格。
**頻道主持人**
`CreateChannelModerator` API 會在彈性頻道層級建立主持人。主持人可以檢視所有子頻道中的所有訊息。當您將一般成員提升為頻道主持人時，系統會移除該成員的所有現有頻道成員資格。當您降級主持人時，也會發生相同情況。
**頻道禁止**
`CreateChannelBan` API 會在彈性頻道層級建立禁止。禁止的 `AppInstanceUser` 不能屬於任何子頻道。當您禁止成員時，系統會移除該成員的所有頻道成員資格。
# 在 Amazon Chime SDK 會議中傳送彈性管道訊息
[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html) API 會在子通道層級建立訊息。若要傳送訊息，您必須擁有 `subChannelId`。您也可以使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_UpdateChannelMessage.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_UpdateChannelMessage.html)、 和 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_RedactChannelMessage.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_RedactChannelMessage.html) API 來編輯和刪除訊息，但在所有情況下，您必須擁有 `subChannelId`。 APIs
**注意**
訊息寄件者只有在屬於傳送訊息的子通道時，才能編輯或修訂訊息。如果成員平衡將成員轉移到另一個子通道，則該成員只能編輯或修改他們在新子通道中傳送的訊息。
# 了解 Amazon Chime SDK 會議彈性管道中的 WebSocket 系統訊息
Amazon Chime SDK 會針對在頻道中發生的事件，將系統訊息傳送至所有連線的用戶端。下列清單說明彈性頻道的系統訊息。
**訊息事件**
彈性頻道的事件承載包含 `subChannelId` 欄位。非彈性頻道的承載保持不變。
**成員事件**
`CREATE_CHANNEL_MEMBERSHIP` 和 `DELETE_CHANNEL_MEMBERSHIP`事件現在在其承載中具有 `subChannelId` 欄位。
彈性頻道不支援 `BATCH_CREATE_CHANNEL_MEMBERHSIP`事件。當您呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_BatchCreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_BatchCreateChannelMembership.html) API 時，系統會傳送個別`CREATE_CHANNEL_MEMBERSHIP`事件。
您現在可以使用 `UPDATE_CHANNEL_MEMBERSHIP` 事件類型來表示成員資格資訊中的變更。例如，在成員從一個子通道轉移到另一個子通道期間，系統會傳送承載`SubChannelId`中具有新 `UPDATE_CHANNEL_MEMBERSHIP`的事件，以指出成員已轉移。
系統只會將`UPDATE_CHANNEL_MEMBERSHIP`事件傳送給已傳輸的成員，而不是子通道的其他成員。因此，我們建議您使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ListChannelMemberships.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ListChannelMemberships.html) API 而非 WebSockets 來填入您的頻道成員資格名單。如需詳細資訊，請參閱 [使用 WebSockets Amazon Chime SDK 訊息中接收訊息](websockets.md)。
# 使用 Kinesis 串流接收 Amazon Chime SDK 會議的系統訊息
您可以設定 `AppInstance` 來接收串流形式的資料。例如，串流可以包含訊息、子頻道事件和頻道事件。
為此，我們支援 `CREATE_SUB_CHANNEL`和 `DELETE_SUB_CHANNEL`事件。它們表示在成員資格平衡過程中建立或刪除子頻道的時間。如需接收資料串流的詳細資訊，請參閱 [在 Amazon Chime SDK 訊息中串流訊息資料](streaming-export.md)。
# 在我們的示範應用程式中測試 Amazon Chime SDK 會議的彈性管道
您可以在 GitHub 上測試所有 Amazon Chime SDK 傳訊功能，網址為 https：//[https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/chat](https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/chat)。
# 使用 Amazon Chime SDK 訊息的行動推播通知來接收訊息
您可以設定 Amazon Chime SDK Messaging 將頻道訊息傳送到行動推播通知頻道。Amazon Chime SDK 需要為推送通知設定的 Amazon Pinpoint 應用程式。您的 Amazon Pinpoint 應用程式必須符合下列先決條件：
+ 您的 Amazon Pinpoint 應用程式必須至少設定並啟用 FCM 或 APNS 頻道。
+ 您的 Amazon Pinpoint 應用程式必須與 Amazon Chime SDK 應用程式執行個體位於相同的 AWS 帳戶和區域。
**注意**
根據預設，推播通知管道的所有成員都會收到推播通知，包括訊息寄件者。不過，您可以設定篩選條件規則，防止訊息傳送至寄件者。如需詳細資訊，請參閱本節稍後的 [使用篩選規則篩選 Amazon Chime SDK 訊息的訊息](filter-msgs.md)。
**Topics**
+ [
# 為 Amazon Chime SDK 訊息建立 Amazon Pinpoint 應用程式
](create-pinpoint.md)
+ [
# 建立 Amazon Chime SDK 訊息的服務角色
](create-service-role.md)
+ [
# 將行動裝置端點註冊為 Amazon Chime SDK 訊息的應用程式執行個體使用者
](register-endpoint.md)
+ [
# 傳送頻道訊息，並在 Amazon Chime SDK 訊息中啟用通知
](send-channel-msg-with-notifications.md)
+ [
# 在 Amazon Chime SDK 訊息中接收推播通知
](receive-notifications.md)
+ [
# 對 Amazon Chime SDK 訊息的推送通知失敗進行偵錯
](debug-notifications.md)
+ [
# 使用篩選規則篩選 Amazon Chime SDK 訊息的訊息
](filter-msgs.md)
# 為 Amazon Chime SDK 訊息建立 Amazon Pinpoint 應用程式
若要傳送推送通知，Amazon Chime SDK 需要設定 Amazon Pinpoint 應用程式，才能將推送傳送至您的行動應用程式。下列步驟說明如何使用 AWS 主控台來建立 Pinpoint 應用程式。
**建立 Amazon Pinpoint 應用程式**
1. 登入 AWS 管理主控台，並在 [https://console.aws.amazon.com/pinpoint/](https://console.aws.amazon.com/pinpoint/)：// 開啟 Amazon Pinpoint 主控台。
如果這是您第一次使用 Amazon Pinpoint，您會看到服務功能的介紹頁面。
1. 在 **Get started (入門)** 區段中，輸入專案的名稱，然後選擇 **Create a project (建立專案)**。
1. 在**設定功能**頁面上，於**推送通知**旁邊選擇**設定**。
1. 在**設定推送通知**頁面上，切換 **Apple 推送通知服務 (APNs)**、**Firebase Cloud Messaging (FCM)** 或兩者，並填寫必要欄位。
**重要**
Amazon Chime SDK 目前僅支援傳送推播通知至 APNs和 FCM。
1. 完成時，選擇**儲存**。
1. 返回位於 https：//[https://console.aws.amazon.com/pinpoint/](https://console.aws.amazon.com/pinpoint/) 的 Amazon Pinpoint 主控台，並記下**專案 ID** 值。您可以使用它做為 Amazon Pinpoint 應用程式的 ARN。
# 建立 Amazon Chime SDK 訊息的服務角色
AWS 使用 服務角色來授予 AWS 服務的許可，使其可以存取 AWS 資源。您連接到服務角色的政策會決定服務可存取哪些資源，以及該服務可以如何處理這些資源。您為 Amazon Chime SDK 建立的服務角色提供服務許可，以`SendMessages`呼叫您的 Amazon Pinpoint 應用程式。
**若要建立服務角色**
1. 登入 AWS 管理主控台，並在 https：//[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。
1. 在導覽窗格中，選擇 **Policies (政策)**，然後選擇 **Create Policy (建立政策)**。
1. 選擇 **JSON** 索引標籤，並將以下政策複製到文字方塊。請務必將 `project_id`取代為上一個步驟中建立之 Amazon Pinpoint 應用程式的 ID，並將 `aws_account_id`取代為 AWS 您的帳戶 ID。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Action": "mobiletargeting:SendMessages",
"Resource": "arn:aws:mobiletargeting:us-east-1:123456789012:apps/project_id/messages",
"Effect": "Allow"
}
}
```
------
1. 選擇下**一步：標籤**。
1. 選擇**下一步：檢閱**，然後在**AmazonChimePushNotificationPolicy****名稱**欄位中輸入 ，然後選擇**建立政策**。
1. 在導覽窗格中，選擇**角色**，然後選擇**建立角色**。
1. 在**建立角色**頁面上，選擇**AWS 服務**，開啟**選擇使用者案例**清單，然後選擇 **EC2**。
1. 選擇**下一步：許可**，然後在搜尋方塊中輸入 **AmazonChimePushNotificationPolicy**，然後選取政策旁的核取方塊。
1. 選擇下**一步：標籤**。
1. 選擇**下一步：檢閱**，然後在**ServiceRoleForAmazonChimePushNotification****名稱**欄位中輸入 。
**重要**
您必須使用上面列出的名稱。Amazon Chime SDK 只接受該特定名稱。
1. 選擇**建立角色**，然後在**角色**頁面上。**ServiceRoleForAmazonChimePushNotification**在搜尋方塊中輸入 ，然後選擇相符的角色。
1. 選擇**信任關係**索引標籤，選擇**編輯信任關係**，並將現有政策取代為下列政策。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "messaging.chime.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. 選擇 **Update Trust Policy** (更新信任政策)。
**重要**
透過變更名稱、許可政策或信任政策來修改角色，可能會中斷推播通知功能。
# 將行動裝置端點註冊為 Amazon Chime SDK 訊息的應用程式執行個體使用者
若要接收推播通知，應用程式執行個體使用者必須先使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_RegisterAppInstanceUserEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_RegisterAppInstanceUserEndpoint.html) API 來註冊行動裝置。他們必須從可存取裝置作業系統的裝置字符的行動應用程式註冊。
為了確保應用程式執行個體 使用者可存取 ARN 中列出的 Amazon Pinpoint 應用程式，使用者必須具有在 Amazon Pinpoint ARN `mobiletargeting:GetApp`上呼叫 的許可。否則，Amazon Chime SDK 會在呼叫 時擲回 403 禁止錯誤[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_RegisterAppInstanceUserEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_RegisterAppInstanceUserEndpoint.html)。
此範例顯示註冊端點所需的政策。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "PermissionToRegisterEndpoint",
"Effect": "Allow",
"Action": "chime:RegisterAppInstanceUserEndpoint",
"Resource": "arn:aws:chime:us-east-1:123456789012:app-instance/app_instance_id/user/app_instance_user_id"
},
{
"Sid": "PermissionToGetAppOnPinpoint",
"Effect": "Allow",
"Action": "mobiletargeting:GetApp",
"Resource": "arn:aws:mobiletargeting:us-east-1:123456789012:apps/project_id"
}
]
}
```
------
**註冊端點**
+ 使用 Amazon Pinpoint ARN 和您的裝置字符來呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_RegisterAppInstanceUserEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_RegisterAppInstanceUserEndpoint.html) API。
# 傳送頻道訊息，並在 Amazon Chime SDK 訊息中啟用通知
[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html) API 具有選用屬性，Amazon Chime SDK 會使用此`PushNotification`屬性來建置推送通知以傳送至 Amazon Pinpoint。目前，Amazon Chime SDK 僅支援通知標題和內文欄位。
Amazon Chime SDK 也支援 APNs VoIP 推送。若要傳送推送通知做為 APNs VoIP 推送，請將 `PushNotification` 屬性中的 類型設定為 VOIP。
# 在 Amazon Chime SDK 訊息中接收推播通知
除了頻道訊息推送通知標題和內文之外，Amazon Chime SDK 還在資料承載中包含頻道訊息 ID 和頻道 ARN。您可以使用該資訊來載入完整的頻道訊息。
下列範例顯示典型的推送通知承載。
```
{
"pinpoint.openApp=true",
"pinpoint.notification.title=PushNotificationTitle",
"pinpoint.notification.body=PushNotificationBody",
"pinpoint.campaign.campaign_id=_DIRECT",
"pinpoint.notification.silentPush=0",
"pinpoint.jsonBody="{
"chime.message_id":"ChannelMessageId",
"chime.channel_arn":"ChannelARN"
}
}
```
## 停用或篩選推送通知回條
Amazon Chime SDK 提供多種選項，可讓應用程式執行個體使用者控制他們是否想要接收推送通知。
**停用所有推送通知**
應用程式執行個體使用者可以呼叫 `AllowMessages` 並將 屬性[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_UpdateAppInstanceUserEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_UpdateAppInstanceUserEndpoint.html)設定為 ，以完全停用推送通知`NONE`。
**停用頻道的推送通知**
應用程式執行個體使用者可以透過呼叫 PushNotification 偏好設定欄位中的 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelMembershipPreferences.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelMembershipPreferences.html) 來停用特定頻道`NONE`的推送通知。 **PushNotification **
**篩選頻道的推送通知**
應用程式執行個體使用者可以設定篩選規則，以便他們只使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelMembershipPreferences.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelMembershipPreferences.html) API 接收特定的推送通知。如需詳細資訊，請參閱 [使用篩選規則篩選 Amazon Chime SDK 訊息的訊息](filter-msgs.md)。
# 對 Amazon Chime SDK 訊息的推送通知失敗進行偵錯
Amazon Chime SDK 與 Amazon EventBridge 整合，以通知您推送訊息交付失敗。若要進一步偵錯失敗，您也可以查看 Amazon Pinpoint 針對失敗傳送的 [CloudWatch 指標](https://docs.aws.amazon.com/pinpoint/latest/userguide/monitoring-metrics.html)。
下表列出並說明交付錯誤訊息。
| 訊息 | Description |
| --- | --- |
| 由於不明的錯誤、例外狀況或故障，處理請求失敗。 | 我們遭遇了內部錯誤。請再試一次。 |
| 找不到指定的資源。AppInstanceUserEndpoint 將停用。 | Amazon Pinpoint 應用程式不存在。 |
| 傳送至 Amazon Pinpoint 的請求太多。 | Amazon Pinpoint 已調節您的傳出訊息。 |
| 無法傳送訊息。請驗證 ServiceRoleForAmazonChimePushNotification 上的 IAM 許可政策。 | 為 Amazon Chime SDK 建立的角色沒有呼叫 的許可`mobiletargeting:SendMessages`。請驗證角色上的 IAM 政策。 |
| 無法傳送訊息。請驗證 ServiceRoleForAmazonChimePushNotification 上的 IAM 信任關係。 | Amazon Chime SDK 沒有存取 角色以進行推送通知的許可。 請確認 IAM 角色的信任政策包含服務主體 `messaging.chime.amazonaws.com`。 |
# 使用篩選規則篩選 Amazon Chime SDK 訊息的訊息
Amazon Chime SDK 支援在應用程式執行個體使用者的頻道成員資格上設定篩選規則，以限制他們將接收的訊息。篩選條件規則是在頻道成員資格上設定，並根據訊息屬性映射執行。訊息屬性映射必須是字串索引鍵對字串值的映射。篩選條件規則支援包含和排除與確切的字串比對。
**重要**
Amazon Chime SDK 僅支援逸出的 JSON 字串做為篩選條件規則。
通知管道的所有成員都會收到推播通知，包括訊息寄件者。若要防止這種情況發生，請參閱下列第一個範例規則。
若要設定頻道成員資格的篩選規則，請使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelMembershipPreferences.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutChannelMembershipPreferences.html) API。您可以在頻道訊息中包含訊息屬性，做為 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html) API 呼叫的一部分。
**Topics**
+ [
## 篩選規則類型
](#filter-rule-types)
+ [
## 篩選規則限制
](#filter-rule-limits)
+ [
## 範例篩選條件規則
](#example-preference-rule)
## 篩選規則類型
Amazon Chime SDK 支援以下類型的篩選規則：
+ 包含確切字串比對
+ 獨佔的確切字串比對
+ 使用 AND 或 OR 的多個篩選規則
## 篩選規則限制
Amazon Chime SDK 對篩選規則實施下列限制：
+ 我們僅支援確切的字串比對。
+ 總篩選條件規則大小為 2KB。
+ 訊息屬性大小總計為 1KB。
+ OR 篩選條件規則內最多有五 (5) 個不同的限制條件。
+ 整個篩選規則的最大複雜性為 20。*複雜度*的計算方式為篩選規則中索引鍵和值的數量總和：
例如，此篩選規則的複雜性為 4。
```
"FilterRule": "{\"type\":[{\"anything-but\": [\"Room\"]}],\"mention\":[\"Bob\"]}
```
我們會計算該值，如下所示：
```
Keys = “type” and “mention” - Complexity 2
Values = "Room" and "Bob" - Complexity 2
Total complexity = 4
```
## 範例篩選條件規則
下列範例顯示數種使用頻道成員偏好設定和篩選規則的方式。
**防止訊息傳送至寄件者**
此篩選規則會將訊息傳送給訊息寄件者以外的所有頻道成員。
```
{
"Preferences": {
"PushNotifications": {
"FilterRule": "{\"type\":[{\"anything-but\": [\"USER_ARN\"]}]}",
"AllowNotifications": "FILTERED"
}
}
}
```
具有上述偏好設定的應用程式執行個體使用者會收到具有下列屬性的頻道訊息：
```
"MessageAttributes": {
"senderId": {
"StringValues": ["USER_ARN"]
}
}
```
**包含字串比對**
此篩選規則允許具有訊息屬性索引鍵「mention」和值「Bob」的任何訊息。
```
{
"Preferences": {
"PushNotifications": {
"FilterRule": "{\"mention\":[\"Bob\"]}",
"AllowNotifications": "FILTERED"
}
}
}
```
具有上述偏好設定的應用程式執行個體使用者會收到具有下列訊息屬性的頻道訊息：
```
"MessageAttributes": {
"mention": {
"StringValues": ["Bob", "Alice"]
}
}
```
不過，應用程式執行個體使用者不會收到具有下列屬性的頻道訊息：
```
"MessageAttributes": {
"mention": {
"StringValues": ["Tom"]
}
}
```
**獨佔字串比對**
此篩選規則允許包含屬性索引鍵「類型」和值「房間」以外的任何訊息。
```
{
"Preferences": {
"PushNotifications": {
"FilterRule": "{\"type\":[{\"anything-but\": [\"Room\"]}]}",
"AllowNotifications": "FILTERED"
}
}
}
```
具有這些偏好設定的應用程式執行個體使用者會收到具有下列訊息屬性的頻道訊息：
```
"MessageAttributes": {
"type": {
"StringValues": ["Conversation"]
}
}
```
不過，應用程式執行個體使用者不會看到具有下列屬性的頻道訊息：
```
"MessageAttributes": {
"type": {
"StringValues": ["Room"]
}
}
```
**具有 AND 邏輯的多個篩選條件規則**
當您將篩選條件規則與 AND 邏輯結合時，訊息必須符合篩選條件套用的所有篩選條件條件。
```
{
"Preferences": {
"PushNotifications": {
"FilterRule": "{\"type\":[{\"anything-but\": [\"Room\"]}],\"mention\":[\"Bob\"]}",
"AllowNotifications": "FILTERED"
}
}
}
```
具有上述偏好設定的應用程式執行個體使用者會收到具有下列訊息屬性的頻道訊息：
```
"MessageAttributes": {
"mention": {
"StringValues": ["Bob"]
},
"type": {
"StringValues": ["Conversation"]
}
}
```
**具有 OR 邏輯的多個篩選條件規則**
您可以使用 `$or` 將篩選條件規則與 OR 邏輯結合。當您使用 OR 邏輯時，訊息必須符合篩選條件套用的其中一個條件。
```
{
"Preferences": {
"PushNotifications": {
"FilterRule": "{\"$or\":[{\"mention\":[\"Bob\"]},{\"type\":[{\"anything-but\": [\"Room\"]}]}]}",
"AllowNotifications": "FILTERED"
}
}
}
```
具有上述偏好設定的應用程式執行個體使用者會收到具有下列訊息屬性的頻道訊息：
```
"MessageAttributes": {
"mention": {
"StringValues": ["Bob"]
}
}
```
具有上述偏好設定的應用程式執行個體使用者會收到具有下列訊息屬性的頻道訊息：
```
"MessageAttributes": {
"type": {
"StringValues": ["Conversation"]
}
}
```
# 針對 Amazon Chime SDK 訊息使用服務連結角色
Amazon Chime SDK 使用 AWS Identity and Access Management (IAM) [ 服務連結角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role)。服務連結角色是一種獨特的 IAM 角色類型，可直接連結至 Amazon Chime SDK。Amazon Chime SDK 會預先定義服務連結角色，其中包含服務代表您呼叫其他 AWS 服務所需的所有許可。
服務連結角色可讓設定 Amazon Chime SDK 更有效率，因為您不需要手動新增必要的許可。Amazon Chime SDK 會定義其服務連結角色的許可，除非另有定義，否則只有 Amazon Chime SDK 可以擔任其角色。已定義的許可包括信任和許可政策。許可原則無法附加到其他任何 IAM 實體。
您必須先刪除角色的相關資源，才能刪除服務連結角色。這可保護您的 Amazon Chime SDK 資源，因為您不會不小心移除存取資源的許可。
關於支援服務連結角色的其他服務，如需相關資訊，請參閱[搭配 IAM 使用的AWS 服務](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html)。尋找**服務連結角色**欄中顯示 **Yes** (是) 的服務。選擇有連結的**是**，以檢視該服務的文件。
**Topics**
+ [
# 在 Amazon Chime SDK 訊息中使用服務連結角色進行資料串流
](stream-service-linked.md)
# 在 Amazon Chime SDK 訊息中使用服務連結角色進行資料串流
下列各節說明如何管理資料串流的服務連結角色。
**Topics**
+ [
## 服務連結角色許可
](#role-permissions)
+ [
## 建立服務連結角色
](#create-service-linked-role)
+ [
## 編輯服務連結角色
](#editing-roles)
+ [
## 刪除服務連結角色使用的資源
](#cleaning-up)
+ [
## 刪除服務連結角色
](#deleting-roles)
## 服務連結角色許可
Amazon Chime SDK 使用名為 的服務連結角色**AWSServiceRoleForChimeSDKMessaging**。此角色會授予 Amazon Chime SDK 使用或管理之 AWS 服務的存取權，例如用於資料串流的 Kinesis 串流。
**AWSServiceRoleForChimeSDKMessaging** 服務連結角色信任下列服務，以便這些服務可以擔任該角色：
+ messaging.chime.amazonaws.com
角色許可政策允許 Amazon Chime SDK 對指定的資源完成下列動作：
+ `kms:GenerateDataKey` 只有在使用 提出請求時`kinesis.*.amazonaws.com`。
+ `kinesis:PutRecord`、 `kinesis:PutRecords`或 `kinesis:DescribeStream`僅適用於下列格式的串流：`arn:aws:kinesis:*:*:stream/chime-messaging-*`。
下列範例顯示 政策。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kms:GenerateDataKey"
],
"Resource": "*",
"Condition": {
"StringLike": {
"kms:ViaService": [
"kinesis.*.amazonaws.com"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"kinesis:PutRecord",
"kinesis:PutRecords",
"kinesis:DescribeStream"
],
"Resource": [
"arn:aws:kinesis:*:*:stream/chime-messaging-*"
]
}
]
}
```
------
您必須設定許可，以允許使用者、群組或角色等 IAM 實體建立、編輯或刪除服務連結角色。如需詳細資訊，請參閱《*IAM 使用者指南*》中的[服務連結角色許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#service-linked-role-permissions)。
## 建立服務連結角色
您不需要手動建立服務連結角色，當您使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutMessagingStreamingConfigurations.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_PutMessagingStreamingConfigurations.html) API 建立資料串流組態時，Amazon Chime SDK 會為您建立服務連結角色。
您也可以使用 IAM 主控台，透過 Amazon Chime SDK 使用案例建立服務連結角色。在 AWS CLI 或 AWS API 中，使用服務名稱建立`messaging.chime.amazonaws.com`服務連結角色。如需詳細資訊，請參閱《*IAM 使用者指南*》中的[建立服務連結角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#create-service-linked-role)。如果您刪除此角色，您可以重複此程序以再次建立該角色。
## 編輯服務連結角色
建立服務連結角色之後，您只能編輯其描述，並使用 IAM 執行此操作。如需詳細資訊，請參閱[《IAM 使用者指南》中的編輯服務連結角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#edit-service-linked-role)。 **
## 刪除服務連結角色使用的資源
在您使用 IAM 刪除服務連結角色之前，您必須先刪除該角色所使用的任何資源。
**注意**
如果您在 Amazon Chime SDK 使用資源時嘗試刪除資源，刪除可能會失敗。如果刪除失敗，請等待幾分鐘，然後重試操作。
**刪除AmazonChimeServiceChatStreamingAccess角色使用的資源**
執行下列 CLI 命令來關閉應用程式執行個體的資料串流：
+ `aws chime-sdk-messaging delete-messaging-streaming-configurations --app-instance-arn app_instance_arn`
此動作會刪除應用程式執行個體的所有串流組態。
## 刪除服務連結角色
當您不再需要需要服務連結角色的功能或服務時，最佳實務是刪除該角色。否則，您有一個未使用的實體未受到主動監控或維護。不過，您必須先刪除服務連結角色所使用的資源，才能手動刪除角色。
您可以使用 IAM 主控台 AWS CLI或 AWS API 來刪除**AmazonChimeServiceRoleForChimeSDKMessaging**服務連結角色。如需詳細資訊，請參閱[《IAM 使用者指南》中的刪除服務連結角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#delete-service-linked-role)。
# 使用頻道流程來處理 Amazon Chime SDK 訊息
您使用頻道流程在傳輸中的訊息上執行商業邏輯，然後再交付給訊息頻道中的收件人。管道流程可以執行動作，例如從訊息中移除政府 ID 號碼、電話號碼或褻瀆。您也可以使用頻道流程來執行函數，例如在將結果傳回給參與者之前彙總輪詢的回應。
**先決條件**
+ 了解基本的 Amazon Chime SDK 功能，例如管理頻道，以及傳送和接收訊息。
+ 能夠叫用 Amazon Chime SDK 訊息 APIs。
**頻道流程概念**
若要有效使用頻道流程，您必須了解這些概念：
**通道處理器**
對頻道訊息執行預先處理邏輯的 AWS Lambda 函數。當您將頻道與頻道流程建立關聯時，會針對頻道中的每個訊息調用流程中的處理器。為了減少延遲，單一處理器最適合大多數使用案例。最後，每個處理器都必須在處理完成後回呼 Amazon Chime SDK 服務。
我們目前每個頻道流程僅支援一個處理器。如果您需要多個處理器，請提交增加的支援票證。
**頻道流程**
頻道流程是最多三個頻道處理器的容器，加上執行序列。您可以將流程與頻道建立關聯，而處理器會對傳送至該頻道的所有訊息採取動作。
**叫用頻道流程**
下列項目會叫用頻道流程：
+ 新的持久性標準訊息
+ 新的非持久性標準訊息
+ 更新持續性標準訊息
**注意**
頻道流程不會處理控制或系統訊息。如需 Amazon Chime SDK Messaging 所提供訊息類型的詳細資訊，請參閱 [了解 Amazon Chime SDK 訊息類型](msg-types.md)。
**Topics**
+ [
# 設定 Amazon Chime SDK 訊息的頻道處理器
](processor-setup.md)
+ [
# 建立 Amazon Chime SDK 訊息的頻道流程
](create-channel-flow.md)
+ [
# 關聯和取消關聯 Amazon Chime SDK 訊息的頻道流程
](associate-channel-flow.md)
+ [
# 在 Amazon Chime SDK 訊息中傳送訊息
](sending-msgs.md)
+ [
# 使用 EventBridge for Amazon Chime SDK 訊息自動建立失敗提醒
](event-bridge-events.md)
# 設定 Amazon Chime SDK 訊息的頻道處理器
若要開始使用頻道流程，請先建立處理器 Lambda 函數來處理使用案例的預先處理。例如，您可以更新訊息內容或中繼資料、拒絕訊息並防止傳送，或讓原始訊息通過。
**先決條件**
+ Lambda 函數必須位於與 AppInstance 相同的 AWS 帳戶和相同 AWS 區域。
**授予調用許可**
您必須授予 Amazon Chime SDK 訊息服務調用 Lambda 資源的許可。如需許可的詳細資訊，請參閱[使用 的資源型政策 AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html)。例如：
**委託人**：「messaging.chime.amazonaws.com」
**動作**：lambda：InvokeFunction
**Effect (效果)**：允許
**AWS：SourceAccount**：*您的 AWS AccountId*。
**AWS：SourceArn**： `"arn:aws:chime:region:AWS AccountId: appInstance/"`
**注意**
您可以提供特定的應用程式執行個體 ID 來叫用您的處理器，或使用萬用字元來允許帳戶中的所有 Amazon Chime SDK 應用程式執行個體叫用您的處理器。
**授予回呼許可**
您也需要允許處理器 Lambda 函數呼叫 `ChannelFlowCallback` API。如需有關這樣做的資訊，請參閱 *AWS Lambda 開發人員指南*中的[AWS Lambda 執行角色](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html)。
您可以將內嵌政策新增至 Lambda 函數的執行角色。此範例允許處理器叫用 `ChannelFlowCallback API`。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"chime:ChannelFlowCallback"
],
"Resource": [
"arn:aws:chime:us-east-1:111122223333:appInstance/*"
]
}
]
}
```
------
**注意**
遵循 Lambda 函數的最佳實務。如需詳細資訊，請參閱下列主題：
[ 效能效率最佳實務](https://docs.aws.amazon.com/whitepapers/latest/serverless-architectures-lambda/performance-efficiency-best-practices.html)
[使用 的最佳實務 AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/best-practices.html)
[設定預留並行](https://docs.aws.amazon.com/lambda/latest/dg/configuration-concurrency.html#configuration-concurrency-reserved)
[非同步叫用](https://docs.aws.amazon.com/lambda/latest/dg/invocation-async.html)
**叫用處理器 Lambda 函數**
當使用者傳送訊息時，下列輸入請求會叫用處理器 Lambda 函數。
```
{
"EventType": "string"
"CallbackId": "string"
"ChannelMessage": {
"MessageId": "string",
"ChannelArn": "string",
"Content": "string",
"Metadata": "string",
"Sender":{
"Arn": "string",
"Name": "string"
},
"Persistence": "string",
"LastEditedTimestamp": "string",
"Type": "string",
"CreatedTimestamp": "string",
}
}
```
EventType
正在傳送至處理器的事件。此值為`CHANNEL_MESSAGE_EVENT`常數。
CallbackId
從處理器呼叫 `ChannelFlowCallback` API 時所使用的字符。
ChannelMessage
*ChannelArn* 頻道的 ARN
要處理*的內容* 訊息內容
*CreatedTimestamp* 訊息建立的時間
*LastEditedTimestamp* 訊息編輯 的時間
*MessageId* 訊息識別符
要處理的*中繼資料* 訊息中繼資料
*持續性* 布林值，可控制訊息是否保留在後端。有效值:`PERSISTENT | NON_PERSISTENT`
*寄件者* 訊息寄件者。類型： [identity 物件](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_Identity.html)。
*類型* 訊息類型。 ChannelFlow僅支援 `STANDARD` 訊息類型。有效值： `STANDARD`
處理器函數會決定每個訊息的下列項目。
+ 是否更新訊息內容、中繼資料或兩者
+ 是否拒絕訊息
+ 是否保持不變訊息
處理完成時，處理器 Lambda 函數會將結果傳回 Amazon Chime SDK Messaging 服務，以便將訊息傳送給所有收件人。訊息狀態會標示，`PENDING`直到處理器 Lambda 函數傳回結果為止。處理器 Lambda 函數有 48 小時可傳回結果。在此之後，我們無法保證訊息交付，且 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelFlowCallback.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelFlowCallback.html) API 會擲回禁止的例外狀況錯誤訊息。若要傳回結果，請叫用 `ChannelFlowCallback` API。
# 建立 Amazon Chime SDK 訊息的頻道流程
設定處理器後，您可以使用 Amazon Chime SDK Messaging APIs(Amazon Chime SDK Messaging API) 來建立頻道流程。您可以使用`Fallback`動作來定義如果頻道流程無法連線至處理器 Lambda 函數，是否停止或繼續處理。如果處理器有 的備用動作`ABORT`，處理器會將訊息狀態設定為 `FAILED`，而且不會傳送訊息。請注意，如果頻道流程序列中的最後一個處理器具有 的備用動作`CONTINUE`，則訊息會被視為已處理並傳送給頻道中的收件人。建立頻道流程後，您可以將其與個別頻道建立關聯。如需詳細資訊，請參閱 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelFlow.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelFlow.html) API 文件。
# 關聯和取消關聯 Amazon Chime SDK 訊息的頻道流程
當您將頻道與頻道流程建立關聯時，頻道流程中的處理器會預先處理傳送至頻道的所有訊息。您必須是頻道主持人或管理員，才能叫用頻道流程關聯和取消關聯 APIs。隨時記住這些事實。
+ 您可以隨時將最多 1 個頻道流程與頻道建立關聯。若要關聯頻道流程，請呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_AssociateChannelFlow.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_AssociateChannelFlow.html) API。
+ 若要取消頻道流程的關聯並停止頻道訊息的預先處理，請呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_DisassociateChannelFlow.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_DisassociateChannelFlow.html) API。
# 在 Amazon Chime SDK 訊息中傳送訊息
您可以使用 `SendChannelMessage` API 將訊息傳送到頻道。對於與頻道流程相關聯的頻道，處理器會指派下列其中一個狀態值。
| 訊息狀態 | Description |
| --- | --- |
| `SENT` | 已成功處理訊息。 |
| `PENDING` | 持續處理。 |
| `FAILED` | 處理失敗，因為無法連線處理器 Lambda 函數。 |
| `DENIED` | 訊息不會傳送。 |
**接收中繼狀態事件**
**Websocket 事件**
Websocket 事件成功建立連線後，會傳送至頻道。如需詳細資訊，請參閱 [使用 WebSockets Amazon Chime SDK 訊息中接收訊息](websockets.md)。
| 事件類型 | 狀態 | 收件人 | 備註 |
| --- | --- | --- | --- |
| `CREATE_CHANNEL_MESSAGE` | `SENT` | 所有頻道成員 | `SendChannelMessage` 預先處理成功的 API |
| `UPDATE_CHANNEL_MESSAGE` | `SENT` | 所有頻道成員 | `UpdateChannelMessage` 預先處理成功的 API |
| `PENDING_CREATE_CHANNEL_MESSAGE` | `PENDING` | 僅限訊息寄件者 | `SendChannelMessage` 持續預先處理的 API |
| `PENDING_UPDATE_CHANNEL_MESSAGE` | `PENDING` | 僅限訊息寄件者 | `UpdateChannelMessage` 具有持續預處理功能的 API |
| `FAILED_CREATE_CHANNEL_MESSAGE` | `FAILED` | 僅限訊息寄件者 | `SendChannelMessage` 預先處理失敗的 API |
| `FAILED_UPDATE_CHANNEL_MESSAGE` | `FAILED` | 僅限訊息寄件者 | `UpdateChannelMessage` 預處理失敗的 API |
| `DENIED_CREATE_CHANNEL_MESSAGE` | `DENIED` | 僅限訊息寄件者 | `SendChannelMessage` 具有處理器拒絕訊息的 API |
| `DENIED_UPDATE_CHANNEL_MESSAGE` | `DENIED` | 僅限訊息寄件者 | `UpdateChannelMessage` 具有處理器拒絕訊息的 API |
**GetChannelMessageStatus API**
如果因為 Websocket 連線錯誤而未收到事件，此 API 會提供另一種擷取訊息狀態的方式。如需詳細資訊，請參閱 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetChannelMessageStatus.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetChannelMessageStatus.html) API 文件。
**注意**
此 API 不會傳回拒絕訊息的狀態，因為我們不會儲存它們。
# 使用 EventBridge for Amazon Chime SDK 訊息自動建立失敗提醒
當呼叫處理器 Lambda 函數時發生錯誤時，Amazon Chime SDK 會交付事件。無論建立頻道流程時為處理器指定的`Fallback`動作為何，都會傳送事件。您可以撰寫簡單的規則來指定這些事件，以及當任何這些事件符合規則時要採取的自動化動作。如需詳細資訊，請參閱[「Amazon EventBridge 使用者指南」](https://docs.aws.amazon.com/eventbridge/latest/userguide/)。當發生這類錯誤時，根據您設定`Fallback`的動作，頻道上的成員無法傳送訊息，或者訊息會流經頻道而不處理。如需 `Fallback`動作的詳細資訊，請參閱《Amazon Chime SDK API 參考[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_Processor.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_Processor.html)》中的 。
此範例顯示典型的失敗事件。
```
{
"version": "0",
"id": "12345678-1234-1234-1234-111122223333",
"detail-type": "Chime ChannelFlow Processing Status",
"source": "aws.chime",
"account": "111122223333",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "region",
"resources": [],
"detail": {
"eventType": "ProcessorInvocationFailure",
"appInstanceArn": "arn:aws:chime:region:AWSAccountId:app-instance/AppInstanceId",
"channelArn": "arn:aws:chime:region:AWSAccountId:app-instance/AppInstanceId/channel/ChannelId",
"messageId": "298efac7298efac7298efac7298efac7298efac7298efac7298efac7298efac7",
"processorResourceArn": "arn:aws:lambda:region:AWSAccountId:function:ChannelFlowLambda",
"failureReason": "User is not authorized to perform: lambda:InvokeFunction on resource: arn:aws:lambda:region:AppInstanceId:function:ChannelFlowLambda because no resource-based policy allows the lambda:InvokeFunction action"
}
}
```
# 使用 AppInstanceBots 做為 Amazon Chime SDK 訊息的智慧型頻道代理程式
您可以使用 `AppInstanceBots`做為智慧型頻道代理程式。客服人員會辨識管道成員透過 傳送`ChannelMessages`的金鑰片語。機器人的自然語言理解模型會解析訊息。反之，這可讓一或多個頻道成員參與由機器人模型定義的自然語言對話方塊。您提供機器人，以便控制對話方塊的深度以及與企業系統的整合。
**先決條件**
+ 了解基本的 Amazon Chime SDK 功能，例如建立 `AppInstanceUsers`、管理頻道，以及傳送和接收訊息。
+ 調用 Amazon Chime SDK 訊息 APIs的功能。
+ 了解基本的 Amazon Lex V2 功能，例如建立 Amazon Lex V2 機器人、建立意圖和槽模型、建立機器人版本、別名、使用工作階段狀態和 Lambda 勾點整合。
**重要**
Amazon Lex V2 的使用受 [AWS 服務條款](https://aws.amazon.com/service-terms/)的約束，包括 AWS Machine Learning 和人工智慧服務的特定條款。
**Topics**
+ [
# 為 Amazon Chime SDK 訊息建立 Amazon Lex V2 機器人
](create-lex-bot.md)
+ [
# 設定 Amazon Chime SDK 訊息的 AppInstance 機器人
](appinstance-bot-setup.md)
+ [
# 為 Amazon Chime SDK 訊息的 AppInstanceBot 建立頻道成員資格
](channel-membership.md)
+ [
# 傳送訊息至適用於 Amazon Chime SDK 訊息的 AppInstanceBot
](message-appinstancebot.md)
+ [
# 處理來自 Amazon Lex for Amazon Chime SDK 訊息的訊息
](process-from-lexv2.md)
+ [
# 處理來自 AppInstanceBot for Amazon Chime SDK 訊息的回應
](process-response.md)
+ [
# 使用規則將事件傳送至 Amazon EventBridge 以取得 Amazon Chime SDK 訊息
](event-bridge-alerts.md)
+ [
# 針對使用 Amazon Lex V2 機器人設定用於 Amazon Chime SDK 訊息的 AppInstanceBots 進行故障診斷
](troubleshoot-lex-bots.md)
# 為 Amazon Chime SDK 訊息建立 Amazon Lex V2 機器人
若要使用 AppInstance 機器人做為代理程式，您必須先建立 Amazon Lex V2 機器人來管理智慧代理程式案例的對話方塊互動。若要開始建置 Amazon Lex V2 機器人，請參閱《[Amazon Lex V2 開發人員指南》中的 Amazon Lex V2 入門](https://docs.aws.amazon.com/lexv2/latest/dg/getting-started.html)。 *Amazon Lex V2 * 如需有關將 Amazon Lex V1 機器人遷移至 Amazon Lex V2 的資訊，請參閱 [Amazon Lex V1 遷移至 V2 指南](https://docs.aws.amazon.com/lexv2/latest/dg/migration.html)。
**Topics**
+ [
## 先決條件
](#lex-prereqs)
+ [
## 授予調用許可
](#invocation-perms)
+ [
# 建立 Amazon Chime SDK 訊息的歡迎意圖
](welcome-intent.md)
+ [
# 為 Amazon Chime SDK 訊息建立 Amazon Lex V2 機器人版本
](lex-versions.md)
+ [
# 為 Amazon Chime SDK 訊息建立 Amazon Lex V2 機器人別名
](lex-aliases.md)
## 先決條件
您的 Amazon Lex V2 機器人必須具備下列先決條件。
+ 您必須在支援 Amazon Lex V2 執行時間端點的 AWS 區域中建立機器人。
+ 您必須在與 和 相同的 AWS 帳戶和區域中建立機器人`AppInstance``AppInstanceBot`。
+ 機器人必須透過以資源為基礎的政策，將調用許可授予`messaging.chime.amazonaws.com`服務委託人。
+ 機器人可以建立歡迎意圖的模型。這允許 `AppInstanceBot` 在頻道中的成員資格時宣告本身及其功能。
+ 機器人應具有生產版本和別名，才能設定 `AppInstanceBot`。
+ 機器人必須使用支援的語言和地區設定。如需語言和地區設定的詳細資訊，請參閱《[Amazon Lex V2 開發人員指南》中的 Amazon Lex V2 支援的語言和地區設定](https://docs.aws.amazon.com/lexv2/latest/dg/how-languages.html)。 *Amazon Lex V2 *
## 授予調用許可
若要`AppInstanceBot`讓 叫用 Amazon Lex V2 機器人，Amazon Chime SDK 訊息服務主體必須具有叫用 Amazon Lex 機器人資源的許可。如需 Amazon Lex V2 資源型政策許可的詳細資訊，請參閱《[Amazon Lex V2 開發人員指南》中的 Amazon Lex V2 的資源型政策範例](https://docs.aws.amazon.com/lexv2/latest/dg/security_iam_resource-based-policy-examples.html)。 *Amazon Lex V2 *
下列範例顯示以資源為基礎的政策。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "messaging.chime.amazonaws.com"
},
"Action": [
"lex:PutSession",
"lex:DeleteSession",
"lex:RecognizeText"
],
"Resource": "arn:aws:lex:us-east-1:111122223333:bot-alias/lex-bot-id/lex-bot-alias-id",
"Condition": {
"StringEquals": {
"AWS:SourceAccount": "111122223333"
},
"ArnEquals": {
"AWS:SourceArn": "arn:aws:chime:us-east-1:111122223333:app-instance/app-instance-id/bot/app-instance-bot-id"
}
}
}
]
}
```
------
**注意**
若要允許一個 `AppInstanceBot` 叫用 Amazon Lex V2 機器人，請使用 AppInstanceBot 的 ID。若要允許 `AppInstanceBots`內的所有 `AppInstance` 叫用 Amazon Lex V2 機器人，請使用萬用字元。例如：
`arn:aws:chime:region:aws-account-id:app-instance/app-instance-id/bot/*`
# 建立 Amazon Chime SDK 訊息的歡迎意圖
如果您將選用的歡迎意圖新增至 Amazon Lex V2 機器人模型，您的 `AppInstanceBot`可以在加入頻道時宣告本身及其功能。歡迎意圖可以顯示訊息，也可以啟動具有頻道成員的對話方塊。歡迎意圖的名稱可能會有所不同，您可以在 AppInstanceBot 的組態中定義它。
如需意圖的詳細資訊，請參閱《*Amazon Lex V2 開發人員指南*》中的[新增意圖](https://docs.aws.amazon.com/lexv2/latest/dg/build-intents.html)
# 為 Amazon Chime SDK 訊息建立 Amazon Lex V2 機器人版本
當您建立 Amazon Lex V2 機器人時，您只會建立*草稿*版本。草稿是您可以更新之機器人的運作副本。根據預設，草稿版本會與名為 的別名相關聯`TestBotAlias`，您只應使用草稿機器人進行手動測試。
完成對話方塊建模並建置草稿機器人之後，您可以建立一或多個*版本*、已編號的草稿 Lex 機器人快照。版本可讓您控制用戶端應用程式使用的實作。例如，您可以發佈版本以用於工作流程的不同部分，例如開發、Beta 部署和生產。
如需 Lex 機器人版本控制的詳細資訊，請參閱《*Amazon Lex V2 開發人員指南*》中的[建立版本](https://docs.aws.amazon.com/lexv2/latest/dg/versions.html)。
# 為 Amazon Chime SDK 訊息建立 Amazon Lex V2 機器人別名
建立一或多個版本的 Amazon Lex V2 機器人後，即可建立*別名*。別名做為 Amazon Lex V2 機器人版本的具名指標。例如，您一次只能將別名與一個版本建立關聯。
如需 Lex 機器人別名的詳細資訊，請參閱 *Lex V2 開發人員指南*中的[建立別名](https://docs.aws.amazon.com/lexv2/latest/dg/aliases.html)。
# 設定 Amazon Chime SDK 訊息的 AppInstance 機器人
在您擁有具有模型、版本和別名的 Amazon Lex V2 機器人之後，您可以使用 Amazon Chime SDK 訊息 APIs 或 CLI 來建立 AppInstanceBot。如需使用 APIs的詳細資訊，請參閱 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_CreateAppInstanceBot.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_identity-chime_CreateAppInstanceBot.html) API 文件。
**注意**
您可以使用 `InvokedBy` 屬性來設定 的對話方塊互動行為`AppInstanceBot`。您可以設定觸發機器人的訊息類型，例如標準訊息或目標訊息。
下列範例示範如何使用 AWS CLI 來建立 AppInstanceBot，讓具有 `MENTIONS`和目標訊息的所有標準訊息都可以叫用。
```
aws chime-sdk-identity create-app-instance-bot \
--app-instance-arn app-instance-arn \
--name app-instance-bot-name \
--configuration '{
"Lex": {
"LexBotAliasArn": "lex-bot-alias-arn",
"LocaleId": "lex_bot_alias_locale_id",
"InvokedBy": {
"StandardMessages": "MENTIONS",
"TargetedMessages": "ALL"
}
"WelcomeIntent": "welcome-intent-name"
}
}
```
# 為 Amazon Chime SDK 訊息的 AppInstanceBot 建立頻道成員資格
建立 AppInstanceBot 後，您可以將它新增為新頻道或現有頻道的成員。如需詳細資訊，請參閱 *Amazon Chime SDK 訊息 API* 文件中的 [CreateChannel](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannel.html) 和 [ CreateChannelMembership](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html)。
下列範例示範如何使用 AWS CLI 建立頻道，並將 新增`AppInstanceBot`為成員。
```
aws chime-sdk-messaging create-channel \
--chime-bearer caller_app_instance_user_arn \
--app-instance-arn app_instance_arn \
--name channel_name \
--member-arns '[
"app_instance_bot_arn"
]'
```
下列範例示範如何使用 AWS CLI 將 `AppInstanceBot` 新增至現有頻道。
```
aws chime-sdk-messaging create-channel-membership \
--chime-bearer caller_app_instance_user_arn \
--channel-arn channel_arn \
--member-arn app_instance_bot_arn
```
# 傳送訊息至適用於 Amazon Chime SDK 訊息的 AppInstanceBot
您可以使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_SendChannelMessage.html) API 將訊息傳送至 AppInstanceBot。您可以將訊息傳送到 AppInstanceBot 為成員的頻道。如果[自然語言理解模型](https://docs.aws.amazon.com/lexv2/latest/dg/what-is.html)辨識訊息內容並引發 Amazon Lex 意圖，AppInstanceBot 會以頻道訊息回應並啟動對話方塊。
您也可以將目標訊息傳送至頻道的成員，可以是 AppInstanceUser 或 AppInstanceBot。只有目標和寄件者可以檢視目標訊息。只有可以看到目標訊息的使用者才能對其採取動作。不過，管理員可以刪除他們看不到的目標訊息。
下列範例示範如何使用 AWS CLI 傳送頻道訊息。
```
aws chime-sdk-messaging send-channel-message \
--chime-bearer caller_app_instance_user_arn \
--channel-arn channel_arn \
--content content \
--type STANDARD \
--persistence PERSISTENT
```
# 處理來自 Amazon Lex for Amazon Chime SDK 訊息的訊息
傳送訊息至 Amazon Lex 時，Amazon Chime SDK Messaging 會將頻道和寄件者的 ARN 資訊填入 `CHIME.channel.arn`和 `CHIME.sender.arn`，做為請求屬性。您可以使用屬性來判斷誰傳送訊息，以及寄件者所屬的頻道。如需詳細資訊，請參閱《*Amazon Lex 開發人員指南*》中的[使用 AWS Lambda 函數啟用自訂邏輯](https://docs.aws.amazon.com/lexv2/latest/dg/lambda.html)。
# 處理來自 AppInstanceBot for Amazon Chime SDK 訊息的回應
當使用者傳送訊息時，AppInstanceBot 會以頻道訊息回應。您可以列出頻道訊息，以取得機器人的回應。
下列範例顯示使用 CLI 列出頻道訊息。
```
aws chime-sdk-messaging list-channel-messages \
--chime-bearer caller_app_instance_user_arn \
--channel-arn channel_arn
```
AppInstanceBot 的成功回應採用下列格式。
```
{
"MessageId": "messageId",
"Content": "*{\"Messages\":[{\"...\"}]}*",
"ContentType": "application/amz-chime-lex-msgs",
"MessageAttributes": {
"CHIME.LEX.sessionState.intent.name": {
"StringValues": [
"lex_bot_intent_name"
]
},
"CHIME.LEX.sessionState.intent.state": {
"StringValues": [
"lex_bot_intent_fullfilment_status"
]
},
"CHIME.LEX.sessionState.originatingRequestId": {
"StringValues": [
"lex_bot_originating_request_id"
]
},
"CHIME.LEX.sessionState.sessionId": {
"StringValues": [
"lex_bot_session_id"
]
}
},
"Sender": {
"Arn": "app_instance_bot_arn",
"Name": "app_instance_bot_name"
},
"Type": "STANDARD",
}
```
**Content**
`Content` 欄位包含來自 Amazon Lex V2 機器人的訊息清單。如需這些訊息的詳細資訊，請參閱 Amazon Lex V2 `RecognizeText` API 中的[訊息](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_runtime_RecognizeText.html#lexv2-runtime_RecognizeText-response-messages)。
下列範例示範如何在歡迎訊息中使用 `Content` 欄位。
```
{
"Messages":
[
{
"Content": "Hello!",
"ContentType": "PlainText"
},
{
"ContentType": "ImageResponseCard",
"ImageResponseCard":
{
"Title": "Hello! I'm BB, the Bank Bot.",
"Subtitle": "I can help you with the following transactions",
"Buttons":
[
{
"Text": "Check balance",
"Value": "Check balance"
},
{
"Text": "Escalate to agent",
"Value": "Escalate to agent"
}
]
}
}
]
}
```
對於失敗回應，內容欄位包含以下格式的錯誤訊息和程式碼：
```
{
"Code": error_code
}
```
**ContentType**
`ContentType` 是指`Content`欄位包含的承載類型，必須勾選才能剖析`Content`欄位。
Lex V2 機器人使用不同的 `ContentType`。
`ContentType` 設定為 `application/amz-chime-lex-msgs` 以取得成功回應，或`application/amz-chime-lex-error`設定為失敗回應。
**MessageAttribute**
*MessageAttribute* 是字串索引鍵對字串值的映射。的回應`AppInstanceBot`包含下列映射至 Amazon Lex 機器人回應的訊息屬性。
+ **CHIME.LEX.sessionState.intent.name** – 請求嘗試履行的 Lex 機器人意圖名稱。
+ **CIFNE.LEX.sessionState.intent.state** – 意圖的目前狀態。可能的值包括：`Fulfilled`、 `InProgress`和 `Failed`。
+ **CIFNE.LEX.sessionState.originatingRequestId** – 對 Amazon Lex 機器人提出特定請求的唯一識別符。這是設定為觸發 AppInstanceBot `MessageId` 之原始使用者訊息的 。
+ **CIFNE.LEX.sessionState.sessionId** – 使用者與機器人之間對話的唯一識別符。當使用者開始與您的機器人聊天時，Amazon Lex 會建立工作階段。
如需 Amazon Lex 工作階段和工作階段狀態的詳細資訊，請參閱《*Amazon Lex API 參考*[https://docs.aws.amazon.com/lexv2/latest/APIReference/API_runtime_SessionState.html](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_runtime_SessionState.html)》中的 和《Amazon Lex V2 開發人員指南》中的[管理工作階段](https://docs.aws.amazon.com/lexv2/latest/dg/using-sessions.html)。 * Amazon Lex V2 *
如需 Amazon Lex V2 傳回屬性的詳細資訊，請參閱 [Amazon Lex 執行期 V2](https://docs.aws.amazon.com/lexv2/latest/APIReference/API_Operations_Amazon_Lex_Runtime_V2.html) APIs。
# 使用規則將事件傳送至 Amazon EventBridge 以取得 Amazon Chime SDK 訊息
當錯誤阻止它叫用 Amazon Lex V2 機器人時，Amazon Chime SDK 會提供 EventBridge 事件。 V2 您可以建立識別這些事件的 EventBridge 規則，並在規則相符時自動採取行動。如需詳細資訊，請參閱[《Amazon EventBridge 使用者指南](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rules.html)*》中的 Amazon EventBridge *規則。
下列範例顯示典型的失敗事件。
```
{
version: '0',
id: '12345678-1234-1234-1234-111122223333',
'detail-type': 'Chime Messaging AppInstanceBot Lex Failure',
source: 'aws.chime',
account: 'aws-account-id',
time: 'yyyy-mm-ddThh:mm:ssZ',
region: "region",
resources: [],
detail: {
resourceArn: 'arn:aws:chime:region:aws-account-id:app-instance/app-instance-id/bot/app-instance-bot-id',
failureReason: "1 validation error detected: Value at 'text' failed to satisfy constraint: Member must have length less than or equal to 1024 (Service: LexRuntimeV2, Status Code: 400, Request ID: request-id)"
}
}
```
# 針對使用 Amazon Lex V2 機器人設定用於 Amazon Chime SDK 訊息的 AppInstanceBots 進行故障診斷
下列主題說明如何疑難排解 AppInstanceBots 的常見問題。
## 尋找 Amazon Lex V2 失敗
當錯誤阻止 Amazon Lex V2 [機器人叫用時，Amazon Chime SDK 訊息傳送 Amazon EventBridge 事件](https://docs.aws.amazon.com/chime-sdk/latest/dg/event-bridge-alerts.html)。 V2 如需設定規則和設定通知目標的詳細資訊，請參閱《[Amazon EventBridge 使用者指南](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-get-started.html)*》中的 Amazon EventBridge *入門。
如果您在 AWS CloudWatch Logs 中收到 EventBridge 事件，您可以使用 AWS CloudWatch Logs Insights 根據 Amazon Chime SDK 訊息詳細資訊類型查詢 EventBridge 事件。`failureReason` 列出失敗的原因。
下列範例顯示典型查詢。
```
fields @timestamp, @message
| filter `detail-type` = "Chime Messaging AppInstanceBot Lex Failure"
| sort @timestamp desc
```
如果 Amazon Chime SDK Messaging 可以叫用您的 Amazon Lex V2 機器人，則 SDK 會傳送訊息`CONTROL`並顯示錯誤訊息。
## 對 Amazon Lex V2 機器人許可錯誤進行故障診斷
若要讓 AppInstanceBot 叫用 Amazon Lex V2 機器人，Amazon Chime SDK 訊息服務主體必須具有叫用 Amazon Lex V2 機器人資源的許可。此外，請確定資源政策條件`AWS:SourceArn`的 符合 AppInstanceBot 的 ARN。
如需設定 AppInstanceBot 以叫用 Amazon Lex V2 機器人的詳細資訊，請參閱本節[為 Amazon Chime SDK 訊息建立 Amazon Lex V2 機器人](create-lex-bot.md)稍早的 。
## 對 Amazon Lex V2 機器人限流進行故障診斷
Amazon Lex 具有每個機器人別名的並行文字模式對話數量上限的服務配額。您可以聯絡 Amazon Lex 服務團隊以增加配額。如需詳細資訊，請參閱《[Amazon Lex 開發人員指南》中的 Amazon Lex 準則和配額](https://docs.aws.amazon.com/lexv2/latest/dg/quotas.html)。 *Amazon Lex *
# 管理 Amazon Chime SDK 訊息的訊息保留
帳戶擁有者可以使用 Amazon Chime SDK APIs 來開啟訊息的保留。系統會根據管理員設定的期限自動刪除訊息。保留期可以持續一天到 15 年。您也可以使用 APIs隨時更新訊息保留期或關閉訊息保留期。
**Topics**
+ [
## CLI 保留命令範例
](#retention-examples)
+ [
## 啟用訊息保留
](#enable-retention)
+ [
## 還原和刪除訊息
](#restore-and-delete)
## CLI 保留命令範例
下列範例顯示用於保留的典型 CLI 命令：
**啟用**
`aws chime-sdk-identity put-app-instance-retention-settings --app-instance-arn {appInstanceArn} --app-instance-retention-settings ChannelRetentionSettings={RetentionDays=60}`
**更新中**
`aws chime-sdk-identity put-app-instance-retention-settings --app-instance-arn {appInstanceArn} --app-instance-retention-settings ChannelRetentionSettings={RetentionDays=30}`
**停用**
`aws chime-sdk-identity put-app-instance-retention-settings --app-instance-arn {appInstanceArn} --app-instance-retention-settings ChannelRetentionSettings={}`
## 啟用訊息保留
您可以使用 Amazon Chime SDK APIs來開啟訊息的保留。您也可以使用 APIs隨時更新訊息保留期或關閉訊息保留期。如需設定訊息保留的詳細資訊，請參閱 [Amazon Chime SDK API 參考](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/Welcome.html)。
## 還原和刪除訊息
您可以在設定或更新訊息保留期的 30 天內還原訊息給使用者。不過，在該 30 天的寬限期之後，屬於保留期間的所有訊息都會永久刪除，而新訊息會在超過保留期間後立即永久刪除。
**注意**
在 30 天的寬限期內，如果您延長保留政策或將其關閉，則帳戶中的使用者會再次看到未超過新保留期間的訊息。
當 刪除頻道或訊息時，也會永久`AppInstanceUser`刪除訊息。
# Amazon Chime SDK 訊息的使用者介面元件
您可以使用元件程式庫來減少建置聊天訊息使用者介面所需的工作量。如需詳細資訊，請參閱 GitHub 上的 [Amazon Chime React 元件程式庫](https://github.com/aws/amazon-chime-sdk-component-library-react)。
# 將 Amazon Chime SDK 訊息與用戶端程式庫整合
若要使用 Amazon Chime SDK 的訊息功能，您必須將用戶端應用程式與下列用戶端程式庫整合：
+ **AWS SDK** – 包含用於傳送訊息和管理資源APIs。
+ 適用於** JavaScript 的 Amazon Chime SDK 用戶端程式庫 (NPM)** – 具有 TypeScript 類型定義的 JavaScript 程式庫，可協助您整合用戶端與 Amazon Chime SDK 訊息 Web 通訊端以接收訊息。
若要整合您的用戶端應用程式與 Amazon Chime SDK，請參閱用戶端程式庫 https：//README.md。
# 搭配 JavaScript 使用 Amazon Chime SDK 訊息
您可以使用 JavaScript 來管理 Amazon Chime SDK 資源並傳送訊息。如需詳細資訊，請參閱 [AWS JavaScript 開發套件](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Chime.html)。
您也可以在用戶端應用程式中建立訊息工作階段，以接收來自 Amazon Chime SDK 訊息的訊息。如需詳細資訊，請參閱[在 GitHub 上使用適用於 JavaScript 的 Amazon Chime SDK 用戶端程式庫](https://github.com/aws/amazon-chime-sdk-js/blob/master/README.md)。 GitHub