本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 针对 Amazon Chime SDK 使用呼叫分析从呼叫中生成见解
本节中的主题介绍如何使用 Amazon Chime SDK 呼叫分析从呼叫数据中生成见解数据。
Amazon Chime SDK 呼叫分析为开发者提供了低代码解决方案，用于从实时音频中生成具有成本效益的见解，包括音频摄取、分析、警报和数据湖集成。呼叫分析使您能够通过与 Amazon Transcribe 和 Transcribe 呼叫分析 (TCA) 集成以及在本地通过 Amazon Chime SDK 语音分析生成见解。呼叫分析还可以记录对您的 Amazon S3 存储桶的呼叫。
您可以使用以下方法配置和运行呼叫分析。
+ 使用 Amazon Chime SDK 控制台创建呼叫分析配置并将其与 Amazon Chime SDK Voice Connector 相关联。在此过程中，您可以启用通话录音和分析。您无需编写代码即可完成此过程。
+ 使用一组 Amazon Chime SDK A [mazon Ch APIs ime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/welcome.html) 软件 APIs 开发工具包以编程方式创建和运行配置。
有关更多信息，请参阅本节后文中的 [针对 Amazon Chime SDK 创建呼叫分析配置。](creating-ca-configuration.md) 和 [针对 Amazon Chime SDK 使用呼叫分析配置](using-call-analytics-configurations.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 Chime 软件开发工具包的呼叫分析渠道 CloudWatch](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 Connector 或 Amazon Kinesis Video Streams。呼叫分析通过与 Amazon Transcribe 和 Transcribe 呼叫分析 (TCA) 的集成以及在本地通过[ Amazon Chime SDK 语音分析](voice-analytics.md)（一项在呼叫分析下运行的服务）生成见解。
要使用呼叫分析，请按照以下步骤操作：
![\[该图显示了设置 Amazon Chime SDK 呼叫分析的过程。\]](http://docs.aws.amazon.com/zh_cn/chime-sdk/latest/dg/images/CallAnalyticsOverview.png)
在下图中：
1. 您首先要创建呼叫分析配置。
1. 您可以设置输出目的地和可选的数据湖。
1. 您可以创建将您的配置与 Voice Connector 和 Amazon Kinesis Video Streams 关联的工作流程。
1. 您可以分析并可视化您的见解。
您可以使用 Amazon Chime SDK 控制台创建呼叫分析配置，并启用自动启动呼叫分析。如果您需要控制适用于给定呼叫类型的配置，则可以使用 APIs 创建配置。无论哪种方式，配置都包含有关要调用的 AWS 机器学习服务以获取呼叫音频、启用呼叫录音以及见解、元数据和录音的目的地的详细信息。呼叫分析提供以下目的地：
+ Amazon Kinesis Data Stream (KDS)。您可以使用 KDS 接收实时通话见解，然后将其集成到您的应用程序中。例如，您可以整合实时见解以在客户电话中为销售或客户支持代理提供帮助，或者使用这些见解来增强生成式 AI 提示和摘要。
+ 配置作为数据仓库的 Amazon S3 存储桶。存储桶以 Parquet 格式存储数据。Parquet 是一种开源文件格式，旨在压缩和存储大量数据。然后，您可以使用 Amazon Athena 查询使用简单查询语言 (SQL) 的数据，或者将数据移至现有的数据仓库以与您的业务数据配对。例如，您可以进行通话后汇总分析，以了解客户来电的有效性、产品的问题领域或培训员工以实现更好客户成果的机会。
除了这些目的地，呼叫分析还支持实时警报，您可以根据见解预先配置这些警报。提醒将发送到亚马逊 EventBridge。
**注意**
创建呼叫分析配置时，无需选择特定的音频源。这使您可以跨多个音频源重复使用配置。例如，配置可以启用通话录音并提供呼叫转录。然后，您可以将该配置与 Chime SDK Voice Connector 一起使用，也可以通过 Kinesis 视频流使用音频流。您还可以在多个 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 数据目录**
用于存储各种数据来源的数据资产的集中式元数据存储库。该目录由数据库和表组成。对于呼叫分析，表中的元数据会将 Amazon S3 存储桶的位置告知 Athena。元数据还指定数据结构，例如列名、数据类型和表名。数据库仅保存数据集的元数据和架构信息。有关更多信息，请参阅本节后文中的 [了解 Amazon Chime 软件开发工具包 AWS Glue 的数据目录表结构](ca-data-model-diagram.md)。
**媒体见解管道**
由唯一 `MediaPipelineId` 标识的临时资源。通过使用呼叫分析管道配置和运行时系统参数创建。运行时系统参数指定管道的数据来源。
**媒体见解管道配置**
用于创建媒体见解管道的静态配置。您可以使用配置来实例化一个或多个管道。
**媒体见解管道配置元素**
媒体见解管道配置元素包括使用处理器元素处理媒体或使用接收器元素提供发送生成见解的指令。
**媒体见解管道任务**
媒体见解管道的临时子资源。任务包含有关特定流 ARN 和频道 ID 的进程状态的元数据。由唯一 ID 识别。通过在媒体见解管道上启动语音分析而创建。
**发言人搜索**
一种语音分析功能，可帮助您识别呼叫参与者。
**语音分析**
一项 Amazon Chime SDK 功能，包括发言人搜索和语音分析。
**语音嵌入**
呼叫者声音的矢量表示形式，外加一个唯一的 ID。
**语音增强**
一种可提高电话通话音频质量的系统。
**语音配置文件**
语音嵌入、其 ID 和到期日期的组合。
**语音配置文件域**
语音配置文件集合。
**语音音调分析**
一种语音分析功能，可让您分析呼叫者的声音，以了解 `positive`、`negative`、或 `neutral` 情绪。
有关 APIs 用于创建呼叫分析配置、启动管道和运行语音分析的更多信息，请参阅《[Amazon Chime SDK API 参考》中的 Amaz *on 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 存储桶，以便进一步分析。
但是，*配置不包括特定的音频源*。这允许您在多个呼叫分析工作流程中重复使用配置。例如，您可以对不同的 Voice Connector 使用相同的呼叫分析配置，也可以跨不同的 Amazon Kinesis Video Streams (KVS) 来源使用相同的呼叫分析配置。
当通过 Voice Connector 进行 SIP 呼叫时，或者当新媒体被发送到 Amazon Kinesis Video Streams (KVS) 时，您可以使用这些配置来创建管道。反过来，管道根据配置中的规格处理媒体。
您可以随时以编程方式停止管道。当 Voice Connector 呼叫结束时，管道也会停止处理媒体。此外，您还可以暂停管道。这样做会禁用对底层 Amazon 机器学习服务的调用，并在需要时恢复调用。但是，当您暂停管道时，会运行通话录音。
以下各节说明了创建呼叫分析配置的先决条件以及如何创建呼叫分析配置。
**Topics**
+ [了解 Amazon Chime SDK 的呼叫分析先决条件](ca-prerequisites.md)
+ [使用 Amazon Chime SDK 控制台创建呼叫分析配置](create-config-console.md)
+ [用于 APIs 为 Amazon Chime 软件开发工具包创建通话分析配置](create-config-apis.md)
+ [针对 Amazon Chime SDK 将配置与 Voice Connector 关联](ca-associate-vc-steps.md)
# 了解 Amazon Chime SDK 的呼叫分析先决条件
在创建呼叫分析配置之前，您必须具有以下项目。你可以使用 AWS 控制台来创建它们：
+ Amazon Chime SDK Voice Connector。如果不是，请参阅[创建 Amazon Chime SDK Voice Connector](https://docs.aws.amazon.com/chime-sdk/latest/ag/ca-prerequisites.html)。您还必须：
+ 为 Voice Connector 启用流媒体。有关更多信息，请参阅[《亚马逊 Chime 软件开发工具包管理员指南》中的 “ EventBridge使用自动化 Amazon *Chime* 软件开发工具包](https://docs.aws.amazon.com/chime-sdk/latest/ag/automating-chime-with-cloudwatch-events.html)”
+ 将 Voice Connector 配置为使用呼叫分析。有关更多信息，请参阅《Amazon Chime SDK 管理员指南》**中的[配置 Voice Connector 以使用呼叫分析](https://docs.aws.amazon.com/chime-sdk/latest/ag/configure-voicecon.html)。
+ 亚马逊的 EventBridge 目标。如果没有，请参阅[《Amazon Chime 软件开发工具包管理员指南》中的 “使用 EventBridge监控](https://docs.aws.amazon.com/chime-sdk/latest/ag/automating-chime-with-cloudwatch-events.html)*亚马逊 Chime* 软件开发工具包”。
+ 一种服务相关角色，允许语音连接器访问对 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 Data Streams。如果不是，请参阅《Amazon Kinesis Streams 开发者指南》**中的[创建和管理流](https://docs.aws.amazon.com/streams/latest/dev/working-with-streams.html)。语音分析和转录需要 Kinesis Data Streams。
+ 要离线分析通话，您必须创建 Amazon Chime SDK 数据湖。要执行此操作，请参阅本指南后面的 [创建 Amazon Chime SDK 数据湖](ca-data-lake.md)。
# 使用 Amazon Chime SDK 控制台创建呼叫分析配置
在创建了上一节中列出的先决条件后，您可以使用 Amazon Chime SDK 控制台创建一个或多个呼叫分析配置。您还可以使用该控制台将一个或多个 Voice Connector 与配置关联。完成该过程后，呼叫分析将使用您在创建配置时启用的功能开始运行。
您可以按照以下步骤创建呼叫分析配置：
1. 指定配置详细信息，包括名称和可选标签。
1. 配置您的录制设置。创建呼叫分析配置，包括录音和基于机器学习的见解。
1. 配置您的分析服务。
1. 选择用于获取实时见解的输出目的地。创建可选的数据湖以执行通话后分析。
1. 创建新的服务角色或使用现有角色。
1. 设置实时提醒，在满足特定条件 EventBridge 时通过 Amazon 发送通知。
1. 检查您的设置，然后创建配置。
创建配置后，您可以通过将 Voice Connector 与配置关联来启用呼叫分析。完成此操作后，当呼叫进入该 Voice Connector 时，呼叫分析会自动启动。有关更多信息，请参阅本节后文中的 [针对 Amazon Chime SDK 将配置与 Voice Connector 关联](ca-associate-vc-steps.md)。
以下章节介绍如何完成流程的每个步骤。按列出的顺序展开各章节。
## 指定配置详细信息
**若要指定配置详细信息**
1. [在家中打开 Amazon Chime 主机。https://console.aws.amazon.com/chime-sdk/](https://console.aws.amazon.com/chime-sdk/home)
1. 在导航窗格中的**呼叫分析**下，选择**配置**，然后选择**创建配置**。
1. 在**基本信息**中，执行以下操作：
1. 为配置输入名称。名称应反映您的用例和所有标签。
1. （可选）在**标签**下，选择**添加新标签**，然后输入标签键和可选值。您可以定义键和值。标签可帮助您查询配置。
1. 选择**下一步**。
## 配置录制
**若要配置录制**
+ 在**配置录制**页面上，执行以下操作：
1. 选中**激活通话录音**复选框。这样可以为 Voice Connector 呼叫或 KVS 流启用录制并将数据发送到您的 Amazon S3 存储桶。
1. 在**文件格式**下，选择**采用 PCM 编码的 WAV** 以获得最佳音频质量。
—或者—
选择**采用 OPUS 编码的 OGG** 来压缩音频并优化存储空间。
1. （可选）根据需要，选择 **Create an Amazon S3 bucket** 链接，然后按照以下步骤创建 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 发布到现有的 Glue 数据目录表 *call\$1anal* ytics\$1rec AWS ording\$1metadata 中。*为了识别语音增强型通话录音中的原始通话录音记录，在 KDS 通知和粘合表 call\$1analytics\$1recording\$1metadata 中添加了一个名为 deta *il-sub *VoiceEnhancement*type* 的新字段，该字段具有值。*有关数据仓库架构的更多信息，请参阅 [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 软件开发工具包控制台来配置目标。
+ 增强录音在基本文件名后面附加了 **\$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 软件开发工具包控制台来配置文件格式。
以下示例介绍了一个典型的文件名格式。
```
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 通话分析功能是一款基于机器学习的 API，可提供通话记录、情绪和实时对话见解。该服务无需记笔记，并且可以对检测到的问题立即采取行动。该服务还提供通话后分析，例如呼叫者情绪、呼叫驱动程序、非通话时间、中断、通话速度和对话特征。
**注意**
默认情况下，通话后分析会将通话录音流式传输到您的 Amazon S3 存储桶。为避免创建重复的录音，请勿同时启用通话录音和通话后分析。
最后，Transcribe 通话分析可以根据特定的短语自动标记对话，并帮助编辑音频和文本中的敏感信息。有关呼叫分析媒体处理器、其生成的见解以及输出目的地的更多信息，请参阅本节后文中的 [Amazon Chime SDK 的呼叫分析处理器和输出目的地](call-analytics-processor-and-output-destinations.md)。
**若要配置分析服务**
1. 在**配置分析服务**页面上，选中**语音分析**或**转录服务**旁边的复选框。您可以同时选择这两个项目。
选中**语音分析**复选框以启用**发言人搜索**和**语调分析**的任意组合。
选中**转录服务**复选框以启用 Amazon Transcribe 或 Transcribe 呼叫分析。
1. **若要启用发言人搜索**
+ 选中 **Yes, I agree to the Consent Acknowledgement for Amazon Chime SDK voice analytics** 复选框，然后选择**接受**。
1. 启用语调分析
+ 选中**语调分析**复选框。
1. 启用 Amazon Transcribe
1. 选择 **Amazon Transcribe** 按钮。
1. 在**语言设置**下，执行以下任一操作：
1. 如果您的呼叫者只讲一种语言，请选择**特定语言**，然后打开**语言**列表并选择语言。
1. 如果您的呼叫者讲多种语言，您可以自动识别这些语言。选择 **Automatic language detection**。
1. 打开 **Language options for automatic language identification** 列表并选择至少两种语言。
1. （可选）打开**首选语言**列表并指定首选语言。当您在上一步中选择的语言具有匹配的置信度分数时，该服务会转录首选语言。
1. （可选）展开**内容删除设置**，选择一个或多个选项，然后选择显示的一个或多个其他选项。帮助文本解释了每个选项。
1. （可选）展开**其他设置**，选择一个或多个选项，然后选择显示的一个或多个其他选项。帮助文本解释了每个选项。
1. 若要启用 Amazon Transcribe 通话分析功能
1. 选择 **Amazon Transcribe 通话分析功能**按钮。
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 简单队列服务或亚马逊简单通知服务。以下步骤说明了操作方法。
**若要配置输出详细信息**
1. 打开 **Kinesis Data Streams **列表并选择您的数据流。
**注意**
如果要对数据进行可视化，则必须选择 Amazon S3 存储桶和 Amazon Kinesis Data Firehose 使用的 Kinesis Data Streams。
1. （可选）展开**其他语音分析通知目的地**，然后选择 AWS Lambda、Amazon SNS 和亚马逊 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 分析。
您可以创建一组向 Amazon 发送实时提醒的规则 EventBridge。在分析会话期间，当 Amazon Transcribe 或 Amazon Transcribe 通话分析功能生成的见解与您的指定规则相匹配时，就会发送警报。警报具有详细类型`Media Insights Rules Matched`。 EventBridge 支持与 Amazon Lambda、Amazon SQS 和 Amazon SNS 等下游服务集成，以触发终端用户的通知或启动其他自定义业务逻辑。有关更多信息，请参阅本节后文中的 [为亚马逊 Chime 软件开发工具包使用亚马逊 EventBridge 通知](using-eventbridge-notifications.md)。
**若要配置警报**
1. 在**实时警报**下，选择 **Active real-time alerts**。
1. 在**规则**下，选择**创建规则**。
1. 在**规则名称**框中，输入规则的名称。
1. 打开**规则类型**列表并选择要使用的规则类型。
1. 使用显示的控件向规则添加关键字并应用逻辑，例如 **mentioned** 或 **not mentioned**。
1. 选择**下一步**。
## 审核并创建
**若要创建配置文件**
1. 查看每个章节的设置。根据需要选择**编辑**以更改设置。
1. 选择**创建配置**。
您的配置会显示在 Amazon Chime SDK 控制台的**配置**页面上。
# 用于 APIs 为 Amazon Chime 软件开发工具包创建通话分析配置
您可以通过编程方式创建 Voice Connector 和呼叫分析配置，然后将其关联以启动呼叫分析工作流程。本指南假设您知道如何编写代码。
根据工作流程 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 将配置与 Voice Connector 关联起来。
相反，要使用 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 关联
使用控制台创建呼叫分析配置后，您可以通过将 Voice Connector 与其关联来使用该配置。然后，Voice Connector 会自动调用您的配置中指定的分析服务。Voice Connector 会为每个呼叫调用呼叫分析。
**关联 Voice Connector**
1. [在家中打开 Amazon Chime 主机。https://console.aws.amazon.com/chime-sdk/](https://console.aws.amazon.com/chime-sdk/home)
1. 在导航窗格的 **SIP 中继**下，选择 **Voice Connector**。
1. 选择要与配置关联的 Voice Connector 的名称，然后选择**流式传输**选项卡。
1. 如果尚未选中，选择**开始**以便开始向 Kinesis 视频流进行流式传输。
1. 在**呼叫分析**下，选择**激活**，然后在出现的菜单上，选择您的呼叫分析配置 ARN。
1. 选择**保存**。
**注意**
启用、禁用或修改与 Voice Connector 关联的配置后，请等待 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 以及有关音频源的信息。呼叫分析配置包括有关音频处理器、见解目的地和警报事件配置的详细信息，*但不包括音频源*。这允许您在不同的呼叫分析工作流程中重复使用配置，例如使用不同的 Voice Connector 或 KVS 源。呼叫分析管道调用配置中指定的机器学习服务并录制音频。呼叫结束后，您可以手动或自动停止管道。
您可以在各种用例中使用呼叫分析管道。以下工作流程介绍了使用呼叫分析配置和管道的潜在方法。
**Topics**
+ [了解 Amazon Chime SDK 的通话录音工作流程](recording-workflows.md)
+ [了解 Amazon Chime SDK 基于机器学习的分析工作流程](ml-based-analytics.md)
# 了解 Amazon Chime SDK 的通话录音工作流程
本节中的主题列出并描述了录制通话和 Kinesis 视频流的工作流程。
# 录制 Voice Connector 通话
在以下情况下使用此工作流程：
+ 您已经使用或计划使用 Voice Connector 将 SIP 媒体引入呼叫分析。
**注意**
Voice Connector 支持 SIP 和 SIPREC。有关更多信息，请参阅《Amazon Chime SDK 管理员指南》**中的[管理 Amazon Chime SDK Voice Connector](https://docs.aws.amazon.com/chime-sdk/latest/ag/voice-connectors.html)。
+ 您想以低延迟自动录制到您选择的 Amazon Simple Storage Service 目的地的 SIP 或 SIPREC 呼叫。
+ 您想使用 Amazon Chime SDK 控制台来创建配置并将其与 Voice Connector 关联。
+ 您想对每个 Voice Connector 呼叫应用相同的录音配置。如果要对一个或多个 Voice Connector 应用多种配置，请参阅下一节。
要启用以编程方式调用，请使用以下 Amazon Ch APIs ime 软件开发工具包。
+ 使用 [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) 创建 Voice Connector。
+ 使用 [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 将配置与 Voice Connector 关联。
有关更多信息，请参阅《Amazon Chime SDK 管理员指南》**中的[配置 Voice Connector 以使用呼叫分析](https://docs.aws.amazon.com/chime-sdk/latest/ag/configure-voicecon.html)。
下图显示了 Voice Connector 启动呼叫录音会话时的数据流。图表中的数字对应于下面的带编号的文本。
![\[该图显示了 Voice Connector 开始录制呼叫时的数据流。\]](http://docs.aws.amazon.com/zh_cn/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 将配置与 Voice Connector 关联起来。要使用控制台，请参阅[配置 Voice Connector 以使用呼叫分析](https://docs.aws.amazon.com/chime-sdk/latest/ag/configure-voicecon.html)。
1. 在拨出呼叫期间，Voice Connector 会接收每个呼叫参与者的音频。
1. 如果将呼叫分析录音配置附加到 Voice Connector，则 Voice Connector 服务将使用媒体管道服务启动呼叫分析录音会话。
1. 媒体管道服务启动监视正在进行的呼叫的呼叫录音处理器。
1. 通话结束后，媒体管道服务会将通话录音文件传送到指定的 Amazon S3 存储桶，并通过 Amazon Kinesis Data Streams 提供录音元数据。如果启用了数据仓库，则呼叫元数据也会进入 Amazon Simple Storage Service 数据仓库。如果使用 SIPREC 将 SIP 音频整合到呼叫分析中，则呼叫元数据会纳入表格格式的 SIPREC 元数据。有关录音表的更多信息，请参阅本节后文中的 [了解 Amazon Chime 软件开发工具包 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 视频流。有关更多信息，请参阅《Amazon Chime SDK 管理员指南》**中的[将 Amazon Chime SDK Voice Connector 媒体流式传输到 Kinesis 视频流](https://docs.aws.amazon.com/chime-sdk/latest/ag/start-kinesis-vc.html)。
您还可以将 Voice Connector 创建的呼叫数据存储在 Kinesis 视频流中，持续时间各不相同，从几小时到几天甚至几年。选择不保留数据会限制呼叫数据的可用性，便于立即使用。Kinesis 视频流的成本是根据使用的带宽和总存储空间来确定的。您可以随时在 Voice Connector 流媒体配置中调整数据保留期。要启用呼叫分析录音，您必须确保 Kinesis 视频流将数据保留足够长的时间以进行呼叫分析。您可以通过指定合适的数据保留期来达到此目的。
您可以根据需要将呼叫见解管道配置与任意数量的 Voice Connector 相关联。您也可以为每个 Voice Connector 创建不同的配置。语音连接器使用代表您 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 Connector 使用 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 视频流制作人一起录制
在以下情况下，您可以录制 Amazon Kinesis 视频流：
+ 您需要对呼叫应用不同的配置，而不是为每个 Voice Connector 呼叫使用相同的配置。
+ 您想要录制未由 Voice Connector 处理的 SIP 或非 SIP 音频。
要使用此通话录音选项，您需要将音频发布到 Kinesis 视频流（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 流式传输，然后使用语音连接器 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，则呼叫分析将开始处理来自最新可用片段的流。
下图显示了 Voice Connector 启动呼叫录音会话时的数据流。图表中的数字对应于下面的带编号的文本。
![\[该图显示了 Voice Connector 开始录制呼叫时的数据流。\]](http://docs.aws.amazon.com/zh_cn/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 视频流](https://docs.aws.amazon.com/chime-sdk/latest/ag/start-kinesis-vc.html)。
1. 如果启用了语音连接器流式传输，则语音连接器服务会将通知发送到默认设置 EventBridge。
1. 如果是 Voice Connector 流式传输，您的应用程序可以使用来自的 Amazon Chime Voice Connector 流媒体`STARTED`事件 EventBridge 来收集有关通话时段的 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 Streams 提供录音元数据。如果启用了数据仓库，则呼叫元数据也将发送到 Amazon S3 数据仓库。如果使用 SIPREC 将 SIP 音频整合到呼叫分析中，则呼叫元数据会纳入采用方便表格格式的 SIPREC 元数据。有关录音表的更多信息，请参阅本节后文中的 [了解 Amazon Chime 软件开发工具包 AWS Glue 的数据目录表](glue-tables.md)。
1. 您的应用程序可以使用发布到 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 视频流上运行多个机器学习分析，则可能需要提高视频流 `GetMedia` 和 `GetMediaForFragmentList` 的连接级别限制。有关更多信息，请参阅《Kinesis 视频流开发者指南》**中的 [Kinesis 视频流限制](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/limits.html)。
# 使用 Voice Connector 自动启动呼叫分析
在以下情况下使用此工作流程：
+ 您需要控制台驱动的设置。
+ 您已经使用或计划使用 Voice Connector 将 SIP 媒体引入呼叫分析。Voice Connector 支持 SIP 和 SIPREC。有关配置 Voice Connector 的更多信息，请参阅[管理 Amazon Chime SDK Voice Connector](https://docs.aws.amazon.com/chime-sdk/latest/ag/voice-connectors.html)。
+ 您希望将相同的媒体见解配置应用于每个 Voice Connector 呼叫。
+ 您需要使用 Amazon Chime SDK 语音分析，这需要 Voice Connector 或媒体见解管道。
要在 Amazon Chime SDK 控制台中启用此工作流程，请按照[配置 Voice Connector 以使用呼叫分析](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 管理员指南》**中的[配置 Voice Connector 以使用语音分析](https://docs.aws.amazon.com/chime-sdk/latest/ag/configure-voicecon.html)。
下图显示了 Voice Connector 启动呼叫分析会话时的数据流。图表中的数字对应于下面的带编号的文本。
![\[Image showing the flow of data when a Voice Connector initiates a call.\]](http://docs.aws.amazon.com/zh_cn/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 将配置与 Voice Connector 关联起来。要将现有配置与 Voice Connector 相关联，请参阅《Amazon Chime SDK 管理员指南》**中的[配置 Voice Connector 以使用呼叫分析](https://docs.aws.amazon.com/chime-sdk/latest/ag/configure-voicecon.html)。
1. 在拨出呼叫期间，Voice Connector 会接收每个呼叫参与者的音频。
1. 由于与呼叫分析的内置集成，如果将呼叫分析配置附加到 Voice Connector，则 Voice Connector 服务将使用媒体管道服务启动呼叫分析会话。
1. 媒体管道服务调用配置中指定的一个或多个媒体处理器。
1. 媒体管道服务根据配置将输出数据发送到一个或多个目的地。例如，您可以通过 Amazon Kinesis Data Streams 发送实时分析，如果已配置，则可以将呼叫元数据和分析数据发送到 Amazon S3 数据仓库。
1. 媒体管道服务将管道状态事件发送到默认的 Amazon EventBridge。如果您已配置规则，则这些规则的通知也将发送到 EventBridge Amazon。有关更多信息，请参阅[使用 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 视频流。有关更多信息，请参阅《Amazon Chime SDK 管理员指南》**中的[将 Amazon Chime SDK Voice Connector 媒体流式传输到 Kinesis 视频流](https://docs.aws.amazon.com/chime-sdk/latest/ag/start-kinesis-vc.html)。
您可以将 Voice Connector 通话数据存储在 Kinesis 视频流中，存储时间各不相同，从数小时到数年不等。选择不保留数据会限制呼叫数据的可用性，便于立即使用。Kinesis 视频流的成本是根据使用的带宽和总存储空间来确定的。通过编辑 Voice Connector 的流媒体配置，可以随时调整数据保留期。要启用呼叫分析录音，您必须确保 Kinesis 视频流在呼叫分析完成之前保留数据。您可以通过指定合适的数据保留期来达到此目的。
您可以根据需要将媒体见解管道配置与任意数量的 Voice Connector 相关联。您也可以为每个 Voice Connector 创建不同的配置。语音连接器使用代表您 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 Connector 使用 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，但需要控制何时应用呼叫分析配置以及将配置应用于哪个呼叫，请使用此工作流程。
要使用此方法，您需要为 Voice Connector 发布的事件创建 EventBridge 目标，然后使用这些事件触发呼叫分析管道 APIs。有关更多信息，请参阅[《亚马逊 Chime 软件开发工具包管理员指南》中的 “ EventBridge使用自动化 Amaz *on Chime* 软件开发工具包](https://docs.aws.amazon.com/chime-sdk/latest/ag/automating-chime-with-cloudwatch-events.html)”。
下图显示了在 Voice Connector 中使用呼叫分析时如何实现更精细的控制。图表中的数字对应于下方文本中的数字。
![\[该图显示了通过 Voice Connector 使用 API 调用时的数据流。\]](http://docs.aws.amazon.com/zh_cn/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. 在拨出呼叫期间，Voice Connector 将接收参与者的音频。
1. 语音连接器将通话音频发送到 Kinesis 视频流，并将相应的事件发送到。 EventBridge这些事件具有流和通话元数据。
1. 您的应用程序是 EventBridge 通过 Targe EventBridge t 订阅的。
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 Streams 提供实时分析，如果已配置，则可对 Amazon S3 数据仓库进行调用元数据分析。
1. 媒体管道服务将事件发送到 Amazon EventBridge。如果您已配置规则，则这些规则的通知也将发送到 EventBridge Amazon。
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 视频流制作人一起使用呼叫分析
要使用此选项，您需要将音频数据发布到 Kinesis 视频流（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,000Hz 左右。高质量音频的范围通常在 16,000Hz 到 48,000Hz 之间。您指定的采样率必须与音频的采样率相匹配。如需了解更多信息，请参阅《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 创建者开发工具包提供了一组库，您可以用这些库将音频数据流式传输到 Kinesis 视频流。有关更多信息，请参阅《Amazon Kinesis Video Streams 开发者指南》**中的 [Kinesis 视频流创建者库](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/producer-sdk.html)。
下图显示了与自定义 Kinesis Video Streams 创建者一起使用呼叫分析时的数据流。图表中的数字对应于下面的带编号的文本。
![\[该图显示了与 Kinesis Video Streams 创建者一起使用呼叫分析时的数据流。\]](http://docs.aws.amazon.com/zh_cn/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 Streams 创建者向 Kinesis 视频流写入音频。
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 视频流读取音频。
1. 媒体管道服务将事件发送到 Amazon EventBridge。如果您已配置规则，则这些规则的通知也将发送到 EventBridge Amazon。
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)
在满足以下任意条件时，媒体见解管道停止：
+ 任何 Kinesis 视频流在 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_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)。
暂停后，管道停止向处理器发送媒体以及向 Kinesis Data Streams 和数据仓库写入数据。当您 `Resume` 管道时，服务会发送流上最新的可用数据块。暂停超过 2 小时后，媒体见解管道会自动停止。**请注意**，通话录音不支持暂停和恢复。
有关更多信息，请参阅以下主题：
+ [使用 EventBridge 通知](https://docs.aws.amazon.com/chime-sdk/latest/dg/ca-eventbridge-notifications.html)。
+ *《Amazon Kinesis Video Streams 开发者指南》*中的 [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 Transcribe 通话分析功能处理器](https://docs.aws.amazon.com/chime-sdk/latest/dg/ca-processors-sinks.html#ca-transcribe-analytics-processor)。
**注意**
在管道暂停期间，您需要为通话分析的使用量付费。但是，您无需为通过资源访问角色访问的 AWS 服务（例如 Amazon Transcribe 和 Amazon Kinesis）付费。
您可以使用、以及在 Identifier 字段中传递配置名称或 ARN [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_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_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`，则根据您定义的接收器添加 `LambdaFunctionSink`、`SqsQueueSink` 和 `SnsTopicSink` 的策略。
`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)和和[GetVoiceToneAnalysisTask APIs](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetVoiceToneAnalysisTask.html)[语音分析通知目标](va-notification-targets.md)。
媒体见解管道跟踪以下状态。
+ **管道状态**：呼叫分析管道（也称为媒体见解管道）的总体状态。这由元素状态决定。
+ **元素状态**：各个媒体见解管道配置元素的处理状态。
+ **任务状态**：为语音分析而启动的媒体见解管道任务的处理状态。`VoiceAnalyticsProcessor` 元素状态由任务状态决定。呼叫分析管道中没有其他元素具有任务状态。
有关媒体见解管道任务的更多信息，请参阅本指南前文中的 [了解 Amazon Chime SDK 的呼叫分析术语](ca-terms-concepts.md)。
并非所有媒体见解配置元素类型都有元素状态。通常，只有“处理器”类型的媒体见解配置元素才具有元素状态。此外，Amazon S3 录音和语音增强接收器具有处理器状态。具体而言，以下媒体见解配置元素类型存在元素状态：
+ `AmazonTranscribeProcessor`
+ `AmazonTranscribeCallAnalyticsProcessor`
+ `S3RecordingSink`
+ `VoiceAnalyticsProcessor`
+ `VoiceEnhancementSink`
管道状态由元素状态决定，如下所示：
| 管道状态 | 条件 |
| --- | --- |
| NotStarted | 所有元素状态均未启动。 |
| Initializing | 至少有一个元素正在初始化，其余元素尚未启动。 |
| InProgress | 至少有一个元素正在进行中。 |
| 失败 | 至少有一个元素失败，其余元素已停止。 |
| 停止 | 有关停止条件的完整列表，请参阅 [管理 Amazon Chime SDK 的呼叫分析管道](managing-call-analytics-pipelines.md)。 |
| Stopped（已停止） | 所有元素都已停止。 |
| 已暂停 | 所有元素都已暂停。 |
与其他元素状态不同，该 `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` 状态开始，因为 `StartSpeakerSearchTask` 和 `StartVoiceToneAnalysisTask` 必须先调用，然后元素才能将状态更改为 `Initializing`，之后改为 `InProgress`。
+ 只要一个任务已启动，并且在任务运行时不满足[停止条件](managing-call-analytics-pipelines.md)，`VoiceAnalyticsProcessor` 就会一直处于 `InProgress` 状态。
+ 尽管 `VoiceAnalyticsProcessor` 可能是 `InProgress`，但您只需要为任务处理的持续时间付费。
+ 若要清理已启动至少一项语音分析任务且不再运行任务的媒体见解管道，您必须调用 `DeleteMediaPipeline`。
+ 只要任务成功运行或完成，`VoiceAnalyticsProcessor` 元素的状态就会保持在 `InProgress`。
# 使用亚马逊监控 Amazon Chime 软件开发工具包的呼叫分析渠道 CloudWatch
您可以使用亚马逊 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` 命名空间。
| 指标 | 说明 |
| --- | --- |
| `MediaInsightsPipelineCreated` | 已成功创建媒体见解管道。 单位：个 |
| `MediaInsightsPipelineStopped` | 已成功停止媒体见解管道。 单位：个 |
| `MediaInsightsPipelineFailed` | 媒体见解管道失败。 单位：个 |
| `MediaInsightsPipelineDuration` | 从管道创建到停止/失败之间的时间。 单位：秒 |
| `MediaInsightsPipelineBillingDuration` | 媒体见解管道计费持续时间。 单位：个 |
| `RecordingFileSize` | 录音文件大小。 单位：字节 |
| `RecordingDuration ` | 录音持续时间。 单位：秒 |
## CloudWatch 管道指标的维度
下表列出了可用于监控呼叫分析管道的 CloudWatch 维度。
| 维度 | 说明 |
| --- | --- |
| `MediaInsightsPipelineConfigurationId` | 媒体见解管道配置 ID。 |
| `MediaInsightsPipelineConfigurationName` | 媒体见解管道配置名称。 |
# Amazon Chime SDK 的呼叫分析处理器和输出目的地
对于每个媒体见解管道配置，您只能指定一次唯一元素。所有处理器和接收器必须位于同一个 AWS 账户中，并且您必须在与您调用的终端节点相同的 AWS 区域中创建它们。例如，如果您使用 Amazon Chime SDK 媒体管道的 `us-east-1` 终端节点，则无法传递来自 `us-west-2` 区域的 Kinesis Data Stream。
展开每个部分，了解有关每个目的地的信息。
## Amazon Transcribe 通话分析功能处理器目的地
支持的接收器：`KinesisDataStreamSink`。
您不能将此处理器与 Amazon Transcribe 处理器结合使用。有关 Amazon Transcribe 呼叫分析的更多信息，请参阅《Amazon Transcribe 开发者指南》**中的[实时通话分析](https://docs.aws.amazon.com/transcribe/latest/dg/call-analytics-streaming.html)。如果您通过在 `AmazonTranscribeCallAnalyticsProcessorConfiguration` API 调用中添加 `PostCallAnalyticsSettings` 来启用[通话后分析](https://docs.aws.amazon.com/transcribe/latest/dg/tca-post-call.html)，则当媒体见解管道停止并处理完成时，您将在指定的 Amazon S3 位置收到构件。
**注意**
如果您暂停管道超过 35 秒然后恢复管道，则会在 Amazon S3 存储桶中使用不同的会话在单独的文件 IDs 中生成调用后工件。
通话后构件包括分析 JSON 文件和录音 WAV 或 Opus 文件。作为元数据章节中 `onetimeMetadata` 的一部分，对于每个 Amazon Transcribe 通话分析功能通话后会话，已编辑（如果您启用内容编辑）和未编辑录音文件的 Amazon S3 存储桶 URL 都会发送到 Kinesis Data Streams 一次。
使用 Amazon Transcribe 通话分析功能进行呼叫分析采用 Kinesis 视频流中的音频数据输入。
+ 支持的媒体编码：PCM 签名的 16 位小端序音频。
+ 支持的媒体采样率：介于 8,000Hz 和 48,000Hz 之间。
Amazon Transcribe 分析流程的 `StreamConfiguration` 输入：
+ 必须为每个流指定 `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 创建带有 Amazon Transcribe 通话分析功能处理器的 `MediaInsightsPipeline` 时，Voice Connector 账户分支音频是 `AGENT`，PSTN 分支音频是用于 `ParticipantRole` 的 `CUSTOMER`。
对于 Voice Connector SIPREC，我们依赖于 SIPREC 元数据。在大多数情况下，认为 `AGENT` 是词典值最低的流标签。
以下示例介绍了一个双声道音频流的 Kinesis 视频流输入。
```
"StreamChannelDefinition" : {
"NumberOfChannels" : 2
"ChannelDefinitions": [
{
"ChannelId": 0,
"ParticipantRole": "AGENT"
},
{
"ChannelId": 1,
"ParticipantRole": "CUSTOMER"
}
]
}
```
相比之下，以下示例介绍了来自两个不同的 Kinesis 视频流的两个单声道输入。
```
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` 具有 `TranscribeCallAnalyticsCategoryEvent` 的 `detail-type`。
以下示例介绍了 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 通话分析功能输出格式。
```
{
"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 流式处理更新](https://docs.aws.amazon.com/chime-sdk/latest/ag/automating-chime-with-cloudwatch-events.html)时，将发送以下 Voice Connector 更新有效负载。
以下示例显示了 Amazon Transcribe 处理器和 Transcribe 通话分析处理器的更新元数据格式。
```
{
"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"
}
```
以下示例显示了通话分析 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 开发者指南》**中的[转录流式传输音频](https://docs.aws.amazon.com/transcribe/latest/dg/streaming.html)。
Amazon Transcribe 的呼叫分析会话采用 Kinesis 视频流中的音频数据输入。
+ 支持 MediaEncoding：PCM 签名的 16 位小端音频。
+ 支持的 MediaSampleRate 采样率：介于 8,000 Hz 和 48,000 Hz 之间。
Amazon Transcribe 处理器的 `StreamConfiguration` 输入：
+ 必须为每个流指定 `KinesisVideoStreamArn`。
+ （可选）KVS `FragmentNumber`：使用特定片段之后的数据块启动呼叫分析作业。如果未提供，它将使用 Kinesis 视频流中最新的可用区块。
+ `StreamChannelDefinition` Amazon Transcribe 目前支持两个频道的音频。您必须在运行时系统 `StreamChannelDefinition` 中指定 `NumberOfChannels`。此外，如果您在两个不同的频道中发送单声道音频，则必须通过 `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
}
]
}
```
**注意**
对于 Voice Connector 使用 Amazon Transcribe 处理器创建的 `MediaInsightsPipeline`，Voice Connector 账户分支音频分配给 `channel-0`，PSTN 分支音频分配给 `channel-1`。
对于 Voice Connector SIPREC，我们依赖于 SIPREC 元数据。在大多数情况下，会将词典值最低的流标签分配给 `channel-0`。
对于 Amazon Transcribe 和 Amazon Transcribe 通话分析功能处理器，如果您传递两个 Kinesis 视频流，并且每个流都包含一个单声道音频频道，则在处理 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`、`SqsQueueSink`、`SnsTopicSink` 和 `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 Streams 用作接收器
呼叫分析生成的 Kinesis Data Streams (KDS) 记录包括媒体管道 ID、详细信息类型、元数据和处理器特定部分。有关使用来自 Kinesis Data Streams 的数据的更多信息，请参阅《Amazon Kinesis Streams 开发者指南》**中的[从 Amazon Kinesis Data Streams 读取数据](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html)。要使用此接收器创建配置，您必须拥有对指定流的 `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` 中指定的任何键值对。如果呼叫分析会话是由 Voice Connector 发起的，则元数据部分将自动填充以下参数：
+ `transactionId`
+ `fromNumber`
+ `toNumber`
+ `callId`
+ `voiceConnectorId`
+ `direction`
除上述参数外，Voice Connector 启动的呼叫分析会话的元数据部分还将填入一个包含以下内容的 `oneTimeMetadata` 字段：
+ `inviteHeaders`
+ `siprecMetadata`
这仅在会话开始时一次性发布到 Kinesis Data Streams，并且具有 `CallAnalyticsMetadata` 的 `detail-type`。
您可以在 `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 Streams 的每条记录来源进行唯一性标识。
## 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 位小端序字节序。采样率必须为 8 KHz。
+ 构建者必须为 Kinesis Video Streams 设置足够长的数据保留期，以确保呼叫分析保留和使用这些片段。
+ 如果您单独或与其他处理器组合启用通话录音，则必须提供两个 Kinesis 视频流 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 通话分析功能处理器与 Amazon S3 录音接收器结合使用。除了 Amazon RecordingSinkConfiguration Transcribe 处理器之外，生成器还可以通过 [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 调用或使用控制台传递 S3。
与 Amazon S3 录音接收器配合使用，您可以使用 Amazon Transcribe 或 Amazon Transcribe 通话分析功能处理器，但不能两者兼而有之。除了带或不带转录处理器的录音接收器外，您还可以在相同的配置中添加语音分析。
**注意**
您可以使用上面列出的任何处理器启用录制。但是，如果您同时启用 Amazon Transcribe 通话分析功能和 Amazon S3 通话录音，您必须提供两个 Kinesis 视频流，并且您将收到重复的录音文件，一个来自 Amazon Transcribe 通话分析功能，另一个来自 Amazon S3 通话录音。
请记住以下事项：
+ 您必须使用唯一的 `MediaInsightsPipelineConfigurationName`。
+ 有关 `ResourceAccessRoleArn` 的更多信息，请参阅本指南中的 [针对 Amazon Chime SDK 使用通话分析资源访问角色](call-analytics-resource-access-role.md)。
+ `Destination` 值必须是 S3 路径 ARN。Amazon S3 存储桶必须由同一账户拥有。
+ 如果您使用带有 Transcribe 和录制功能的配置来创建管道，则暂停和恢复仅显示在 Kinesis Data Streams 生成的见解中。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"
}
]
}
```
# 为亚马逊 Chime 软件开发工具包使用亚马逊 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 通知：
+ 媒体见解管道的状态发生了变化。
+ 媒体见解管道元素的状态发生了变化。
+ 所有管道元素都已停止。
+ 任何管道元素都出现故障。
详细信息部分始终包含以下字段：
+ `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` 中指定的任何键值对。如果呼叫分析会话是由 Voice Connector 发起的，则元数据部分将自动填充以下参数：
+ `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"
}
}
```
当媒体见解管道包含多个元素时，可能会出现以下事件类型。示例通知针对与 `S3RecordingSink` 组合使用的 `AmazonTranscribeProcessor`。展开每个部分以了解更多信息。
### AmazonTranscribeProcessor 正在进行且 S3 RecordingSink 尚未启动
此示例介绍了典型的事件结构。
```
{
"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 已成功且 S3 RecordingSink 正在进行中
此示例介绍了典型的事件结构。
```
{
"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 已失败且 S3 RecordingSink 正在进行中
此示例介绍了典型的事件结构。
```
{
"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 已失败且 S3 RecordingSink 已成功
此示例介绍了典型的事件结构。
```
{
"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 已成功且 S3 RecordingSink 失败
此示例介绍了典型的事件结构。
```
{
"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 已暂停且 S3 RecordingSink 尚未启动
此示例介绍了典型的事件结构。
```
{
"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 已暂时失败且 S3 RecordingSink 尚未启动
此示例介绍了典型的事件结构。
```
{
"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 然后 S3 RecordingSink 成功了
此示例介绍了典型的事件结构。
```
{
"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"
}
}
```
### S3 RecordingSink 成功且正在 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
}
]
}
}
```
### 由于呼叫时间超过 30 分钟，S3 RecordingSink 成功 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:MediaInsightsStopped",
"version": "0",
"mediaInsightsPipelineElementStatuses": [
{
"type": "VoiceEnhancement",
"status": "NotSupported",
"updatedOn": 1686184070655,
"statusDetail": "Unsupported recording length"
},
{
"type": "S3RecordingSink",
"status": "Stopped",
"updatedOn": 1686184070655
}
]
}
}
```
### 由于呼叫时间少于 30 分钟，S3 RecordingSink 成功 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:MediaInsightsPermanentFailure",
"version": "0",
"mediaInsightsPipelineElementStatuses": [
{
"type": "VoiceEnhancement",
"status": "Failed",
"updatedOn": 1686184070655
},
{
"type": "S3RecordingSink",
"status": "Stopped",
"updatedOn": 1686184070655
}
]
}
}
```
## 实时提醒
**注意**
只有 Amazon Transcribe 和 Amazon Transcribe 通话分析功能处理器支持实时提醒。
Amazon Chime SDK 呼叫分析允许开发者设置规则，以便在分析会话期间通过处理器发送实时警报。提醒将以详细类型发送到亚马逊 EventBridge `Media Insights Rules Matched`。 EventBridge 支持与 Lambda、Amazon SQS 和 Amazon SNS 等下游服务集成，以触发终端用户的通知或启动其他自定义业务逻辑。
针对 `MediaInsightsPipelineConfiguration` 将实时警报设置为 `RealTimeAlertConfiguration` 字段的一部分。您可以使用 Amazon Chime 软件开发工具包控制台来配置该字段，也可以调用或。[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) 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 分析支持这种规则类型。
情绪分析
当特定情绪类型持续一段滚动窗口期时发出警报。只有 Transcribe 呼叫分析支持此规则。
问题检测
在语音事件中检测到问题时发出警报。只有 Transcribe 呼叫分析支持此规则类型。
以下示例介绍了一个 `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 通话分析功能，则为包含匹配关键字的转录 ID。仅适用于口语关键词匹配。
`resultId`：如果您使用 Amazon Transcribe，则为包含匹配关键字的转录 ID。仅适用于口语关键词匹配。
`beginTimestamp`：包含匹配关键字的转录开始时间。仅适用于口语关键词匹配。
**情感分析字段**
`beginTimestamp`：匹配情绪的滚动窗口的开始时间。
`endTimestamp`：匹配情绪的滚动窗口的结束时间。
# 创建 Amazon Chime SDK 数据湖
Amazon Chime SDK 呼叫分析数据湖允许您将基于机器学习的见解和来自 Amazon Kinesis Data Streams 的任何元数据流传输到您的 Amazon S3 存储桶。例如，使用数据湖 URLs 访问录音。要创建数据湖，您可以从 Amazon Chime 软件开发工具包控制台部署一组 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 Data Streams。有关更多信息，请参阅《Amazon Kinesis 流开发者指南》**中的[通过 AWS 管理控制台创建流](https://docs.aws.amazon.com/streams/latest/dev/how-do-i-create-a-stream.html)。
+ 一个 S3 存储桶。有关更多信息，请参阅《Amazon S3 用户指南》**中的[创建第一个 Amazon S3 存储桶](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html)。
## 数据湖术语和概念
使用以下术语和概念来理解数据湖的工作原理。
**Amazon Kinesis Data Firehose**
提取、转换、加载 (ETL) 服务，可靠地捕获、转换、传送流数据到数据湖、数据存储和分析服务。有关更多信息，请参阅什么是 Amazon Kinesis Data Firehose？
**Amazon Athena**
Amazon Athena 是一种交互式查询服务，让您能够使用标准 SQL 分析 Amazon S3 中的数据。Athena 无服务器，因此您无需管理基础设施，只需为运行的查询付费。要使用 Athena，请指向 Amazon S3 中的数据，定义架构，然后使用标准 SQL 查询。您还可以使用工作组对用户进行分组，并控制他们在运行查询时可以访问的资源。工作组使您能够管理查询并发性，并在不同的用户组和工作负载之间确定查询执行的优先级。
**Glue 数据目录**
在 Amazon Athena 中，表和数据库包含详细说明底层源数据架构的元数据。每个数据集都必须在 Athena 中有一个对应的表。表中的元数据将 Amazon S3 存储桶的位置告知 Athena。元数据还指定数据结构，例如列名、数据类型和表名。数据库仅保存数据集的元数据和架构信息。
## 创建多个数据湖
通过提供唯一的 Glue 数据库名称来指定呼叫见解的存储位置，可以创建多个数据湖。对于给定 AWS 账户，可以有多种呼叫分析配置，每种配置都有相应的数据湖。这意味着可以将数据分离应用于某些用例，例如自定义保留策略和数据存储方式的访问策略。可以采用不同的安全策略来访问见解、记录和元数据。
## 数据湖区域可用性
Amazon Chime SDK 数据湖在以下区域中推出。
| Region | Glue 表 | Quick |
| --- | --- | --- |
| us-east-1 | 可用 | 可用 |
| us-west-2 | 可用 | 可用 |
| eu-central-1 | 可用 | 可用 |
## 数据湖架构
下图显示的是数据湖的架构。绘图中的数字对应于下面的编号文本。
![\[该程序流经数据湖。\]](http://docs.aws.amazon.com/zh_cn/chime-sdk/latest/dg/images/call-analytics-data-lake-architecture.png)
在图中，使用 AWS 控制台从媒体见解管道配置设置工作流程部署 CloudFormation模板后，以下数据将流向 Amazon S3 存储桶：
1. Amazon Chime SDK 呼叫分析将开始将实时数据流式传输到客户的 Kinesis Data Streams。
1. Amazon Kinesis Firehose 会缓冲这些实时数据，直到其累积 128MB，或时间达到 60 秒，以先到者为准。然后，Firehose 使用 Glue 数据目录中的 `amazon_chime_sdk_call_analytics_firehose_schema` 来压缩数据，并将 JSON 记录转换为 Parquet 文件。
1. Parquet 文件以分区格式存放在您的 Amazon S3 存储桶中。
1. 除了实时数据外，通话后的 Amazon Transcribe 通话分析功能摘要 .wav 文件（如果在配置中指定，则经过编辑和未编辑）和通话录音 .wav 文件也将发送到您的 Amazon S3 存储桶。
1. 您可以使用 Amazon Athena 和标准 SQL 来查询 Amazon S3 存储桶中的数据。
1. 该 CloudFormation 模板还创建了一个 Glue 数据目录，用于通过 Athena 查询此通话后摘要数据。
1. Amazon S3 存储桶上的所有数据也可以使用 Quick 进行可视化。 QuickSight 使用亚马逊 Athena 与亚马逊 S3 存储桶建立连接。
Amazon Athena 表使用以下功能来优化查询性能：
**数据分区**
分区可将您的表格分成多个部分，并根据日期、国家和地区等列值将相关数据保存在一起。分区充当虚拟列。在这种情况下， CloudFormation 模板在创建表时定义分区，这有助于减少每次查询扫描的数据量并提高性能。您还可以按分区筛选，以限制查询所扫描的数据量。有关更多信息，请参阅《Amazon 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/主页](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. 选中确认复选框，然后选择 **Create data lake**。等待 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**。
为每种 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_cn/chime-sdk/latest/dg/ca-data-lake.html)
# 为 Amazon Chime 软件开发工具包配置快速控制面板
设置数据湖后，您可以配置带有预定义指标的 Quick 仪表板，以实现数据的可视化。您可以使用以下控制面板：
+ **Transcribe 呼叫分析 \$1 语音分析**。指标包括 turn-by-turn笔录、检测到的问题、结果、实体检测和语音配置文件 ID 匹配的摘要和详细视觉效果。
+ **Transcribe \$1 语音分析**。指标包括 turn-by-turn笔录、词汇匹配、语音和语音配置文件 ID 匹配的摘要和详细视觉效果。
以下主题说明了如何设置 Quick 帐户（如果您还没有），以及如何配置控制面板。
**Topics**
+ [创建 QuickSight 账户](#create-quicksight-account)
+ [配置您的 QuickSight 账户](#configure-qs-acct)
+ [创建 QuickSight 仪表板](#create-qs-dashboard)
## 创建 QuickSight 账户
本节中的步骤说明了如何创建 Quick 帐户。如果您已有账户，请跳到 [创建 QuickSight 仪表板](#create-qs-dashboard)。
您可以通过以下方式创建 QuickSight 账户：
+ 使用亚马逊 CloudFormation 模板。
+ 使用 Amazon Chime SDK 控制台。
### 先决条件
开始之前，请收集以下信息：
+ Amazon S3 存储桶的呼叫分析的名称。
+ 通知电子邮件地址。系统将 QuickSight通知发送到该地址。
### 使用 CloudFormation 模板创建账户
以下步骤说明了如何通过部署 Amazon CloudFormation 模板来创建快速账户。该流程仅向您订阅企业版账户。有关定价的信息，请参阅[快速定价](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. 在 **S3** 下BucketName，输入您的亚马逊 S3 存储桶的名称。
1. 选择 “**我确认 AWS CloudFormation 可能会创建 IAM 资源”。** 复选框。
1. 选择**创建堆栈**。
系统创建堆栈需要约 10 分钟的时间。
1. 构建完成后，选择 **Go to Quick** 并输入您的电子邮件地址以登录您的帐户。
### 使用控制台创建账户
以下步骤说明了如何使用 Amazon Chime 软件开发工具包控制台创建 Quick 账户。您必须使用企业版或企业版 \$1 Q 账户。
**要使用 控制台**
1. 在[ https://console.aws.amazon.com/chime-sdk/家](https://console.aws.amazon.com/chime-sdk/home)中启动 Amazon Chime SDK 控制台，进行搜索**QuickSight**，然后在搜索结果中选择。**QuickSight**
![\[链接到 Quick 的搜索结果。\]](http://docs.aws.amazon.com/zh_cn/chime-sdk/latest/dg/images/quicksightsetup-1.png)
1. 选择**注册 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 服务**” 下，使用默认角色，或者选择**使用现有角色**并从列表中选择一个角色。
1. （可选）根据需要，在 **Allow access and autodiscovery for these resources** 下，选择其他资源。
1. 完成后选择**完成**。
1. 构建完成后，选择 **Go to Quick** 并输入您的电子邮件地址以登录您的帐户。
## 配置您的 QuickSight 账户
登录 QuickSight 账户后，您需要配置安全性并将自己添加到设置过程中创建的群组中。
**若要配置安全性**
1. 选择右上角的个人资料图标，然后 QuickSight从出现的菜单中选择 “**管理**”。
![\[带有 “管理” QuickSight 命令的菜单。\]](http://docs.aws.amazon.com/zh_cn/chime-sdk/latest/dg/images/quicksightsetup-1-a.png)
1. 在导航窗格中，选择**安全性和权限**。
1. 在 “**QuickSight 访问 AWS 服务**” 下，选择 “**管理**”，并确保选择了以下服务。
+ Amazon Redshift
+ Amazon RDS
+ Amazon S3
+ Amazon Athena
+ IAM
1. 选择 **Select Amazon S3 buckets** 链接。
1. 选中您的 Amazon S3 存储桶旁边的复选框，然后在 **Athena 工作组的写入权限**列中选中右边的复选框。
1. 选择**结束**。
1. 选择**保存**。
**将自己加入群组**
1. 在导航窗格中，选择**管理组**，然后选择名称中包含**管理员**的组。例如，*S3 BucketName* — **管理员。**
1. 选择**添加用户**，然后在出现的框中输入您的电子邮件别名。
您的姓名显示为**Admin – ***您的别名*。
1. 选择**添加**。
## 创建 QuickSight 仪表板
创建数据湖后，您可以创建一个可视化数据的 QuickSight 仪表板。您可以使用亚马逊 CloudFormation 模板或 Amazon Chime 软件开发工具包控制台来创建控制面板。以下步骤解释了这两种方法。
**若要使用模板**
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**，选择**真**。
1. 在 **QuicksightDashboardSelection**“**呼叫分析”-“转录呼叫分析和语音分析” 控制面板或 “呼叫分析”** **-“转录和语音分析**” 控制面板。
1. 在 **Amazon S3** 下BucketName，输入您的亚马逊 S3 存储桶的 URI。
1. 在下方 **GlueDatabaseName**，输入要在其上部署 QuickSight 仪表板的 Glue 数据库。
1. 选中**我确认 AWS CloudFormation 可能会创建 IAM 资源**复选框，然后选择**创建堆栈**。
**手动配置 QuickSight 仪表板**
1. 导航到您的 QuickSight 账户。
1. 在右上角选择个人资料图标，然后选择**管理 QuickSight**。
![\[“ QuickSight 帐户” 对话框和 “管理” QuickSight 命令。\]](http://docs.aws.amazon.com/zh_cn/chime-sdk/latest/dg/images/quicksightsetup-1-a.png)
1. 在导航窗格中，请选择**管理组**，然后选择设置过程创建的组。
1. 选择**添加用户**，输入您的电子邮件地址，然后选择**添加**。
系统需要 10 分钟来部署该页面。
1. 使用 Amazon Chime 软件开发工具包控制台登录您的 QuickSight 账户并使用控制面板。
# Amazon Chime SDK 的呼叫分析数据模型。
本节中的信息列出并描述了 Amazon Chime SDK 调用分析数据模型，即 Glue 数据目录中的一 AWS 组表。
**Topics**
+ [了解 Amazon Chime 软件开发工具包 AWS Glue 的数据目录表结构](ca-data-model-diagram.md)
+ [了解 Amazon Chime 软件开发工具包 AWS Glue 的数据目录表](glue-tables.md)
+ [提取数据目录中的数据以用于 Amazon Chime S AWS Glue DK 调用分析](ca-data-model-queries.md)
# 了解 Amazon Chime 软件开发工具包 AWS Glue 的数据目录表结构
下图显示了为 Amazon Chime SDK 呼叫分析和语音分析会话创建的 AWS Glue 数据目录的表格结构。
![\[呼叫分析 Glue 数据目录中的表。\]](http://docs.aws.amazon.com/zh_cn/chime-sdk/latest/dg/images/glue-cat-diag-12-03.jpg)
下一部分列出并描述了目录中的表和字段。
# 了解 Amazon Chime 软件开发工具包 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_cn/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_cn/chime-sdk/latest/dg/glue-tables.html)
## transcribe\$1call\$1analytics
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/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_cn/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_cn/chime-sdk/latest/dg/glue-tables.html)
## transcribe
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/chime-sdk/latest/dg/glue-tables.html)
## voice\$1analytics\$1status
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/chime-sdk/latest/dg/glue-tables.html)
## speaker\$1search\$1status
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/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_cn/chime-sdk/latest/dg/glue-tables.html)
# 提取数据目录中的数据以用于 Amazon Chime S AWS Glue DK 调用分析
使用这些示例查询来提取和组织您的 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 表中的元数据（字符串数据类型）中提取值
`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\$1metadatics 表中的 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 表中的元数据（字符串数据类型）中提取值
`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 表中的详细信息（结构数据类型）中提取值
`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 表中提取转录
transcripe\$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 语音连接器呼叫结合使用。我们建议使用[媒体管道 SDK](media-pipelines.md) 并在媒体见解管线上调用任务，以便对任务及有关信息进行更精细的控制。
你可以使用 Voice Connectors 来确保向后兼容，但我们只 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_cn/chime-sdk/latest/dg/images/va-architecture-kvs.png)
在下图中：
1. 音频流式传输到 Kinesis 视频流，供呼叫者和座席使用。您可以使用 Kinesis Video Streams 制作程序或 Amazon Chime SDK 语音连接器流式传输来做到这一点。有关更多信息，请参阅本指南中的 [了解 Amazon Chime SDK 基于机器学习的分析工作流程](ml-based-analytics.md)，以及 *Amazon Chime SDK 管理员指南*中的 [Amazon Chime SDK 语音连接器媒体流式传输到 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_UpdateVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html) APIs 内致电[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)或。
**语音配置文件域**
语音配置文件集合。
# 了解 Amazon Chime SDK 的发言人搜索工作流程
在本节中，我们会展示 Amazon Chime SDK 发言人搜索分析的示例数据和程序流。
发言人搜索功能涉及创建语音嵌入，该嵌入可用于比较呼叫者的语音与先前存储的语音数据。以数字声纹的形式收集、使用、存储和保留生物识别标识符和生物识别信息，可能需要以书面形式获得呼叫者的知情同意。根据各种州法律，包括伊利诺伊州、德克萨斯州、华盛顿州的生物识别法和其他州的隐私法，都要求获得此类同意。在使用发言人搜索功能之前，您必须根据适用法律以及监督您使用该功能的 [AWS 服务条款](https://aws.amazon.com/service-terms/)的要求，全面通知并获得一致同意。
下图显示了通过发言人搜索分析任务的数据流示例。图下方的带编号的描述介绍了该过程的每个步骤。该图假设您已经使用具有 `VoiceAnalyticsProcessor` 的呼叫分析配置来配置了 Amazon Chime SDK 语音连接器。有关更多信息，请参阅 [录制 Voice Connector 通话](record-vc-calls.md)。
![\[显示通过发言人搜索分析的数据流的图。\]](http://docs.aws.amazon.com/zh_cn/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 语音连接器的电话号码拨号。或者，座席使用语音连接器号码执行出站呼叫。
1. Amazon Chime SDK 语音连接器服务会创建一个事务 ID 并将其与呼叫关联。
1. 假设您的应用订阅了 EventBridge 事件，则您的应用程序使用媒体见解管道配置和 Kinesis Video ARNs Stream 调用 Voice Connector 调用 [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. 一旦呼叫者表示同意，如果您具有语音连接器和事务 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 以识别异步任务。
**注意**
在其中任何一个中调用 `StartSpeakerSearchTask` API 之前 SDKs，您必须根据法律和 AW [S 服务](https://aws.amazon.com/service-terms/)条款的要求提供所有必要的通知并获得必要的同意。
1. 系统会累积 10 秒钟的呼叫者语音。呼叫者必须至少在这段时间内说话。系统不会捕获或分析静默。
1. 媒体见解管线比较话音与域中的语音配置文件，并列出置信度最高的十个匹配项。如果找不到匹配项，语音连接器就会创建语音配置文件。
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`。
下图显示了语音音调分析的工作流程示例。图像下方的带编号的内容描述了该过程的每个步骤。
**注意**
该图假设您已经使用具有 `VoiceAnalyticsProcessor` 的呼叫分析配置来配置了 Amazon Chime SDK 语音连接器。有关更多信息，请参阅 [录制 Voice Connector 通话](record-vc-calls.md)。
![\[显示通过语音音调分析的数据流的图。\]](http://docs.aws.amazon.com/zh_cn/chime-sdk/latest/dg/images/voice-tone-workflow-v2.png)
在下图中：
1. 呼叫者使用分配给 Amazon Chime SDK 语音连接器的电话号码拨号。或者，座席使用语音连接器号码执行出站呼叫。
1. 语音连接器服务创建事务 ID 并将其与呼叫关联。
1. 您的应用程序（例如交互式语音应答系统）或座席会向呼叫者提供有关呼叫记录和使用语音嵌入进行语音分析的通知，并征得他们的同意才能参与。
1. 假设您的应用订阅了 EventBridge 事件，则您的应用程序使用媒体见解管道配置和 Kinesis Video ARNs Stream 调用 Voice Connector 调用 [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_Voice.html) SDK APIs ](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_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 仅返回任务的状态。它不返回任务结果。要查看结果，请使用亚马逊 SQS、亚马逊 SNS 或 AWS Lambda 通知目标。
`GetSpeakerSearchTask` API 会同步获取任务 ID、延迟消息或无序到达消息的最新结果。但是，我们建议使用通知目标和异步处理。这样做会消耗更少的计算资源。
# 了解 Amazon Chime SDK 的通知
当发言人搜索或语音音调分析任务开始、运行和完成时，语音分析会自动向目标发送事件。您可以使用通知目标来接收这些事件。如果您的工作流程或应用程序需要高可用性，我们建议使用多个通知目标。
此外，您必须使用具有访问您的通知目标所需策略的 IAM 角色。有关更多信息，请参阅 [针对 Amazon Chime SDK 使用通话分析资源访问角色](call-analytics-resource-access-role.md)。
**注意**
对于亚马逊 SQS 和亚马逊 SNS，我们不支持队列。 first-in-first-out因此，消息可能会无序到达。我们建议您检查时间戳以根据需要排序消息，并保留消息在 Amazon DynamoDB 等数据存储中。您也可以使用 APIs 中所述的 “获取” [轮询 Amazon Chime SDK 的任务结果](va-task-result-poll.md) 来接收最新结果。
下表列出了事件及其相应的细节类型。
| 通知事件 | 细节类型 |
| --- | --- |
| 语音分析元数据 | `VoiceAnalyticsStatus` |
| 发言人搜索 | `SpeakerSearchStatus` |
| 语音音调分析 | `VoiceToneAnalysisStatus` |
# 了解 Amazon Chime SDK 适用于通知目标的 IAM 策略
您必须在呼叫分析配置中使用允许访问您的 Amazon SQS、Amazon SNS、AWS Lambda 或 Amazon KDS 通知目标的 IAM 角色策略。有关更多信息，请参阅本指南中的[针对 Amazon Chime SDK 使用通话分析资源访问角色](call-analytics-resource-access-role.md)。
## 发言人搜索事件
发言人搜索事件具有 `SpeakerSearchStatus` 细节类型。
Amazon Chime SDK 语音连接器发送以下发言人搜索事件：
+ 身份匹配
+ 语音嵌入生成
事件可能具有以下状态：
+ `IdentificationSuccessful` — 在给定语音配置文件域中成功识别出至少一个具有高置信度分数的匹配语音配置文件 ID。
+ `IdentificationFailure` — 无法执行识别。原因：呼叫者至少有 10 秒钟没有说话，音频质量很差。
+ `IdentificationNoMatchesFound` — 在给定语音配置文件域中找不到高置信度匹配项。呼叫者可能是新呼叫者，或者他们的语音可能已经改变。
+ `VoiceprintGenerationSuccessful` — 系统使用 20 秒的非静默音频生成了语音嵌入。
+ `VoiceprintGenerationFailure` — 系统无法生成语音嵌入。原因：呼叫者至少有 20 秒钟没有说话，音频质量很差。
### 身份匹配
为给定 `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) API 后，语音连接器服务会在 10 秒钟的非静默话音后返回识别匹配通知。该服务会返回前 10 个匹配项，以及语音配置文件 ID 和范围为 [0, 1] 的置信度分数。置信度分数越高，呼叫中的发言人与语音配置文件 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 数据流。然后，您可以存储通知到 `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 来移除域。此操作会删除域中的*所有*语音配置文件。
**处理组织级别的选择退出**
要处理整个组织的选择退出，请使用 Organization AWS s 的选择退出政策。使用 `chimesdkvoiceanalytics` 服务名称。有关这些策略的信息，请参阅 *AWS 组织用户指南*中的 [AI 服务选择退出策略](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_ai-opt-out.html)。
**注意**
要使用选择退出政策，您的 AWS 账户必须由 Organizations 集中管理。 AWS 如果您尚未为自己的 AWS 账户创建组织，请参阅 *AWS 组织用户指南*中的[创建和管理组织](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org.html)。
# 了解 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_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_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_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天。
从 a 生成的语音嵌入[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 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 语音连接器来启动分析任务。当您收到语音分析就绪事件时，您可以触发呼叫的发言人搜索或语音分析任务，该任务由以下属性标识：
+ `voiceConnectorId`
+ `transactionId`
**注意**
仅当您的媒体见解管线配置启用了语音分析并与语音连接器关联时，才会提供此通知。当客户调用 `CreateMediaInsightsPipeline` API 并通过媒体管道 SDK 启动发言人搜索任务或语音分析任务时，不提供此通知。
语音连接器返回的 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。
当语音分析准备好进行处理时，语音连接器会以 JSON 正文的形式向通知目标发送包含 `"detailStatus": "AnalyticsReady"` 的事件。如果您使用 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 语音连接器发送以下发言人搜索事件：
+ 身份匹配
+ 语音嵌入生成
事件可能具有以下状态：
+ `IdentificationSuccessful` — 在给定语音配置文件域中成功识别出至少一个具有高置信度分数的匹配语音配置文件 ID。
+ `IdentificationFailure` — 无法执行识别。原因：呼叫者至少有 10 秒钟没有说话，音频质量很差。
+ `IdentificationNoMatchesFound` — 在给定语音配置文件域中找不到高置信度匹配项。呼叫者可能是新呼叫者，或者他们的语音可能已经改变。
+ `VoiceprintGenerationSuccessful` — 系统使用 20 秒的非静默音频生成了语音嵌入。
+ `VoiceprintGenerationFailure` — 系统无法生成语音嵌入。原因：呼叫者至少有 20 秒钟没有说话，音频质量很差。
#### 身份匹配
为给定 `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) API 后，语音连接器服务会在 10 秒钟的非静默话音后返回识别匹配通知。该服务会返回前 10 个匹配项，以及语音配置文件 ID 和范围为 [0, 1] 的置信度分数。置信度分数越高，呼叫中的发言人与语音配置文件 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 呼叫分析和语音分析具有以下服务限额。
| 资源 | 默认限制 | 可调整 |
| --- | --- | --- |
| 每个区域的媒体见解管道配置 | 100 | 是 |
| 每个区域的活跃媒体见解管道 | 20 | 是 |
| 每个区域的语音配置文件域 | 3 | 是 |
| 每个语音配置文件域的语音配置文件 | 20 | 是 |
| 每个区域的活动发言者搜索任务 | 25 | 是 |
| 每个区域的活动语音语调分析任务 | 25 | 是 |
| 活动语音连接器调用以及每个区域的语音分析 | 25 | 是 |
| 每个交易 ID 的每个 Voice Connector 呼叫的活动发言人搜索任务 | 1 | 否 |
| 每个交易 ID 的每个语音连接器调用的活动语音分析任务 | 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 控制台中的 S **ervice Quotas 页面申请增加配额**，也可以联系您的[客户支持代表](https://docs.aws.amazon.com/awssupport/latest/user/getting-started.html)。
一些呼叫分析为其他 AWS 服务 APIs 创建资源和 API 请求。这些额外费用将计入您账户的限额。如果您申请通话分析配额或 transactions-per-second增加配额，则还必须申请增加其他 AWS 服务的配额。否则，您的请求可能会受到限制并失败。