本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 Amazon Chime SDK 的呼叫分析從呼叫產生洞見
本節中的主題說明如何使用 Amazon Chime SDK 呼叫分析從您的呼叫資料產生洞見。
Amazon Chime SDK 呼叫分析為開發人員提供低程式碼解決方案，從即時音訊產生符合成本效益的洞見，包括音訊擷取、分析、提醒和資料湖整合。通話分析可讓您透過與 Amazon Transcribe 和 Transcribe Call Analytics (TCA) 整合，以及原生透過 Amazon Chime SDK 語音分析產生洞見。呼叫分析也可以記錄對 Amazon S3 儲存貯體的呼叫。
您可以使用下列方法來設定和執行通話分析。
+ 使用 Amazon Chime SDK 主控台建立通話分析組態，並將其與 Amazon Chime SDK Voice Connector 建立關聯。在該過程中，您可以啟用通話記錄和分析。您不需要編寫程式碼即可完成程序。
+ 使用一組 Amazon Chime SDK APIs [Amazon Chime SDK](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/welcome.html) APIs，以程式設計方式建立和執行組態。
如需詳細資訊，請參閱本節[使用 Amazon Chime SDK 的通話分析組態](using-call-analytics-configurations.md)稍後的 [為 Amazon Chime SDK 建立通話分析組態](creating-ca-configuration.md)和 。
**Topics**
+ [什麼是 Amazon Chime SDK 呼叫分析](what-is-amazon-chime-sdk-call-analytics.md)
+ [了解 Amazon Chime SDK 的通話分析術語](ca-terms-concepts.md)
+ [為 Amazon Chime SDK 建立通話分析組態](creating-ca-configuration.md)
+ [使用 Amazon Chime SDK 的通話分析組態](using-call-analytics-configurations.md)
+ [管理 Amazon Chime SDK 的通話分析管道](managing-call-analytics-pipelines.md)
+ [暫停和繼續 Amazon Chime SDK 的通話分析管道](pausing-and-resuming-call-analytics-pipelines.md)
+ [使用 Amazon Chime SDK 的呼叫分析資源存取角色](call-analytics-resource-access-role.md)
+ [了解 Amazon Chime SDK 的通話分析狀態](call-analytics-statuses.md)
+ [使用 Amazon CloudWatch 監控 Amazon Chime SDK 的通話分析管道](monitoring-with-cloudwatch.md)
+ [呼叫 Amazon Chime SDK 的分析處理器和輸出目的地](call-analytics-processor-and-output-destinations.md)
+ [Amazon Chime SDK 的呼叫分析資料模型](ca-data-model.md)
+ [使用 Amazon Chime SDK 語音分析](voice-analytics.md)
+ [Amazon Chime SDK 的呼叫分析服務配額](ca-regions.md)
# 什麼是 Amazon Chime SDK 呼叫分析
Amazon Chime SDK 呼叫分析是一種低程式碼解決方案，可從即時音訊產生符合成本效益的洞見，包括音訊擷取、錄音、語音分析、提醒和資料湖的功能。您可以使用通話分析產生機器學習支援的洞見，方法是建立可重複使用的通話分析組態，以決定要為工作流程啟用哪些 AWS 機器學習整合和音訊處理功能。然後，您可以將呼叫分析組態與各種媒體來源搭配使用，例如 Voice Connectors 或 Amazon Kinesis Video Streams。通話分析透過與 Amazon Transcribe 和 Transcribe 通話分析 (TCA) 整合，以及原生透過 [Amazon Chime SDK 語音分析](voice-analytics.md)產生洞見，這是在通話分析下執行的服務。
請依照下列步驟使用通話分析：
![\[本圖顯示設定 Amazon Chime SDK 呼叫分析的程序。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/CallAnalyticsOverview.png)
在圖表中：
1. 首先建立通話分析組態。
1. 您可以設定輸出目的地和選用的資料湖。
1. 您可以建立將組態與語音連接器和 Amazon Kinesis Video Streams 建立關聯的工作流程。
1. 您可以分析並選擇性地將洞見視覺化。
您可以使用 Amazon Chime SDK 主控台來建立通話分析組態，並讓通話分析自動啟動。如果您需要控制適用於指定呼叫類型的組態，您可以使用 APIs來建立組態。無論哪種方式，組態都包含要針對通話音訊叫用之 AWS 機器學習服務的詳細資訊、啟用通話錄音，以及洞見、中繼資料和錄音的目的地。通話分析提供下列目的地：
+ Amazon Kinesis Data Stream (KDS)。您可以使用 KDS 來接收即時通話洞見，然後將其整合到您的應用程式。例如，您可以整合即時洞見，在客戶通話期間協助銷售或客戶支援客服人員，或使用洞見來增強生成式 AI 提示和摘要。
+ 設定為資料倉儲的 Amazon S3 儲存貯體。儲存貯體會以 Parquet 格式存放資料。Parquet 是一種開放原始碼檔案格式，旨在壓縮和存放大量資料。然後，您可以使用 Amazon Athena 使用簡單查詢語言 (SQL) 查詢該資料，或將資料移至現有的資料倉儲，以與您的業務資料配對。例如，您可以執行通話後彙總分析，以了解客戶通話的有效性、產品的問題領域，或訓練員工實現更佳客戶成果的機會。
除了這些目的地之外， 呼叫分析還支援您可以根據洞察預先設定的即時提醒。提醒會傳送至 Amazon EventBridge。
**注意**
當您建立通話分析組態時，不會選取特定的音訊來源。這可讓您重複使用多個音訊來源的組態。例如，組態可以啟用通話錄音並提供通話轉錄。然後，您可以透過 Kinesis Video Stream 搭配 Chime SDK Voice Connector 和音訊串流使用組態。您也可以在多個語音連接器之間共用組態。每個呼叫分析組態都是唯一的，並由 ARN 識別。
# 了解 Amazon Chime SDK 的通話分析術語
下列術語和概念對於了解如何使用 Amazon Chime SDK 呼叫分析至關重要。
**Amazon Athena**
一種互動式查詢服務，可讓您使用標準 SQL 分析 Amazon S3 中的資料。Athena 是無伺服器，因此您不需要管理基礎設施，您只需為執行的查詢付費。若要使用 Athena，請指向 Amazon S3 中的資料、定義結構描述，並使用標準 SQL 查詢。您也可以使用工作群組來將使用者分組，並控制他們在執行查詢時可存取的資源。工作群組可讓您管理查詢並行，並排定不同使用者和工作負載群組的查詢執行優先順序。如需詳細資訊，請參閱[什麼是 Amazon Athena](https://docs.aws.amazon.com/athena/latest/ug/what-is.html)。
**Amazon Kinesis Data Firehose**
擷取、轉換和載入 (ETL) 服務，可可靠地擷取、轉換串流資料，並將資料交付至資料湖、資料存放區和分析服務。如需詳細資訊，請參閱[什麼是 Amazon Kinesis Data Firehose](https://aws.amazon.com/kinesis/data-firehose/)。
**呼叫分析資料倉儲**
用於呼叫分析資料的選用儲存體。倉儲會將資料以 parquet 為基礎的資料檔案格式存放在 Amazon S3 儲存貯體中。您可以使用標準 SQL 來查詢資料。您可以在呼叫分析組態中啟用倉儲。
**Glue Data Catalog**
跨各種資料來源之資料資產的集中式中繼資料儲存庫。目錄包含資料庫和資料表。對於呼叫分析，資料表中的中繼資料會告知 Athena Amazon S3 儲存貯體的位置。它也會指定資料結構，例如資料欄名稱、資料類型和資料表的名稱。資料庫只會保留資料集的中繼資料和結構描述資訊。如需詳細資訊[了解 Amazon Chime SDK AWS Glue 的資料目錄資料表結構](ca-data-model-diagram.md)，請參閱本節稍後的 。
**媒體洞見管道**
由唯一 識別的暫時資源`MediaPipelineId`。使用呼叫分析管道組態和執行時間參數建立。執行時間參數會指定管道的資料來源。
**媒體洞察管道組態**
用來建立媒體洞見管道的靜態組態。您可以使用組態來執行個體化一或多個管道。
**媒體洞察管道組態元素**
媒體洞察管道組態元素包含使用處理器元素處理媒體的說明，或使用接收器元素提供產生的洞察。
**媒體洞見管道任務**
媒體洞見管道的臨時子資源。任務會保留特定串流 ARN 和頻道 ID 程序狀態的相關中繼資料。以唯一 ID 識別。透過在媒體洞察管道上啟動語音分析來建立。
**發言者搜尋**
語音分析功能，可協助您辨識通話參與者。
**語音分析**
Amazon Chime SDK 功能，包括發言者搜尋和語音音調分析。
**語音內嵌**
來電者語音的向量表示法，加上唯一的 ID。
**語音增強功能**
增強通話音訊品質的系統。
**語音設定檔**
語音內嵌、其 ID 及其過期日期的組合。
**語音設定檔網域**
語音設定檔的集合。
**語音音調分析**
一種語音分析功能，可讓您分析 `positive`、 `negative`或 `neutral` 情緒的來電者語音。
如需用於建立通話洞察組態、啟動管道和執行語音分析APIs 的詳細資訊，請參閱[《Amazon Chime SDK API 參考》中的 Amazon Chime SDK 媒體管道](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Media_Pipelines.html)。 **
**注意**
我們強烈建議使用媒體洞察管道 APIs來執行通話分析，因為只有這些 APIs提供新功能。如需媒體管道和語音命名空間之間差異的詳細資訊，請參閱本節[使用語音 APIs執行 Amazon Chime SDK 的語音分析](va-in-voice-namespace.md)稍後的 。
# 為 Amazon Chime SDK 建立通話分析組態
若要使用通話分析，請先建立*組態*，這是保留建立通話分析管道所需資訊的靜態結構。您可以使用 Amazon Chime SDK 主控台來建立組態，或呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html) API。
通話分析組態包含音訊處理器的詳細資訊，例如錄音、語音分析或 Amazon Transcribe。它還包含洞見目的地和提醒事件組態。或者，您可以將呼叫資料儲存至 Amazon S3 儲存貯體以進行進一步分析。
不過，*組態不包含特定的音訊來源*。這可讓您在多個通話分析工作流程中重複使用組態。例如，您可以將相同的通話分析組態與不同的語音連接器或不同的 Amazon Kinesis Video Stream (KVS) 來源搭配使用。
當您透過語音連接器進行 SIP 呼叫，或將新媒體傳送至 Amazon Kinesis Video Stream (KVS) 時，您可以使用組態來建立管道。然後，管道會根據組態中的規格處理媒體。
您可以隨時以程式設計方式停止管道。當 Voice Connector 呼叫結束時，管道也會停止處理媒體。此外，您可以暫停管道。這樣做會停用對基礎 Amazon Machine Learning 服務的呼叫，並在需要時恢復它們。不過，通話錄音會在您暫停管道時執行。
下列各節說明建立通話分析組態的先決條件，以及如何建立組態。
**Topics**
+ [了解 Amazon Chime SDK 呼叫分析先決條件](ca-prerequisites.md)
+ [使用 Amazon Chime SDK 主控台建立通話分析組態](create-config-console.md)
+ [使用 APIs為 Amazon Chime SDK 建立呼叫分析組態](create-config-apis.md)
+ [將組態與 Amazon Chime SDK 的語音連接器建立關聯](ca-associate-vc-steps.md)
# 了解 Amazon Chime SDK 呼叫分析先決條件
建立通話分析組態之前，您必須具有下列項目。您可以使用 AWS 主控台來建立它們：
+ Amazon Chime SDK Voice Connector。如果沒有，請參閱[建立 Amazon Chime SDK 語音連接器](https://docs.aws.amazon.com/chime-sdk/latest/ag/ca-prerequisites.html)。您還必須：
+ 啟用語音連接器的串流。如需詳細資訊，請參閱《[Amazon Chime SDK 管理員指南》中的使用 EventBridge 自動化](https://docs.aws.amazon.com/chime-sdk/latest/ag/automating-chime-with-cloudwatch-events.html) Amazon Chime 開發套件 **
+ 設定語音連接器以使用通話分析。如需詳細資訊，請參閱《*Amazon Chime SDK 管理員指南*》中的[設定語音連接器以使用通話分析](https://docs.aws.amazon.com/chime-sdk/latest/ag/configure-voicecon.html)。
+ Amazon EventBridge 目標。如果沒有，請參閱[使用 EventBridge 監控 Amazon Chime SDK，Amazon](https://docs.aws.amazon.com/chime-sdk/latest/ag/automating-chime-with-cloudwatch-events.html) *Chime SDK 管理員指南*。
+ 服務連結角色，允許 Voice Connector 存取 EventBridge 目標上的動作。如需詳細資訊，請參閱《[Amazon Chime SDK 管理員指南》中的使用 Amazon Chime SDK Voice Connector 服務連結角色政策](https://docs.aws.amazon.com/chime-sdk/latest/ag/using-service-linked-roles-stream.html)。 **
+ Amazon Kinesis 資料串流。如果沒有，請參閱《Amazon Kinesis [ Streams 開發人員指南》中的建立和管理](https://docs.aws.amazon.com/streams/latest/dev/working-with-streams.html)串流。 *Amazon Kinesis * 語音分析和轉錄需要 Kinesis Data Stream。
+ 若要離線分析呼叫，您必須建立 Amazon Chime SDK 資料湖。若要這樣做，請參閱本指南[建立 Amazon Chime SDK 資料湖](ca-data-lake.md)稍後的 。
# 使用 Amazon Chime SDK 主控台建立通話分析組態
建立上一節中列出的先決條件之後，您可以使用 Amazon Chime SDK 主控台來建立一或多個通話分析組態。您也可以使用 主控台，將一或多個語音連接器與您的組態建立關聯。當您完成該程序時，呼叫分析會從您在建立組態時啟用的功能開始執行。
請依照下列步驟建立通話分析組態：
1. 指定組態詳細資訊，包括名稱和選用標籤。
1. 設定您的錄製設定。建立通話分析組態，其中包含錄製和機器學習支援的洞見。
1. 設定您的分析服務。
1. 選取輸出目的地以使用即時洞見。建立選用的資料湖來執行通話後分析。
1. 建立新的服務角色或使用現有的角色。
1. 設定即時提醒，在符合特定條件時透過 Amazon EventBridge 傳送通知。
1. 檢閱您的設定並建立組態
建立組態後，您可以透過將語音連接器與組態建立關聯來啟用通話分析。執行此操作後，當呼叫進入該語音連接器時，呼叫分析會自動開始。如需詳細資訊[將組態與 Amazon Chime SDK 的語音連接器建立關聯](ca-associate-vc-steps.md)，請參閱本節稍後的 。
下列各節說明如何完成程序的每個步驟。依列出的順序展開它們。
## 指定組態詳細資訊
**指定組態詳細資訊**
1. 在 https：//[https://console.aws.amazon.com/chime-sdk/home](https://console.aws.amazon.com/chime-sdk/home) 開啟 Amazon Chime 主控台。
1. 在導覽窗格的**通話分析**下，選擇**組態**，然後選擇**建立組態**。
1. 在**基本資訊**下，請執行下列動作：
1. 輸入組態的名稱。名稱應該反映您的使用案例和任何標籤。
1. （選用） 在**標籤**下，選擇**新增標籤**，然後輸入您的標籤索引鍵和選用值。您可以定義索引鍵和值。標籤可協助您查詢組態。
1. 選擇**下一步**。
## 設定錄製
**設定錄製**
+ 在**設定記錄**頁面上，執行下列動作：
1. 選擇**啟用通話錄音**核取方塊。這可記錄語音連接器呼叫或 KVS 串流，並將資料傳送至 Amazon S3 儲存貯體。
1. 在**檔案格式**下，選擇**具有 PCM 的 WAV** 以獲得最佳音訊品質。
—或—
選擇 **OGG 搭配 OPUS** 來壓縮音訊並最佳化儲存。
1. （選用） 視需要選擇**建立 Amazon S3 儲存貯**體連結，然後依照下列步驟建立 Amazon S3 儲存貯體。
1. 輸入 Amazon S3 儲存貯體的 URI，或選擇**瀏覽**以尋找儲存貯體。
1. （選用） 選擇**啟用語音增強**功能，以協助改善錄音的音訊品質。
1. 選擇**下一步**。
## 了解語音增強功能
建立通話分析組態時，您可以啟用通話錄音，並將錄製的通話存放在 Amazon S3 儲存貯體中。除此之外，您也可以啟用語音增強功能，並改善已儲存通話的音訊品質。語音增強功能僅適用於啟用此功能後產生的錄音。當語音增強功能處於作用中狀態時，除了原始錄音之外，還會建立增強型錄音，並以相同的 Amazon S3 儲存貯體和格式儲存。語音增強功能將為長達 30 分鐘的通話產生增強型錄音。對於超過 30 分鐘的呼叫，不會產生增強型錄音。
電話會經過窄頻帶篩選，並以 8 KHz 取樣。語音增強功能可將取樣率從 8kHz 提升為 16kHz，並使用機器學習模型將頻率內容從窄頻擴展到寬頻，讓語音更自然。語音增強也使用名為 Amazon Voice Focus 的降噪模型，以協助降低增強音訊中的背景雜訊。
語音增強功能也會使用名為 Voice Focus 的降噪模型。此模型有助於降低增強型音訊中的背景雜訊。語音增強會將模型套用至升級的 16 KHz 音訊。
**注意**
語音增強功能僅支援美國東部 （維吉尼亞北部） 區域和美國西部 （奧勒岡） 區域。
語音增強錄製中繼資料會透過您設定的 KDS 發佈到現有的 AWS Glue 資料目錄資料表 *call\$1analytics\$1recording\$1metadata*。若要從語音增強型通話錄音識別原始通話錄音記錄，名為 *detail-subtype* 且值為 *VoiceEnhancement* 的新欄位會新增至 KDS 通知和黏附資料表 *call\$1analytics\$1recording\$1metadata*。如需資料倉儲結構描述的詳細資訊，請參閱 [Amazon Chime SDK 的呼叫分析資料模型](ca-data-model.md)。
### 語音增強檔案格式
請注意下列有關增強型錄製檔案的事項。
+ 增強型錄音會寫入與一般錄音相同的 Amazon S3 儲存貯體。您可以透過呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_S3RecordingSinkConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_S3RecordingSinkConfiguration.html)或 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_S3RecordingSinkRuntimeConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_S3RecordingSinkRuntimeConfiguration.html)APIs，或使用 Amazon Chime SDK 主控台來設定目的地。
+ 增強型錄製會將 **\$1enhanced** 附加到基本檔案名稱。名稱。
+ 增強型錄製會保留與原始錄製相同的檔案格式。您可以透過呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_S3RecordingSinkConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_S3RecordingSinkConfiguration.html)或 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_S3RecordingSinkRuntimeConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_S3RecordingSinkRuntimeConfiguration.html) APIs，或使用 Amazon Chime SDK 主控台來設定檔案格式。
下列範例顯示典型的檔案名稱格式。
```
s3://original_file_name_enhanced.wav
```
或
```
s3://original_file_name_enhanced.ogg
```
## 設定分析服務
Amazon Transcribe 提供通話的文字轉錄。然後，您可以使用文字記錄來增強其他機器學習服務，例如 Amazon Comprehend 或您自己的機器學習模型。
**注意**
Amazon Transcribe 也提供自動語言辨識。不過，您無法將此功能與自訂語言模型或內容修訂搭配使用。此外，如果您搭配其他功能使用語言識別，您只能使用這些功能支援的語言。如需詳細資訊，請參閱《*Amazon Transcribe 開發人員指南*》中的[使用串流轉錄進行語言識別](https://docs.aws.amazon.com/transcribe/latest/dg/lang-id-stream.html)。
Amazon Transcribe Call Analytics 是一種機器學習支援的 API，可提供通話文字記錄、情緒和即時對話洞察。此服務不需要做筆記，而且可以對偵測到的問題啟用立即動作。此服務也提供通話後分析，例如來電者情緒、通話驅動程式、非通話時間、中斷、通話速度和對話特性。
**注意**
根據預設，通話後分析會將通話錄音串流到您的 Amazon S3 儲存貯體。為了避免建立重複的錄音，請勿同時啟用通話錄音和通話後分析。
最後，轉錄通話分析可以根據特定片語自動標記對話，並協助修訂音訊和文字的敏感資訊。如需呼叫分析媒體處理器、這些處理器產生的洞見和輸出目的地的詳細資訊[呼叫 Amazon Chime SDK 的分析處理器和輸出目的地](call-analytics-processor-and-output-destinations.md)，請參閱本節稍後的 。
**設定分析服務**
1. 在**設定分析服務**頁面上，選取**語音分析**或**轉錄服務**旁的核取方塊。您可以同時選取這兩個項目。
選取**語音分析**，核取方塊以啟用**發言者搜尋**和**語音音調分析**的任意組合。
選取**轉錄服務**核取方塊以啟用 Amazon Transcribe 或 Transcribe Call Analytics。
1. **啟用發言者搜尋**
+ 選取**是，我同意 Amazon Chime SDK 語音分析的同意確認**核取方塊，然後選擇**接受**。
1. 啟用語音音調分析
+ 選取**語音音調分析**核取方塊。
1. 啟用 Amazon Transcribe
1. 選擇 **Amazon Transcribe** 按鈕。
1. 在**語言設定**下，執行下列其中一項操作：
1. 如果您的來電者說的是單一語言，請選擇**特定語言**，然後開啟**語言**清單並選取語言。
1. 如果您的來電者說多種語言，您可以自動識別他們。選擇**自動語言偵測**。
1. 開啟**自動語言識別清單的語言選項**，並選取至少兩種語言。
1. （選用） 開啟**偏好語言**清單並指定偏好語言。當您在上一個步驟中選取的語言具有相符的可信度分數時，服務會轉錄偏好的語言。
1. （選用） 展開**內容移除設定**，選取一或多個選項，然後選擇一或多個出現的其他選項。協助程式文字說明每個選項。
1. （選用） 展開**其他設定**，選取一或多個選項，然後選擇一或多個顯示的其他選項。協助程式文字說明每個選項。
1. 啟用 Amazon Transcribe Call Analytics
1. 選擇 **Amazon Transcribe Call Analytics** 按鈕。
1. 開啟**語言**清單並選取語言。
1. （選用） 展開**內容移除設定**，選取一或多個選項，然後選擇一或多個顯示的其他選項。協助程式文字說明每個選項。
1. （選用） 展開**其他設定**，選取一或多個選項，然後選擇一或多個顯示的其他選項。協助程式文字說明每個選項。
1. （選用） 展開**通話後分析設定**並執行下列動作：
1. 選擇**通話後分析**核取方塊。
1. 輸入 Amazon S3 儲存貯體的 URI。
1. 選取內容修訂類型。
1. 完成選擇後，請選擇**下一步**。
## 設定輸出詳細資訊
完成媒體處理步驟後，您可以選取分析輸出的目的地。通話分析透過 Amazon Kinesis Data Streams 提供即時洞見，也可以選擇透過您選擇的 Amazon S3 儲存貯體中的資料倉儲。若要建立資料倉儲，您可以使用 CloudFormation 範本。範本可協助您建立基礎設施，將呼叫中繼資料和洞見交付至 Amazon S3 儲存貯體。如需建立資料倉儲的詳細資訊[建立 Amazon Chime SDK 資料湖](ca-data-lake.md)，請參閱本節稍後的 。如需資料倉儲結構描述的詳細資訊，請參閱本節[Amazon Chime SDK 的呼叫分析資料模型](ca-data-model.md)稍後的 。
如果您在上一節中啟用語音分析，也可以新增語音分析通知目的地，例如 AWS Lambda、Amazon Simple Queue Service 或 Amazon Simple Notification Service。下列步驟說明作法。
**設定輸出詳細資訊**
1. 開啟 **Kinesis 資料串流**清單，然後選取您的資料串流。
**注意**
如果您想要視覺化資料，則必須選取 Amazon S3 儲存貯體和 Amazon Kinesis Data Firehose 所使用的 Kinesis 資料串流。
1. （選用） 展開**其他語音分析通知目的地**，然後選取 AWS Lambda、Amazon SNS 和 Amazon SQS 目的地的任意組合。
1. （選用） 在**分析和視覺化洞**見下，選取**使用資料湖執行歷史分析**核取方塊。如需資料湖的詳細資訊，請參閱本節[建立 Amazon Chime SDK 資料湖](ca-data-lake.md)稍後的 。
1. 完成時，請選擇**下一步**。
## 設定存取許可
若要啟用呼叫分析，機器學習服務和其他資源必須具有存取資料媒體和提供洞見的許可。您可以使用現有的服務角色，或使用 主控台建立新的角色。如需角色的詳細資訊，請參閱本節[使用 Amazon Chime SDK 的呼叫分析資源存取角色](call-analytics-resource-access-role.md)稍後的 。
**設定存取許可**
1. 在**設定存取許可**頁面上，執行下列其中一項操作：
1. 選取**建立並使用新的服務角色**。
1. 在**服務角色名稱尾碼**方塊中，輸入角色的描述性尾碼。
—或—
1. 選取**使用現有的服務角色**。
1. 開啟**服務角色**清單，然後選取角色。
1. 選擇**下一步**。
## （選用） 設定即時提醒
**重要**
若要使用即時提醒，您必須先啟用 Amazon Transcribe 或 Amazon Transcribe Analytics。
您可以建立一組規則，將即時提醒傳送至 Amazon EventBridge。當 Amazon Transcribe 或 Amazon Transcribe Call Analytics 產生的洞見在分析工作階段期間符合您指定的規則時，就會傳送提醒。提醒具有詳細資訊類型 `Media Insights Rules Matched`。EventBridge 支援與下游服務整合，例如 Amazon Lambda、Amazon SQS 和 Amazon SNS，以觸發最終使用者的通知或啟動其他自訂商業邏輯。如需詳細資訊[針對 Amazon Chime SDK 使用 Amazon EventBridge 通知](using-eventbridge-notifications.md)，請參閱本節稍後的 。
**設定提醒**
1. 在**即時提醒**下，選擇**作用中即時提醒**。
1. 在**規則**下，選取**建立規則**。
1. 在**規則名稱**方塊中，輸入規則的名稱。
1. 開啟**規則類型**清單，然後選取您要使用的規則類型。
1. 使用出現的控制項將關鍵字新增至規則，並套用邏輯，例如**提及****或未提及**。
1. 選擇**下一步**。
## Review and create (檢閱和建立)
**建立組態**
1. 檢閱每個區段中的設定。視需要選擇**編輯**以變更設定。
1. 選擇**建立組態**。
您的組態會出現在 Amazon Chime SDK 主控台的**組態**頁面上。
# 使用 APIs為 Amazon Chime SDK 建立呼叫分析組態
您可以以程式設計方式建立 Voice Connectors 和呼叫分析組態，然後將其建立關聯，以啟動呼叫分析工作流程。本指南假設您知道如何撰寫程式碼。
您使用APIs 會根據工作流程類型而有所不同。例如，若要記錄音訊，請先呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html) API 來建立呼叫分析組態。然後，您可以呼叫 [CreateVoiceConnector](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceConnector.html) 來建立語音連接器。最後，您可以使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_PutVoiceConnectorStreamingConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_PutVoiceConnectorStreamingConfiguration.html) API 將組態與語音連接器建立關聯。
相反地，若要使用 Kinesis 視訊串流生產者記錄音訊，您可以呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html)，然後呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API。
如需使用通話分析組態啟用不同工作流程的詳細資訊，請參閱本節[使用 Amazon Chime SDK 的通話分析組態](using-call-analytics-configurations.md)稍後的 中的工作流程。
# 將組態與 Amazon Chime SDK 的語音連接器建立關聯
使用主控台建立通話分析組態之後，您可以透過將語音連接器與其建立關聯來使用組態。然後，語音連接器會自動呼叫您組態中指定的分析服務。Voice Connector 會叫用每個呼叫的呼叫分析。
**建立語音連接器的關聯**
1. 開啟位於 https：//[https://console.aws.amazon.com/chime-sdk/home](https://console.aws.amazon.com/chime-sdk/home) 的 Amazon Chime 主控台。
1. 在導覽窗格的 **SIP Trunking** 下，選擇**語音連接器**。
1. 選擇您要與組態建立關聯的語音連接器名稱，然後選擇**串流**索引標籤。
1. 如果尚未選取，請選擇**開始**以開始串流至 Kinesis Video Streams。
1. 在**通話分析**下，選取**啟用**，然後在顯示的功能表中選擇您的通話分析組態 ARN。
1. 選擇**儲存**。
**注意**
啟用、停用或修改與語音連接器相關聯的組態後，請等待 5 分鐘讓新設定透過服務傳播並生效。
如需有關呼叫分析組態的詳細資訊，請參閱《*Amazon Chime SDK 管理員指南*》中的[管理呼叫分析](https://docs.aws.amazon.com/chime-sdk/latest/ag/ag-call-analytics.html)。
如需使用通話分析組態啟用不同工作流程的詳細資訊[使用 Amazon Chime SDK 的通話分析組態](using-call-analytics-configurations.md)，請參閱本節稍後的 。
# 使用 Amazon Chime SDK 的通話分析組態
若要使用通話分析組態處理音訊，您必須建立通話分析管道，也稱為媒體洞察管道。在通話期間建立管道以處理音訊，並在通話結束時終止。通話分析管道需要通話分析組態的 ARN，以及音訊來源的相關資訊。通話分析組態包含音訊處理器、洞見目的地和提醒事件組態的詳細資訊，*但不包括音訊來源*。這可讓您在不同的通話分析工作流程中重複使用組態，例如使用不同的語音連接器或 KVS 來源。呼叫分析管道會叫用組態中指定的機器學習服務，並記錄音訊。您可以在通話結束時手動或自動停止管道。
您可以在各種使用案例中使用通話分析管道。下列工作流程顯示使用通話分析組態和管道的潛在方法。
**Topics**
+ [了解記錄 Amazon Chime SDK 呼叫的工作流程](recording-workflows.md)
+ [了解 Amazon Chime SDK 機器學習型分析的工作流程](ml-based-analytics.md)
# 了解記錄 Amazon Chime SDK 呼叫的工作流程
本節中的主題會列出並描述記錄通話和 Kinesis Video Streams 的工作流程。
# 錄製語音連接器呼叫
在下列情況下使用此工作流程：
+ 您已使用或計劃使用 Voice Connector 將 SIP 媒體帶入通話分析。
**注意**
Voice Connectors 支援 SIP 和 SIPREC。如需詳細資訊，請參閱《[Amazon Chime SDK 管理員指南》中的管理 Amazon Chime SDK 語音連接器](https://docs.aws.amazon.com/chime-sdk/latest/ag/voice-connectors.html)。 **
+ 您想要自動記錄對您選擇的 Amazon Simple Storage Service 目的地具有低延遲的 SIP 或 SIPREC 呼叫。
+ 您想要使用 Amazon Chime SDK 主控台來建立組態，並將其與語音連接器建立關聯。
+ 您想要將相同的錄製組態套用至每個 Voice Connector 呼叫。如果您想要將多個組態套用至一或多個語音連接器，請參閱下一節。
若要以程式設計方式啟用呼叫，請使用下列 Amazon Chime SDK APIs。
+ 使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html) API 建立呼叫分析組態
+ 使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceConnector.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceConnector.html) 建立語音連接器。
+ 使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_PutVoiceConnectorStreamingConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_PutVoiceConnectorStreamingConfiguration.html) API 將組態與語音連接器建立關聯。
如需詳細資訊，請參閱《*Amazon Chime SDK 管理員指南*》中的[設定語音連接器以使用通話分析](https://docs.aws.amazon.com/chime-sdk/latest/ag/configure-voicecon.html)。
下圖顯示語音連接器啟動通話錄音工作階段時的資料流程。圖表中的數字對應於下方的編號文字。
![\[此圖顯示語音連接器開始記錄通話時的資料流程。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/call-analytics-workflow-1.png)
在圖表中：
1. 使用 Amazon Chime SDK 主控台或 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html) API 來建立呼叫分析組態。在組態建立過程中，您只需啟用通話錄音、選擇所需的錄音檔案格式，以及指定 Amazon S3 目的地來存放錄音檔案。如需詳細資訊，請參閱《*Amazon Chime SDK 管理員指南*》中的[建立通話分析組態](https://docs.aws.amazon.com/chime-sdk/latest/ag/create-ca-config.html)。
1. 您可以使用 Amazon Chime SDK 主控台或 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_PutVoiceConnectorStreamingConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_PutVoiceConnectorStreamingConfiguration.html) API，將組態與語音連接器建立關聯。若要使用主控台，請參閱[設定語音連接器以使用通話分析](https://docs.aws.amazon.com/chime-sdk/latest/ag/configure-voicecon.html)。
1. 在外撥通話期間，語音連接器會收到每個通話參與者的音訊。
1. 如果通話分析錄音組態連接至 Voice Connector，則 Voice Connector 服務會使用媒體管道服務來啟動通話分析錄音工作階段。
1. 媒體管道服務會啟動通話錄音處理器，以監控正在進行的通話。
1. 當呼叫結束時，媒體管道服務會將呼叫記錄檔案交付至指定的 Amazon S3 儲存貯體，並透過 Amazon Kinesis Data Stream 提供記錄中繼資料。如果已啟用資料倉儲，呼叫中繼資料也會前往 Amazon Simple Storage Service 資料倉儲。如果使用 SIPREC 將 SIP 音訊納入通話分析，則通話中繼資料會以資料表格式包含 SIPREC 中繼資料。如需錄製資料表的詳細資訊，請參閱本節[了解 Amazon Chime SDK AWS Glue 的資料目錄資料表](glue-tables.md)稍後的 。
1. 媒體管道服務會將管道狀態事件傳送至預設的 Amazon EventBridge。如需詳細資訊，請參閱本指南中的[使用 EventBridge 通知](https://docs.aws.amazon.com/chime-sdk/latest/dg/ca-eventbridge-notifications.html)。
**注意**
請注意，您必須啟用 Voice Connector 串流，才能使用 Voice Connector 進行錄製。此功能可讓您將通話資料串流到帳戶中的 Voice Connector 受管 Kinesis Video Streams。如需詳細資訊，請參閱[《Amazon Chime SDK 管理員指南》中的將 Amazon Chime SDK Voice Connector 媒體串流至 Kinesis Video Streams](https://docs.aws.amazon.com/chime-sdk/latest/ag/start-kinesis-vc.html)。 **
您也可以將 Voice Connector 建立的通話資料存放在 Kinesis Video Streams 中，持續時間從數小時到數天甚至數年不等。選擇不保留資料會限制呼叫資料的可用性，以供立即使用。Kinesis Video Streams 的成本取決於使用的頻寬和總儲存體。您可以在 Voice Connector 串流組態內隨時調整資料保留期間。若要啟用通話分析記錄，您必須確保 Kinesis Video Stream 保留資料的時間足以執行通話分析。您可以透過指定適當的資料保留期來執行此操作。
您可以將通話洞見管道組態與任意數量的語音連接器建立關聯。您也可以為每個語音連接器建立不同的組態。Voice Connectors 使用 AWSServiceRoleForAmazonChimeVoiceConnector 為每個交易 ID 代表您呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API 一次。如需角色的相關資訊，請參閱《[Amazon Chime SDK 管理員指南》中的使用 Amazon Chime SDK Voice Connectors 的 Amazon Chime SDK 服務連結角色](https://docs.aws.amazon.com/chime-sdk/latest/ag/using-service-linked-roles-stream.html#service-linked-role-permissions-stream)。 **
# 使用 Amazon Kinesis Video 串流生產者進行錄製
在以下情況下，您會記錄 Amazon Kinesis Video 串流：
+ 您需要將不同的組態套用至呼叫，而不是針對每個 Voice Connector 呼叫使用相同的組態。
+ 您想要記錄語音連接器未處理的 SIP 或非 SIP 音訊。
若要使用此通話錄音選項，您需要將音訊發佈至 Kinesis Video Streams (KVS)，然後使用 KVS 串流頻道資訊和通話分析組態 ARN 呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API。
**注意**
呼叫分析 APIs 最多支援兩個音訊通道。您也可以啟用 Voice Connector 串流，然後使用在 Voice Connector 的 EventBridge 通知中發佈的 KVS 資訊來啟動通話錄音。
呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API 時，您可以選擇是否要為每個 KVS 串流頻道定義指定片段編號。如果您提供片段號碼，呼叫分析將開始處理該片段的串流。如果您未指定片段 ID，呼叫分析會開始處理來自最新可用片段的串流。
下圖顯示語音連接器啟動通話錄音工作階段時的資料流程。圖表中的數字對應於下方的編號文字。
![\[此圖顯示語音連接器開始記錄通話時的資料流程。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/call-analytics-workflow-2.png)
在圖表中：
1. 您可以使用 Amazon Chime SDK 主控台或 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html) API 來建立通話錄音組態。
1. 使用 AWS SDK 建立將外部音訊推送至 KVS 的應用程式，或啟用 Voice Connector 串流以自動將通話音訊發佈至 KVS。如需詳細資訊，請參閱[《Amazon Chime SDK 管理員指南》中的將 Amazon Chime SDK Voice Connector 媒體串流至 Kinesis Video Streams](https://docs.aws.amazon.com/chime-sdk/latest/ag/start-kinesis-vc.html)。 **
1. 如果啟用 Voice Connector 串流，語音連接器服務會將通知傳送至預設的 EventBridge。
1. 在 Voice Connector 串流的情況下，您的應用程式可以使用來自 EventBridge 的 Amazon Chime Voice Connector 串流`STARTED`事件來收集有關通話分支的 KVS 串流資訊。
1. 一旦應用程式擁有來自 Voice Connector 串流事件或外部來源的音訊資訊，您的應用程式就會叫用 Amazon Chime SDK [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API。
1. 媒體管道服務會啟動通話錄音處理器，以監控正在進行的通話。
1. 媒體管道服務會將管道狀態事件傳送至預設的 Amazon EventBridge。如需詳細資訊，請參閱[使用 EventBridge 通知](https://docs.aws.amazon.com/chime-sdk/latest/dg/ca-eventbridge-notifications.html)。
1. 通話完成後，媒體管道服務會將通話錄音檔案交付至指定的 Amazon S3 儲存貯體，並透過 Amazon Kinesis Data Stream 提供錄音中繼資料。如果已啟用資料倉儲，呼叫中繼資料也會傳送至 Amazon S3 資料倉儲。如果使用 SIPREC 將 SIP 音訊納入通話分析，則通話中繼資料將以方便的資料表格式包含 SIPREC 中繼資料。如需錄製資料表的詳細資訊，請參閱本節[了解 Amazon Chime SDK AWS Glue 的資料目錄資料表](glue-tables.md)稍後的 。
1. 您的應用程式可以監控管道，如果是 Voice Connector，則會使用發佈至 Amazon EventBridge 的事件來監控呼叫狀態。如需詳細資訊，請參閱本指南中的[使用 EventBridge 通知](https://docs.aws.amazon.com/chime-sdk/latest/dg/ca-eventbridge-notifications.html)。
1. 若要終止錄音，請呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaPipeline.html) API 以終止通話錄音。
如需 API 型錄製和範例，請參閱本指南中的 [Amazon S3 錄製目的地](https://docs.aws.amazon.com/chime-sdk/latest/dg/ca-processors-sinks.html#ca-s3-recording-sink)。
# 使用 CLI 開始錄製
本節中的範例說明如何執行下列動作：
+ 使用 CLI 執行呼叫分析組態並叫用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html)。
+ 使用 CLI 指定錄製目的地音訊檔案格式和音訊檔案名稱。
**Topics**
+ [執行組態並啟動管道](#cli-run-config)
+ [設定目的地、名稱和格式](#cli-set-buckets-formats)
## 執行組態並啟動管道
使用下列命令來執行組態並啟動媒體洞察管道。pipeline.json 檔案包含組態設定。
```
aws chime-sdk-media-pipeline create-media-insights-pipeline --cli-input-json file://pipeline.json
```
下列範例顯示典型`pipeline.json`檔案。
```
{
"MediaInsightsPipelineConfigurationArn": arn:aws:chime:region;account_id:media-insights-pipeline-configuration/MyConfiguration,
"KinesisVideoStreamRecordingSourceRuntimeConfiguration": {
"Streams": [
{
"StreamArn": kinesis_video_stream_arn_1
},
{
"StreamArn": kinesis_video_stream_arn_2
}
],
"FragmentSelector": {
"FragmentSelectorType": "selector_type", // Specify "server_timestamp" or "producer_timestamp" as the fragment selector type
"TimestampRange": {
"StartTimestamp": epoch_time_seconds,
"EndTimestamp": epoch_time_seconds
}
}
},
"S3RecordingSinkRuntimeConfiguration": {
"Destination": arn:aws:s3:::bucket_name/prefix/optional_file_name,
"RecordingFileFormat": file_format // Specify "Opus" or "WAV" as the recording file format, if you want to override the configuration
}
}
```
`MediaInsightsPipelineConfigurationArn` 是您在建立通話分析組態後收到的組態 ARN。
## 設定目的地、名稱和格式
下列範例使用名為 的資料夾`MyRecordingBucket`做為 `S3SinkConfiguration.Destination`值，並使用 `Opus`做為 `RecordingFileFormat`值。
```
arn:aws:s3:::MyRecordingBucket/voice-connector-id/transaction-id_year-month-date-hour-minute-second-millisecond.ogg
```
下列範例使用 `MyRecordingBucket`做為 `S3SinkConfiguration.Destination`值，使用 `Wav`做為 `RecordingFileFormat`值。
```
arn:aws:s3:::MyRecordingBucket/voice-connector-id/transaction-id_year-month-date-hour-minute-second-millisecond.wav
```
# 了解 Amazon Chime SDK 機器學習型分析的工作流程
下列各節說明如何使用 Amazon Chime SDK 呼叫分析提供的機器學習分析功能。
**注意**
如果您計劃在相同的 Kinesis Video Stream 上執行多個機器學習分析，您可能需要提高`GetMediaForFragmentList`影片串流的 `GetMedia`和 連線層級限制。如需詳細資訊，請參閱《[Kinesis Video Streams 開發人員指南》中的 Kinesis Video Streams 限制](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/limits.html)。 **
# 使用語音連接器自動啟動通話分析
在下列情況下使用此工作流程：
+ 您想要主控台驅動的設定。
+ 您已使用或計劃使用 Voice Connector 將 SIP 媒體帶入通話分析。Voice Connectors 支援 SIP 和 SIPREC。如需設定語音連接器的詳細資訊，請參閱[管理 Amazon Chime SDK 語音連接器](https://docs.aws.amazon.com/chime-sdk/latest/ag/voice-connectors.html)。
+ 您想要將相同的媒體洞見組態套用至每個 Voice Connector 呼叫。
+ 您需要使用 Amazon Chime SDK 語音分析，這需要語音連接器或媒體洞察管道。
若要在 Amazon Chime SDK 主控台中啟用此工作流程，請遵循[設定語音連接器以使用通話分析中建立錄製組態的步驟。](https://docs.aws.amazon.com/chime-sdk/latest/ag/configure-voicecon.html)
若要以程式設計方式啟用此工作流程，請使用下列 APIs：[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html)API 建立通話分析組態，然後使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_PutVoiceConnectorStreamingConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_PutVoiceConnectorStreamingConfiguration.html) API 將組態關聯至語音連接器。如需詳細資訊，請參閱《*Amazon Chime SDK 管理員指南*》中的[設定語音連接器以使用語音分析](https://docs.aws.amazon.com/chime-sdk/latest/ag/configure-voicecon.html)。
下圖顯示語音連接器啟動通話分析工作階段時的資料流程。圖表中的數字對應於下方的編號文字。
![\[Image showing the flow of data when a Voice Connector initiates a call.\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/call-analytics-workflow-1.png)
在圖表中：
1. 您可以使用 Amazon Chime SDK 主控台或 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html) API 來建立媒體洞見管道組態。
1. 您可以使用 Amazon Chime SDK 主控台或 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_PutVoiceConnectorStreamingConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_PutVoiceConnectorStreamingConfiguration.html) API，將組態與語音連接器建立關聯。若要將現有組態與語音連接器建立關聯，請參閱《*Amazon Chime SDK 管理員指南*》中的[設定語音連接器以使用通話分析](https://docs.aws.amazon.com/chime-sdk/latest/ag/configure-voicecon.html)。
1. 在外撥通話期間，語音連接器會收到每個通話參與者的音訊。
1. 由於內建與通話分析的整合，如果通話分析組態連接至 Voice Connector，則 Voice Connector 服務會使用媒體管道服務啟動通話分析工作階段。
1. 媒體管道服務會叫用組態中指定的一或多個媒體處理器。
1. 媒體管道服務會根據組態將輸出資料傳送至一或多個目的地。例如，您可以透過 Amazon Kinesis Data Stream 傳送即時分析，如果已設定，您可以將呼叫中繼資料和分析傳送至 Amazon S3 資料倉儲。
1. 媒體管道服務會將管道狀態事件傳送至預設的 Amazon EventBridge。如果您已設定規則，則通知也會傳送至 Amazon EventBridge。如需詳細資訊，請參閱[使用 EventBridge 通知](https://docs.aws.amazon.com/chime-sdk/latest/dg/ca-eventbridge-notifications.html)。
**注意**
語音分析處理器只會在您呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html)或 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysisTask.html) APIs時自動啟動。
您必須啟用 Voice Connector 串流，才能搭配 Voice Connector 使用通話分析。此功能可讓您將通話資料串流到帳戶中的 Voice Connector 受管 Kinesis Video Streams。如需詳細資訊，請參閱[《Amazon Chime SDK 管理員指南》中的將 Amazon Chime SDK Voice Connector 媒體串流至 Kinesis Video Streams](https://docs.aws.amazon.com/chime-sdk/latest/ag/start-kinesis-vc.html)。 **
您可以將 Voice Connector 呼叫資料存放在 Kinesis Video Streams 中，時間從數小時到數年不等。選擇不保留資料會限制呼叫資料的可用性，以供立即使用。Kinesis Video Streams 的成本取決於使用的頻寬和總儲存體。您可以編輯 Voice Connector 的串流組態，隨時調整資料保留期。若要啟用通話分析記錄，您必須確保 Kinesis Video Stream 會保留資料，直到通話分析完成為止。您可以透過指定適當的資料保留期來執行此操作。
您可以將媒體洞見管道組態與任意數量的語音連接器建立關聯。您也可以為每個語音連接器建立不同的組態。Voice Connectors 使用 AWSServiceRoleForAmazonChimeVoiceConnector 為每個交易 ID 代表您呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API 一次。如需角色的相關資訊，請參閱《[Amazon Chime SDK 管理員指南》中的使用 Amazon Chime SDK Voice Connectors 的 Amazon Chime SDK 服務連結角色](https://docs.aws.amazon.com/chime-sdk/latest/ag/using-service-linked-roles-stream.html#service-linked-role-permissions-stream)。 **
# 將通話分析 APIs與語音連接器搭配使用
如果您使用語音連接器，但需要控制何時套用通話分析組態，以及要套用組態的呼叫，請使用此工作流程。
若要使用此方法，您需要為 Voice Connector 發佈的事件建立 EventBridge 目標，然後使用事件來觸發呼叫分析管道 APIs。如需詳細資訊，請參閱《[Amazon Chime SDK 管理員指南》中的使用 EventBridge 自動化](https://docs.aws.amazon.com/chime-sdk/latest/ag/automating-chime-with-cloudwatch-events.html) Amazon Chime 開發套件。 **
下圖說明如何在搭配 Voice Connector 使用通話分析時實作更精細的控制。圖表中的數字對應至下方文字中的數字。
![\[顯示搭配 Voice Connectors 使用 API 呼叫時資料流程的影像。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/analytics-vc-with-apis.png)
在圖表中：
1. 您可以使用 Amazon Chime SDK 主控台或 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html) API 來建立媒體洞見管道組態。
1. 在外撥通話期間，語音連接器會收到參與者音訊。
1. Voice Connector 會將呼叫音訊傳送至 Kinesis Video Stream，並將對應的事件傳送至 EventBridge。這些事件具有串流和呼叫中繼資料。
1. 您的應用程式是透過 EventBridge 目標訂閱 EventBridge。
1. 您的應用程式會叫用 Amazon Chime SDK [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API。
1. 媒體管道服務會根據媒體洞察管道組態中的處理器元素，叫用一或多個媒體處理器。
1. 媒體管道服務會根據組態將輸出資料傳送至一或多個目的地。Amazon Chime SDK 呼叫分析將透過 Amazon Kinesis Data Stream 提供即時分析，如果已將呼叫中繼資料分析設定為 Amazon S3 資料倉儲。
1. 媒體管道服務會將事件傳送至 Amazon EventBridge。如果您已設定規則，則通知也會傳送至 Amazon EventBridge。
1. 您可以透過叫用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineStatus.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineStatus.html) API 來暫停或繼續通話分析工作階段。
**注意**
通話錄音不支援暫停和繼續通話。此外，當您暫停工作階段時，針對通話啟動的語音分析任務也會停止。若要重新啟動它們，您必須呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html)或 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html) APIs。
1. 如果您在組態期間選取語音音分析，您可以呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html)或 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html) APIs 來啟動語音分析。
# 搭配 Kinesis Video Streams 生產者使用呼叫分析
若要使用此選項，您需要將音訊資料發佈至 Kinesis Video Streams (KVS)，然後使用 KVS 串流頻道資訊呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API。
**注意**
呼叫分析 APIs 最多支援兩個音訊通道。
呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API 時，您可以為每個 KVS 串流頻道定義指定片段編號。如果您提供片段號碼，呼叫分析會開始處理該片段的串流。否則，呼叫分析會開始處理來自最新可用片段的串流。
通話分析支援 PCM 音訊 （僅簽署的 16 位元小端音訊格式，不包括 WAV)，音訊取樣率介於 8kHz 和 48kHz 之間。低品質音訊，例如電話音訊，通常約為 8，000 Hz。優質的音訊，通常介於 16,000 Hz 至 48,000 Hz 間。您指定的取樣率必須符合音訊的取樣率。如需詳細資訊，請參閱《*Amazon Chime SDK API 參考*[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_KinesisVideoStreamSourceRuntimeConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_KinesisVideoStreamSourceRuntimeConfiguration.html)》中的 。
Kinesis Video Streams Producer SDK 提供一組程式庫，可用來將音訊資料串流至 Kinesis Video Stream。如需詳細資訊，請參閱《*Amazon Kinesis Video Streams * [ Kinesis Video Streams 開發人員指南》中的 Kinesis Video Streams 生產者程式庫](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/producer-sdk.html)。
下圖顯示搭配自訂 Kinesis Video Stream 生產者使用通話分析時的資料流程。圖表中的數字對應至下方的編號文字。
![\[本圖顯示搭配 Kinesis Video Stream 生產者使用通話分析時的資料流程。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/analytics-kvs-with-apis.png)
1. 您可以使用 AWS 主控台或 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html) API 來建立媒體洞見管道組態。
1. 您可以使用 Kinesis Video Stream Producer 將音訊寫入 Kinesis Video Streams。
1. 您的應用程式會叫用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API。
1. 媒體管道服務會從客戶的 Kinesis Video Streams 讀取音訊。
1. 媒體管道服務會將事件傳送至 Amazon EventBridge。如果您已設定規則，則通知也會傳送至 Amazon EventBridge。
1. 媒體管道服務會叫用一或多個處理器元素。
1. 媒體管道服務會將輸出資料傳送至一或多個接收器元素。
1. 您可以透過叫用 [ UpdateMediaInsightsPipelineStatus](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineStatus.html) API 來暫停或繼續通話分析工作階段。
**注意**
通話錄音不支援暫停和繼續。
1. 您的應用程式可以處理 Amazon EventBridge 事件，以觸發自訂業務工作流程。
1. 如果您在建立組態時選取語音分析，您的應用程式可以透過呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html)或 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html) APIs 來啟動語音分析。
# 管理 Amazon Chime SDK 的通話分析管道
您可以呼叫 、 和 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaPipeline.html) APIs 來讀取[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetMediaPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetMediaPipeline.html)[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_ListMediaPipelines.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_ListMediaPipelines.html)、列出和刪除媒體洞見管道。
符合下列任一條件時，媒體洞察管道會停止：
+ 任何 Kinesis Video 串流都會在 15 秒內不將新片段傳送至`InProgress`管道。
+ [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaPipeline.html) API 稱為 。
+ 媒體洞察管道的建立時間超過 8 小時。系統會自動停止管道。
+ 媒體洞察管道暫停超過 2 小時。系統會自動停止管道。
# 暫停和繼續 Amazon Chime SDK 的通話分析管道
若要暫停和繼續媒體洞察管道，請使用 `Pause`或 `Resume`動作叫用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineStatus.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineStatus.html) API。若要這樣做，請在 `Identifier` 欄位中傳遞管道的 ID 或 ARN。
**警告**
警告：提供`Pause`狀態時，`UpdateMediaInsightsPipelineStatus`API 會*停止*媒體洞察管道上啟動的所有語音分析任務。提供`Resume`狀態時，任務不會繼續，必須再次啟動。重新啟動任務之前，您必須提供所有必要的通知，並取得發言者的所有必要同意。如需詳細資訊，請參閱《*Amazon Chime SDK API 參考*[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html)》中的 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html)或 。
暫停時，管道會停止將媒體傳送到處理器，並將資料寫入 Kinesis Data Streams 和資料倉儲。當您`Resume`使用管道時，服務會傳送串流上可用的最新區塊。媒體洞察管道會在暫停超過 2 小時時自動停止。**請注意**，通話錄音不支援暫停和繼續。
如需詳細資訊，請參閱下列主題：
+ [使用 EventBridge 通知](https://docs.aws.amazon.com/chime-sdk/latest/dg/ca-eventbridge-notifications.html)。
+ [https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_dataplane_StartSelector.html#KinesisVideo-Type-dataplane_StartSelector-StartSelectorType](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_dataplane_StartSelector.html#KinesisVideo-Type-dataplane_StartSelector-StartSelectorType) Amazon *Amazon Kinesis Video Streams 開發人員指南中的 *。
+ [Amazon Transcribe 呼叫分析處理器](https://docs.aws.amazon.com/chime-sdk/latest/dg/ca-processors-sinks.html#ca-transcribe-analytics-processor)。
**注意**
管道暫停時，您需要支付通話分析用量的費用。不過，您不需要為透過 資源存取角色存取 AWS 的服務付費，例如 Amazon Transcribe 和 Amazon Kinesis。
您可以使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetMediaInsightsPipelineConfiguration.html)、 和 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaInsightsPipelineConfiguration.html) APIs 來讀取、更新和刪除現有的通話分析組態[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineConfiguration.html)，方法是在識別符欄位中傳遞組態名稱或 ARN。
您可以呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_media-pipelines-chime_ListMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_media-pipelines-chime_ListMediaInsightsPipelineConfiguration.html) API 來列出組態。
# 使用 Amazon Chime SDK 的呼叫分析資源存取角色
呼叫帳戶必須建立媒體洞察管道組態所使用的資源存取角色。您無法使用跨帳戶角色。
根據您在建立通話分析組態時啟用的功能，您必須使用其他資源政策。展開下列各節以進一步了解。
## 最低必要政策
此角色至少需要下列政策：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"transcribe:StartCallAnalyticsStreamTranscription",
"transcribe:StartStreamTranscription"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"kinesisvideo:GetDataEndpoint",
"kinesisvideo:GetMedia"
],
"Resource": "arn:aws:kinesisvideo:us-east-1:111122223333:stream/Chime*"
},
{
"Effect": "Allow",
"Action": [
"kinesisvideo:GetDataEndpoint",
"kinesisvideo:GetMedia"
],
"Resource": "arn:aws:kinesisvideo:us-east-1:111122223333:stream/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AWSServiceName": "ChimeSDK"
}
}
},
{
"Effect": "Allow",
"Action": ["kms:Decrypt"],
"Resource": "arn:aws:kms:us-east-1:111122223333:key/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AWSServiceName": "ChimeSDK"
}
}
}
]
}
```
------
您還必須使用下列信任政策：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "mediapipelines.chime.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333"
},
"ArnLike": {
"aws:SourceARN": "arn:aws:chime:*:111122223333:*"
}
}
}
]
}
```
------
## KinesisDataStreamSink 政策
如果您使用 `KinesisDataStreamSink`，請新增下列政策：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"kinesis:PutRecord"
],
"Resource": [
"arn:aws:kinesis:us-east-1:111122223333:stream/output_stream_name"
]
},
{
"Effect": "Allow",
"Action": [
"kms:GenerateDataKey"
],
"Resource": [
"arn:aws:kms:us-east-1:111122223333:key/*"
],
"Condition": {
"StringLike": {
"aws:ResourceTag/AWSServiceName": "ChimeSDK"
}
}
}
]
}
```
------
## S3RecordingSink 政策
如果您使用 `S3RecordingSink`，請新增下列政策：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:PutObjectAcl",
"s3:PutObjectTagging"
],
"Resource": [
"arn:aws:s3:::input_bucket_path/*"
]
},
{
"Effect": "Allow",
"Action": [
"kinesisvideo:GetDataEndpoint",
"kinesisvideo:ListFragments",
"kinesisvideo:GetMediaForFragmentList"
],
"Resource": [
"arn:aws:kinesisvideo:us-east-1:111122223333:stream/*"
],
"Condition": {
"StringLike": {
"aws:ResourceTag/AWSServiceName": "ChimeSDK"
}
}
},
{
"Effect": "Allow",
"Action": [
"kinesisvideo:ListFragments",
"kinesisvideo:GetMediaForFragmentList"
],
"Resource": [
"arn:aws:kinesisvideo:us-east-1:111122223333:stream/Chime*"
]
},
{
"Effect": "Allow",
"Action": [
"kms:GenerateDataKey"
],
"Resource": [
"arn:aws:kms:us-east-1:111122223333:key/*"
],
"Condition": {
"StringLike": {
"aws:ResourceTag/AWSServiceName": "ChimeSDK"
}
}
}
]
}
```
------
## 通話後分析政策
如果您使用 的通話後分析功能`AmazonTranscribeCallAnalyticsProcessor`，請新增下列政策：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": [
"arn:aws:iam::111122223333:role/transcribe_role_name"
],
"Condition": {
"StringEquals": {
"iam:PassedToService": "transcribe.streaming.amazonaws.com"
}
}
}
]
}
```
------
## VoiceEnhancementSinkConfiguration 政策
如果您使用 `VoiceEnhancementSinkConfiguration`元素，請新增下列政策：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"s3:GetObject",
"s3:PutObject",
"s3:PutObjectAcl",
"s3:PutObjectTagging"
],
"Resource":[
"arn:aws:s3:::input_bucket_path/*"
]
},
{
"Effect":"Allow",
"Action":[
"kinesisvideo:GetDataEndpoint",
"kinesisvideo:ListFragments",
"kinesisvideo:GetMediaForFragmentList"
],
"Resource":[
"arn:aws:kinesisvideo:us-east-1:111122223333:stream/*"
],
"Condition":{
"StringLike":{
"aws:ResourceTag/AWSServiceName":"ChimeSDK"
}
}
},
{
"Effect":"Allow",
"Action":[
"kinesisvideo:ListFragments",
"kinesisvideo:GetMediaForFragmentList"
],
"Resource":[
"arn:aws:kinesisvideo:us-east-1:111122223333:stream/Chime*"
]
},
{
"Effect":"Allow",
"Action":[
"kms:GenerateDataKey"
],
"Resource":[
"arn:aws:kms:us-east-1:111122223333:key/*"
],
"Condition":{
"StringLike":{
"aws:ResourceTag/AWSServiceName":"ChimeSDK"
}
}
}
]
}
```
------
## VoiceAnalyticsProcessor 政策
如果您使用 `VoiceAnalyticsProcessor`，`SnsTopicSink`請根據您定義的目的地`SqsQueueSink`來新增 `LambdaFunctionSink`、 和 的政策。
`LambdaFunctionSink` 政策：
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"lambda:InvokeFunction",
"lambda:GetPolicy"
],
"Resource": [
"arn:aws:lambda:us-east-1:111122223333:function:function_name"
],
"Effect": "Allow"
}
]
}
```
`SqsQueueSink` 政策
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"sqs:SendMessage",
"sqs:GetQueueAttributes"
],
"Resource": [
"arn:aws:sqs:us-east-1:111122223333:queue_name"
],
"Effect": "Allow"
},
{
"Effect": "Allow",
"Action": ["kms:GenerateDataKey", "kms:Decrypt"],
"Resource": "arn:aws:kms:us-east-1:111122223333:key/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AWSServiceName": "ChimeSDK"
}
}
}
]
}
```
`SnsTopicSink` 政策：
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"sns:Publish",
"sns:GetTopicAttributes"
],
"Resource": [
"arn:aws:sns:us-east-1:111122223333:topic_name"
],
"Effect": "Allow"
},
{
"Effect": "Allow",
"Action": ["kms:GenerateDataKey", "kms:Decrypt"],
"Resource": "arn:aws:kms:us-east-1:111122223333:key/*",
"Condition": {
"StringLike": {
"aws:ResourceTag/AWSServiceName": "ChimeSDK"
}
}
}
]
}
```
# 了解 Amazon Chime SDK 的通話分析狀態
當您執行下列其中一項或兩項操作時，媒體洞察管道會追蹤一組狀態：
+ 使用多個機器學習處理元素，例如 Amazon Transcribe 和語音分析。
+ 啟用或停用機器學習處理來啟用通話錄音。
若要取得管道和元素狀態，請使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetMediaPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetMediaPipeline.html) API 和 [EventBridge 通知](using-eventbridge-notifications.md)。
若要取得語音分析任務的狀態，請使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetSpeakerSearchTask.html)和 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetVoiceToneAnalysisTask.html) APIs，以及[語音分析通知目標](va-notification-targets.md)。
媒體洞察管道會追蹤下列狀態。
+ **管道狀態** – 呼叫分析管道的整體狀態，也稱為媒體洞見管道。這取決於元素狀態。
+ **元素狀態** – 個別媒體洞見管道組態元素的處理狀態。
+ **任務狀態** – 針對語音分析啟動的媒體洞見管道任務的處理狀態。`VoiceAnalyticsProcessor` 元素狀態取決於任務狀態。呼叫分析管道中沒有其他元素具有任務狀態。
如需媒體洞察管道任務的詳細資訊，請參閱本指南[了解 Amazon Chime SDK 的通話分析術語](ca-terms-concepts.md)稍早的 。
並非所有媒體洞察組態元素類型都有元素狀態。一般而言，只有「處理器」類型的媒體洞察組態元素具有元素狀態。此外，Amazon S3 錄音和語音增強接收器具有處理器狀態。具體而言，下列媒體洞察組態元素類型存在元素狀態：
+ `AmazonTranscribeProcessor`
+ `AmazonTranscribeCallAnalyticsProcessor`
+ `S3RecordingSink`
+ `VoiceAnalyticsProcessor`
+ `VoiceEnhancementSink`
管道狀態由元素狀態決定，如下所示：
| 管道狀態 | 條件 |
| --- | --- |
| NotStarted | 所有元素狀態都不會啟動。 |
| 初始化 | 至少一個元素正在初始化，其他元素未啟動。 |
| InProgress | 至少一個元素正在進行中。 |
| 失敗 | 至少一個元素已失敗，其餘元素已停止。 |
| 正在停止 | 如需停止條件的完整清單[管理 Amazon Chime SDK 的通話分析管道](managing-call-analytics-pipelines.md)，請參閱 。 |
| 已停止 | 所有元素都會停止。 |
| Paused | 所有元素都會暫停。 |
與其他元素狀態不同，`VoiceAnalyticsProcessor`元素有一些細微差別。如前所述，對應至 Amazon Chime SDK 語音分析功能的`VoiceAnalyticsProcessor`元素狀態，取決於從 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html)和 建立的任務狀態[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html)。
+ `VoiceAnalyticsProcessor`的元素狀態會以 `NotStarted` 狀態開始，因為`StartVoiceToneAnalysisTask`必須先呼叫 `StartSpeakerSearchTask`和 ，才能將狀態變更為 `Initializing`，然後呼叫 `InProgress`。
+ `InProgress` 只要啟動一個任務，而且任務執行時不符合[停止條件](managing-call-analytics-pipelines.md)， 就會`VoiceAnalyticsProcessor`保留。
+ 即使 `VoiceAnalyticsProcessor`可能是 `InProgress`，您仍需支付任務處理期間的費用。
+ 若要清除至少有一個語音分析任務已啟動且不再執行任務的媒體洞見管道，您必須呼叫 `DeleteMediaPipeline`。
+ 只要任務成功執行或完成，`VoiceAnalyticsProcessor`元素狀態就會維持在 `InProgress`。
# 使用 Amazon CloudWatch 監控 Amazon Chime SDK 的通話分析管道
您可以使用 Amazon CloudWatch 監控 Amazon Chime SDK 呼叫分析管道。您也可以設定留意特定閾值的警示，當滿足這些閾值時傳送通知或採取動作。如需有關 CloudWatch 的詳細資訊，請參閱《[Amazon CloudWatch 使用者指南](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)》。
**Topics**
+ [先決條件](#monitoring-prereqs)
+ [呼叫分析指標](#monitoring-metrics)
+ [管道指標的 CloudWatch 維度](#monitoring-dimensions)
## 先決條件
若要使用 CloudWatch 指標，您必須先建立媒體管道服務連結角色，以授予將服務指標發佈至 Amazon CloudWatch 的許可。如需服務連結角色的詳細資訊，請參閱本指南[為 Amazon Chime SDK 媒體管道建立服務連結角色](create-pipeline-role.md)中的 。
## 呼叫分析指標
Amazon Chime SDK 呼叫分析會將下列指標發佈至您使用媒體洞察組態建立的媒體洞察管道`AWS/ChimeSDK`命名空間。
| 指標 | Description |
| --- | --- |
| `MediaInsightsPipelineCreated` | 已成功建立媒體洞察管道。 單位：計數 |
| `MediaInsightsPipelineStopped` | 媒體洞察管道已成功停止。 單位：計數 |
| `MediaInsightsPipelineFailed` | 媒體洞察管道失敗。 單位：計數 |
| `MediaInsightsPipelineDuration` | 管道建立與停止/失敗之間的時間。 單位：秒 |
| `MediaInsightsPipelineBillingDuration` | 媒體洞察管道的計費持續時間。 單位：計數 |
| `RecordingFileSize` | 錄製檔案的大小。 單位：位元組 |
| `RecordingDuration ` | 錄製的持續時間。 單位：秒 |
## 管道指標的 CloudWatch 維度
下表列出可用於監控呼叫分析管道的 CloudWatch 維度。
| 維度 | Description |
| --- | --- |
| `MediaInsightsPipelineConfigurationId` | 媒體洞察管道組態的 ID。 |
| `MediaInsightsPipelineConfigurationName` | 媒體洞見管道組態的名稱。 |
# 呼叫 Amazon Chime SDK 的分析處理器和輸出目的地
每個媒體洞見管道組態只能指定唯一元素一次。所有處理器和接收器都必須位於相同的 AWS 帳戶中，而且您必須在與您呼叫的端點相同的 AWS 區域中建立它們。例如，如果您使用 Amazon Chime SDK 媒體管道的`us-east-1`端點，則無法從 `us-west-2`區域傳遞 Kinesis Data Stream。
展開每個區段以取得每個目的地的相關資訊。
## Amazon Transcribe Call Analytics 處理器目的地
支援的接收器：`KinesisDataStreamSink`。
您無法將此處理器與 Amazon Transcribe 處理器結合。如需 Amazon Transcribe Call Analytics 的詳細資訊，請參閱《*Amazon Transcribe 開發人員指南*》中的[即時通話分析](https://docs.aws.amazon.com/transcribe/latest/dg/call-analytics-streaming.html)。如果您在 `AmazonTranscribeCallAnalyticsProcessorConfiguration` API [呼叫中包含 以啟用通話後分析](https://docs.aws.amazon.com/transcribe/latest/dg/tca-post-call.html)，當媒體洞察管道停止且處理完成時，您會在指定的 Amazon S3 位置收到成品。 `PostCallAnalyticsSettings`
**注意**
如果您暫停管道超過 35 秒，然後繼續，通話後成品會在 Amazon S3 儲存貯體中具有不同工作階段 IDs 的個別檔案中產生。
通話後成品包括分析 JSON 檔案和錄音 WAV 或 Opus 檔案。在中繼資料區段`onetimeMetadata`中，每個 Amazon Transcribe 呼叫分析通話後工作階段的修訂後 （如果您啟用內容修訂） 和非編輯記錄檔案的 Amazon S3 儲存貯體 URL 會傳送至 Kinesis Data Stream 一次。 Amazon Transcribe
使用 Amazon Transcribe 呼叫分析的呼叫分析會從 Kinesis Video Stream 取得音訊資料輸入。
+ 支援的媒體編碼：PCM 簽署的 16 位元小端音訊。
+ 支援的媒體取樣率：介於 8，000 Hz 和 48，000 Hz 之間。
`StreamConfiguration` Amazon Transcribe Analytics 程序的 輸入：
+ 您必須`KinesisVideoStreamArn`為每個串流指定 。
+ （選用） KVS 會在指定片段之後使用 區塊`FragmentNumber`啟動呼叫分析任務。如果未提供，則會在 Kinesis 影片串流上使用最新的區塊。
+ `StreamChannelDefinition` 定義誰在說話。Amazon Transcribe 呼叫分析需要雙聲道音訊。當您呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API 時，必須指定哪個發言者位於哪個頻道上。例如，如果您的客服人員先說話，您可以將 `ChannelId` 設定為 `0` 以表示第一個頻道，並將 `ParticipantRole` 設定為 `AGENT` 以表示客服人員正在說話。
**注意**
當您使用 Voice Connector 建立`MediaInsightsPipeline`具有 Amazon Transcribe 呼叫分析處理器的 時，語音連接器帳戶腿部音訊為 ，`AGENT`而 PSTN 腿部音訊`CUSTOMER`為 `ParticipantRole`。
對於語音連接器 SIPREC，我們依賴 SIPREC 中繼資料。在大多數情況下，具有最低語義值的串流標籤會被視為 `AGENT`。
下列範例顯示一個雙聲道音訊串流的 Kinesis Video Stream 輸入。
```
"StreamChannelDefinition" : {
"NumberOfChannels" : 2
"ChannelDefinitions": [
{
"ChannelId": 0,
"ParticipantRole": "AGENT"
},
{
"ChannelId": 1,
"ParticipantRole": "CUSTOMER"
}
]
}
```
相反地，以下範例顯示來自兩個不同 Kinesis Video 串流的兩個單輸入。
```
KVS-1:
"StreamChannelDefinition" : {
"NumberOfChannels" : 1
"ChannelDefinitions": [
{
"ChannelId": 0,
"ParticipantRole": "AGENT"
}
]
}
KVS-2:
"StreamChannelDefinition" : {
"NumberOfChannels" : 1
"ChannelDefinitions": [
{
"ChannelId": 1,
"ParticipantRole": "CUSTOMER"
}
]
}
```
## Amazon Transcribe 呼叫分析輸出
每個 Amazon Transcribe 記錄都包含 `UtteranceEvent`或 `CategoryEvent`，但不能同時包含兩者。 `CategoryEvents` 具有 `detail-type`的 `TranscribeCallAnalyticsCategoryEvent`。
下列範例顯示 Amazon Transcribe 的一次性中繼資料輸出格式。
```
{
"time": "string", // ISO8601 format
"service-type": "CallAnalytics",
"detail-type": "CallAnalyticsMetadata",
"mediaInsightsPipelineId": "string",
"metadata": "string" // JSON encoded string of the metadata object
}
// metadata object
{
"voiceConnectorId": "string",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"direction": "string",
"oneTimeMetadata": "string" // JSON encoded string of oneTimeMetadata object
}
// onetimeMetadata object
{
"inviteHeaders": "string", // JSON encoded string of SIP Invite headers key-value pair
"siprecMetadata": "string", // siprec metadata in XML
"siprecMetadataJson": "string", // siprec metadata in JSON (converted from above XML)
// If PostcallSettings are enabled for Amazon Transcribe Call Analytics
"s3RecordingUrl": "string",
"s3RecordingUrlRedacted": "string"
}
// inviteHeaders object
{
"string": "string"
}
```
下列範例顯示 Amazon Transcribe Call Analytics 輸出格式。
```
{
"time": "string", // ISO8601 format
"service-type": "CallAnalytics",
"detail-type": "TranscribeCallAnalytics",
"mediaInsightsPipelineId": "string",
"metadata": {
"voiceConnectorId": "string",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"direction": "string"
},
"UtteranceEvent": {
"UtteranceId": "string",
"ParticipantRole": "string",
"IsPartial": boolean,
"BeginOffsetMillis": number,
"EndOffsetMillis": number,
"Transcript": "string",
"Sentiment": "string",
"Items": [{
"Content": "string",
"Confidence": number,
"VocabularyFilterMatch": boolean,
"Stable": boolean,
"ItemType": "string",
"BeginOffsetMillis": number,
"EndOffsetMillis": number,
}, ]
"Entities": [{
"Content": "string",
"Confidence": number,
"Category": "string", // Only PII is supported currently
"Type": "string",
"BeginOffset": number,
"EndOffset": number,
}, ],
"IssuesDetected": [{
"CharacterOffsets": {
"Begin": number,
"End": number
}
}]
},
"CategoryEvent": {
"MatchedCategories": ["string"],
"MatchedDetails": {
"string": {
"TimestampRanges": [{
"BeginOffsetMillis": number,
"EndOffsetMillis": number
}]
}
}
}
}
```
## Amazon Chime SDK Voice Connector 串流更新中繼資料
如果呼叫分析組態與 Amazon Chime SDK Voice Connector 相關聯，則在有 Voice Connector [串流更新時，將會傳送下列 Voice Connector](https://docs.aws.amazon.com/chime-sdk/latest/ag/automating-chime-with-cloudwatch-events.html) Update 承載。
下列範例顯示 Amazon Transcribe 處理器和 Transcribe Call Analytics 處理器的更新中繼資料格式。
```
{
"time": "string", // ISO8601 format
"service-type": "CallAnalytics",
"detail-type": "CallAnalyticsMetadata",
"callevent-type": "Update",
"metadata": "string" // JSON encoded string of the metadata object
}
// metadata object
{
"voiceConnectorId": "string",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"direction": "string",
"oneTimeMetadata": "string" // JSON encoded string of oneTimeMetadata object
}
// onetimeMetadata object
{
"sipHeaders": "string", // JSON encoded string of SIP Invite headers key-value pair
"siprecMetadata": "string", // siprec metadata in XML
"siprecMetadataJson": "string" // siprec metadata in JSON (converted from above XML)
}
// sipHeaders object
{
"string": "string"
}
```
下列範例顯示 Call Analytics Amazon S3 錄製的更新中繼資料格式。
```
{
"time": "string", // ISO8601 format
"service-type": "CallAnalytics",
"detail-type": "Recording",
"callevent-type": "Update",
"metadata": "string" // JSON encoded string of the metadata object
}
// metadata object
{
"voiceConnectorId": "string",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"direction": "string",
"oneTimeMetadata": "string" // JSON encoded in string of oneTimeMetadata object
}
// onetimeMetadata object
{
"sipHeaders": "string", // JSON encoded string of SIP Invite headers key-value pair
"siprecMetadata": "string", // siprec metadata in XML
"siprecMetadataJson": "string" // siprec metadata in JSON (converted from above XML)
}
// sipHeaders object
{
"string": "string"
}
```
## SIP 呼叫錄製中繼資料
下列範例顯示記錄 Alice 和 Bob 之間 SIP 呼叫的中繼資料。兩位參與者都會傳送和接收音訊和視訊。為了簡化，此範例只有 SIP 和 SDP 的程式碼片段，而 SRC 會將每個參與者的串流記錄到 SRS，而不會混合。
```
INVITE sip:recorder@example.com SIP/2.0
Via: SIP/2.0/TCP src.example.com;branch=z9hG4bKdf6b622b648d9
From: ;tag=35e195d2-947d-4585-946f-09839247
To:
Call-ID: d253c800-b0d1ea39-4a7dd-3f0e20a
Session-ID: ab30317f1a784dc48ff824d0d3715d86
;remote=00000000000000000000000000000000
CSeq: 101 INVITE
Max-Forwards: 70
Require: siprec
Accept: application/sdp, application/rs-metadata,
application/rs-metadata-request
Contact: ;+sip.src
Content-Type: multipart/mixed;boundary=boundary
Content-Length: [length]
Content-Type: application/SDP
...
m=audio 49170 RTP/AVP 0
a=rtpmap:0 PCMU/8000
a=label:96
a=sendonly
...
m=video 49174 RTP/AVPF 96
a=rtpmap:96 H.264/90000
a=label:97
a=sendonly
...
m=audio 51372 RTP/AVP 0
a=rtpmap:0 PCMU/8000
a=label:98
a=sendonly
...
m=video 49176 RTP/AVPF 96
a=rtpmap:96 H.264/90000
a=label:99
a=sendonly
....
Content-Type: application/rs-metadata
Content-Disposition: recording-session
complete
2010-12-16T23:41:07Z
sip:alice@atlanta.com
structure!
structure
ab30317f1a784dc48ff824d0d3715d86;
remote=47755a9de7794ba387653f2099600ef2
7+OTCyoxTmqmqyA/1weDAg==
FOO!
bar
Alice
FOO!
bar
Bob
FOO!
bar
2010-12-16T23:41:07Z
2010-12-16T23:41:07Z
2010-12-16T23:41:07Z
i1Pz3to5hGk8fuXl+PbwCw==
UAAMm5GRQKSCMVvLyl4rFw==
8zc6e0lYTlWIINA6GR+3ag==
EiXGlc+4TruqqoDaNE76ag==
8zc6e0lYTlWIINA6GR+3ag==
EiXGlc+4TruqqoDaNE76ag==
UAAMm5GRQKSCMVvLyl4rFw==
i1Pz3to5hGk8fuXl+PbwCw==
```
下列範例顯示當一個通話參與者保留另一個通話時，已更新的中繼資料。在此情況下， `participant_id srfBElmCRp2QB23b7Mpk0w==`只會接收媒體串流，而不會傳送任何媒體，因此會省略 `send` XML 元素。相反地， `participant_id zSfPoSvdSDCmU3A3TRDxAw==`會將媒體傳送至其他參與者，但不接收來自該參與者的媒體，因此會省略 `recv` XML 元素。
```
INVITE sip:recorder@example.com SIP/2.0
Via: SIP/2.0/TCP src.example.com;branch=z9hG4bKdf6b622b648d9
From: ;tag=35e195d2-947d-4585-946f-09839247
To:
Call-ID: d253c800-b0d1ea39-4a7dd-3f0e20a
Session-ID: ab30317f1a784dc48ff824d0d3715d86
;remote=f81d4fae7dec11d0a76500a0c91e6bf6
CSeq: 101 INVITE
Max-Forwards: 70
Require: siprec
Accept: application/sdp, application/rs-metadata,
application/rs-metadata-request
Contact: ;+sip.src
Content-Type: multipart/mixed;boundary=foobar
Content-Length: [length]
Content-Type: application/SDP
...
m=audio 49170 RTP/AVP 0
a=rtpmap:0 PCMU/8000
a=label:96
a=sendonly
...
m=video 49174 RTP/AVPF 96
a=rtpmap:96 H.264/90000
a=label:97
a=sendonly
...
m=audio 51372 RTP/AVP 0
a=rtpmap:0 PCMU/8000
a=label:98
a=sendonly
...
m=video 49176 RTP/AVPF 96
a=rtpmap:96 H.264/90000
a=label:99
a=sendonly
....
Content-Type: application/rs-metadata
Content-Disposition: recording-session
partial
8zc6e0lYTlWIINA6GR+3ag==
EiXGlc+4TruqqoDaNE76ag==
8zc6e0lYTlWIINA6GR+3ag==
EiXGlc+4TruqqoDaNE76ag==
```
下列範例顯示通話繼續時的中繼資料更新。承載現在具有 `send`和 `recv` XML 元素。
```
INVITE sip:recorder@example.com SIP/2.0
Via: SIP/2.0/TCP src.example.com;branch=z9hG4bKdf6b622b648d9
From: ;tag=35e195d2-947d-4585-946f-09839247
To:
Call-ID: d253c800-b0d1ea39-4a7dd-3f0e20a
Session-ID: ab30317f1a784dc48ff824d0d3715d86
;remote=f81d4fae7dec11d0a76500a0c91e6bf6
CSeq: 101 INVITE
Max-Forwards: 70
Require: siprec
Accept: application/sdp, application/rs-metadata,
application/rs-metadata-request
Contact: ;+sip.src
Content-Type: multipart/mixed;boundary=foobar
Content-Length: [length]
Content-Type: application/SDP
...
m=audio 49170 RTP/AVP 0
a=rtpmap:0 PCMU/8000
a=label:96
a=sendonly
...
m=video 49174 RTP/AVPF 96
a=rtpmap:96 H.264/90000
a=label:97
a=sendonly
...
m=audio 51372 RTP/AVP 0
a=rtpmap:0 PCMU/8000
a=label:98
a=sendonly
...
m=video 49176 RTP/AVPF 96
a=rtpmap:96 H.264/90000
a=label:99
a=sendonly
....
Content-Type: application/rs-metadata
Content-Disposition: recording-session
partial
i1Pz3to5hGk8fuXl+PbwCw==
UAAMm5GRQKSCMVvLyl4rFw==
8zc6e0lYTlWIINA6GR+3ag==
EiXGlc+4TruqqoDaNE76ag==
8zc6e0lYTlWIINA6GR+3ag==
EiXGlc+4TruqqoDaNE76ag==
i1Pz3to5hGk8fuXl+PbwCw==
UAAMm5GRQKSCMVvLyl4rFw==
```
## Amazon Transcribe 處理器目的地
支援的接收器：`KinesisDataStreamSink`。
您無法將此處理器與 Amazon Transcribe 呼叫分析結合。如需 Amazon Transcribe 輸入和輸出的詳細資訊，請參閱《Amazon [ Transcribe 開發人員指南》中的 Transcribe 串流音訊](https://docs.aws.amazon.com/transcribe/latest/dg/streaming.html)。 *Amazon Transcribe *
使用 Amazon Transcribe 呼叫分析工作階段會從 Kinesis Video Stream 取得音訊資料輸入。
+ 支援的 MediaEncoding：PCM 已簽章的 16 位元小端音訊。
+ 支援的 MediaSampleRate 取樣率：介於 8，000 Hz 和 48，000 Hz 之間。
`StreamConfiguration` Amazon Transcribe 處理器的 輸入：
+ 您必須`KinesisVideoStreamArn`為每個串流指定 。
+ （選用） KVS `FragmentNumber` - 在特定片段之後使用 區塊啟動呼叫分析任務。如果未提供，則會在 Kinesis Video Stream 上使用最新的可用區塊。
+ `StreamChannelDefinition` Amazon Transcribe 目前支援兩個聲道的音訊。您必須在執行時間 `NumberOfChannels`中指定 `StreamChannelDefinition`。此外，`ChannelId`如果您在兩個不同的頻道中傳送單聲道音訊，則必須傳遞 。在您的文字記錄中，聲道會指定標籤 `ch_0` 和 `ch_1`。下列範例顯示單一音訊頻道串流的 KVS 輸入。
```
"StreamChannelDefinition" : {"
NumberOfChannels" : 1
}
```
下列範例顯示兩個不同串流中兩個單音音訊輸入的 KVS 輸入。
```
KVS-1:
"StreamChannelDefinition" : {
"NumberOfChannels" : 1
"ChannelDefinitions": [
{
"ChannelId": 0
}
]
}
KVS-2:
"StreamChannelDefinition" : {
"NumberOfChannels" : 1
"ChannelDefinitions": [
{
"ChannelId": 1
}
]
}
```
**注意**
對於`MediaInsightsPipeline`使用 Amazon Transcribe 處理器建立的 Voice Connector，會將 Voice Connector 帳戶腿部音訊指派給 ，`channel-0`並將 PSTN 腿部音訊指派給 `channel-1`。
對於語音連接器 SIPREC，我們依賴 SIPREC 中繼資料。在大多數情況下，具有最低語義值的串流標籤會指派給 `channel-0`。
對於 Amazon Transcribe 和 Amazon Transcribe 呼叫分析處理器，如果您傳遞兩個 Kinesis Video 串流，且每個串流都包含單一音訊通道，我們會在處理 Transcribe 或 Transcribe 呼叫分析資料之前，將這兩個頻道交錯至單一音訊串流。
## Amazon Transcribe 輸出
下列範例顯示 Amazon Transcribe 的一次性中繼資料輸出格式。
```
{
"time": "string", // ISO8601 format
"service-type": "CallAnalytics",
"detail-type": "CallAnalyticsMetadata",
"mediaInsightsPipelineId": "string",
"metadata": "string" // JSON encoded string of the metadata object
}
// metadata object
{
"voiceConnectorId": "string",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"direction": "string",
"oneTimeMetadata": "string" // JSON encoded string of oneTimeMetadata object
}
// onetimeMetadata object
{
"inviteHeaders": "string", // JSON encoded string of SIP Invite headers key-value pair
"siprecMetadata": "string", // siprec metadata in XML
"siprecMetadataJson": "string" // siprec metadata in JSON (converted from above XML)
}
// inviteHeaders object
{
"string": "string"
}
```
下列範例顯示 Amazon Transcribe 輸出格式。
```
{
"time": "string", // ISO8601 format
"service-type": "CallAnalytics",
"detail-type": "Transcribe",
"mediaInsightsPipelineId": "string",
"metadata": {
"voiceconnectorId": "string",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"direction": "string"
}
"TranscriptEvent": {
"Transcript": {
"Results": [{
"Alternatives": [{
"Entities": [{
"Category": "string",
"Confidence": number,
"Content": "string",
"EndTime": number,
"StartTime": number,
"Type": "string"
}],
"Items": [{
"Confidence": number,
"Content": "string",
"EndTime": number,
"Speaker": "string",
"Stable": boolean,
"StartTime": number,
"Type": "string",
"VocabularyFilterMatch": boolean
}],
"Transcript": "string"
}],
"ChannelId": "string",
"EndTime": number,
"IsPartial": boolean,
"LanguageCode": "string",
"LanguageIdentification": [{
"LanguageCode": "string",
"Score": number
}],
"ResultId": "string",
"StartTime": number
}]
}
}
}
```
## 語音分析處理器目的地
支援的接收器：`KinesisDataStreamSink`、`SnsTopicSink`、 `SqsQueueSink`和 `LambdaFunctionSink`。
您可以結合此處理器與 Amazon Transcribe 通話分析處理器、Amazon Transcribe 處理器或通話錄音。您必須使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html)或 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html) APIs來叫用語音分析處理器。如需使用語音分析的詳細資訊，請參閱[使用 Amazon Chime SDK 語音分析](https://docs.aws.amazon.com/chime-sdk/latest/dg/voice-analytics.html)。
## 使用 Kinesis Data Stream 做為接收器
呼叫分析產生的 Kinesis Data Stream (KDS) 記錄包括媒體管道 ID、詳細資訊類型、中繼資料和處理器特定區段。如需有關從 Kinesis Data Stream 取用資料的資訊，請參閱《[Amazon Kinesis Streams 開發人員指南》中的從 Amazon Kinesis Data Streams 讀取資料](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html)。 *Amazon Kinesis * 若要使用此接收器建立組態，您必須具有指定串流的`kinesis:DescribeStream`許可。
**中繼資料**
產生的 KDS 記錄`metadata`區段包含 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API 呼叫`CallAnalyticsRuntimeMetadata`期間在 中指定的任何鍵值對。如果通話分析工作階段是由語音連接器啟動，中繼資料區段會自動填入下列參數：
+ `transactionId`
+ `fromNumber`
+ `toNumber`
+ `callId`
+ `voiceConnectorId`
+ `direction`
除了上述參數之外，語音連接器起始通話分析工作階段的中繼資料區段也會填入包含下列項目`oneTimeMetadata`的欄位：
+ `inviteHeaders`
+ `siprecMetadata`
這只會在工作階段開始時發佈至 Kinesis Data Streams 一次，並具有 `detail-type`的 `CallAnalyticsMetadata`。
您可以在 中`MediaInsightsRuntimeMetadata`針對每個 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API 呼叫傳遞唯一識別符，以便唯一識別交付至 Kinesis Data Stream 的每個記錄來源。
## Amazon S3 通話錄音
通話分析記錄會從 KVS 串流讀取音訊，將其記錄為音訊檔案，並將檔案上傳至指定的 Amazon S3 儲存貯體。記錄通話分析之後， 也會將通話中繼資料以及檔案位置傳送至 KDS。如果您啟用資料倉儲，呼叫中繼資料 （包括使用 SIPREC 時的 SIPREC 中繼資料） 會交付至一組 Parquet 資料表中的資料倉儲，供您查詢。
如同任何其他呼叫分析處理器，您必須先為管道建立組態。您可以使用 Amazon Chime SDK 主控台或 CLI 來建立組態。然後，您可以使用 CLI 來建立管道。如需使用主控台建立錄製組態的詳細資訊，請參閱本節[為 Amazon Chime SDK 建立通話分析組態](creating-ca-configuration.md)稍早的 。如需使用錄製工作流程的詳細資訊，請參閱本節[了解記錄 Amazon Chime SDK 呼叫的工作流程](recording-workflows.md)稍早的 。
**使用 CLI 建立組態**
執行以下命令：
```
aws chime-sdk-media-pipeline create-media-insights-pipeline-configuration --cli-input-json file://configuration.json
```
下列範例顯示僅啟用記錄的組態 JSON 檔案：
```
{
"MediaInsightsPipelineConfigurationName": configuration_name,
"ResourceAccessRoleArn": role_arn,
"Elements": [
{
"KinesisDataStreamSinkConfiguration": {
"InsightsTarget": KDS_arn //Where recording live metadata will be delivered.
},
"Type": "KinesisDataStreamSink"
},
{
"S3RecordingSinkConfiguration": {
"Destination": "arn:aws:s3:::kvs-recording-testing",
"RecordingFileFormat": file_format // Specify "Opus" or "WAV" as the recording file format.
},
"Type": "S3RecordingSink"
}
]
}
```
請記得以下事項：
+ 若要透過 Kinesis Video Streams 啟用通話錄音，音訊應為 PCM 簽署的 16 位元小端。取樣率必須為 8KHz。
+ 建置器必須為 Kinesis Video Stream 設定足夠長的資料保留期，以確保透過呼叫分析保留和消耗片段。
+ 如果您啟用通話錄音，無論是單獨使用還是與其他處理器結合，都必須提供兩個 Kinesis Video Stream ARNs 進行錄音。通話錄音不支援單一立體聲音訊輸入。
## Amazon S3 通話記錄中繼資料輸出
下列範例顯示呼叫分析 Amazon S3 記錄的中繼資料輸出格式。
```
{
"time": "string", // ISO8601 format
"service-type": "CallAnalytics",
"detail-type": "Recording",
"mediaInsightsPipelineId": "string",
"s3MediaObjectConsoleUrl": "string",
"recordingDurationSeconds": "number",
"metadata": "string" // JSON encoded string of the metadata object
}
// metadata object
{
"voiceConnectorId": "string",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"direction": "string",
"startTime": "string", // ISO8601 format
"endTime": "string", // ISO8601 format
"oneTimeMetadata": "string" // JSON encoded in string of oneTimeMetadata object
}
// onetimeMetadata object
{
"sipHeaders": "string", // JSON encoded string of SIP Invite headers key-value pair
"siprecMetadata": "string", // siprec metadata in XML
"siprecMetadataJson": "string" // siprec metadata in JSON (converted from above XML)
}
// sipHeaders object
{
"string": "string"
}
```
## 啟用語音增強功能
若要啟用語音增強功能，請在 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html) API 呼叫中包含 `VoiceEnhancementSinkConfiguration`元素。
此範例顯示典型的 元素。
```
{
"Type":"VoiceEnhancementSink",
"VoiceEnhancementSinkConfiguration": {
"Disabled": Boolean (string) // FALSE ==> Voice Enhancement will be performed
}
```
若要更新組態，請將 `VoiceEnhancementSinkConfiguration`元素新增至 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineConfiguration.html) API 呼叫。當您這麼做時，[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetMediaInsightsPipelineConfiguration.html)API 會在結果中包含 `VoiceEnhancementSinkConfiguration`元素。
此範例請求說明如何啟用語音增強功能和 Amazon S3 錄製。
```
POST /media-insights-pipeline-configurations HTTP/1.1
Content-type: application/json
{
"MediaInsightsPipelineConfigurationName":"media_insights_configuration_name",
"ResourceAccessRoleArn":"arn:aws:iam::account_id:role/resource_access_role",
"Elements":[
{
"Type":"S3RecordingSink",
"S3RecordingSinkConfiguration":{
"Destination":"arn:aws:s3:::input_bucket_path",
"RecordingFileFormat":"Wav"
}
},
{
"Type":"VoiceEnhancementSink",
"VoiceEnhancementSinkConfiguration": {
"disabled":"false"
}
}
],
"ClientRequestToken":"client_request_token"
}
```
**注意**
`VoiceEnhancementSink` 元素一律需要呼叫分析組態中的 `S3RecordingSink`元素。
# 將轉錄與 Amazon Chime SDK 的錄製接收器結合
您可以結合 Amazon Transcribe 和 Amazon Transcribe Call Analytics 處理器與 Amazon S3 錄音接收器。除了 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html) API 呼叫中的 Amazon Transcribe 處理器之外，建置器也可以使用 主控台傳遞 S3RecordingSinkConfiguration。
搭配 Amazon S3 錄音接收器，您可以使用 Amazon Transcribe 或 Amazon Transcribe Call Analytics 處理器，但不能同時使用兩者。除了錄製接收器之外，您還可以將語音分析新增至相同的組態，無論是否使用轉錄處理器。
**注意**
您可以使用上述任何處理器啟用錄製。不過，如果您啟用 Amazon Transcribe Call Analytics 與 Amazon S3 通話錄音，您必須提供兩個 Kinesis 影片串流，而且會收到重複的錄音檔案，一個來自 Amazon Transcribe Call Analytics，另一個來自 Amazon S3 通話錄音。
請記得以下事項：
+ 您必須使用唯一的 `MediaInsightsPipelineConfigurationName`。
+ 如需 的相關資訊`ResourceAccessRoleArn`，請參閱本指南[使用 Amazon Chime SDK 的呼叫分析資源存取角色](call-analytics-resource-access-role.md)中的 。
+ `Destination` 值必須是 S3 路徑 ARN。Amazon S3 儲存貯體必須由相同的帳戶擁有。
+ 如果您搭配 Transcribe 和記錄使用組態來建立管道，則 暫停和繼續只會出現在 Kinesis Data 串流所產生的洞見中。KVS 串流中的所有資料都會記錄並上傳至 Amazon S3。
+ 如果組態除了錄製使用 Amazon 轉錄或轉錄通話分析 (TCA)，媒體洞察管道會即時提供轉錄或轉錄通話分析洞察，然後在通話結束時進行 Amazon S3 錄製。如果在呼叫分析期間轉錄服務失敗，S3 錄製任務仍會嘗試執行。相反地，Amazon S3 記錄失敗不會影響轉錄洞察，因為它在轉錄完成後執行。
此範例顯示具有 Amazon Transcribe 處理器和 Amazon S3 錄製接收器的組態。此範例也啟用部分結果穩定功能，這可以減少輸出的延遲，但可能會影響準確性。如需詳細資訊，請參閱《*Amazon Transcribe 開發人員指南*》中的[部分結果穩定](https://docs.aws.amazon.com/transcribe/latest/dg/streaming-partial-results.html#streaming-partial-result-stabilization)功能。
```
{
"MediaInsightsPipelineConfigurationName": unique_configuration_name,
"ResourceAccessRoleArn": role_arn,
"Elements": [{
"AmazonTranscribeProcessorConfiguration": {
"ContentIdentificationType": "string",
"ContentRedactionType": "string",
"EnablePartialResultsStabilization": boolean, //Enables partial result stabilization. Can reduce latency. May impact accuracy.
"FilterPartialResults": boolean, //To control partial utterance events
"LanguageCode": "string",
"LanguageModelName": "string",
"PartialResultsStability": "string",
"PiiEntityTypes": "string",
"ShowSpeakerLabel": boolean,
"VocabularyFilterMethod": "string",
"VocabularyFilterName": "string",
"VocabularyName": "string"
},
"Type": "AmazonTranscribeProcessor"
},
{
"KinesisDataStreamSinkConfiguration": {
"InsightsTarget": KDS_arn //Where recording and insights live metadata will be delivered.
},
"Type": "KinesisDataStreamSink"
},
{
"S3RecordingSinkConfiguration": {
"Destination": S3_Arn,
"RecordingFileFormat": file_format // Specify "Opus" or "WAV" as the recording file format.
},
"Type": "S3RecordingSink"
}
]
}
```
# 針對 Amazon Chime SDK 使用 Amazon EventBridge 通知
Amazon Chime SDK 呼叫分析支援在媒體洞察管道的狀態變更，或符合呼叫分析即時警示條件時，將事件傳送至預設 EventBridge 匯流排。針對媒體洞察管道錯誤狀態更新，建議您設定 EventBridge 目標，以便在資源非同步失敗時通知您。通話分析通知具有 aws.chime 來源和各種詳細資訊類型，在下列各節中共用。如需詳細資訊，請參閱[「Amazon EventBridge 使用者指南」](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html)。
**Topics**
+ [狀態更新](#status-updates)
+ [即時提醒](#realtime-alerts)
## 狀態更新
媒體洞察管道會在通話分析工作階段進行時傳送 EventBridge 通知，並成功結束或發生錯誤。在以下情況下，您會收到 EventBridge 通知，其中包含「Media Insights 狀態變更」詳細資訊類型：
+ 媒體洞見管道的狀態會變更。
+ 媒體洞見管道元素的狀態會變更。
+ 任何管道元素都會停止。
+ 任何管道元素都會失敗。
詳細資訊區段一律包含下列欄位：
+ `version`
+ `mediaInsightsPipelineArn`
+ `eventType`
如果媒體洞察管道包含多個元素，例如分析處理器和資料接收器，詳細資訊區段也會包含 `mediaInsightsPipelineElementStatuses` 欄位。此欄位表示管道中每個元素的狀態。每個管道元素的可能狀態可以是：
+ `NotStarted`
+ `InProgress`
+ `Stopped`
+ `Failed`
詳細資訊區段也包含 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API 呼叫`MediaInsightsRuntimeMetadata`期間在 中指定的任何鍵值對。如果通話分析工作階段是由語音連接器啟動，中繼資料區段會自動填入下列參數：
+ `transactionId`
+ `fromNumber`
+ `toNumber`
+ `callId`
+ `voiceConnectorId`
+ `direction`
每當媒體洞察管道包含單一元素時，可能會出現下列事件類型。展開每個區段以進一步了解。
### Amazon Chime SDK 媒體洞察正在進行中
此範例顯示典型的事件結構。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": []
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsInProgress",
"version": "0",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string"
}
}
```
### Amazon Chime SDK 媒體洞察已暫停
此範例顯示典型的事件結構。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": []
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsPaused",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string"
}
}
```
### Amazon Chime SDK 媒體洞察已停止
此範例顯示典型的事件結構。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": []
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsStopped",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string"
}
}
```
### Amazon Chime SDK 媒體洞察暫時失敗
表示服務遇到暫時失敗，並會嘗試重試。您不需要採取任何動作。
此範例顯示典型的事件結構。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": []
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsTemporaryFailure",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string"
}
}
```
### Amazon Chime SDK 媒體洞察永久故障
表示需要您採取動作的失敗。使用 `failureReason`對問題進行疑難排解。典型失敗可能包括下列項目：
+ 資源存取角色的許可不足
+ 遺失或刪除的資源
+ 從 AWS 服務調節，呼叫 分析會代表您叫用，例如 Amazon Transcribe 或 Amazon Kinesis。
+ KVS 串流上的不相容媒體格式
此範例顯示典型的事件結構。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": []
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsPermanentFailure",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string",
"failureReason": "string"
}
}
```
**注意**
此 `failureReason` 欄位為選用。例如，典型原因可能是 `Access denied when assuming resource access role`。
每當建立媒體洞見管道，或建立嘗試失敗時，Amazon Chime SDK Voice Connector 啟動的呼叫分析工作階段，可能會出現下列事件類型。展開每個區段以進一步了解。
### 已建立 Amazon Chime SDK 媒體洞察
此範例顯示典型的成功事件。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": []
"detail":
{
"version": "0",
"mediaInsightsPipelineConfigurationArn": "string",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsCreated",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string",
}
}
```
### Amazon Chime SDK 媒體洞察建立失敗
此範例顯示典型的失敗事件。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": []
"detail":
{
"version": "0",
"mediaInsightsPipelineConfigurationArn": "string",
"eventType": "chime:MediaInsightsCreateFailed",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string",
"failureOrigin": "Voice Connector",
"httpStatusCode": "string",
"failureReason": "string"
}
}
```
當媒體洞察管道包含多個元素時，可能會出現下列事件類型。通知範例適用於 與 `AmazonTranscribeProcessor`結合使用`S3RecordingSink`。展開每個區段以進一步了解。
### AmazonTranscribeProcessor 正在進行中，且 S3RecordingSink 尚未啟動
此範例顯示典型的事件結構。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": [],
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsInProgress",
"mediaInsightsPipelineElementStatuses": [
{
"type": "AmazonTranscribeProcessor",
"status": "InProgress",
"updatedOn": 1686184070655
},
{
"type": "S3RecordingSink",
"status": "NotStarted",
"updatedOn": 1686184070655
}
]
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string"
}
}
```
### AmazonTranscribeProcessor 已成功且 S3RecordingSink 正在進行中
此範例顯示典型的事件結構。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": [],
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsInProgress",
"mediaInsightsPipelineElementStatuses": [
{
"type": "AmazonTranscribeProcessor",
"status": "Stopped",
"updatedOn": 1686184070655
},
{
"type": "S3RecordingSink",
"status": "InProgress",
"updatedOn": 1686184070655
}
]
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string"
}
}
```
### AmazonTranscribeProcessor 失敗且 S3RecordingSink 正在進行中
此範例顯示典型的事件結構。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": [],
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsInProgress",
"mediaInsightsPipelineElementStatuses": [
{
"type": "AmazonTranscribeProcessor",
"status": "Failed",
"updatedOn": 1686184070655
},
{
"type": "S3RecordingSink",
"status": "InProgress",
"updatedOn": 1686184070655
}
]
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string"
}
}
```
### AmazonTranscribeProcessor 失敗且 S3RecordingSink 成功
此範例顯示典型的事件結構。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": [],
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsPermanentFailure",
"mediaInsightsPipelineElementStatuses": [
{
"type": "AmazonTranscribeProcessor",
"status": "Failed",
"updatedOn": 1686184070655
},
{
"type": "S3RecordingSink",
"status": "Stopped",
"updatedOn": 1686184070655
}
]
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string",
"failureReason": "string"
}
}
```
### AmazonTranscribeProcessor 已成功且 S3RecordingSink 失敗
此範例顯示典型的事件結構。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": [],
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsPermanentFailure",
"mediaInsightsPipelineElementStatuses": [
{
"type": "AmazonTranscribeProcessor",
"status": "Stopped",
"updatedOn": 1686184070655
},
{
"type": "S3RecordingSink",
"status": "Failed",
"updatedOn": 1686184070655
}
]
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string",
"failureReason": "string"
}
}
```
### AmazonTranscribeProcessor 已暫停且 S3RecordingSink 尚未啟動
此範例顯示典型的事件結構。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": [],
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsPaused",
"mediaInsightsPipelineElementStatuses": [
{
"type": "AmazonTranscribeProcessor",
"status": "Paused",
"updatedOn": 1686184070655
},
{
"type": "S3RecordingSink",
"status": "NotStarted",
"updatedOn": 1686184070655
}
]
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string"
}
}
```
### AmazonTranscribeProcessor 暫時失敗，且 S3RecordingSink 尚未啟動
此範例顯示典型的事件結構。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": [],
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsTemporaryFailure",
"mediaInsightsPipelineElementStatuses": [
{
"type": "AmazonTranscribeProcessor",
"status": "TemporarilyFailed",
"updatedOn": 1686184070655
},
{
"type": "S3RecordingSink",
"status": "NotStarted",
"updatedOn": 1686184070655
}
]
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string"
}
}
```
### AmazonTranscribeProcessor 和 S3RecordingSink 成功
此範例顯示典型的事件結構。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": [],
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsStopped",
"mediaInsightsPipelineElementStatuses": [
{
"type": "AmazonTranscribeProcessor",
"status": "Stopped",
"updatedOn": 1686184070655
},
{
"type": "S3RecordingSink",
"status": "Stopped",
"updatedOn": 1686184070655
}
]
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string"
}
}
```
### S3RecordingSink 成功且 VoiceEnhancement 進行中
此範例顯示典型的事件結構。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "string",
"detail": {
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsInProgress",
"version": "0",
"mediaInsightsPipelineElementStatuses": [
{
"type": "VoiceEnhancementSink",
"status": "InProgress",
"updatedOn": 1686184070655
},
{
"type": "S3RecordingSink",
"status": "Stopped",
"updatedOn": 1686184070655
}
]
}
}
```
### S3RecordingSink 成功且 VoiceEnhancement 失敗，因為呼叫時間超過 30 分鐘
此範例顯示典型的事件結構。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "string",
"detail": {
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsStopped",
"version": "0",
"mediaInsightsPipelineElementStatuses": [
{
"type": "VoiceEnhancement",
"status": "NotSupported",
"updatedOn": 1686184070655,
"statusDetail": "Unsupported recording length"
},
{
"type": "S3RecordingSink",
"status": "Stopped",
"updatedOn": 1686184070655
}
]
}
}
```
### S3RecordingSink 成功且 VoiceEnhancement 由於呼叫少於 30 分鐘而失敗
此範例顯示典型的事件結構。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "string",
"detail": {
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsPermanentFailure",
"version": "0",
"mediaInsightsPipelineElementStatuses": [
{
"type": "VoiceEnhancement",
"status": "Failed",
"updatedOn": 1686184070655
},
{
"type": "S3RecordingSink",
"status": "Stopped",
"updatedOn": 1686184070655
}
]
}
}
```
## 即時提醒
**注意**
只有 Amazon Transcribe 和 Amazon Transcribe Call Analytics 處理器支援即時警示。
Amazon Chime SDK 呼叫分析可讓開發人員設定在分析工作階段期間透過處理器傳送即時提醒的規則。警示會以詳細資訊類型 傳送至 Amazon EventBridge`Media Insights Rules Matched`。EventBridge 支援與 Lambda、Amazon SQS 和 Amazon SNS 等下游服務的整合，以觸發最終使用者的通知或啟動其他自訂商業邏輯。
即時提醒會設定為 `RealTimeAlertConfiguration` 欄位的一部分`MediaInsightsPipelineConfiguration`。您可以使用 Amazon Chime SDK 主控台來設定 欄位，也可以呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html)或 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineConfiguration.html) APIs。
此範例示範如何透過 API 建立或更新即時提醒組態。
```
{
"MediaInsightsPipelineConfigurationName": "config_name",
"ResourceAccessRoleArn": "arn:aws:iam::account_id:role/role_name",
"RealTimeAlertConfiguration": {
"Disabled": false,
"Rules": [{
"Type": "KeywordMatch",
"KeywordMatchConfiguration": {
"RuleName": "rule_name_1",
"Keywords": [
"hello",
"thank you"
],
"Negate": false
}
},
{
"Type": "Sentiment",
"RuleName": "rule_name_2",
"SentimentType": "NEGATIVE",
"TimePeriod": 60
},
{
"Type": "IssueDetection",
"RuleName": "rule_name_3"
}
]
},
"Elements": [{
"Type": "AmazonTranscribeCallAnalyticsProcessor",
"AmazonTranscribeCallAnalyticsProcessorConfiguration": {
"LanguageCode": "en-US"
}
},
{
"Type": "KinesisDataStreamSink",
"KinesisDataStreamSinkConfiguration": {
"InsightsTarget": "arn:aws:kinesis:us-east-1:account_id:stream/stream_name"
}
}
]
}
```
即時警示組態中的每個規則都會獨立觸發。如果同時符合多個規則條件，您可能會收到多個 EventBridge 通知。若要建立提醒的規則清單，您可以在下列規則類型中選取：
關鍵字比對
在表達用語或文字記錄事件中符合指定的一組關鍵字或片語時發出警示。您可以設定警示以發出事件，如果：
+ 系統會說出任何指定的關鍵字，並將 `Negate` 設定為 `false`。
+ 如果 `Negate` 設定為 ，則整個呼叫的所有指定關鍵字都是不說出的`true`。
Amazon Transcribe 和 Amazon Transcribe Analytics 支援此規則類型。
情緒分析
當特定情緒類型在滾動時段持續時發出警示。只有轉錄通話分析支援此規則。
問題偵測
在表達用語事件中偵測到問題時發出警示。只有 Transcribe Call Analytics 支援此規則類型。
下列範例顯示`KeywordMatch`規則的即時提醒事件。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights Rules Matched",
"source": "aws.chime",
"account": number,
"region": "us-east-1",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": [],
"detail": {
"version": "0",
"sourceMetadata": {}
"ruleName": "string"
"utteranceId": "string",
"beginTimestamp": "yyyy-mm-ddThh:mm:ssZ",
}
}
```
有些 EventBridge 欄位專屬於符合的規則類型：
**關鍵字比對欄位**
`utteranceId`：如果您使用 Amazon Transcribe Call Analytics，包含相符關鍵字的文字記錄 ID。僅適用於口語關鍵字比對。
`resultId`：如果您使用 Amazon Transcribe，包含相符關鍵字的文字記錄 ID。僅適用於口語關鍵字比對。
`beginTimestamp`：包含相符關鍵字之文字記錄的開始時間。僅適用於口語關鍵字比對。
**情緒分析欄位**
`beginTimestamp`：相符情緒滾動時段的開始時間。
`endTimestamp`：相符情緒滾動時段的結束時間。
# 建立 Amazon Chime SDK 資料湖
Amazon Chime SDK 呼叫分析資料湖可讓您將機器學習支援的洞見和任何中繼資料從 Amazon Kinesis Data Stream 串流到 Amazon S3 儲存貯體。例如，使用資料湖來存取錄製的 URLs。若要建立資料湖，您可以從 Amazon Chime SDK 主控台或以程式設計方式使用 部署一組 AWS CloudFormation 範本 AWS CLI。資料湖可讓您在 Amazon Athena 中參考 AWS Glue 資料表，以查詢通話中繼資料和語音分析資料。
**Topics**
+ [先決條件](#data-lake-prereqs)
+ [資料湖術語和概念](#data-lake-terms)
+ [建立多個資料湖](#creating-multiple-data-lakes)
+ [資料湖區域可用性](#data-lake-regions)
+ [資料湖架構](#data-lake-architecture)
+ [資料湖設定](#data-lake-setup)
## 先決條件
您必須具有下列項目，才能建立 Amazon Chime SDK 湖：
+ Amazon Kinesis 資料串流。如需詳細資訊，請參閱《Amazon Kinesis [Streams 開發人員指南》中的透過 AWS 管理主控台建立](https://docs.aws.amazon.com/streams/latest/dev/how-do-i-create-a-stream.html)串流。 *Amazon Kinesis *
+ S3 儲存貯體。如需詳細資訊，請參閱《[Amazon S3 使用者指南》中的建立您的第一個 Amazon S3 儲存貯](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html)體。 *Amazon S3 *
## 資料湖術語和概念
使用以下術語和概念來了解資料湖的運作方式。
**Amazon Kinesis Data Firehose**
擷取、轉換和載入 (ETL) 服務，可可靠地擷取、轉換串流資料，並將資料交付至資料湖、資料存放區和分析服務。如需詳細資訊，請參閱什麼是 Amazon Kinesis Data Firehose？
**Amazon Athena**
Amazon Athena 是一種互動式查詢服務，可讓您使用標準 SQL 分析 Amazon S3 中的資料。Athena 是無伺服器，因此您不需要管理基礎設施，您只需為執行的查詢付費。若要使用 Athena，請指向 Amazon S3 中的資料、定義結構描述，並使用標準 SQL 查詢。您也可以使用工作群組來將使用者分組，並控制他們在執行查詢時可存取的資源。工作群組可讓您管理查詢並行，並排定不同使用者和工作負載群組的查詢執行優先順序。
**Glue Data Catalog**
在 Amazon Athena 中，資料表和資料庫包含詳細說明基礎來源資料的結構描述的中繼資料。對於每個資料集，資料表必須存在於 Athena 中。資料表中的中繼資料會告知 Athena Amazon S3 儲存貯體的位置。它也會指定資料結構，例如資料欄名稱、資料類型和資料表的名稱。資料庫只會保留資料集的中繼資料和結構描述資訊。
## 建立多個資料湖
可以透過提供唯一的 Glue 資料庫名稱來指定存放呼叫洞見的位置來建立多個資料湖。對於指定的 AWS 帳戶，可以有數個呼叫分析組態，每個組態都有對應的資料湖。這表示資料分離適用於特定使用案例，例如自訂保留政策，以及資料存放方式的存取政策。可以套用不同的安全政策來存取洞見、錄製和中繼資料。
## 資料湖區域可用性
Amazon Chime SDK 資料湖可在下列區域使用。
| 區域 | Glue 資料表 | 快速 |
| --- | --- | --- |
| us-east-1 | Available | Available |
| us-west-2 | Available | Available |
| eu-central-1 | Available | Available |
## 資料湖架構
下圖顯示資料湖架構。繪圖中的數字對應於下方的編號文字。
![\[程式會流經資料湖。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/call-analytics-data-lake-architecture.png)
在圖表中，當您使用 AWS 主控台從媒體洞見管道組態設定工作流程部署 CloudFormation 範本時，下列資料會流向 Amazon S3 儲存貯體：
1. Amazon Chime SDK 呼叫分析將開始將即時資料串流到客戶的 Kinesis Data Stream。
1. Amazon Kinesis Firehose 會緩衝此即時資料，直到累積 128 MB 或經過 60 秒，以先到者為準。接著 Firehose 會使用 Glue Data Catalog `amazon_chime_sdk_call_analytics_firehose_schema`中的 來壓縮資料，並將 JSON 記錄轉換為 parquet 檔案。
1. parquet 檔案以分割格式存放在 Amazon S3 儲存貯體中。
1. 除了即時資料之外，通話後 Amazon Transcribe Call Analytics 摘要 .wav 檔案 （已編輯和未編輯，如果在組態中指定） 和通話記錄 .wav 檔案也會傳送至您的 Amazon S3 儲存貯體。
1. 您可以使用 Amazon Athena 和標準 SQL 來查詢 Amazon S3 儲存貯體中的資料。
1. CloudFormation 範本也會建立 Glue Data Catalog，透過 Athena 查詢此通話後摘要資料。
1. Amazon S3 儲存貯體上的所有資料也可以使用 Quick 視覺化。QuickSight 使用 Amazon Athena 與 Amazon S3 儲存貯體建立連線。 Amazon Athena
Amazon Athena 資料表使用下列功能來最佳化查詢效能：
**資料分割**
分割會將資料表分成數個部分，並根據日期、國家/地區和區域等資料欄值將相關資料保留在一起。分割區充當虛擬資料欄。在此情況下，CloudFormation 範本會在建立資料表時定義分割區，這有助於減少每個查詢掃描的資料量並改善效能。您也可以依分割區篩選，以限制查詢掃描的資料量。如需詳細資訊，請參閱《*Amazon Athena * [Athena 使用者指南》中的 Athena 中的分割資料](https://docs.aws.amazon.com/athena/latest/ug/partitions.html)。
此範例顯示日期為 2023 年 1 月 1 日的分割結構：
1.
```
s3://example-bucket/amazon_chime_sdk_data_lake
/serviceType=CallAnalytics/detailType={DETAIL_TYPE}/year=2023
/month=01/day=01/example-file.parquet
```
1. 其中 `DETAIL_TYPE`是下列其中一項：
1. `CallAnalyticsMetadata`
1. `TranscribeCallAnalytics`
1. `TranscribeCallAnalyticsCategoryEvents`
1. `Transcribe`
1. `Recording`
1. `VoiceAnalyticsStatus`
1. `SpeakerSearchStatus`
1. `VoiceToneAnalysisStatus`
**最佳化單欄式資料存放區產生**
Apache Parquet 使用資料欄式壓縮、以資料類型為基礎的壓縮，以及述詞下推來存放資料。更佳的壓縮率或略過資料區塊，表示從 Amazon S3 儲存貯體讀取的位元組較少。這可提高查詢效能並降低成本。為此最佳化，Amazon Kinesis Data Firehose 中已啟用從 JSON 到 parquet 的資料轉換。
**分割區投影**
此 Athena 功能會自動為每天建立分割區，以改善以日期為基礎的查詢效能。
## 資料湖設定
使用 Amazon Chime SDK 主控台來完成下列步驟。
1. 啟動 Amazon Chime SDK 主控台 ([ https://console.aws.amazon.com/chime-sdk/home](https://console.aws.amazon.com/chime-sdk/home)：//)，然後在導覽窗格中的**通話分析**下，選擇**組態**。
1. 完成步驟 1，選擇**下一步**，然後在步驟 2 頁面上，選擇**語音分析**核取方塊。
1. 在**輸出詳細資訊**下，選取**資料倉儲以執行歷史分析**核取方塊，然後選擇**部署 CloudFormation 堆疊**連結。
系統會將您傳送至 CloudFormation 主控台中的**快速建立堆疊**頁面。
1. 輸入堆疊的名稱，然後輸入下列參數：
1. `DataLakeType` – 選擇**建立通話分析 DataLake**。
1. `KinesisDataStreamName` – 選擇您的串流。它應該是用於通話分析串流的串流。
1. `S3BucketURI` – 選擇您的 Amazon S3 儲存貯體。URI 必須有 字首 `s3://bucket-name`
1. `GlueDatabaseName` – 選擇唯一的 AWS Glue 資料庫名稱。您無法重複使用 AWS 帳戶中現有的資料庫。
1. 選擇確認核取方塊，然後選擇**建立資料湖**。系統需要 10 分鐘的時間來建立湖。
### 使用 設定資料湖 AWS CLI
使用 AWS CLI 建立具有呼叫 CloudFormation 建立堆疊許可的角色。請依照下列程序建立和設定 IAM 角色。如需詳細資訊，請參閱《*AWS CloudFormation 使用者指南*》中的[建立堆疊](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-cli-creating-stack.html)。
1. 建立名為 *AmazonChimeSdkCallAnalytics-Datalake-Provisioning-Role* 的角色，並將信任政策連接至允許 CloudFormation 擔任該角色的角色。
1. 使用下列範本建立 IAM 信任政策，並以 .json 格式儲存檔案。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "cloudformation.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {}
}
]
}
```
------
1. 執行 **aws iam create-role**命令，並將信任政策做為參數傳遞。
```
aws iam create-role \
--role-name AmazonChimeSdkCallAnalytics-Datalake-Provisioning-Role
--assume-role-policy-document file://role-trust-policy.json
```
1. 記下從回應傳回*的角色 arn*。下一個步驟中需要*角色 arn*。
1. 建立具有建立 CloudFormation 堆疊許可的政策。
1. 使用下列範本建立 IAM 政策，並以 .json 格式儲存檔案。呼叫 create-policy 時需要此檔案。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "DeployCloudFormationStack",
"Effect": "Allow",
"Action": [
"cloudformation:CreateStack"
],
"Resource": "*"
}
]
}
```
------
1. 執行**aws iam create-policy**並傳遞建立堆疊政策做為參數。
```
aws iam create-policy --policy-name testCreateStackPolicy
--policy-document file://create-cloudformation-stack-policy.json
```
1. 記下從回應傳回*的角色 arn*。在下一個步驟中需要*角色 arn*。
1. 將 **aws iam attach-role-policy** 政策連接到角色。
```
aws iam attach-role-policy --role-name {Role name created above}
--policy-arn {Policy ARN created above}
```
1. 建立 CloudFormation 堆疊並輸入必要的參數：**aws cloudformation create-stack**。
使用 ParameterValue 提供每個 ParameterKey 的參數值。 ParameterValue
```
aws cloudformation create-stack --capabilities CAPABILITY_NAMED_IAM
--stack-name testDeploymentStack
--template-url https://chime-sdk-assets.s3.amazonaws.com/public_templates/AmazonChimeSDKDataLake.yaml
--parameters ParameterKey=S3BucketURI,ParameterValue={S3 URI}
ParameterKey=DataLakeType,ParameterValue="Create call analytics datalake"
ParameterKey=KinesisDataStreamName,ParameterValue={Name of Kinesis Data Stream}
--role-arn {Role ARN created above}
```
#### 資料湖設定建立的資源
下表列出建立資料湖時建立的資源。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/ca-data-lake.html)
# 設定 Amazon Chime SDK 的快速儀表板
設定資料湖後，您可以使用視覺化資料的預先定義指標來設定快速儀表板。您可以使用下列儀表板：
+ **轉錄通話分析 \$1 語音分析**。指標包括turn-by-turn轉錄的摘要和詳細視覺效果、偵測到的問題、結果、實體偵測和語音設定檔 ID 比對。
+ **轉錄 \$1 Voice Analytics**。指標包括turn-by-turn轉錄、詞彙配對、語音音調和語音設定檔 ID 配對的摘要和詳細視覺效果。
下列主題說明如何在還沒有快速帳戶時設定快速帳戶，以及如何設定儀表板。
**Topics**
+ [建立 QuickSight 帳戶](#create-quicksight-account)
+ [設定您的 QuickSight 帳戶](#configure-qs-acct)
+ [建立 QuickSight 儀表板](#create-qs-dashboard)
## 建立 QuickSight 帳戶
本節中的步驟說明如何建立快速帳戶。如果您已有 帳戶，您可以跳到 [建立 QuickSight 儀表板](#create-qs-dashboard)。
您可以透過以下方式建立 QuickSight 帳戶：
+ 使用 Amazon CloudFormation 範本。
+ 使用 Amazon Chime SDK 主控台。
### 先決條件
開始之前，請先收集下列資訊：
+ 您的呼叫分析 Amazon S3 儲存貯體的名稱。
+ 通知電子郵件地址。系統會傳送 QuickSight 通知到此地址。
### 使用 CloudFormation 範本建立 帳戶
下列步驟說明如何透過部署 Amazon CloudFormation 範本來建立 Quick 帳戶。程序只會訂閱您的企業帳戶。如需定價的相關資訊，請參閱 [Quick Pricing](https://aws.amazon.com/quicksight/pricing/)。
**部署範本**
1. 啟動 AWS 主控台並登入您的 AWS 帳戶。
1. 將下列 URL 貼到瀏覽器的地址列。請務必依照指示輸入您的區域。
`https://region.console.aws.amazon.com/cloudformation/home?region=region#/stacks/quickcreate?templateURL=https://chime-sdk-assets.s3.amazonaws.com/public_templates/AmazonChimeSDKQuickSightSubscription.yaml`.
1. 在**快速建立堆疊**頁面上，輸入下列內容：
1. 在**堆疊名稱**下，輸入您帳戶的名稱。
1. 在 **QuickSightNotificationEmail** 下，您先前收集的電子郵件地址。
1. 在 **QuickSightSubscriptionForDataVisualization** 下，選擇**建立新的 AWS QuickSight 帳戶**。
1. 在 **S3BucketName** 下，輸入 Amazon S3 儲存貯體的名稱。
1. 選取**我確認 AWS CloudFormation 可能會建立 IAM 資源。**核取方塊。
1. 選擇**建立堆疊**。
系統大約需要 10 分鐘才能建立堆疊。
1. 當建置完成時，請選擇**前往快速**，然後輸入您的電子郵件地址以登入您的帳戶。
### 使用主控台建立 帳戶
下列步驟說明如何使用 Amazon Chime SDK 主控台建立快速帳戶。您必須使用 Enterprise 或 Enterprise \$1 Q 帳戶。
**使用主控台**
1. 在 [https://console.aws.amazon.com/chime-sdk/home](https://console.aws.amazon.com/chime-sdk/home)：// 啟動 Amazon Chime SDK 主控台，搜尋 **QuickSight**，然後在搜尋結果中選擇 **QuickSight**。
![\[連結至 Quick 的搜尋結果。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/quicksightsetup-1.png)
1. 選擇 **Sign up for QuickSight (註冊 QuickSight)**。
1. 選擇**企業**或**企業 \$1 Q**，然後選擇**繼續**。
1. 輸入您的名字、姓氏、電話號碼，以及您先前收集的電子郵件地址，然後選擇**繼續**。
1. 請執行下列操作：
1. 在**身分驗證方法**下，選擇選項。
**注意**
如果您使用聯合身分使用者選擇 選項，則需要正確的 IAM 許可。如需詳細資訊，請參閱《 [ 快速使用者指南》中的註冊快速訂閱](https://docs.aws.amazon.com/quicksight/latest/user/signing-up.html)。 **
1. 在 **QuickSight 區域**下，選取區域。
1. 在**帳戶資訊**下，輸入帳戶的名稱，以及您先前收集的電子郵件地址。
1. 在 **QuickSight 存取 AWS Services** 下，使用預設角色，或選擇**使用現有角色**，然後從清單中選擇角色。
1. （選用） 視需要，在**允許這些資源的存取和自動探索**下，選擇其他資源。
1. 完成後，請選擇**完成**。
1. 當建置完成時，請選擇**前往快速**，然後輸入您的電子郵件地址以登入您的帳戶。
## 設定您的 QuickSight 帳戶
登入您的 QuickSight 帳戶後，您需要設定安全性，並將自己新增至設定程序建立的群組。
**設定安全性**
1. 選擇右上角的設定檔圖示，然後從產生的功能表中選擇**管理 QuickSight**。
![\[具有管理 QuickSight 命令的功能表。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/quicksightsetup-1-a.png)
1. 在導覽窗格中，選擇**安全性與許可**。
1. 在 **QuickSight 存取 AWS 服務**下，選擇**管理**，並確保已選取下列服務。
+ Amazon Redshift
+ Amazon RDS
+ Amazon S3
+ Amazon Athena
+ IAM
1. 選擇**選取 Amazon S3 儲存貯**體連結。
1. 選取 Amazon S3 儲存貯體旁的核取方塊，然後在 **Athena 工作群組的寫入許可**欄中選取右側的核取方塊。
1. 選擇**完成**。
1. 選擇**儲存**。
**若要將自己新增至群組**
1. 在導覽窗格中，選擇**管理群組**，然後在名稱中選擇具有**管理員的**群組。例如，*S3BucketName*–**Admins**。
1. 選擇**新增使用者**，然後在出現的方塊中輸入您的電子郵件別名。
您的名稱會顯示為 **Admin – ***your-alias*。
1. 選擇**新增**。
## 建立 QuickSight 儀表板
建立資料湖之後，您可以建立 QuickSight 儀表板來視覺化您的資料。您可以使用 Amazon CloudFormation 範本或 Amazon Chime SDK 主控台來建立儀表板。下列步驟說明這兩種方法。
**使用範本**
1. 啟動 Amazon CloudFormation 主控台。
1. 將以下連結貼到瀏覽器的地址列： `https://region.console.aws.amazon.com/cloudformation/home?region=region#/stacks/quickcreate?templateURL=https://chime-sdk-assets.s3.amazonaws.com/public_templates/AmazonChimeSDKQuickSightDashboards.yaml`
1. 在**快速建立堆疊**頁面的**堆疊名稱**下，輸入帳戶的名稱。
1. 在 **ActiveQuickSightAccount** 下，選擇 **True**。
1. 在 **QuicksightDashboardSelection** 下，選擇**通話分析 – 轉錄通話分析和語音分析儀表板**或**通話分析 – 轉錄和語音分析儀表板**。
1. 在 **Amazon S3BucketName** 下，輸入 Amazon S3 儲存貯體的 URI。
1. 在 **GlueDatabaseName** 下，輸入您要部署 QuickSight 儀表板的 Glue 資料庫。
1. 選擇**我確認 AWS CloudFormation 可能會建立 IAM 資源**核取方塊，然後選擇**建立堆疊**。
**手動設定 QuickSight 儀表板**
1. 導覽至您的 QuickSight 帳戶。
1. 在右上角選擇設定檔圖示，然後選擇**管理 QuickSight**。
![\[QuickSight 帳戶對話方塊和管理 QuickSight 命令。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/quicksightsetup-1-a.png)
1. 在導覽窗格中，選擇**管理群組**，然後選擇設定程序建立的群組。
1. 選擇**新增使用者**，輸入您的電子郵件地址，然後選擇**新增**。
系統需要 10 分鐘才能部署頁面。
1. 使用 Amazon Chime SDK 主控台登入您的 QuickSight 帳戶並使用儀表板。
# Amazon Chime SDK 的呼叫分析資料模型
本節中的資訊會列出並描述 Amazon Chime SDK 呼叫分析資料模型，這是 Glue AWS 資料目錄中的一組資料表。
**Topics**
+ [了解 Amazon Chime SDK AWS Glue 的資料目錄資料表結構](ca-data-model-diagram.md)
+ [了解 Amazon Chime SDK AWS Glue 的資料目錄資料表](glue-tables.md)
+ [擷取資料目錄中 AWS Glue 的資料以進行 Amazon Chime SDK 呼叫分析](ca-data-model-queries.md)
# 了解 Amazon Chime SDK AWS Glue 的資料目錄資料表結構
下圖顯示為 Amazon Chime SDK AWS 呼叫分析和語音分析工作階段建立的 Glue 資料目錄的資料表結構。
![\[呼叫分析 Glue 資料目錄中的資料表。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/glue-cat-diag-12-03.jpg)
下一節列出並說明 目錄中的資料表和欄位。
# 了解 Amazon Chime SDK AWS Glue 的資料目錄資料表
下表列出並描述 Amazon Chime SDK 呼叫分析 Glue 資料目錄中的資料欄、資料類型和元素。
**Topics**
+ [call\$1analytics\$1metadata](#ca-glue-metadata)
+ [call\$1analytics\$1recording\$1metadata](#ca-glue-analytics-recording)
+ [transcribe\$1call\$1analytics](#ca-glue-transcribe-ca)
+ [transcribe\$1call\$1analytics\$1category\$1events](#ca-glue-transcribe-ca-events)
+ [transcribe\$1call\$1analytics\$1post\$1call](#ca-glue-transcribe)
+ [transcribe](#ca-glue-transcribe)
+ [voice\$1analytics\$1status](#ca-glue-va-status)
+ [speaker\$1search\$1status](#ca-glue-speaker-status)
+ [voice\$1tone\$1analysis\$1status](#ca-glue-tone-status)
## call\$1analytics\$1metadata
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/glue-tables.html)
## call\$1analytics\$1recording\$1metadata
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/glue-tables.html)
## transcribe\$1call\$1analytics
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/glue-tables.html)
## transcribe\$1call\$1analytics\$1category\$1events
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/glue-tables.html)
## transcribe\$1call\$1analytics\$1post\$1call
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/glue-tables.html)
## transcribe
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/glue-tables.html)
## voice\$1analytics\$1status
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/glue-tables.html)
## speaker\$1search\$1status
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/glue-tables.html)
## voice\$1tone\$1analysis\$1status
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/glue-tables.html)
# 擷取資料目錄中 AWS Glue 的資料以進行 Amazon Chime SDK 呼叫分析
使用這些範例查詢來擷取和整理 Amazon Chime SDK 呼叫分析 Glue 資料目錄中的資料。
**注意**
如需有關連線至 Amazon Athena 和查詢 Glue 資料目錄的資訊，請參閱[使用 ODBC 連線至 Amazon Athena](https://docs.aws.amazon.com/athena/latest/ug/connect-with-odbc.html)。
請根據需要展開每個區段。
## 從 call\$1analytics\$1metadata 資料表中的中繼資料 (STRING 資料類型） 擷取值
`call_analytics_metadata` 具有 JSON 字串格式`metadata`的欄位。使用 Athena 中的 [json\$1extract\$1scalar 函數](https://docs.aws.amazon.com/athena/latest/ug/extracting-data-from-JSON.html)來查詢此字串中的元素。
```
SELECT
json_extract_scalar(metadata,'$.voiceConnectorId') AS "VoiceConnector ID",
json_extract_scalar(metadata,'$.fromNumber') AS "From Number",
json_extract_scalar(metadata,'$.toNumber') AS "To Number",
json_extract_scalar(metadata,'$.callId') AS "Call ID",
json_extract_scalar(metadata,'$.direction') AS Direction,
json_extract_scalar(metadata,'$.transactionId') AS "Transaction ID"
FROM
"GlueDatabaseName"."call_analytics_metadata"
```
## 在 call\$1analytics\$1metadata 資料表中查詢 SIPRECMetadata 更新
`call_analytics_metadata` 欄位具有 JSON 字串格式的中繼資料欄位。 `metadata` 具有另一個名為 的巢狀物件`oneTimeMetadata`，此物件包含原始 XML 和轉換 JSON 格式的 SIPRec 中繼資料。使用 Athena 中的 `json_extract_scalar`函數來查詢此字串中的元素。
```
SELECT
json_extract_scalar(metadata,'$.voiceConnectorId') AS "VoiceConnector ID",
json_extract_scalar(metadata,'$.fromNumber') AS "From Number",
json_extract_scalar(metadata,'$.toNumber') AS "To Number",
json_extract_scalar(metadata,'$.callId') AS "Call ID",
json_extract_scalar(metadata,'$.direction') AS Direction,
json_extract_scalar(metadata,'$.transactionId') AS "Transaction ID",
json_extract_scalar(json_extract_scalar(metadata,'$.oneTimeMetadata'),'$.siprecMetadata') AS "siprec Metadata XML",
json_extract_scalar(json_extract_scalar(metadata,'$.oneTimeMetadata'),'$.siprecMetadataJson') AS "Siprec Metadata JSON",
json_extract_scalar(json_extract_scalar(metadata,'$.oneTimeMetadata'),'$.inviteHeaders') AS "Invite Headers"
FROM
"GlueDatabaseName"."call_analytics_metadata"
WHERE
callevent-type = "update";
```
## 從 call\$1analytics\$1recording\$1metadata 資料表中的中繼資料 (STRING 資料類型） 擷取值
`call_analytics_recording_metadata` 具有 JSON 字串格式的中繼資料欄位。使用 Athena 中的 [json\$1extract\$1scalar 函數](https://docs.aws.amazon.com/athena/latest/ug/extracting-data-from-JSON.html)來查詢此字串中的元素。
```
SELECT
json_extract_scalar(metadata,'$.voiceConnectorId') AS "VoiceConnector ID",
json_extract_scalar(metadata,'$.fromNumber') AS "From Number",
json_extract_scalar(metadata,'$.toNumber') AS "To Number",
json_extract_scalar(metadata,'$.callId') AS "Call ID",
json_extract_scalar(metadata,'$.direction') AS Direction,
json_extract_scalar(metadata,'$.transactionId') AS "Transaction ID"
FROM
"GlueDatabaseName"."call_analytics_recording_metadata"
WHERE
detail-subtype = "Recording"
```
## 從 voice\$1analytics\$1status 資料表中的詳細資訊 (STRUCT 資料類型） 擷取值
`voice_analytics_status` 在 `struct` 資料類型中具有詳細資訊欄位。下列範例示範如何查詢`struct`資料類型欄位：
```
SELECT
detail.transactionId AS "Transaction ID",
detail.voiceConnectorId AS "VoiceConnector ID",
detail.siprecmetadata AS "Siprec Metadata",
detail.inviteheaders AS "Invite Headers",
detail.streamStartTime AS "Stream Start Time"
FROM
"GlueDatabaseName"."voice_analytics_status"
```
## 聯結 voice\$1analytics\$1status 和 call\$1analytics\$1metadata 資料表
下列範例查詢會聯結 `call_analytics_metadata`和 `voice_analytics_status`：
```
SELECT
a.detail.transactionId AS "Transaction ID",
a.detail.voiceConnectorId AS "VoiceConnector ID",
a.detail.siprecmetadata AS "Siprec Metadata",
a.detail.inviteheaders AS "Invite Headers",
a.detail.streamStartTime AS "Stream Start Time"
json_extract_scalar(b.metadata,'$.fromNumber') AS "From Number",
json_extract_scalar(b.metadata,'$.toNumber') AS "To Number",
json_extract_scalar(b.metadata,'$.callId') AS "Call ID",
json_extract_scalar(b.metadata,'$.direction') AS Direction
FROM
"GlueDatabaseName"."voice_analytics_status" a
INNER JOIN
"GlueDatabaseName"."call_analytics_metadata" b
ON a.detail.transactionId = json_extract_scalar(b.metadata,'$.transactionId')
```
## 從 transcribe\$1call\$1analytics\$1post\$1call 資料表擷取文字記錄
transcribe\$1call\$1analytics\$1post\$1call 具有具有巢狀陣列的結構格式文字記錄欄位。使用下列查詢取消巢狀陣列：
```
SELECT
jobstatus,
languagecode,
IF(CARDINALITY(m.transcript)=0 OR CARDINALITY(m.transcript) IS NULL, NULL, e.transcript.id) AS utteranceId,
IF(CARDINALITY(m.transcript)=0 OR CARDINALITY(m.transcript) IS NULL, NULL, e.transcript.content) AS transcript,
accountid,
channel,
sessionid,
contentmetadata.output AS "Redaction"
FROM
"GlueDatabaseName"."transcribe_call_analytics_post_call" m
CROSS JOIN UNNEST
(IF(CARDINALITY(m.transcript)=0, ARRAY[NULL], transcript)) AS e(transcript)
```
## 加入 transcribe\$1call\$1analytics\$1post\$1call 和 call\$1analytics\$1metadata 資料表
下列查詢聯結 transcribe\$1call\$1analytics\$1post\$1call 和 call\$1analytics\$1metadata：
```
WITH metadata AS(
SELECT
from_iso8601_timestamp(time) AS "Timestamp",
date_parse(date_format(from_iso8601_timestamp(time), '%m/%d/%Y %H:%i:%s') , '%m/%d/%Y %H:%i:%s') AS "DateTime",
date_parse(date_format(from_iso8601_timestamp(time) , '%m/%d/%Y') , '%m/%d/%Y') AS "Date",
date_format(from_iso8601_timestamp(time) , '%H:%i:%s') AS "Time",
mediainsightspipelineid,
json_extract_scalar(metadata,'$.toNumber') AS "To Number",
json_extract_scalar(metadata,'$.voiceConnectorId') AS "VoiceConnector ID",
json_extract_scalar(metadata,'$.fromNumber') AS "From Number",
json_extract_scalar(metadata,'$.callId') AS "Call ID",
json_extract_scalar(metadata,'$.direction') AS Direction,
json_extract_scalar(metadata,'$.transactionId') AS "Transaction ID",
REGEXP_REPLACE(REGEXP_EXTRACT(json_extract_scalar(metadata,'$.oneTimeMetadata.s3RecordingUrl'), '[^/]+(?=\.[^.]+$)'), '\.wav$', '') AS "SessionID"
FROM
"GlueDatabaseName"."call_analytics_metadata"
),
transcript_events AS(
SELECT
jobstatus,
languagecode,
IF(CARDINALITY(m.transcript)=0 OR CARDINALITY(m.transcript) IS NULL, NULL, e.transcript.id) AS utteranceId,
IF(CARDINALITY(m.transcript)=0 OR CARDINALITY(m.transcript) IS NULL, NULL, e.transcript.content) AS transcript,
accountid,
channel,
sessionid,
contentmetadata.output AS "Redaction"
FROM
"GlueDatabaseName"."transcribe_call_analytics_post_call" m
CROSS JOIN UNNEST
(IF(CARDINALITY(m.transcript)=0, ARRAY[NULL], transcript)) AS e(transcript)
)
SELECT
jobstatus,
languagecode,
a.utteranceId,
transcript,
accountid,
channel,
a.sessionid,
"Redaction"
"Timestamp",
"DateTime",
"Date",
"Time",
mediainsightspipelineid,
"To Number",
"VoiceConnector ID",
"From Number",
"Call ID",
Direction,
"Transaction ID"
FROM
"GlueDatabaseName"."transcribe_call_analytics_post_call" a
LEFT JOIN
metadata b
ON
a.sessionid = b.SessionID
```
## 查詢媒體物件 URLs以進行語音增強通話錄音
下列範例查詢會聯結 `Voice enhancement call recording` URL：
```
SELECT
json_extract_scalar(metadata,'$.voiceConnectorId') AS "VoiceConnector ID",
json_extract_scalar(metadata,'$.fromNumber') AS "From Number",
json_extract_scalar(metadata,'$.toNumber') AS "To Number",
json_extract_scalar(metadata,'$.callId') AS "Call ID",
json_extract_scalar(metadata,'$.direction') AS Direction,
json_extract_scalar(metadata,'$.transactionId') AS "Transaction ID",
s3MediaObjectConsoleUrl
FROM
{GlueDatabaseName}."call_analytics_recording_metadata"
WHERE
detail-subtype = "VoiceEnhancement"
```
# 使用 Amazon Chime SDK 語音分析
Amazon Chime SDK 語音分析功能可讓您實作發言者搜尋和語音音調分析。您可以使用發言者搜尋來識別和註冊新發起人，以及識別重複發起人，並為這些識別指派可信度分數。您可以使用語音音調分析，將來電者的情緒預測為 `negative`、 `neutral`或 `positive`。
您可以執行語音分析，做為 Amazon Chime SDK 呼叫分析工作階段的選用元件。
語音分析適用於媒體洞察管道或 Amazon Chime SDK Voice Connectors 呼叫。我們建議您使用[媒體管道 SDK](media-pipelines.md) 並在媒體洞察管道上調用任務，以更精細地控制任務，以及有關任務的資訊。
您可以使用語音連接器來確保回溯相容性，但我們只會使用新功能更新媒體洞見管道 APIs。
如需建立和使用語音連接器的詳細資訊，請參閱《[Amazon Chime SDK 管理員指南》中的管理 Amazon Chime SDK 語音連接器](https://docs.aws.amazon.com/chime-sdk/latest/ag/voice-connectors.html)。 **
語音分析也提供：
+ 非同步任務處理。任務彼此獨立執行。
+ 控制您處理洞見的時間。
您可以呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html)和 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html) APIs 來啟動語音分析。
下列主題說明如何使用語音分析。
**Topics**
+ [了解 Amazon Chime SDK 的語音分析架構](va-architecture.md)
+ [了解 Amazon Chime SDK 的發言者搜尋工作流程](va-data-flow.md)
+ [Amazon Chime SDK 的語音音調分析工作流程範例](va-tone-flow.md)
+ [輪詢 Amazon Chime SDK 的任務結果](va-task-result-poll.md)
+ [了解 Amazon Chime SDK 的通知](va-notification-targets.md)
+ [了解 Amazon Chime SDK 的資料儲存、選擇退出和資料保留政策](va-opt-out.md)
+ [使用語音 APIs執行 Amazon Chime SDK 的語音分析](va-in-voice-namespace.md)
# 了解 Amazon Chime SDK 的語音分析架構
本節中的主題提供 Amazon Chime SDK 語音分析架構的概觀，包括每個功能的資料流程。
此圖表提供資料如何流經語音分析的高階檢視。
![\[圖表顯示語音分析的高階資料流程。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/va-architecture-kvs.png)
在圖表中：
1. 音訊會串流到來電者和客服人員的 Kinesis Video Stream。您可以使用 Kinesis Video Streams 生產者或 Amazon Chime SDK Voice Connector 串流來執行此操作。如需詳細資訊，請參閱本指南[了解 Amazon Chime SDK 機器學習型分析的工作流程](ml-based-analytics.md)中的 ，以及[《Amazon Chime SDK 管理員指南》中的將 Amazon Chime SDK Voice Connector 媒體串流至 Kinesis](https://docs.aws.amazon.com/chime-sdk/latest/ag/start-kinesis-vc.html)。 **
1. 應用程式或建置器會在發起人同意後觸發音訊串流的發言者搜尋、語音音調分析或兩者。
1. 在通話期間，語音分析會將通知傳送至目標，Amazon Simple Queue Service (SQS)、Amazon Simple Notification Service (SNS)、 AWS Lambda 或 Amazon Kinesis Data Streams。
此外，語音分析提供這些工具來管理其產生的資料。
**語音設定檔**
語音內嵌、內嵌的唯一 ID 及其過期日期的組合。基於安全考量，語音設定檔會在三年後過期，因為語音會隨著時間而變更。若要避免重新建立語音設定檔，請呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html) API。如需過期日期的詳細資訊，請參閱 [了解 Amazon Chime SDK 語音分析的資料保留](va-data-retention.md)。
若要註冊語音內嵌，或更新已註冊的語音內嵌，您必須在通話結束後的 24 小時內呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfile.html)或 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html) APIs。
**語音設定檔網域**
語音設定檔的集合。
# 了解 Amazon Chime SDK 的發言者搜尋工作流程
在本節中，我們向您展示 Amazon Chime SDK 發言者搜尋分析的範例資料和程式流程。
發言者搜尋函數涉及建立語音內嵌，可用來比較來電者的語音與先前儲存的語音資料。以數位聲紋形式收集、使用、儲存和保留生物識別符和生物識別資訊，可能需要發起人透過書面版本取得同意。根據各種州法律，包括伊利諾州、德克薩斯州、華盛頓州和其他州隱私權法律，此類同意是必要的。在使用發言者搜尋功能之前，您必須提供所有通知，並依據適用法律以及規範您使用此功能的 [AWS 服務條款](https://aws.amazon.com/service-terms/)，取得所有同意。
下圖顯示透過發言者搜尋分析任務的範例資料流程。圖表下方的編號描述說明程序的每個步驟。圖表假設您已使用具有 的通話分析組態來設定 Amazon Chime SDK Voice Connector`VoiceAnalyticsProcessor`。如需詳細資訊，請參閱[錄製語音連接器呼叫](record-vc-calls.md)。
![\[圖表顯示透過發言者搜尋分析的資料流程。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/speaker-search-workflow-2.png)
1. 您或系統管理員會建立語音設定檔網域，以存放語音內嵌和語音設定檔。如需建立語音設定檔網域的詳細資訊，請參閱《*Amazon Chime SDK 管理員指南*》中的[建立語音設定檔網域](https://docs.aws.amazon.com/chime-sdk/latest/ag/create-vp-domain.html)。您也可以使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfileDomain.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfileDomain.html) API。
1. 來電者使用指派給 Amazon Chime SDK Voice Connector 的電話號碼撥入 。或者，客服人員使用語音連接器號碼進行外撥通話。
1. Amazon Chime SDK Voice Connector 服務會建立交易 ID，並將其與呼叫建立關聯。
1. 假設您的應用程式訂閱 EventBridge 事件，您的應用程式會使用媒體洞察管道組態和語音連接器呼叫的 Kinesis Video Stream ARNs 來呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API。
如需使用 EventBridge 的詳細資訊，請參閱 [了解 Amazon Chime SDK 機器學習型分析的工作流程](ml-based-analytics.md)。
1. 您的應用程式，例如互動式語音回應系統，或客服人員會通知來電者有關通話錄音和使用語音內嵌進行語音分析，並尋求他們的參與同意。
1. 發起人提供同意後，如果您有 Voice Connector 和交易 ID，您的應用程式或客服人員可以透過[語音 SDK](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Voice.html) 呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask.html) API。或者，如果您有媒體洞察管道 ID 而不是交易 ID，您可以在[媒體管道 SDK ](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Media_Pipelines.html)中呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html) API。
一旦發起人提供同意，您的應用程式或客服人員就會呼叫 `StartSpeakerSearchTask` API。您必須將語音連接器 ID、交易 ID 和語音設定檔網域 ID 傳遞給 API。會傳回發言者搜尋任務 ID，以識別非同步任務。
**注意**
在任一SDKs中調用 `StartSpeakerSearchTask` API 之前，您必須根據法律和 [AWS 服務條款](https://aws.amazon.com/service-terms/)的要求，提供任何必要的通知，並取得任何必要的同意。
1. 系統會累積 10 秒的來電者語音。發起人必須至少說出該時間。系統不會擷取或分析靜音。
1. 媒體洞察管道會將語音與網域中的語音設定檔進行比較，並列出前 10 個高可信度配對。如果找不到相符項目，語音連接器會建立語音設定檔。
1. 媒體洞察管道服務會將通知事件傳送至設定的通知目標。
1. 發起人會繼續說話，並提供額外 10 秒的非靜音語音。
1. 媒體洞察管道會產生註冊語音內嵌，您可以用來建立語音設定檔或更新現有的語音設定檔。
1. 媒體洞察管道會將`VoiceprintGenerationSuccessful`通知傳送至設定的通知目標。
1. 您的應用程式會呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfile.html)或 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html) APIs來建立或更新設定檔。
1. 您的應用程式會視需要呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetSpeakerSearchTask.html) API，以取得發言者搜尋任務的最新狀態。
# Amazon Chime SDK 的語音音調分析工作流程範例
**重要**
語音音調分析涉及根據語言和音調資訊，對發言者的情緒進行預測。您不得以任何法律禁止的方式使用情緒分析，包括做出有關個人的決策，這些決策會對這些個人產生法律或類似的重大影響 （例如，與就業、房屋、信用價值或財務優惠等相關）。
語音音調分析會分析通話中人物的語音，並預測他們的情緒，可能是 `positive`、 `negative`或 `neutral`。
下圖顯示語音音調分析的範例工作流程。影像下方的編號項目說明程序的每個步驟。
**注意**
圖表假設您已使用具有 的通話分析組態來設定 Amazon Chime SDK Voice Connector`VoiceAnalyticsProcessor`。如需詳細資訊，請參閱[錄製語音連接器呼叫](record-vc-calls.md)。
![\[顯示透過語音音調分析之資料流程的圖表。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/voice-tone-workflow-v2.png)
在圖表中：
1. 來電者使用指派給 Amazon Chime SDK Voice Connector 的電話號碼撥入 。或者，客服人員使用語音連接器號碼進行外撥通話。
1. Voice Connector 服務會建立交易 ID，並將其與呼叫建立關聯。
1. 您的應用程式，例如互動式語音回應系統，或客服人員會通知來電者有關通話錄音和使用語音內嵌進行語音分析，並尋求他們的參與同意。
1. 假設您的應用程式訂閱 EventBridge 事件，您的應用程式會使用媒體洞察管道組態和語音連接器呼叫的 Kinesis Video Stream ARNs 來呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API。
如需使用 EventBridge 的詳細資訊，請參閱 [了解 Amazon Chime SDK 機器學習型分析的工作流程](ml-based-analytics.md)。
1. 發起人提供同意後，如果您有語音連接器和交易 ID，您的應用程式或客服人員可以透過語音 [ SDK](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Voice.html) 呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask.html) API。或者，如果您有媒體洞察管道 ID 而不是交易 ID，您可以在[媒體管道 SDK ](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Media_Pipelines.html)中呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html) API。
一旦發起人提供同意，您的應用程式或客服人員就會呼叫 `StartSpeakerSearchTask` API。您必須將語音連接器 ID、交易 ID 和語音設定檔網域 ID 傳遞給 API。會傳回發言者搜尋任務 ID，以識別非同步任務。
1. 使用者在整個通話中說話。
1. 客服人員會在通話過程中說話。
1. 每 5 秒，媒體洞察管道會使用機器學習模型來分析最後 30 秒的語音，並預測該間隔的發起人語氣，以及從`StartVoiceToneAnalysisTask`第一次呼叫 時開始的整個通話。
1. 媒體洞察管道會將含有該資訊的通知傳送至設定的通知目標。您可以根據其串流 ARN 和頻道 ID 來識別通知。如需詳細資訊[了解 Amazon Chime SDK 的通知](va-notification-targets.md)，請參閱本節稍後的 。
1. 重複步驟 9 和 10，直到通話結束。
1. 在通話結束時，媒體洞察管道會傳送一個最終通知，其中包含過去 30 秒內目前的平均音調預測，以及整個通話的平均音調。
1. 您的應用程式會視需要呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetVoiceToneAnalysisTask.html) API，以取得語音音調分析任務的最新狀態。
**注意**
`GetVoiceToneAnalysisTask` API 不會串流音調資料。
**注意**
[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetVoiceToneAnalysisTask.html) API 不會傳回語音音調資料。
# 輪詢 Amazon Chime SDK 的任務結果
**重要**
根據預設，語音分析會提供 7 天的結果，然後會自動刪除資料。如果您想要長時間使用任務資料，或要遵守資料保留法，則必須存放任務資料。如需詳細資訊[了解 Amazon Chime SDK 語音分析的資料保留](va-data-retention.md)，請參閱本指南稍後的 。
語音分析會嘗試確保每個任務結果至少傳遞一次。不過，網路問題可能會增加延遲。若要解決潛在問題，或者如果您偏好同步程序，您可以在[媒體管道 SDK ](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Media_Pipelines.html)或[語音 SDK](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Voice.html) 中使用下列 APIs：
+ [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetSpeakerSearchTask.html)
+ [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetVoiceToneAnalysisTask.html)
**重要**
`GetVoiceToneAnalysisTask` API 只會傳回任務的狀態。它不會傳回任務結果。若要查看結果，請使用 Amazon SQS、Amazon SNS 或 AWS Lambda 通知目標。
`GetSpeakerSearchTask` API 會同步取得任務 ID、延遲訊息或不符合順序的訊息的最新結果。不過，我們建議您使用通知目標和非同步處理。這樣做會消耗較少的運算資源。
# 了解 Amazon Chime SDK 的通知
語音分析會在發言者搜尋或語音音調分析任務開始時、執行期間以及完成時，自動將事件傳送至目標。您可以使用通知目標來接收這些事件。如果您的工作流程或應用程式需要高可用性，我們建議您使用多個通知目標。
此外，您必須使用 IAM 角色搭配存取通知目標所需的政策。如需詳細資訊，請參閱[使用 Amazon Chime SDK 的呼叫分析資源存取角色](call-analytics-resource-access-role.md)。
**注意**
對於 Amazon SQS 和 Amazon SNS，我們不支援first-in-first-out佇列。因此，訊息可能無法按順序送達。建議您檢查時間戳記以視需要排序訊息，並在 Amazon DynamoDB 等資料存放區中保留訊息。您也可以使用中所述APIs [輪詢 Amazon Chime SDK 的任務結果](va-task-result-poll.md) 來接收最新結果。
下表列出事件及其對應的詳細資訊類型。
| 通知事件 | 詳細資訊類型 |
| --- | --- |
| 語音分析中繼資料 | `VoiceAnalyticsStatus` |
| 發言者搜尋 | `SpeakerSearchStatus` |
| 語音音調分析 | `VoiceToneAnalysisStatus` |
# 了解 Amazon Chime SDK 通知目標的 IAM 政策
您必須在通話分析組態中使用 IAM 角色中的政策，以允許存取您的 Amazon SQS、Amazon SNS、AWS Lambda 或 Amazon KDS 通知目標。如需詳細資訊，請參閱本指南中的 [使用 Amazon Chime SDK 的呼叫分析資源存取角色](call-analytics-resource-access-role.md)。
## 發言者搜尋事件
發言者搜尋事件具有`SpeakerSearchStatus`詳細資訊類型。
Amazon Chime SDK Voice Connectors 會傳送下列發言者搜尋事件：
+ 識別相符項目
+ 語音內嵌產生
事件可以有下列狀態：
+ `IdentificationSuccessful` – 成功識別至少一個在指定語音設定檔網域中具有高可信度分數的相符語音設定檔 ID。
+ `IdentificationFailure` – 無法執行識別。原因：來電者至少 10 秒沒有說話，音訊品質不佳。
+ `IdentificationNoMatchesFound` – 在指定的語音設定檔網域中找不到高度可信度相符項目。發起人可能是新的，或其語音可能已變更。
+ `VoiceprintGenerationSuccessful` – 系統使用 20 秒的非靜音音訊產生語音內嵌。
+ `VoiceprintGenerationFailure` – 系統無法產生語音內嵌。原因：來電者至少 20 秒沒有說話，音訊品質不佳。
### 識別相符項目
為指定的 呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask) API 之後`transactionId`，語音連接器服務會在 10 秒的非無提示語音之後傳回識別比對通知。服務會傳回前 10 個相符項目，以及 【0， 1】 範圍內的語音設定檔 ID 和可信度分數。可信度分數越高，通話的發言者越有可能符合語音設定檔 ID。如果機器學習模型找不到相符項目，通知`detailStatus`的欄位會包含 `IdentificationNoMatchesFound`。
下列範例顯示成功配對的通知。
```
{
"version": "0",
"id": "12345678-1234-1234-1234-111122223333",
"detail-type": "SpeakerSearchStatus",
"service-type": "VoiceAnalytics",
"source": "aws.chime",
"account": "111122223333",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [],
"detail": {
"taskId": "uuid",
"detailStatus": "IdentificationSuccessful",
"speakerSearchDetails" : {
"results": [
{
"voiceProfileId": "vp-505e0992-82da-49eb-9d4a-4b34772b96b6",
"confidenceScore": "0.94567856",
},
{
"voiceProfileId": "vp-fba9cbfa-4b8d-4f10-9e41-9dfdd66545ab",
"confidenceScore": "0.82783350",
},
{
"voiceProfileId": "vp-746995fd-16dc-45b9-8965-89569d1cf787",
"confidenceScore": "0.77136436",
}
]
},
"mediaInsightsPipelineId": "87654321-33ca-4dc6-9cdf-abcde6612345",
"sourceArn": "arn:aws:chime:us-east-1:111122223333:media-pipeline/87654321-33ca-4dc6-9cdf-abcde6612345",
"streamArn": "arn:aws:kinesisvideo:us-east-1:111122223333:stream/my-stream/0123456789012",
"channelId": 0
}
}
```
### 語音內嵌產生
在額外 10 秒的非靜音語音之後，語音連接器會將語音內嵌產生通知傳送至通知目標。您可以在語音設定檔中註冊新的語音內嵌，或更新已在語音設定檔中的列印。
下列範例顯示成功配對的通知，這表示您可以更新相關聯的語音設定檔。
```
{
"version": "0",
"id": "12345678-1234-1234-1234-111122223333",
"detail-type": "SpeakerSearchStatus",
"service-type": "VoiceAnalytics",
"source": "aws.chime",
"account": "111122223333",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [],
"detail": {
"taskId": "guid",
"detailStatus": "VoiceprintGenerationSuccess",
"mediaInsightsPipelineId": "87654321-33ca-4dc6-9cdf-abcde6612345",
"sourceArn": "arn:aws:chime:us-east-1:111122223333:media-pipeline/87654321-33ca-4dc6-9cdf-abcde6612345",
"streamArn": "arn:aws:kinesisvideo:us-east-1:111122223333:stream/my-stream/0123456789012",
"channelId": 0
}
}
```
## 語音音調分析事件
語音音調分析事件具有`VoiceToneAnalysisStatus`詳細資訊類型。分析可以傳回這些狀態：
+ `VoiceToneAnalysisSuccessful` – 成功將來電者和客服人員的語音分析為情緒的機率：正面、負面或中性。
+ `VoiceToneAnalysisFailure` – 無法執行音調分析。如果來電者未說話就掛斷 10 秒，或音訊品質變得太差，就會發生這種情況。
+ `VoiceToneAnalysisCompleted` – 成功將使用者和客服人員的語音分析為整個通話的情緒可能性。這是語音音調分析完成時傳送的最終事件。
下列範例顯示典型的音調分析事件。
```
{
"detail-type": "VoiceToneAnalysisStatus",
"service-type": "VoiceAnalytics",
"source": "aws.chime",
"account": "216539279014",
"time": "2022-08-26T17:55:15.563441Z",
"region": "us-east-1",
"detail": {
"taskId": "uuid",
"detailStatus": "VoiceToneAnalysisSuccessful",
"voiceToneAnalysisDetails": {
"currentAverageVoiceTone": {
"startTime": "2022-08-26T17:55:15.563Z",
"endTime": "2022-08-26T17:55:45.720Z",
"voiceToneLabel": "neutral",
"voiceToneScore": {
"neutral": "0.83",
"positive": "0.13",
"negative": "0.04"
}
},
"overallAverageVoiceTone": {
"startTime": "2022-08-26T16:23:13.344Z",
"endTime": "2022-08-26T17:55:45.720Z",
"voiceToneLabel": "positive",
"voiceToneScore": {
"neutral": "0.25",
"positive": "0.65",
"negative": "0.1"
}
}
},
"startFragmentNumber": "01234567890123456789",
"mediaInsightsPipelineId": "87654321-33ca-4dc6-9cdf-abcde6612345",
"sourceArn": "arn:aws:chime:us-east-1:111122223333:media-pipeline/87654321-33ca-4dc6-9cdf-abcde6612345",
"streamArn": "arn:aws:kinesisvideo:us-east-1:111122223333:stream/my-stream/0123456789012",
"channelId": 0
},
"version": "0",
"id": "Id-f928dfe3-f44b-4965-8a17-612f9fb92d59"
}
```
## 通話後摘要事件
通話結束後 5 分鐘會傳送通話後摘要事件。這些摘要提供在整個通話中發生的發言者搜尋任務的概觀。
下列範例顯示通話後摘要，其中包含最佳語音設定檔相符項目、已確認的發言者身分，以及透過 `CreateVoiceProfile`和 `UpdateVoiceProfile` API 在通話期間所建立或更新的語音設定檔清單。
```
{
"version": "0",
"id": "12345678-1234-1234-1234-111122223333",
"detail-type": "VoiceAnalyticsStatus",
"service-type": "VoiceAnalytics",
"source": "aws.chime",
"account": "111122223333",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [],
"detail": {
"detailStatus": "PostCallVoiceAnalytics",
"callId": "22e8dee8-bbd7-4f94-927b-2d0ebaeddc1c",
"transactionId": "daaeb6bf-2fe2-4e51-984e-d0fbf2f09436",
"voiceConnectorId": "abcdef1ghij2klmno3pqr4",
"isCaller": true | false,
"speakerSearchResults": {
"bestMatchedVoiceProfileId": "vp-04c25ba1-a059-4fd3-8495-4ac91b55e2bf",
"customerValidatedCallerIdentity": "vp-04c25ba1-a059-4fd3-8495-4ac91b55e2bf",
"createVoiceProfileTransactions": [
{
"voiceProfileId": "vp-04c25ba1-a059-4fd3-8495-4ac91b55e2bf",
"requestTimestamp": "2022-12-14T18:38:38.796Z"
},
{
"voiceProfileId": "vp-04c25ba1-a059-4fd3-8495-4ac91b55e2bf",
"requestTimestamp": "2022-12-14T18:38:38.796Z",
}
],
"updateVoiceProfileTransactions": [
{
"voiceProfileId": "vp-04c25ba1-a059-4fd3-8495-4ac91b55e2bf",
"requestTimestamp": "2022-12-14T18:38:38.796Z",
},
{
"voiceProfileId": "vp-04c25ba1-a059-4fd3-8495-4ac91b55e2bf",
"requestTimestamp": "2022-12-14T18:38:38.796Z",
}
]
}
}
}
```
# Amazon Chime SDK 的語音分析範例 Lambda 函數
下列範例中的 Python 程式碼會處理從語音連接器收到的通知。您可以將程式碼新增至 AWS Lambda 函數。您也可以使用它來觸發 Amazon SQS 佇列、Amazon SNS 主題或 Amazon Kinesis Data Stream。然後，您可以將通知存放在 中`EventTable`以供日後處理。如需確切的通知格式，請參閱 [了解 Amazon Chime SDK 的通知](va-notification-targets.md)。
```
import base64
import boto3
import json
import logging
import time
from datetime import datetime
from enum import Enum
log = logging.getLogger()
log.setLevel(logging.INFO)
dynamo = boto3.client("dynamodb")
EVENT_TABLE_NAME = "EventTable"
class EventType(Enum):
"""
This example code uses a single Lambda processor to handle either
triggers from SQS, SNS, Lambda, or Kinesis. You can adapt it to fit your
desired infrastructure depending on what you prefer. To distinguish
where we get events from, we use an EventType enum as an
example to show the different ways of parsing the notifications.
"""
SQS = "SQS"
SNS = "SNS"
LAMBDA = "LAMBDA"
KINESIS = "KINESIS"
class AnalyticsType(Enum):
"""
Define the various analytics event types that this Lambda will
handle.
"""
SPEAKER_SEARCH = "SpeakerSearch"
VOICE_TONE_ANALYSIS = "VoiceToneAnalysis"
ANALYTICS_READY = "AnalyticsReady"
UNKNOWN = "UNKNOWN"
class DetailType(Enum):
"""
Define the various detail types that Voice Connector's voice
analytics feature can return.
"""
SPEAKER_SEARCH_TYPE = "SpeakerSearchStatus"
VOICE_TONE_ANALYSIS_TYPE = "VoiceToneAnalysisStatus"
ANALYTICS_READY = "VoiceAnalyticsStatus"
def handle(event, context):
"""
Example of how to handle incoming Voice Analytics notification messages
from Voice Connector.
"""
logging.info(f"Received event of type {type(event)} with payload {event}")
is_lambda = True
# Handle triggers from SQS, SNS, and KDS. Use the below code if you would like
# to use this Lambda as a trigger for an existing SQS queue, SNS topic or Kinesis
# stream.
if "Records" in event:
logging.info("Handling event from SQS or SNS since Records exists")
is_lambda = False
for record in event.get("Records", []):
_process_record(record)
# If you would prefer to have your Lambda invoked directly, use the
# below code to have the Voice Connector directly invoke your Lambda.
# In this scenario, there are no "Records" passed.
if is_lambda:
logging.info(f"Handling event from Lambda")
event_type = EventType.LAMBDA
_process_notification_event(event_type, event)
def _process_record(record):
# SQS and Kinesis use eventSource.
event_source = record.get("eventSource")
# SNS uses EventSource.
if not event_source:
event_source = record.get("EventSource")
# Assign the event type explicitly based on the event source value.
event_type = None
if event_source == "aws:sqs":
event = record["body"]
event_type = EventType.SQS
elif event_source == "aws:sns":
event = record["Sns"]["Message"]
event_type = EventType.SNS
elif event_source == "aws:kinesis":
raw_data = record["kinesis"]["data"]
raw_message = base64.b64decode(raw_data).decode('utf-8')
event = json.loads(raw_message)
event_type = EventType.KINESIS
else:
raise Exception(f"Event source {event_source} is not supported")
_process_notification_event(event_type, event)
def _process_notification_event(
event_type: EventType,
event: dict
):
"""
Extract the attributes from the Voice Analytics notification message
and store it as a DynamoDB item to process later.
"""
message_id = event.get("id")
analytics_type = _get_analytics_type(event.get("detail-type"))
pk = None
if analytics_type == AnalyticsType.ANALYTICS_READY.value or analytics_type == AnalyticsType.UNKNOWN.value:
transaction_id = event.get("detail").get("transactionId")
pk = f"transactionId#{transaction_id}#notificationType#{event_type.value}#analyticsType#{analytics_type}"
else:
task_id = event.get("detail").get("taskId")
pk = f"taskId#{task_id}#notificationType#{event_type.value}#analyticsType#{analytics_type}"
logging.info(f"Generated PK {pk}")
_create_request_record(pk, message_id, json.dumps(event))
def _create_request_record(pk: str, sk: str, body: str):
"""
Record this notification message into the Dynamo db table
"""
try:
# Use consistent ISO8601 date format.
# 2019-08-01T23:09:35.369156 -> 2019-08-01T23:09:35.369Z
time_now = (
datetime.utcnow().isoformat()[:-3] + "Z"
)
response = dynamo.put_item(
Item={
"PK": {"S": pk},
"SK": {"S": sk},
"body": {"S": body},
"createdOn": {"S": time_now},
},
TableName=EVENT_TABLE_NAME,
)
logging.info(f"Added record in table {EVENT_TABLE_NAME}, response : {response}")
except Exception as e:
logging.error(f"Error in adding record: {e}")
def _get_analytics_type(detail_type: str):
"""
Get analytics type based on message detail type value.
"""
if detail_type == DetailType.SPEAKER_SEARCH_TYPE.value:
return AnalyticsType.SPEAKER_SEARCH.value
elif detail_type == DetailType.VOICE_TONE_ANALYSIS_TYPE.value:
return AnalyticsType.VOICE_TONE_ANALYSIS.value
elif detail_type == DetailType.ANALYTICS_READY.value:
return AnalyticsType.ANALYTICS_READY.value
else:
return AnalyticsType.UNKNOWN.value
```
**重要**
您必須先取得同意，才能呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask)或 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysis.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysis.html) APIs。我們建議您將事件保留在保留區域中，例如 Amazon DynamoDB，直到您取得同意為止。
# 了解 Amazon Chime SDK 的資料儲存、選擇退出和資料保留政策
Amazon Chime SDK 使用語音資料來提供和改善發言者搜尋服務。為此，我們使用註冊音訊、用於建立語音內嵌的錄製程式碼片段，來訓練我們的機器學習和人工智慧模型。您可以選擇不讓資料用於訓練模型，本節中的主題會說明如何進行。
**Topics**
+ [了解 Amazon Chime SDK 發言者搜尋的資料儲存](speaker-search-data-storage.md)
+ [處理 Amazon Chime SDK 的發言者搜尋選擇退出](va-handle-opt-outs.md)
+ [了解 Amazon Chime SDK 語音分析的資料保留](va-data-retention.md)
# 了解 Amazon Chime SDK 發言者搜尋的資料儲存
Amazon Chime SDK 會存放下列用於發言者搜尋的資料：
+ 連接至語音設定檔的語音內嵌，用於提供發言者搜尋功能。
+ 註冊音訊，用於為每個語音設定檔建立語音內嵌的錄製語音片段。我們使用註冊錄音來：
+ 將發言者搜尋模型保持在最新狀態，這是提供發言者搜尋功能的關鍵部分。
+ 訓練機器學習模型以開發和改善服務。使用註冊音訊進行訓練是選用的，您可以透過選取選擇退出政策來選擇退出此使用，如下節所述。
# 處理 Amazon Chime SDK 的發言者搜尋選擇退出
您可以為最終使用者和整個組織處理選擇退出。選擇退出具有以下影響：
+ 在您選擇退出後，語音分析將不會使用任何新的註冊音訊進行模型訓練，也不會使用在您選擇退出之前收集和儲存的任何註冊音訊。
+ 在您選擇退出後，語音分析將存放和使用註冊音訊，以提供發言者搜尋服務。
**警告**
下列選擇退出動作是不可復原的。您無法復原已刪除的資料。
**處理最終使用者選擇退出**
當最終使用者想要選擇退出發言者搜尋時，請呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_DeleteVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_DeleteVoiceProfile.html) API。此動作會移除語音設定檔，以及語音內嵌和註冊音訊。
若要刪除一組語音內嵌，請呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_DeleteVoiceProfileDomain.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_DeleteVoiceProfileDomain.html) API 以移除網域。此動作會刪除網域中的所有**語音設定檔。
**在組織層級處理選擇退出**
若要處理整個組織的選擇退出，請使用 AWS Organizations 選擇退出政策。使用 `chimesdkvoiceanalytics` 服務名稱。如需政策的相關資訊，請參閱 *AWS Organizations 使用者指南*中的 [ AI 服務選擇退出政策](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_ai-opt-out.html)。
**注意**
若要使用選擇退出政策， AWS 您的帳戶必須由 AWS Organizations 集中管理。如果您尚未為 AWS 帳戶建立組織，請參閱 [Organizations 使用者指南中的建立和管理](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org.html)*AWS 組織*。
# 了解 Amazon Chime SDK 語音分析的資料保留
根據預設，Amazon Chime SDK 語音分析會在 3 年後刪除語音內嵌。我們這樣做是因為人們的聲音會隨著時間而改變，也為了安全著想。您可以使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html) API 來更新過期的語音內嵌。
來自 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask.html)和 的結果[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysisTask.html)也會從其各自的 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetSpeakerSearchTask.html) 和 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetVoiceToneAnalysisTask.html) APIs 提供最多 7 天。
從 產生的語音內嵌[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask.html)可透過 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfile.html)和 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html) APIs 進行 24 小時的持久性，之後就會將其刪除且無法使用。
若要移除結果，以及處理客戶撤回的同意，請參閱上一節。
# 使用語音 APIs執行 Amazon Chime SDK 的語音分析
為了回溯相容性，您可以使用 Amazon Chime SDK Voice APIs來啟動和管理語音分析。不過，只有用於語音分析的媒體洞察管道 APIs 提供新功能，因此我們強烈建議改用它們。
下列各節說明語音和媒體洞察管道 APIs 之間的差異。
## 停止任務
如果您使用語音連接器啟動語音分析任務，然後使用 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineStatus.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineStatus.html) API 暫停管道，則任務會繼續執行。若要停止任務，您必須呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StopSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StopSpeakerSearchTask.html)和 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StopVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StopVoiceToneAnalysisTask.html) APIs。
## 了解通知差異
當您使用語音 APIs執行語音分析時，通知會與媒體洞察管道產生的通知不同。
+ 語音分析就緒事件僅適用於開始使用語音 APIs的任務。
+ 您需要使用通知中的 `voiceConnectorId`、 `transactionId`或 `callId` 欄位，將語音分析任務與通話建立關聯。如果您使用媒體洞察管道來執行語音分析，您可以使用 `mediaInsightsPipelineId`和 `streamArn`或 `channelId` 欄位將任務與通話建立關聯。
下列主題說明如何搭配語音 APIs使用通知。
**Topics**
+ [語音分析就緒事件](#va-ready-events)
+ [發言者搜尋事件](#va-speaker-search-events)
+ [語音音調分析事件](#va-tone-status)
### 語音分析就緒事件
語音分析就緒事件具有`VoiceAnalyticsStatus`詳細資訊類型。
您可以使用 Amazon Chime SDK Voice Connectors 來啟動分析任務。當您收到語音分析就緒事件時，您可以觸發通話的發言者搜尋或語音音分析任務，由下列屬性識別：
+ `voiceConnectorId`
+ `transactionId`
**注意**
只有在您已啟用語音分析並與語音連接器建立關聯的媒體洞見管道組態時，才會提供此通知。當客戶透過媒體管道 SDK 呼叫 `CreateMediaInsightsPipeline` API 並啟動發言者搜尋任務或音調分析任務時，不會提供此通知。
Voice Connector 傳回的 SIP 標頭包含 `transactionId`。如果您無法存取 SIP 標頭，`AnalyticsReady`通知事件也會包含 `voiceConnectorId`和 `transactionId`。這可讓您以程式設計方式接收資訊並呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask)、 或 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysis.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysis.html) APIs。
當語音分析準備好進行處理時，語音連接器會將事件`"detailStatus": "AnalyticsReady"`以 JSON 內文的形式傳送至通知目標。如果您使用 Amazon SNS 或 Amazon SQS，則該內文會出現在 Amazon SNS 或 Amazon SQS 承載的「記錄」欄位中。
下列範例顯示典型的 JSON 內文。
```
{
"detail-type": "VoiceAnalyticsStatus",
"version": "0",
"id": "Id-f928dfe3-f44b-4965-8a17-612f9fb92d59",
"source": "aws.chime",
"account": "123456789012",
"time": "2022-08-26T17:55:15.563441Z",
"region": "us-east-1",
"resources": [],
"detail": {
"detailStatus": "AnalyticsReady",
"callDetails": {
"isCaller": false,
"transactionId": "daaeb6bf-2fe2-4e51-984e-d0fbf2f09436",
"voiceConnectorId": "fuiopl1fsv9caobmqf2vy7"
}
}
}
```
此通知可讓您在呼叫語音分析任務 APIs 之前，觸發應用程式的其他回呼，並處理任何法律要求，例如通知和同意。
### 發言者搜尋事件
發言者搜尋事件具有`SpeakerSearchStatus`詳細資訊類型。
Amazon Chime SDK Voice Connectors 會傳送下列發言者搜尋事件：
+ 識別相符項目
+ 語音內嵌產生
事件可以有下列狀態：
+ `IdentificationSuccessful` – 成功識別至少一個在指定語音設定檔網域中具有高可信度分數的相符語音設定檔 ID。
+ `IdentificationFailure` – 無法執行識別。原因：來電者至少 10 秒沒有說話，音訊品質不佳。
+ `IdentificationNoMatchesFound` – 在指定的語音設定檔網域中找不到高度可信度相符項目。發起人可能是新的，或其語音可能已變更。
+ `VoiceprintGenerationSuccessful` – 系統使用 20 秒的非靜音音訊產生語音內嵌。
+ `VoiceprintGenerationFailure` – 系統無法產生語音內嵌。原因：來電者至少 20 秒沒有說話，音訊品質不佳。
#### 識別相符項目
為指定的 呼叫 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask) API 之後`transactionId`，語音連接器服務會在 10 秒的非無提示語音之後傳回識別比對通知。服務會傳回前 10 個相符項目，以及 【0， 1】 範圍內的語音設定檔 ID 和可信度分數。可信度分數越高，通話的發言者越有可能符合語音設定檔 ID。如果機器學習模型找不到相符項目，通知`detailStatus`的欄位會包含 `IdentificationNoMatchesFound`。
下列範例顯示成功配對的通知。
```
{
"version": "0",
"id": "12345678-1234-1234-1234-111122223333",
"detail-type": "SpeakerSearchStatus",
"service-type": "VoiceAnalytics",
"source": "aws.chime",
"account": "111122223333",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [],
"detail": {
"taskId": "uuid",
"detailStatus": "IdentificationSuccessful",
"speakerSearchDetails" : {
"results": [
{
"voiceProfileId": "vp-505e0992-82da-49eb-9d4a-4b34772b96b6",
"confidenceScore": "0.94567856",
},
{
"voiceProfileId": "vp-fba9cbfa-4b8d-4f10-9e41-9dfdd66545ab",
"confidenceScore": "0.82783350",
},
{
"voiceProfileId": "vp-746995fd-16dc-45b9-8965-89569d1cf787",
"confidenceScore": "0.77136436",
}
]
},
"isCaller": false,
"voiceConnectorId": "abcdef1ghij2klmno3pqr4",
"transactionId": "daaeb6bf-2fe2-4e51-984e-d0fbf2f09436"
}
}
```
#### 語音內嵌產生
多過 10 秒的非靜音語音後，語音連接器會傳送語音內嵌產生通知至通知目標。您可以在語音設定檔中註冊新的語音內嵌，或更新已在語音設定檔中的列印。
下列範例顯示成功配對的通知，這表示您可以更新相關聯的語音設定檔。
```
{
"version": "0",
"id": "12345678-1234-1234-1234-111122223333",
"detail-type": "SpeakerSearchStatus",
"service-type": "VoiceAnalytics",
"source": "aws.chime",
"account": "111122223333",
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "us-east-1",
"resources": [],
"detail": {
"taskId": "guid",
"detailStatus": "VoiceprintGenerationSuccess",
"isCaller": false,
"transactionId": "12345678-1234-1234",
"voiceConnectorId": "abcdef1ghij2klmno3pqr"
}
}
```
### 語音音調分析事件
語音音調分析事件具有`VoiceToneAnalysisStatus`詳細資訊類型。分析可以傳回這些狀態：
+ `VoiceToneAnalysisSuccessful` – 成功將來電者和客服人員的語音分析為情緒的機率：正面、負面或中性。
+ `VoiceToneAnalysisFailure` – 無法執行音調分析。如果來電者未說話就掛斷 10 秒，或音訊品質變得太差，就會發生這種情況。
+ `VoiceToneAnalysisCompleted` – 成功將使用者和客服人員的語音分析為整個通話的情緒可能性。這是語音音調分析完成時傳送的最終事件。
下列範例顯示典型的音調分析事件。
```
{
"detail-type": "VoiceToneAnalysisStatus",
"service-type": "VoiceAnalytics",
"source": "aws.chime",
"account": "216539279014",
"time": "2022-08-26T17:55:15.563441Z",
"region": "us-east-1",
"detail": {
"taskId": "uuid",
"detailStatus": "VoiceToneAnalysisSuccessful",
"voiceToneAnalysisDetails": {
"currentAverageVoiceTone": {
"startTime": "2022-08-26T17:55:15.563Z",
"endTime": "2022-08-26T17:55:45.720Z",
"voiceToneLabel": "neutral",
"voiceToneScore": {
"neutral": "0.83",
"positive": "0.13",
"negative": "0.04"
}
},
"overallAverageVoiceTone": {
"startTime": "2022-08-26T16:23:13.344Z",
"endTime": "2022-08-26T17:55:45.720Z",
"voiceToneLabel": "positive",
"voiceToneScore": {
"neutral": "0.25",
"positive": "0.65",
"negative": "0.1"
}
}
},
"isCaller": true,
"transactionId": "daaeb6bf-2fe2-4e51-984e-d0fbf2f09436",
"voiceConnectorId": "fuiopl1fsv9caobmqf2vy7"
},
"version": "0",
"id": "Id-f928dfe3-f44b-4965-8a17-612f9fb92d59"
}
```
# Amazon Chime SDK 的呼叫分析服務配額
本節中的資料表列出 Amazon Chime SDK 呼叫分析的服務配額。
如需 呼叫分析區域的詳細資訊，請參閱本指南[Amazon Chime SDK 的可用 AWS 區域](sdk-available-regions.md)稍早的 。
Amazon Chime SDK 呼叫分析和語音分析具有下列服務配額。
| 資源 | 預設值限制 | 可調整 |
| --- | --- | --- |
| 每個區域的 Media Insights 管道組態 | 100 | 是 |
| 每個區域的作用中 Media Insights 管道 | 20 | 是 |
| 每個區域的語音設定檔網域 | 3 | 是 |
| 每個語音設定檔網域的語音設定檔 | 20 | 是 |
| 每個區域的作用中發言者搜尋任務 | 25 | 是 |
| 每個區域的作用中語音音調分析任務 | 25 | 是 |
| 每個區域具有語音分析的作用中 Voice Connector 呼叫 | 25 | 是 |
| 每個交易 ID 每個 Voice Connector 呼叫的作用中發言者搜尋任務 | 1 | 否 |
| 每個交易 ID 每個 Voice Connector 呼叫的作用中音調分析任務 | 1 | 否 |
| 每個語音設定檔網域的並行 API 呼叫上限 | 1 | 是 |
| 每個語音設定檔的並行 API 呼叫上限 | 1 | 是 |
| 每個發言者搜尋任務的並行 API 呼叫上限 | 1 | 是 |
| 每個語音音調分析任務的並行 API 呼叫上限 | 1 | 是 |
如需 API 速率和配額的詳細資訊，請參閱《 *AWS 一般參考*》中的 [Amazon Chime SDK 端點和配額](https://docs.aws.amazon.com/general/latest/gr/chime-sdk.html)。
**注意**
如果您超過任何區域的配額，您會收到**超出資源限制的**例外狀況。您可以使用 AWS 主控台中的 **Service Quotas** 頁面來請求提高，也可以聯絡您的[客戶支援代表](https://docs.aws.amazon.com/awssupport/latest/user/getting-started.html)。
數個呼叫分析 APIs會為其他服務建立資源和 API 請求 AWS 。這些額外計數會計入您帳戶的配額。如果您請求提高通話分析的配額或transactions-per-second，您還必須為那些其他服務請求提高 AWS 。否則，您的請求可能會受到調節並失敗。