翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Amazon Chime SDK の通話分析を使用して通話からインサイトを生成する
このセクションのトピックでは、Amazon Chime SDK 通話分析を使用して通話データからインサイトを生成する方法について説明します。
Amazon Chime SDK 通話分析の導入により、ローコードソリューションを実現して、リアルタイム音声から費用対効果の高いインサイトを生成でき、音声データの取り込み、分析、アラート、データレイク統合なども行えます。通話分析を使用すると、Amazon Transcribe と Transcribe Call Analytics (TCA) の統合に加え、Amazon Chime SDK 音声分析をネイティブに行うことで、インサイトを生成できます。また、Amazon S3 バケットに通話を録音することも可能です。
通話分析を設定および実行するには、次の方法を使用します。
+ Amazon Chime SDK コンソールを使用して通話分析を設定し、それを Amazon Chime SDK Voice Connector に関連付けます。その過程で、通話の録音と分析を有効にできます。この手順を完了するためにコードを記述する必要はありません。
+ [Amazon Chime SDK](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/welcome.html) API のセットを使用して、プログラムで設定を行い、実行します。
詳細については、このセクションで後述する「[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 CloudWatch を使用して Amazon Chime SDK の通話分析パイプラインをモニタリングする](monitoring-with-cloudwatch.md)
+ [Amazon Chime SDK の通話分析プロセッサと出力先](call-analytics-processor-and-output-destinations.md)
+ [Amazon Chime SDK の通話分析のデータモデル](ca-data-model.md)
+ [Amazon Chime SDK 音声分析を使用する](voice-analytics.md)
+ [Amazon Chime SDK の通話分析のサービスクォータ](ca-regions.md)
# Amazon Chime SDK 通話分析とは
Amazon Chime SDK の導入により、ローコードソリューションを実現して、リアルタイム音声から費用対効果の高いインサイトを生成でき、音声データの取り込み、録音、音声分析、アラート、データレイクの利用なども行えます。ワークフローで有効にする機械学習統合とオーディオ処理機能を決定する再利用可能な通話分析設定を作成することで、通話分析を使用して AWS 機械学習を活用したインサイトを生成できます。その通話分析設定は、Voice Connector や Amazon Kinesis Video Streams などのさまざまなメディアソースにも使用します。通話分析では、Amazon Transcribe と Transcribe Call Analytics (TCA) の統合に加え、[Amazon Chime SDK 音声分析](voice-analytics.md) (通話分析で実行されるサービス) をネイティブに行うことでインサイトを生成します。
通話分析を使用するには、次の手順に従います。
![\[Amazon Chime SDK 通話分析を設定するプロセスを示す画像。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/CallAnalyticsOverview.png)
図中の手順を説明します。
1. 最初に通話分析を設定します。
1. 出力先とデータレイク (オプション) を設定します。
1. その設定を Voice Connector と Amazon Kinesis Video Streams に関連付けるワークフローを作成します。
1. インサイトを分析し、必要に応じて視覚化します。
Amazon Chime SDK コンソールを使用して、通話分析を設定し、通話分析の自動開始を有効にすることができます。特定のタイプの呼び出しに適用する設定を制御する必要がある場合は、API を使用して設定を行います。いずれの場合も、設定には、通話音声に対して呼び出す AWS 機械学習サービスの詳細、通話録音の有効化、インサイト、メタデータ、録音の送信先が含まれます。通話分析では次の送信先を使用できます。
+ 1 つの Amazon Kinesis Data Streams (KDS)。KDS を使用して通話のインサイトをライブで受信し、それをアプリケーションに統合できます。例えば、ライブインサイトを統合して顧客との通話中に販売エージェントやカスタマーサポートエージェントを支援したり、インサイトを使用して生成 AI のプロンプトや概要を改善したりできます。
+ データウェアハウスとして設定された Amazon S3 バケット。バケットには Parquet 形式でデータを格納します。Parquet は、大量のデータを圧縮し、保存することを目的としたオープンソースのファイル形式です。データを格納したら、Amazon Athena を利用して、単純なクエリ言語 (SQL) でそれらのデータを参照したり、データを既存のデータウェアハウスに移動してビジネスデータと統合したりできます。例えば、通話後の集計を分析して、顧客との通話の有効性や製品の問題点を把握することも、従業員のトレーニング機会を把握して顧客満足度を向上させることも可能です。
こうした送信先に加え、通話分析は、インサイトに基づいて事前構成できるリアルタイムアラートにも対応しています。アラートは Amazon EventBridge に送信されます。
**注記**
通話分析の設定では、特定の音声ソースを選択しません。これにより、複数の音声ソース間で設定を再利用できます。例えば、通話録音の有効化と、通話の文字起こしを 1 つの設定で行えます。その設定は、Chime SDK Voice Connector や、Kinesis Video Streams 経由のオーディオストリームでも使用できます。複数の Voice Connector 間で共有することも可能です。通話分析の各設定は一意であり、ARN によって識別されます。
# Amazon Chime SDK の通話分析の用語について
Amazon Chime SDK 通話分析を理解するために重要な用語と概念を次に示します。
**Amazon Athena**
標準 SQL を使用して Amazon S3 のデータを分析できるインタラクティブなクエリサービス。Athena は、サーバーレスであるため、インフラストラクチャを管理する必要がなく、料金は実行したクエリに対してのみ発生します。Athena を利用するには、Amazon S3 内のデータを指定してスキーマを定義し、標準 SQL クエリを使用します。また、ワークグループでユーザーをグループ化し、クエリの実行時にユーザーがアクセスできるリソースを制御することもできます。ワークグループを使用すると、クエリの同時実行を管理して、さまざまなユーザーグループやワークロードによるクエリ実行に優先順位を付けることが可能です。詳細については、「[Amazon Athena とは](https://docs.aws.amazon.com/athena/latest/ug/what-is.html)」を参照してください。
**Amazon Kinesis Data Firehose**
抽出、変換、ロード (ETL) サービス。これにより、ストリーミングデータをデータレイク、データストア、分析サービスに、確実にキャプチャ、変換、配信することが可能です。詳細については、「[Amazon Kinesis Data Firehose](https://aws.amazon.com/kinesis/data-firehose/)」を参照してください。
**通話分析データウェアハウス**
通話分析データ用のオプションストレージ。このウェアハウスでは、Parquet ベースのデータファイル形式で Amazon S3 バケットにデータを格納します。データのクエリには、標準 SQL を使用できます。ウェアハウスは通話分析設定で有効にします。
**Glue Data Catalog**
さまざまなデータソースのデータ資産を一元管理できるメタデータリポジトリであり、データベースとテーブルで構成されています。通話分析を行う際、Athena では、このテーブル内のメタデータによって Amazon S3 バケットの場所が判断されます。また、列名、データ型、テーブル名などのデータ構造も指定されます。データベースで保持されるのは、データセットのメタデータとスキーマ情報のみです。詳細については、このセクションで後述する「[Amazon Chime SDK AWS Glue のデータカタログテーブル構造を理解する](ca-data-model-diagram.md)」を参照してください。
**メディアインサイトパイプライン**
一意の `MediaPipelineId` によって識別される一時的なリソース。これを作成するには、通話分析パイプラインの設定と、ランタイムパラメータを使用します。このランタイムパラメータによって、パイプラインのデータソースを指定します。
**メディアインサイトのパイプライン設定**
メディアインサイトパイプラインの作成に使用する静的な設定。1 つ以上のパイプラインをインスタンス化するには、この設定を使用します。
**メディアインサイトパイプライン設定の構成要素**
メディアインサイトパイプライン設定は、プロセッサ要素によっててメディアを処理するための命令や、シンク要素によって生成したインサイトを配信するための命令などで構成されます。
**メディアインサイトパイプラインタスク**
メディアインサイトパイプラインの一時的なサブリソース。このタスクにより、特定のストリーム ARN およびチャネル ID のプロセスステータスに関するメタデータが保持されます。タスクは、固有の ID で識別され、メディアインサイトパイプラインで音声分析を開始する際に作成されます。
**発話者検索**
通話参加者の認識に役立つ音声分析機能。
**音声分析**
発話者検索やボイストーン分析などを行える Amazon Chime SDK の機能。
**音声埋め込み**
発信者の音声を、一意の ID を付け、ベクター形式で表現した情報。
**音声エンハンスメント**
通話の音質を向上させるシステム。
**音声プロファイル**
音声埋め込み、ID、有効期限を組み合わせた情報。
**音声プロファイルドメイン**
音声プロファイルの集合体。
**音声トーン分析**
音声分析機能。これにより、`positive`、`negative` または `neutral` のセンチメントを分析できます。
通話インサイトの設定、パイプラインの開始、音声分析の実行に使用する API の詳細については、「*Amazon Chime SDK API Reference*」の「[Amazon Chime SDK Media Pipelines](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Media_Pipelines.html)」を参照してください。
**注記**
通話分析の実行には、メディアインサイトパイプライン API の使用を強くお勧めします。新しい機能が利用できるのは、メディアインサイトパイプライン API のみだからです。メディアパイプラインと音声名前空間の違いについては、このセクションで後述する「[音声 API を使用して 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)
+ [API を使用して Amazon Chime SDK の通話分析を設定する](create-config-apis.md)
+ [設定と Amazon Chime SDK の Voice Connector を関連付ける](ca-associate-vc-steps.md)
# Amazon Chime SDK 通話分析の前提条件について
通話分析を設定する前に必要な事項を次に示します。 AWS コンソールを使用して作成できます。
+ Amazon Chime SDK Voice Connector。これを用意できない場合は、「[Creating Amazon Chime SDK Voice Connectors](https://docs.aws.amazon.com/chime-sdk/latest/ag/ca-prerequisites.html)」を参照してください。次の操作も必要です。
+ Voice Connector のストリーミングを有効にします。詳細については、「*Amazon Chime SDK Administrator Guide*」の「[Automating the Amazon Chime SDK with EventBridge](https://docs.aws.amazon.com/chime-sdk/latest/ag/automating-chime-with-cloudwatch-events.html)」を参照してください。
+ 通話分析を使用するよう、Voice Connector を設定します。詳細については、「*Amazon Chime SDK Administrator Guide*」の「[Configuring Voice Connectors to use call analytics](https://docs.aws.amazon.com/chime-sdk/latest/ag/configure-voicecon.html)」を参照してください。
+ Amazon EventBridge の対象。これらを用意できない場合は、「*Amazon Chime SDK Administrator Guide*」の「[Monitoring the Amazon Chime SDK with EventBridge](https://docs.aws.amazon.com/chime-sdk/latest/ag/automating-chime-with-cloudwatch-events.html)」を参照してください。
+ サービスにリンクされたロール。これにより、Voice Connector が EventBridge の対象で生じるアクションにアクセスできるようにします。詳細については、「*Amazon Chime SDK Administrator Guide*」の「[Using the Amazon Chime SDK Voice Connector service linked role policy](https://docs.aws.amazon.com/chime-sdk/latest/ag/using-service-linked-roles-stream.html)」を参照してください。
+ 1 つの Amazon Kinesis Data Streams。これを用意できない場合は、「*Amazon Kinesis Streams Developer Guide*」の「[Creating and Managing Streams](https://docs.aws.amazon.com/streams/latest/dev/working-with-streams.html)」を参照してください。音声分析と文字起こしには Kinesis Data Stream が必要です。
+ 通話をオフラインで分析するには、Amazon Chime SDK データレイクを作成する必要があります。これを行うには、本ガイドで後述する「[Amazon Chime SDK データレイクを作成する](ca-data-lake.md)」を参照してください。
# Amazon Chime SDK コンソールを使用して、通話分析を設定する
前のセクションに記載されている前提条件を満たすことができたら、Amazon Chime SDK コンソールを使用して 1 つ以上の通話分析を設定できます。コンソールからは、1 つまたは複数の Voice Connector を関連付けることもできます。このプロセスを完了すると、設定時に有効にした機能を使用して通話分析が実行されます。
通話分析を設定するには、次の手順に従います。
1. 名前やオプションのタグなど、設定の詳細を指定します。
1. 録音の設定を行います。録音に加え、機械学習を活用したインサイトといった、通話分析を設定します。
1. 分析サービスを設定します。
1. リアルタイムでのインサイト取得に必要な出力先を選択します。データレイクを作成し、通話後分析を行います (オプション)。
1. 新しいサービスロールを作成するか、既存のロールを使用します。
1. リアルタイムアラートを設定します。これにより、特定の条件が満たされた際に、Amazon EventBridge 経由で通知を送信できます。
1. 指定した内容を確認し、設定を完了します。
設定を完了したら、Voice Connector をその設定に関連付けて通話分析を有効にします。これにより、その Voice Connector で通話の着信が発生したタイミングで通話分析が自動的に開始されます。詳細については、このセクションで後述する「[設定と Amazon Chime SDK の Voice Connector を関連付ける](ca-associate-vc-steps.md)」を参照してください。
次のセクションでは、プロセスの各手順を完了する方法について説明します。リストされている項目をこの順序で展開してください。
## 設定の詳細を指定する
**設定の詳細を指定するには、**
1. [https://console.aws.amazon.com/chime-sdk/home](https://console.aws.amazon.com/chime-sdk/home) から Amazon Chime コンソールを開きます。
1. ナビゲーションペインの **[通話分析]** で **[設定]** を選択し、**[設定の作成]** を選択します。
1. **[基本的な情報]** で、以下を実行します。
1. 設定の名前を入力します。ユースケースとタグがわかる名前にする必要があります。
1. (オプション) **[タグ]** で **[新しいタグの追加]** を選択し、タグキーとオプションの値を入力します。キーと値を定義します。タグは、設定のクエリに役立ちます。
1. [**次へ**] を選択します。
## 録音を設定する
**録音を設定するには**
+ **[記録を設定]** ページで、次の手順を実行します。
1. **[通話録音を有効にする]** チェックボックスを選択します。これにより、Voice Connector の通話や KVS のストリームを録音し、そのデータを Amazon S3 バケットに送信できます。
1. **[ファイル形式]** で **[WAV と PCM]** を選択します。これにより、最良の音質が得られます。
または
**[OGG と OPUS]** を選択すると、音声を圧縮し、ストレージを最適化できます。
1. (オプション) 必要に応じて、**[Amazon S3 バケットの作成]** リンクを選択し、次の手順に従って Amazon S3 バケットを作成します。
1. Amazon S3 バケットの URI を入力するか、**[参照]** を選択してバケットを検索します。
1. (オプション) **[音声エンハンスメントを有効にする]** を選択すると、録音の音質が向上します。
1. [**次へ**] を選択します。
## 音声エンハンスメントを理解する
通話分析の設定が完了したら、通話録音を有効にして、録音した通話を Amazon S3 バケットに保存できます。その手順中に音声エンハンスメントを有効にし、保存した通話の音質を向上させることも可能です。音声エンハンスメントは、それを有効にした後に生成された録音にのみ適用されます。音声エンハンスメントが有効な場合、元の録音に加え、拡張録音が行われ、それらは Amazon S3 バケットに同じ形式で保存されます。音声エンハンスメントでは、通話の拡張録音を最大 30 分行えます。30 分を超える通話では、拡張録音は行えません。
通話は、ナローバンドフィルタ処理され、8 kHz でサンプリングされます。音声エンハンスメントでは、サンプリングレートを 8 kHz から 16 kHz に引き上げ、機械学習モデルを使用して周波数成分を狭帯域から広帯域に拡張することで、より自然な音声を実現しています。また、Amazon Voice Focus と呼ばれるノイズリダクションモデルを使用し、拡張機能を使用した音声でバックグラウンドノイズも低減します。
音声エンハンスメントでは、Voice Focus と呼ばれるノイズリダクションモデルも使用します。このモデルにより、拡張機能を使用した音声で、バックグラウンドノイズを低減できます。このモデルは、アップグレードされた 16 kHz 音声に適用されます。
**注記**
音声エンハンスメントは、米国東部 (バージニア北部) リージョンと米国西部 (オレゴン) リージョンでのみサポートされています。
音声エンハンスメント録音メタデータは、設定された KDS を介して既存の AWS Glue データカタログテーブル *call\$1analytics\$1recording\$1metadata* に発行されます。元の通話録音データと、音声エンハンスメントによる通話録音データを識別するために、*VoiceEnhancement* という値を持つ新規フィールド *detail-subtype* が KDS の通知と Glue テーブル *call\$1analytics\$1recording\$1metadata* に追加されます。データウェアハウススキーマの詳細については、「[Amazon Chime SDK の通話分析のデータモデル](ca-data-model.md)」を参照してください。
### 音声エンハンスメントで使用されるファイル形式
音声の拡張機能のファイルについては、次の点に注意します。
+ 拡張機能による録音は、通常の録音と同じ Amazon S3 バケットに書き込まれます。送信先を設定するには、[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_S3RecordingSinkConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_S3RecordingSinkConfiguration.html) または [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_S3RecordingSinkRuntimeConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_S3RecordingSinkRuntimeConfiguration.html) API を呼び出すか、Amazon Chime SDK コンソールを使用します。
+ 音声の拡張機能では、ベースファイル名に **\$1enhanced** が追加されます。
+ 音声の拡張機能では、元の録音と同じファイル形式が維持されます。ファイル形式を設定するには、[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_S3RecordingSinkConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_S3RecordingSinkConfiguration.html) または [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_S3RecordingSinkRuntimeConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_S3RecordingSinkRuntimeConfiguration.html) API を呼び出すか、Amazon Chime SDK コンソールを使用します。
次の例は、一般的なファイル名の形式を示しています。
```
s3://original_file_name_enhanced.wav
```
または
```
s3://original_file_name_enhanced.ogg
```
## 分析サービスを設定する
Amazon Transcribe を使用すると、通話の文字起こしを行えます。その後、文字起こししたテキストを使用して、Amazon Comprehend といった他の機械学習サービスや独自の機械学習モデルを強化できます。
**注記**
Amazon Transcribe は、自動言語認識機能も備えていますが、この機能は、カスタム言語モデルやコンテンツ編集では使用できません。また、他の機能で言語識別を使用する場合は、その機能が対応している言語しか使用できません。詳細については、「*Amazon Transcribe Developer Guide*」の「[Language identification with streaming transcriptions](https://docs.aws.amazon.com/transcribe/latest/dg/lang-id-stream.html)」を参照してください。
Amazon Transcribe Call Analytics は、機械学習を活用した API であり、これによって、通話の文字起こし、センチメント分析、会話に関するインサイトのリアルタイム取得などが可能になります。このサービスを利用すると、メモを取る必要がなくなり、見つかった問題にすぐに対処できます。また、発信者の感情、通話の要因、会話のない時間、会話のさえぎり、会話の速度、会話の特徴などに通話後分析も行えます。
**注記**
デフォルトの場合、通話後分析は、Amazon S3 バケットにストリーミングされます。録音の重複を防ぐには、通話録音と通話後分析を同時に有効化しないようにします。
さらに、Transcribe Call Analytics では、特定のフレーズに基づいて会話に自動的にタグを付けることで、音声やテキストから機密情報を削除できます。通話分析のメディアプロセッサ、これらのプロセッサで生成するインサイト、出力先については、このセクションで後述する「[Amazon Chime SDK の通話分析プロセッサと出力先](call-analytics-processor-and-output-destinations.md)」で詳しく確認できます。
**分析サービスを設定するには**
1. **[分析サービスを設定]** ページで、**[音声分析]** または **[文字起こしサービス]** の横にあるチェックボックスを選択します。両方の選択も可能です。
**[音声分析]** チェックボックスを選択すると、**[発話者検索]** と **[ボイストーン分析]** を任意に組み合わせることができます。
**[文字起こしサービス]** チェックボックスを選択して、Amazon Transcribe または Transcribe Call Analytics を有効にします。
1. **発話者検索を有効にするには**
+ **[はい、Amazon Chime SDK 音声分析の同意確認を認めます]** チェックボックスを選択し、**[承諾]** を選択します。
1. ボイストーン分析を有効にするには
+ **[ボイストーン分析]** チェックボックスを選択します。
1. Amazon Transcribe を有効にするには
1. **[Amazon Transcribe]** ボタンを選択します。
1. **[言語設定]** で、次のいずれかを実行します。
1. 発信者が 1 つの言語を話す場合は、**[特定の言語]** を選択して **[言語]** リストを開き、対象の言語を指定します。
1. 発信者が複数の言語を話す場合は、自動的に識別されます。**[言語の自動検出]** を選択します。
1. **[自動言語識別の言語オプション]** リストを開き、少なくとも 2 つの言語を選択します。
1. (オプション) **[優先言語]** リストを開き、優先言語を指定します。前の手順で選択した言語の信頼スコアが一致すると、優先言語での文字起こしが実行されます。
1. (オプション) **[コンテンツ削除設定]** を展開して 1 つまたは複数のオプションを選択し、表示される追加オプションから 1 つ以上を選択します。各オプションの説明は、ヘルパーテキストで確認できます。
1. (オプション) **[その他の設定]** を展開して 1 つまたは複数のオプションを選択し、表示される追加オプションから 1 つ以上を選択します。各オプションの説明は、ヘルパーテキストで確認できます。
1. Amazon Transcribe Call Analytics を有効にするには
1. **[Amazon Transcribe Call Analytics]** ボタンを選択します。
1. **[言語]** リストを開き、言語を選択します。
1. (オプション) **[コンテンツ削除設定]** を展開して 1 つまたは複数のオプションを選択し、表示される追加オプションから 1 つ以上を選択します。各オプションの説明は、ヘルパーテキストで確認できます。
1. (オプション) **[その他の設定]** を展開して 1 つまたは複数のオプションを選択し、表示される追加オプションから 1 つ以上を選択します。各オプションの説明は、ヘルパーテキストで確認できます。
1. (オプション) **[通話後分析]** 設定を展開し、次の操作を行います。
1. **[通話後分析]** チェックボックスを選択します。
1. Amazon S3 バケットの URI を入力します。
1. コンテンツ編集タイプを選択します。
1. 選択したら、**[次へ]** を選択します。
## 出力の詳細設定を行う
メディア処理の手順を完了したら、分析結果の出力先を選択します。通話分析では、Amazon Kinesis Data Streams を介して、また、オプションにより、選択した Amazon S3 バケット内のデータウェアハウスを介して、インサイトをライブで取得できます。データウェアハウスを作成するには、CloudFormation テンプレートを使用します。このテンプレートにより、通話のメタデータとインサイトを Amazon S3 バケットに配信するインフラストラクチャを構築できます。データウェアハウス作成の詳細については、このセクションで後述する「[Amazon Chime SDK データレイクを作成する](ca-data-lake.md)」を参照してください。データウェアハウススキーマの詳細については、同じくこのセクションで後述する「[Amazon Chime SDK の通話分析のデータモデル](ca-data-model.md)」を参照してください。
前のセクションで音声分析を有効にした場合は、 AWS Lambda、Amazon Simple Queue Service、Amazon Simple Notification Service などの音声分析通知の送信先を追加することもできます。以下では、その手順を説明します。
**出力の詳細を設定するには**
1. **[Kinesis Data Stream]** リストを開き、データストリームを選択します。
**注記**
データを視覚化するには、Amazon S3 バケットと Amazon Kinesis Data Firehose で使用する Kinesis Data Stream を選択する必要があります。
1. (オプション) **追加の音声分析通知の送信先**を展開し、 AWS Lambda、Amazon SNS、Amazon SQS の送信先を任意に組み合わせて選択します。
1. (オプション) **[インサイトの分析と視覚化]** で、**[データレイクを使用した過去データ分析を実行]** チェックボックスを選択します。データレイクの詳細については、このセクションで後述する「[Amazon Chime SDK データレイクを作成する](ca-data-lake.md)」を参照してください。
1. 完了したら、[**次へ**] を選択します。
## アクセス許可を設定する
通話分析を有効にするには、機械学習サービスなどのリソースに、データメディアにアクセスしてインサイトを提供するための権限が必要です。既存のサービスロールを使用することも、コンソールから新しいロールを作成することもできます。ロールの詳細については、このセクションで後述する「[Amazon Chime SDK で通話分析のリソースアクセスロールを使用する](call-analytics-resource-access-role.md)」を参照してください。
**アクセス許可を設定するには**
1. **[アクセス許可を設定]** ページで、次の操作のいずれかを行います。
1. **[新しいサービスロールを作成し使用する]** を選択します。
1. **[サービスロール名のサフィックス]** ボックスに、どのようなロールかがわかるようなサフィックスを入力します。
または
1. **[既存のサービスロールを使用する]** を選択します。
1. **[サービスロール]** リストを開き、ロールを選択します。
1. [**次へ**] を選択します。
## (オプション) リアルタイムアラートを設定する
**重要**
リアルタイムアラートを使用するには、最初に Amazon Transcribe または Amazon Transcribe Analytics を有効にする必要があります。
Amazon EventBridge にリアルタイムアラートを送信するルールセットを作成できます。Amazon Transcribe または Amazon Transcribe Call Analytics によって生成されたインサイトが、分析セッション中に指定されたルールと一致すると、アラートが送信されます。アラートには `Media Insights Rules Matched` という詳細タイプが設定されています。EventBridge は、Amazon Lambda、Amazon SQS、Amazon SNS などのダウンストリームサービスにも対応しているため、エンドユーザーへの通知をトリガーしたり、他のカスタムビジネスロジックを開始したりできます。詳細については、このセクションで後述する「[Amazon Chime SDK で Amazon EventBridge の通知を使用する](using-eventbridge-notifications.md)」を参照してください。
**アラートを設定するには**
1. **[リアルタイムアラート]** で **[リアルタイムアラートを有効にする]** を選択します。
1. **[ルール]** で **[ルールを作成]** を選択します。
1. **[ルール名]** ボックスにルールの名前を入力します。
1. **[ルールタイプ]** リストを開き、使用するルールタイプを選択します。
1. 表示されるコントロールを使用して、ルールにキーワードを追加したり、**[言及あり]** や **[言及なし]** などのロジックを適用したりできます。
1. [**次へ**] を選択します。
## 確認と作成
**設定を行うには**
1. 各セクションの設定内容を確認します。必要に応じて **[編集]** を選択し、設定を変更します。
1. **[設定を作成]** を選択します。
設定内容は、Amazon Chime SDK コンソールの **[設定]** ページに表示されます。
# API を使用して Amazon Chime SDK の通話分析を設定する
Voice Connector の作成と通話分析の設定をプログラムで行い、それらを関連付けることで、通話分析ワークフローを開始できます。このガイドは、読者の皆様にプログラミングのご経験があることを前提としています。
使用する API は、ワークフローのタイプによって異なります。例えば、音声を録音するには、最初に [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) を呼び出し、Voice Connector を作成します。最後に、[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 Video Streams プロデューサーで音声を録音するには、[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 を関連付けるには**
1. [https://console.aws.amazon.com/chime-sdk/home](https://console.aws.amazon.com/chime-sdk/home) から Amazon Chime コンソールを開きます。
1. ナビゲーションペインの **[SIP トランキング]** で、**[Voice Connector]** を選択します。
1. 設定に関連付ける Voice Connector の名前を選択し、**[ストリーミング]** タブを選択します。
1. **[開始]** を選択していない場合は、それを選択して、Kinesis Video Streams へのストリーミングを開始します。
1. **[通話分析]** で **[有効化]** を選択し、表示されるメニューで、対象の通話分析設定 ARN を選択します。
1. **[保存]** を選択します。
**注記**
Voice Connector に関連付けた設定を有効化、無効化、または変更した後、新しい設定がサービスに反映され有効になるまで 5 分かかります。
通話分析設定の詳細については、「*Amazon Chime SDK Administrator Guide*」の「[Managing call analytics](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 Video Streams の録音および録画に関する各種ワークフローについて説明します。
# Voice Connector の通話を録音する
このワークフローの用途:
+ Voice Connector を既に使用し SIP メディアを通話分析に取り込んでいる、または使用する予定がある。
**注記**
Voice Connector は SIP と SIPREC に対応しています。詳細については、「*Amazon Chime SDK Administrator Guide*」の「[ Managing Amazon Chime SDK Voice Connectors](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 の通話に同じ録音設定を適用する。1 つまたは複数の Voice Connector に複数の設定を適用する場合は、次のセクションを参照してください。
プログラムによる呼び出しを有効にするには、次の Amazon Chime SDK API を使用してください。
+ [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 Administrator Guide*」の「[Configuring Voice Connectors to use call analytics](https://docs.aws.amazon.com/chime-sdk/latest/ag/configure-voicecon.html)」を参照してください。
次の図は、Voice Connector によって通話録音セッションを開始するときのデータフローを示しています。図の数字は、次の各説明の番号に対応しています。
![\[Voice Connector によって通話録音を開始するデータフローを示す画像。\]](http://docs.aws.amazon.com/ja_jp/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 Administrator Guide*」の「[Creating call analytics configurations](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 に関連付けます。コンソールを使用するには、「[Configuring Voice Connectors to use call analytics](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 SDK AWS Glue のデータカタログテーブルについて](glue-tables.md)」を参照してください。
1. メディアパイプラインサービスによって、パイプラインステータスイベントがデフォルトの Amazon EventBridge に送信されます。詳細については、このガイドの「[Event Bridge 通知の使用](https://docs.aws.amazon.com/chime-sdk/latest/dg/ca-eventbridge-notifications.html)」を参照してください。
**注記**
Voice Connector による録音を有効にするには、Voice Connector のストリーミングを有効にする必要があります。この機能によって、アカウント内の Voice Connector で管理する Kinesis Video Streams に通話データをストリーミングできるようになるからです。詳細については、「*Amazon Chime SDK Administrator Guide*」の「[Streaming Amazon Chime SDK Voice Connector media to Kinesis Video Streams](https://docs.aws.amazon.com/chime-sdk/latest/ag/start-kinesis-vc.html)」を参照してください。
また、Voice Connector で作成した通話データは、数時間、数日、数年まで、さまざまな期間、Kinesis Video Streams に保存できます。データ保持を行わない場合、通話データをすぐに使用しなければならなくなります。Kinesis Video Streams のコストは、使用する帯域幅と合計ストレージに基づいて判断します。データ保持期間は、Voice Connector のストリーミング設定内でいつでも調整できます。通話分析の記録を有効にするには、通話分析の実行に十分な期間のデータを Kinesis Video Streams 内に保持する必要があります。これを行うには、適切なデータ保持期間を指定します。
通話インサイトパイプライン設定は、必要な数の Voice Connector に関連付けることができます。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 Administrator Guide*」の「[Using the Amazon Chime SDK service-linked role for Amazon Chime SDK Voice Connectors](https://docs.aws.amazon.com/chime-sdk/latest/ag/using-service-linked-roles-stream.html#service-linked-role-permissions-stream)」を参照してください。
# Amazon Kinesis Video Streams プロデューサーを使用して録画する
Amazon Kinesis Video Streams の録画が必要なケースを次に示します。
+ Voice Connector のすべての通話に同じ設定を使用せず、各通話に異なる設定を適用する。
+ Voice Connector で処理しない SIP 音声または SIP 以外の音声を録音する。
この通話録音オプションを使用するには、Kinesis Video Streams (KVS) に音声を発行し、KVS ストリームチャネル情報と通話分析設定 ARN を使用して [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API を呼び出す必要があります。
**注記**
通話分析 API は最大 2 つの音声チャネルに対応しています。通話録音は、Voice Connector ストリーミングを有効にし、Voice Connector の EventBridge 通知内に発行済みの KVS 情報を使用することでも開始できます。
[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API を呼び出すときに、KVS ストリームチャネル定義ごとにフラグメント番号を指定するかどうかを選択できます。フラグメント番号を指定すると、そのフラグメントからストリームの処理が開始されます。フラグメント ID を指定しない場合、利用可能な最新のフラグメントからストリームの処理が開始されます。
次の図は、Voice Connector によって通話録音セッションを開始するときのデータフローを示しています。図の数字は、次の各説明の番号に対応しています。
![\[Voice Connector によって通話録音を開始するデータフローを示す画像。\]](http://docs.aws.amazon.com/ja_jp/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 Administrator Guide*」の「[Streaming Amazon Chime SDK Voice Connector media to Kinesis Video Streams](https://docs.aws.amazon.com/chime-sdk/latest/ag/start-kinesis-vc.html)」を参照してください。
1. Voice Connector ストリーミングが有効な場合、Voice Connector サービスによって、デフォルトの EventBridge に通知が送信されます。
1. Voice Connector ストリーミングでは、アプリケーションで EventBridge からの Amazon Chime Voice Connector ストリーミング `STARTED` イベントを使用して、通話のレッグに関する KVS ストリーム情報を収集できます。
1. アプリケーションで、Voice Connector ストリーミングイベントまたは外部ソースから音声情報が取得されると、Amazon Chime SDK [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API が呼び出されます。
1. メディアパイプラインサービスによって、進行中の通話をモニタリングする通話録音プロセッサが起動します。
1. メディアパイプラインサービスによって、パイプラインステータスイベントがデフォルトの Amazon EventBridge に送信されます。詳細については、「[Event Bridge 通知の使用](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 SDK AWS Glue のデータカタログテーブルについて](glue-tables.md)」を参照してください。
1. アプリケーションによってパイプラインをモニタリングできます。Voice Connector では、通話ステータスに、Amazon EventBridge に発行済みのイベントを使用可能です。詳細については、このガイドの「[Event Bridge 通知の使用](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 recording sink](https://docs.aws.amazon.com/chime-sdk/latest/dg/ca-processors-sinks.html#ca-s3-recording-sink)」を参照してください。
# CLI を使用して録音を開始する
このセクションの例では、次の操作について説明します。
+ CLI を使用して通話分析設定を実行し、[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) を呼び出します。
+ CLI を使用して、録音先、音声ファイル形式、音声ファイル名を指定します。
**Topics**
+ [設定を実行してパイプラインを開始する](#cli-run-config)
+ [録音先、ファイル名、ファイル形式を設定する](#cli-set-buckets-formats)
## 設定を実行してパイプラインを開始する
次のコマンドを使用して設定を実行し、メディアインサイトパイプラインを開始します。pipeline.json ファイルには設定情報が記述されています。
```
aws chime-sdk-media-pipeline create-media-insights-pipeline --cli-input-json file://pipeline.json
```
一般的な `pipeline.json` ファイルの例を次に示します。
```
{
"MediaInsightsPipelineConfigurationArn": arn:aws:chime:region;account_id:media-insights-pipeline-configuration/MyConfiguration,
"KinesisVideoStreamRecordingSourceRuntimeConfiguration": {
"Streams": [
{
"StreamArn": kinesis_video_stream_arn_1
},
{
"StreamArn": kinesis_video_stream_arn_2
}
],
"FragmentSelector": {
"FragmentSelectorType": "selector_type", // Specify "server_timestamp" or "producer_timestamp" as the fragment selector type
"TimestampRange": {
"StartTimestamp": epoch_time_seconds,
"EndTimestamp": epoch_time_seconds
}
}
},
"S3RecordingSinkRuntimeConfiguration": {
"Destination": arn:aws:s3:::bucket_name/prefix/optional_file_name,
"RecordingFileFormat": file_format // Specify "Opus" or "WAV" as the recording file format, if you want to override the configuration
}
}
```
`MediaInsightsPipelineConfigurationArn` は、通話分析を設定した後に受け取る設定 ARN を表しています。
## 録音先、ファイル名、ファイル形式を設定する
次の例では、`MyRecordingBucket` という名前のフォルダを `S3SinkConfiguration.Destination` 値として使用し、`Opus` を `RecordingFileFormat` 値として使用しています。
```
arn:aws:s3:::MyRecordingBucket/voice-connector-id/transaction-id_year-month-date-hour-minute-second-millisecond.ogg
```
次の例では、`MyRecordingBucket` を `S3SinkConfiguration.Destination` 値として使用し、`Wav` を `RecordingFileFormat` 値として使用しています。
```
arn:aws:s3:::MyRecordingBucket/voice-connector-id/transaction-id_year-month-date-hour-minute-second-millisecond.wav
```
# Amazon Chime SDK の機械学習ベースの分析を目的としたワークフローについて
このセクションでは、Amazon Chime SDK 通話分析が備える機械学習分析機能の使用方法について説明します。
**注記**
同じ Kinesis Video Streams で複数の機械学習分析を実行する際には、ビデオストリームの `GetMedia` および `GetMediaForFragmentList` の接続レベル制限を引き上げなければならない場合があります。詳細については、「*Kinesis Video Streams Developer Guide*」の「[Kinesis Video Streams limits](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/limits.html)」を参照してください。
# Voice Connector を使用して通話分析を自動的に開始する
このワークフローの用途:
+ コンソールを主に使用してセットアップを行う。
+ Voice Connector を既に使用し SIP メディアを通話分析に取り込んでいる、または使用する予定がある。Voice Connector は SIP と SIPREC の両方に対応しています。Voice Connector の設定については、「[Managing 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 コンソールでこのワークフローを有効にするには、「[Configuring Voice Connectors to use call analytics](https://docs.aws.amazon.com/chime-sdk/latest/ag/configure-voicecon.html)」に記載の録音設定手順に従ってください。
このワークフローをプログラミングによって有効にするには、次の API を使用します。[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 を使用してその設定を Voice Connector に関連付けます。詳細については、「*Amazon Chime SDK Administrator Guide*」の「[Configuring Voice Connectors to use voice analytics](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/ja_jp/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 に関連付けます。詳細については、「*Amazon Chime SDK Administrator Guide*」の「[ Configuring Voice Connectors to use call analytics](https://docs.aws.amazon.com/chime-sdk/latest/ag/configure-voicecon.html)」を参照してください。
1. 発信中には、Voice Connector によって、各通話参加者の音声を受信します。
1. Voice Connector サービスは通話分析と既に統合されているため、通話分析設定をこのサービスにアタッチすると、メディアパイプラインサービスを使用した通話分析セッションが開始されます。
1. メディアパイプラインサービスによって、1 つ以上のメディアプロセッサが設定の指定どおりに呼び出されます。
1. メディアパイプラインサービスによって、出力データが 1 つ以上の宛先に設定どおりに送信されます。例えば、Amazon Kinesis Data Streams を介してリアルタイム分析を送信できます。設定によっては、通話のメタデータおよび分析を Amazon S3 データウェアハウスに送信することも可能です。
1. メディアパイプラインサービスによって、パイプラインステータスイベントがデフォルトの Amazon EventBridge に送信されます。ルールを設定している場合、そのルールに関する通知が Amazon EventBridge にも送信されます。詳細については、「[Event Bridge 通知の使用](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) 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) API を呼び出す場合のみです。
Voice Connector で通話分析を使用するには、Voice Connector ストリーミングを有効にする必要があります。この機能によって、アカウント内の Voice Connector で管理する Kinesis Video Streams に通話データをストリーミングできるようになるからです。詳細については、「*Amazon Chime SDK Administrator Guide*」の「[Streaming Amazon Chime SDK Voice Connector media to Kinesis Video Streams](https://docs.aws.amazon.com/chime-sdk/latest/ag/start-kinesis-vc.html)」を参照してください。
また、Voice Connector の通話データは、数時間から数年まで、さまざまな期間、Kinesis Video Streams に保存できます。データ保持を行わない場合、通話データをすぐに使用しなければならなくなります。Kinesis Video Streams のコストは、使用する帯域幅と合計ストレージに基づいて判断します。データ保持期間は、Voice Connector のストリーミング設定を編集することで、いつでも調整できます。通話分析の記録を有効にするには、通話分析の終了時まで Kinesis Video Streams にデータが保持されるようにする必要があります。これを行うには、適切なデータ保持期間を指定します。
メディアインサイトパイプライン設定は、必要な数の Voice Connector に関連付けることができます。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 Administrator Guide*」の「[Using the Amazon Chime SDK service-linked role for Amazon Chime SDK Voice Connectors](https://docs.aws.amazon.com/chime-sdk/latest/ag/using-service-linked-roles-stream.html#service-linked-role-permissions-stream)」を参照してください。
# Voice Connector で通話分析 API を使用する
Voice Connector を導入済みで、通話分析設定を適用するタイミングや、適用先の通話を制御する必要がある場合は、このワークフローを使用すると良いでしょう。
この方法を取るには、Voice Connector によって発行するイベント用に EventBridge のターゲットを作成し、それらのイベントを使用して通話分析パイプライン API をトリガーする必要があります。詳細については、「*Amazon Chime SDK Administrator Guide*」の「[Automating the Amazon Chime SDK with EventBridge](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/ja_jp/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. Voice Connector によって、通話音声が Kinesis Video Streams に送信され、対応するイベントが EventBridge に送信されます。これらのイベントには、ストリームおよび通話のメタデータが含まれています。
1. アプリケーションは、EventBridge のターゲットを介して EventBridge にサブスクライブされます。
1. アプリケーションによって、Amazon Chime SDK の [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API が呼び出されます。
1. メディアパイプラインサービスによって、1 つ以上のメディアプロセッサが呼び出されます。呼び出しは、メディアインサイトパイプライン設定内のプロセッサ要素に基づいて行われます。
1. メディアパイプラインサービスによって、出力データが 1 つ以上の宛先に設定どおりに送信されます。Amazon Chime SDK 通話分析によって、Amazon Kinesis Data Streams 経由でのリアルタイム分析が可能になり、設定済みの場合、通話のメタデータ分析を Amazon S3 データウェアハウスに送信できます。
1. メディアパイプラインサービスによって、そのイベントが Amazon EventBridge に送信されます。ルールを設定している場合、そのルールに関する通知が Amazon EventBridge にも送信されます。
1. [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineStatus.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineStatus.html) API を呼び出すことで、通話分析セッションを一時停止または再開できます。
**注記**
通話録音は、通話の一時停止と再開に対応していません。また、通話中に開始した音声分析タスクも、セッションを一時停止すると停止します。再起動するには、[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartSpeakerSearchTask.html) または [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html) API を呼び出す必要があります。
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) API または [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html) API を呼び出して音声分析を開始します。
# Kinesis Video Streams プロデューサーで通話分析を使用する
このオプションを使用するには、音声データを Kinesis Video Streams (KVS) に発行し、KVS ストリームチャネル情報を使用して [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API を呼び出す必要があります。
**注記**
通話分析 API は最大 2 つの音声チャネルに対応しています。
[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 を指定しない場合、利用可能な最新のフラグメントからストリームの処理が開始されます。
通話分析は、音声サンプルレートが 8 kHz～48 kHz の PCM 音声 (符号付き 16 ビットリトルエンディアン音声形式のみ。WAV には未対応) に対応しています。電話音声などの低品質音声では一般的に約 8000 Hz のレートが使用され、高品質の音声では通常 16,000 Hz～48,000 Hz の範囲のレートが使用されます。指定するサンプルレートは、音声のサンプルレートと一致させる必要があります。詳細については、「*Amazon Chime SDK API リファレンス*」の「[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_KinesisVideoStreamSourceRuntimeConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_KinesisVideoStreamSourceRuntimeConfiguration.html)」を参照してください。
Kinesis Video Streams プロデューサー SDK には、音声データを Kinesis Video Streams にストリーミングするために使用できるライブラリセットが用意されています。詳細については、「*Amazon Kinesis Video Streams Developer Guide*」の「[Kinesis Video Streams Producer Libraries](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/producer-sdk.html)」を参照してください。
次の図は、カスタム Kinesis Video Streams プロデューサーで通話分析を使用する場合のデータフローを示しています。図の数字は、次の各説明の番号に対応しています。
![\[Kinesis Video Streams プロデューサーで通話分析を使用する場合のデータフローを示す画像。\]](http://docs.aws.amazon.com/ja_jp/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 Video Streams に音声を書き込みます。
1. アプリケーションで [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipeline.html) API が呼び出されます。
1. メディアパイプラインサービスによって、顧客の Kinesis Video Streams から音声が読み取られます。
1. メディアパイプラインサービスによって、そのイベントが Amazon EventBridge に送信されます。ルールを設定している場合、そのルールに関する通知が Amazon EventBridge にも送信されます。
1. メディアパイプラインサービスによって、1 つ以上のプロセッサ要素が呼び出されます。
1. メディアパイプラインサービスによって、出力データが 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) API または [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_StartVoiceToneAnalysisTask.html) API を呼び出して、アプリケーションで音声分析を開始できます。
# Amazon Chime SDK の通話分析パイプラインの管理
[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetMediaPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetMediaPipeline.html)、[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_ListMediaPipelines.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_ListMediaPipelines.html)、および [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 を呼び出すことで、メディアインサイトパイプラインの読み取り、一覧表示、削除を行うことができます。
次のいずれかの条件が満たされると、メディアインサイトパイプラインは停止します。
+ いずれの Kinesis Video Streams からも 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 を呼び出します。これを行うには、パイプラインの ID または ARN のいずれかを `Identifier` フィールドに渡します。
**警告**
警告: `UpdateMediaInsightsPipelineStatus` API に `Pause` ステータスを指定すると、メディアインサイトパイプラインで開始したすべての音声分析タスクが停止します。`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 時間以上一時停止すると、自動的に停止します。通話録音は一時停止と再開に対応していない点に**留意してください**。
詳細については、次のトピックを参照してください。
+ 「[Event Bridge 通知の使用](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 call analytics processor](https://docs.aws.amazon.com/chime-sdk/latest/dg/ca-processors-sinks.html#ca-transcribe-analytics-processor)」
**注記**
パイプラインを一時停止している間の通話分析の使用量には課金が発生します。ただし、Amazon Transcribe や Amazon Kinesis など、リソースアクセスロールを介してアクセスされた AWS サービスには課金されません。
Identifier フィールドの設定名または ARN を渡すことで、[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_UpdateMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineConfiguration.html)、および [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaInsightsPipelineConfiguration.html) API を使用して、既存の通話分析設定の読み取り、更新、削除を実行できます。
[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) API と [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) API に加え、[音声分析通知のターゲット](va-notification-targets.md)を使用します。
メディアインサイトパイプラインでは、次のステータスが追跡されます。
+ **パイプラインステータス** — 通話分析パイプライン (メディアインサイトパイプラインとも呼ばれる) の全体的なステータス。これは、その要素のステータスによって決まります。
+ **要素ステータス** — 各メディアインサイトパイプライン設定要素の処理ステータス。
+ **タスクステータス** — 音声分析用に開始したメディアインサイトパイプラインタスクの処理ステータス。`VoiceAnalyticsProcessor` 要素のステータスは、タスクステータスによって決まります。通話分析パイプラインの他の要素には、タスクステータスはありません。
メディアインサイトパイプラインタスクの詳細については、このガイドで前述した「[Amazon Chime SDK の通話分析の用語について](ca-terms-concepts.md)」を参照してください。
必ずしもすべてのメディアインサイト設定要素タイプに要素ステータスがあるわけではありません。一般的に、「プロセッサ」タイプのメディアインサイト設定要素にのみ要素ステータスがあります。また、Amazon S3 録音シンクと音声エンハンスメントシンクにはプロセッサステータスがあります。具体的には、次のメディアインサイト設定要素タイプに要素ステータスがあります。
+ `AmazonTranscribeProcessor`
+ `AmazonTranscribeCallAnalyticsProcessor`
+ `S3RecordingSink`
+ `VoiceAnalyticsProcessor`
+ `VoiceEnhancementSink`
パイプラインのステータスは、次に示すように、要素ステータスによって決まります。
| パイプラインのステータス | Condition |
| --- | --- |
| NotStarted | すべての要素ステータスが開始になっていません。 |
| Initializing | 少なくとも 1 つの要素が初期化中で、それ以外は開始されていません。 |
| InProgress | 少なくとも 1 つの要素が稼働中です。 |
| 失敗 | 少なくとも 1 つの要素に障害が発生し、それ以外の要素は停止しています。 |
| 停止中 | 停止条件をすべて確認するには、[Amazon Chime SDK の通話分析パイプラインの管理](managing-call-analytics-pipelines.md) を参照してください。 |
| 停止 | すべての要素が停止しています。 |
| 一時停止中 | すべての要素が一時停止しています。 |
他の要素のステータスとは異なり、`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` に変わらないからです。
+ `VoiceAnalyticsProcessor` では、1 つのタスクを開始し、タスクの実行中に[停止条件](managing-call-analytics-pipelines.md)を満たさない限り、`InProgress` が維持されます。
+ `VoiceAnalyticsProcessor` が `InProgress` の場合にも、タスクの処理時間に対してのみ課金が発生します。
+ 少なくとも 1 つの音声分析タスクを開始し、それ以外のタスクを実行していないメディアインサイトパイプラインをクリーンアップするには、`DeleteMediaPipeline` を呼び出す必要があります。
+ タスクが実行中、または正常に完了している限り、`VoiceAnalyticsProcessor` 要素のステータスは `InProgress` が維持されます。
# Amazon CloudWatch を使用して Amazon Chime SDK の通話分析パイプラインをモニタリングする
Amazon CloudWatch を使用して Amazon Chime SDK コール分析パイプラインをモニタリングできます。また、特定のしきい値を監視するアラームを設定し、これらのしきい値に達したときに通知を送信したりアクションを実行したりできます。CloudWatch の詳細については、「[Amazon CloudWatch ユーザーガイド](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/)」を参照してください。
**Topics**
+ [前提条件](#monitoring-prereqs)
+ [コール分析メトリクス](#monitoring-metrics)
+ [パイプラインメトリクスの CloudWatch ディメンション](#monitoring-dimensions)
## 前提条件
CloudWatch メトリクスを使用するには、まず Amazon CloudWatch にサービスのメトリクスを発行するアクセス許可を付与するメディアパイプラインのサービスリンクロールを作成する必要があります。サービスリンクロールの詳細については、このガイドの「[Amazon Chime SDK メディアパイプラインのサービスリンクロールの作成](create-pipeline-role.md)」を参照してください。
## コール分析メトリクス
Amazon Chime SDK コール分析は、メディアインサイト設定を使用して作成したメディアインサイトパイプラインの `AWS/ChimeSDK` 名前空間に以下のメトリクスを公開します。
| メトリクス | 説明 |
| --- | --- |
| `MediaInsightsPipelineCreated` | メディアインサイトパイプラインは正常に作成されました。 単位: 数 |
| `MediaInsightsPipelineStopped` | メディアインサイトパイプラインは正常に停止されました。 単位: 数 |
| `MediaInsightsPipelineFailed` | メディアインサイトパイプラインは失敗しました。 単位: 数 |
| `MediaInsightsPipelineDuration` | パイプラインの作成から停止/失敗までの時間。 単位: 秒 |
| `MediaInsightsPipelineBillingDuration` | メディアインサイトパイプラインの課金期間。 単位: 数 |
| `RecordingFileSize` | 記録ファイルのサイズ。 単位: バイト |
| `RecordingDuration ` | 記録の期間。 単位: 秒 |
## パイプラインメトリクスの CloudWatch ディメンション
次の表は、コール分析パイプラインのモニタリングに使用できる CloudWatch ディメンションを示しています。
| ディメンション | 説明 |
| --- | --- |
| `MediaInsightsPipelineConfigurationId` | メディアインサイトパイプライン設定の ID。 |
| `MediaInsightsPipelineConfigurationName` | メディアインサイトパイプライン設定の名前。 |
# Amazon Chime SDK の通話分析プロセッサと出力先
各メディアインサイトパイプライン設定では、一意の要素を 1 回のみ指定できます。すべてのプロセッサとシンクは同じ AWS アカウントに存在し、呼び出すエンドポイントと同じ AWS リージョンに作成する必要があります。例えば、Amazon Chime SDK メディアパイプライン向けに `us-east-1` のエンドポイントを使用する場合、`us-west-2` リージョンから Kinesis Data Stream を渡すことはできません。
各送信先に関する情報については、各セクションを展開してください。
## Amazon Transcribe Call Analytics プロセッサの送信先
対応シンク: `KinesisDataStreamSink`
このプロセッサを Amazon Transcribe プロセッサと組み合わせることはできません。Amazon Transcribe Call Analytics の詳細については、「* Amazon Transcribe Developer Guide*」の「[Real-time call analytics](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 秒以上一時停止した後に再開すると、通話後分析のアーティファクトは、異なるセッション ID を持つ個別のファイルとして Amazon S3 バケット内に保存されます。
通話後分析のアーティファクトは、分析 JSON ファイルと音声録音 (WAV または Opus ファイル) で構成されています。編集済み (コンテンツの編集を有効にした場合) および編集済みでない録音ファイルの Amazon S3 バケット URL は、メタデータセクションの `onetimeMetadata` の一部として、Amazon Transcribe Call Analytics の通話後分析セッションごとに 1 回 Kinesis Data Stream に送信されます。
Amazon Transcribe Call Analytics による通話分析では、Kinesis Video Streams から音声データの入力を取得します。
+ 対応メディアエンコーディング: PCM 符号付き 16 ビットリトルエンディアン音声。
+ 対応メディアサンプリングレート: 8,000 Hz～48,000 Hz
Amazon Transcribe Analytics プロセスの `StreamConfiguration` 入力:
+ ストリームごとに `KinesisVideoStreamArn` を指定する必要があります。
+ (オプション) KVS `FragmentNumber` により、指定したフラグメントの後のチャンクを使用して通話分析ジョブが開始されます。指定していない場合は、Kinesis Video Streams の最新のチャンクが使用されます。
+ `StreamChannelDefinition` により、スピーカーを定義します。Amazon Transcribe Call Analytics には 2 チャネルの音声が必要です。そのため、[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 Call Analytics プロセッサで `MediaInsightsPipeline` を作成する場合、Voice Connector アカウントレッグの音声には `AGENT` を、PSTN レッグの音声には `ParticipantRole` の `CUSTOMER` を設定します。
Voice Connector で SIPREC を使用する場合は、SIPREC メタデータによってそれらが決定されます。ほとんどの場合、辞書順に基づく値が最も小さいストリームラベルのスピーカーが `AGENT` と見なされます。
次の例は、1 つのデュアルチャネルオーディオストリームを使用する Kinesis Video Streams の入力を示しています。
```
"StreamChannelDefinition" : {
"NumberOfChannels" : 2
"ChannelDefinitions": [
{
"ChannelId": 0,
"ParticipantRole": "AGENT"
},
{
"ChannelId": 1,
"ParticipantRole": "CUSTOMER"
}
]
}
```
対照的に、次の例は、2 つの異なる Kinesis Video Streams から取得した 2 つのモノラル入力を示しています。
```
KVS-1:
"StreamChannelDefinition" : {
"NumberOfChannels" : 1
"ChannelDefinitions": [
{
"ChannelId": 0,
"ParticipantRole": "AGENT"
}
]
}
KVS-2:
"StreamChannelDefinition" : {
"NumberOfChannels" : 1
"ChannelDefinitions": [
{
"ChannelId": 1,
"ParticipantRole": "CUSTOMER"
}
]
}
```
## Amazon Transcribe Call Analytics の出力
各 Amazon Transcribe レコードには、`UtteranceEvent` または `CategoryEvent` が含まれますが、両方は含まれません。`CategoryEvents` には、`detail-type` の `TranscribeCallAnalyticsCategoryEvent` があります。
次の例は、Amazon Transcribe に使用する 1 回限りのメタデータ出力形式を示しています。
```
{
"time": "string", // ISO8601 format
"service-type": "CallAnalytics",
"detail-type": "CallAnalyticsMetadata",
"mediaInsightsPipelineId": "string",
"metadata": "string" // JSON encoded string of the metadata object
}
// metadata object
{
"voiceConnectorId": "string",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"direction": "string",
"oneTimeMetadata": "string" // JSON encoded string of oneTimeMetadata object
}
// onetimeMetadata object
{
"inviteHeaders": "string", // JSON encoded string of SIP Invite headers key-value pair
"siprecMetadata": "string", // siprec metadata in XML
"siprecMetadataJson": "string", // siprec metadata in JSON (converted from above XML)
// If PostcallSettings are enabled for Amazon Transcribe Call Analytics
"s3RecordingUrl": "string",
"s3RecordingUrlRedacted": "string"
}
// inviteHeaders object
{
"string": "string"
}
```
次の例は、Amazon Transcribe Call Analytics の出力形式を示しています。
```
{
"time": "string", // ISO8601 format
"service-type": "CallAnalytics",
"detail-type": "TranscribeCallAnalytics",
"mediaInsightsPipelineId": "string",
"metadata": {
"voiceConnectorId": "string",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"direction": "string"
},
"UtteranceEvent": {
"UtteranceId": "string",
"ParticipantRole": "string",
"IsPartial": boolean,
"BeginOffsetMillis": number,
"EndOffsetMillis": number,
"Transcript": "string",
"Sentiment": "string",
"Items": [{
"Content": "string",
"Confidence": number,
"VocabularyFilterMatch": boolean,
"Stable": boolean,
"ItemType": "string",
"BeginOffsetMillis": number,
"EndOffsetMillis": number,
}, ]
"Entities": [{
"Content": "string",
"Confidence": number,
"Category": "string", // Only PII is supported currently
"Type": "string",
"BeginOffset": number,
"EndOffset": number,
}, ],
"IssuesDetected": [{
"CharacterOffsets": {
"Begin": number,
"End": number
}
}]
},
"CategoryEvent": {
"MatchedCategories": ["string"],
"MatchedDetails": {
"string": {
"TimestampRanges": [{
"BeginOffsetMillis": number,
"EndOffsetMillis": number
}]
}
}
}
}
```
## Amazon Chime SDK Voice Connector ストリーミング更新メタデータ
コール分析設定が Amazon Chime SDK Voice Connector に関連付けられている場合、[Voice Connector のストリーミング更新](https://docs.aws.amazon.com/chime-sdk/latest/ag/automating-chime-with-cloudwatch-events.html)があると、次の Voice Connector Update ペイロードが送信されます。
次の例は、Amazon Transcribe プロセッサと Transcribe Call Analytics プロセッサの更新メタデータ形式を示しています。
```
{
"time": "string", // ISO8601 format
"service-type": "CallAnalytics",
"detail-type": "CallAnalyticsMetadata",
"callevent-type": "Update",
"metadata": "string" // JSON encoded string of the metadata object
}
// metadata object
{
"voiceConnectorId": "string",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"direction": "string",
"oneTimeMetadata": "string" // JSON encoded string of oneTimeMetadata object
}
// onetimeMetadata object
{
"sipHeaders": "string", // JSON encoded string of SIP Invite headers key-value pair
"siprecMetadata": "string", // siprec metadata in XML
"siprecMetadataJson": "string" // siprec metadata in JSON (converted from above XML)
}
// sipHeaders object
{
"string": "string"
}
```
次の例は、Call Analytics Amazon S3 Recording のメタデータ更新形式を示しています。
```
{
"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 の 2 人の間の 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 Call Analytics と組み合わせることはできません。Amazon Transcribe への入力と出力の詳細については、「*Amazon Transcribe Developer Guide*」の「[Transcribe streaming audio](https://docs.aws.amazon.com/transcribe/latest/dg/streaming.html)」を参照してください。
Amazon Transcribe による通話分析セッションでは、Kinesis Video Streams から音声データの入力を取得します。
+ 対応メディアエンコーディング: PCM 符号付き 16 ビットリトルエンディアン音声。
+ 対応 MediaSampleRate サンプリングレート: 8,000 Hz～48,000 Hz
Amazon Transcribe プロセッサの `StreamConfiguration` 入力:
+ ストリームごとに `KinesisVideoStreamArn` を指定する必要があります。
+ (オプション) KVS `FragmentNumber` により、指定したフラグメントの後のチャンクを使用して通話分析ジョブが開始されます。指定していない場合は、Kinesis Video Streams の利用可能な最新のチャンクが使用されます。
+ `StreamChannelDefinition` Amazon Transcribe は現在、2 つのチャネルの音声に対応しています。`NumberOfChannels` は、ランタイム `StreamChannelDefinition` で指定する必要があります。さらに、モノラル音声を 2 つの個別チャネルで送信する場合は、`ChannelId` を渡さなければなりません。トランスクリプトでは、チャネルに `ch_0` および `ch_1` というラベルが割り当てられます。次の例は、1 つのモノラル音声チャネルストリームに使用する KVS 入力を示しています。
```
"StreamChannelDefinition" : {"
NumberOfChannels" : 1
}
```
次の例は、2 つの異なるストリームの 2 つのモノラル音声入力に使用する KVS 入力を示しています。
```
KVS-1:
"StreamChannelDefinition" : {
"NumberOfChannels" : 1
"ChannelDefinitions": [
{
"ChannelId": 0
}
]
}
KVS-2:
"StreamChannelDefinition" : {
"NumberOfChannels" : 1
"ChannelDefinitions": [
{
"ChannelId": 1
}
]
}
```
**注記**
Amazon Transcribe プロセッサを使用して `MediaInsightsPipeline` を作成する Voice Connector の場合、Voice Connector アカウントレッグの音声は `channel-0` に、PSTN レッグの音声は `channel-1` に割り当てられます。
Voice Connector で SIPREC を使用する場合は、SIPREC メタデータによってそれらが決定されます。ほとんどの場合、辞書順に基づく値が最も小さいストリームラベルの音声が `channel-0` に割り当てられます。
Amazon Transcribe および Amazon Transcribe Call Analytics プロセッサでは、2 つの Kinesis Video Streams を渡し、各ストリームにモノラル音声チャネルが含まれている場合、両方のチャネルが 1 つの音声ストリームにインターリーブされた後に、Transcribe または Transcribe Call Analytics のデータが処理されます。
## Amazon Transcribe の出力
次の例は、Amazon Transcribe に使用する 1 回限りのメタデータ出力形式を示しています。
```
{
"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 Call Analytics プロセッサ、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) API を使用する必要があります。音声分析の使用方法の詳細については、「[Using Amazon Chime SDK voice analytics](https://docs.aws.amazon.com/chime-sdk/latest/dg/voice-analytics.html)」を参照してください。
## Kinesis Data Stream をシンクとして使用する
通話分析によって生成される Kinesis Data Stream (KDS) レコードには、メディアパイプライン ID、詳細タイプ、メタデータ、プロセッサ固有のセクションが含まれます。Kinesis Data Stream からのデータを利用する方法については、「*Amazon Kinesis Streams Developer guide*」の「[Reading Data from 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`
これは、セッションの開始時に 1 回だけ Kinesis Data Streams に発行され、`CallAnalyticsMetadata` の `detail-type` を持ちます。
[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` で一意の識別子を渡すことで、Kinesis Data Stream に配信する各レコードソースを一意に識別できます。
## Amazon S3 での通話録音
通話分析の録音では、KVS ストリームから音声を読み取り、録音を音声ファイルにし、そのファイルを指定した Amazon S3 バケットにアップロードします。録音後、ファイルの場所と共に通話メタデータも KDS に送信します。データウェアハウスを有効にすると、通話メタデータ (SIPREC を使用している場合は、SIPREC メタデータも含まれる) は、クエリ可能な Parquet テーブルのセットとしてデータウェアハウスに配信されます。
他の通話分析プロセッサと同様に、最初にパイプラインの設定を行う必要があります。この設定を行うには、Amazon Chime SDK コンソールまたは CLI を使用します。次に、CLI を使用してパイプラインを作成します。コンソールを使用して録音設定を行う方法については、このセクションで前述した「[Amazon Chime SDK の通話分析を設定する](creating-ca-configuration.md)」で詳しく確認できます。録音ワークフローの使用方法については、このセクションで前述した「[Amazon Chime SDK の通話を記録するためのワークフローについて](recording-workflows.md)」で詳しく確認できます。
**CLI を使用して設定を行うには**
次のコマンドを実行します。
```
aws chime-sdk-media-pipeline create-media-insights-pipeline-configuration --cli-input-json file://configuration.json
```
次の例は、記録のみ有効にする設定用 JSON ファイルを示しています。
```
{
"MediaInsightsPipelineConfigurationName": configuration_name,
"ResourceAccessRoleArn": role_arn,
"Elements": [
{
"KinesisDataStreamSinkConfiguration": {
"InsightsTarget": KDS_arn //Where recording live metadata will be delivered.
},
"Type": "KinesisDataStreamSink"
},
{
"S3RecordingSinkConfiguration": {
"Destination": "arn:aws:s3:::kvs-recording-testing",
"RecordingFileFormat": file_format // Specify "Opus" or "WAV" as the recording file format.
},
"Type": "S3RecordingSink"
}
]
}
```
次の点に注意してください。
+ Kinesis Video Streams による通話録音を有効にするには、PCM 符号付き 16 ビットリトルエンディアン音声を使用する必要があります。サンプルレートは 8 kHz でなければなりません。
+ Kinesis Video Streams のデータ保持期間を十分に長く設定してフラグメントを保持し、通話分析でそれらを利用できるようにする必要があります。
+ 通話録音を有効にする場合は、単独で使用する場合も、他のプロセッサと組み合わせて使用する場合も、録音用の Kinesis Video Streams ARN を 2 つ指定する必要があります。通話録音は 1 つのステレオ音声入力には対応していません。
## Amazon S3 に通話録音する場合のメタデータ出力
次の例は、Amazon S3 に録音する通話分析でのメタデータ出力形式を示しています。
```
{
"time": "string", // ISO8601 format
"service-type": "CallAnalytics",
"detail-type": "Recording",
"mediaInsightsPipelineId": "string",
"s3MediaObjectConsoleUrl": "string",
"recordingDurationSeconds": "number",
"metadata": "string" // JSON encoded string of the metadata object
}
// metadata object
{
"voiceConnectorId": "string",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"direction": "string",
"startTime": "string", // ISO8601 format
"endTime": "string", // ISO8601 format
"oneTimeMetadata": "string" // JSON encoded in string of oneTimeMetadata object
}
// onetimeMetadata object
{
"sipHeaders": "string", // JSON encoded string of SIP Invite headers key-value pair
"siprecMetadata": "string", // siprec metadata in XML
"siprecMetadataJson": "string" // siprec metadata in JSON (converted from above XML)
}
// sipHeaders object
{
"string": "string"
}
```
## 音声エンハンスメントを有効にする
音声強化を有効にするには、[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html) API コールに `VoiceEnhancementSinkConfiguration` 要素を含めます。
一般的な要素の例を次に示します。
```
{
"Type":"VoiceEnhancementSink",
"VoiceEnhancementSinkConfiguration": {
"Disabled": Boolean (string) // FALSE ==> Voice Enhancement will be performed
}
```
設定を更新するには、`VoiceEnhancementSinkConfiguration` 要素を [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineConfiguration.html) API コールに追加します。これを行うと、[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetMediaInsightsPipelineConfiguration.html) API には `VoiceEnhancementSinkConfiguration` 要素が結果に含まれます。
このリクエスト例は、音声エンハンスメントと Amazon S3 への録音を有効にする方法を示しています。
```
POST /media-insights-pipeline-configurations HTTP/1.1
Content-type: application/json
{
"MediaInsightsPipelineConfigurationName":"media_insights_configuration_name",
"ResourceAccessRoleArn":"arn:aws:iam::account_id:role/resource_access_role",
"Elements":[
{
"Type":"S3RecordingSink",
"S3RecordingSinkConfiguration":{
"Destination":"arn:aws:s3:::input_bucket_path",
"RecordingFileFormat":"Wav"
}
},
{
"Type":"VoiceEnhancementSink",
"VoiceEnhancementSinkConfiguration": {
"disabled":"false"
}
}
],
"ClientRequestToken":"client_request_token"
}
```
**注記**
`VoiceEnhancementSink` 要素を使用するには、通話分析の設定で `S3RecordingSink` 要素を常に設定する必要があります。
# Amazon Chime SDK の文字起こしの機能と録音シンクを組み合わせる
Amazon Transcribe と Amazon Transcribe Call Analytics のプロセッサを Amazon S3 録音シンクと連携させることができます。Amazon Transcribe プロセッサに加え S3RecordingSinkConfiguration を渡すには、[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 Transcribe または Amazon Transcribe Call Analytics のプロセッサを使用できますが、両方を使用することはできません。これと同じ設定には、文字起こしプロセッサの有無にかかわらず、録音シンクの他に音声分析を追加できます。
**注記**
前述のプロセッサのいずれでも、録音を有効にできます。ただし、Amazon Transcribe Call Analytics と Amazon S3 通話録音の両方を有効にする場合、2 つの Kinesis Video Streams を指定する必要があります。すると、録音ファイルが重複して配信されます。1 つは Amazon Transcribe Call Analytics から、もう 1 つは Amazon S3 通話録音からのファイルです。
次の点に注意してください。
+ 一意の `MediaInsightsPipelineConfigurationName` を使用する必要があります。
+ `ResourceAccessRoleArn` 詳細については、このガイドの「[Amazon Chime SDK で通話分析のリソースアクセスロールを使用する](call-analytics-resource-access-role.md)」を参照してください。
+ `Destination` 値には S3 パスの ARN を指定する必要があります。同じアカウントで所有している Amazon S3 バケットを指定する必要があります。
+ Transcribe と録音の指定がある設定を使用してパイプラインを作成する場合、一時停止と再開は Kinesis Data Stream で生成したインサイトにのみ表示されます。KVS ストリーム内のすべてのデータが記録され、Amazon S3 にアップロードされます。
+ 設定で、録音に加え、Amazon Transcribe または Transcribe Call Analytics (TCA) を指定すると、メディアインサイトパイプラインによって、文字起こしまたは Transcribe Call Analytics のインサイトがリアルタイムで生成されます。その後、通話が終了すると、Amazon S3 への録音が行われます。通話分析中に文字起こしサービスで障害が発生しても、S3 録音ジョブの実行は試行されます。Amazon S3 への録音は、文字起こし完了後に実行されるため、録音が失敗しても、文字起こしのインサイトは影響を受けません。
この例は、Amazon Transcribe プロセッサと Amazon S3 録音シンクを指定した設定を示しています。この例を使用すると、結果を部分的に安定化でき、出力のレイテンシーも抑えられますが、精度上の影響が出る可能性があります。詳細については、「*Amazon Transcribe Developer Guide*」の「[Partial-result stabilization](https://docs.aws.amazon.com/transcribe/latest/dg/streaming-partial-results.html#streaming-partial-result-stabilization)」を参照してください。
```
{
"MediaInsightsPipelineConfigurationName": unique_configuration_name,
"ResourceAccessRoleArn": role_arn,
"Elements": [{
"AmazonTranscribeProcessorConfiguration": {
"ContentIdentificationType": "string",
"ContentRedactionType": "string",
"EnablePartialResultsStabilization": boolean, //Enables partial result stabilization. Can reduce latency. May impact accuracy.
"FilterPartialResults": boolean, //To control partial utterance events
"LanguageCode": "string",
"LanguageModelName": "string",
"PartialResultsStability": "string",
"PiiEntityTypes": "string",
"ShowSpeakerLabel": boolean,
"VocabularyFilterMethod": "string",
"VocabularyFilterName": "string",
"VocabularyName": "string"
},
"Type": "AmazonTranscribeProcessor"
},
{
"KinesisDataStreamSinkConfiguration": {
"InsightsTarget": KDS_arn //Where recording and insights live metadata will be delivered.
},
"Type": "KinesisDataStreamSink"
},
{
"S3RecordingSinkConfiguration": {
"Destination": S3_Arn,
"RecordingFileFormat": file_format // Specify "Opus" or "WAV" as the recording file format.
},
"Type": "S3RecordingSink"
}
]
}
```
# Amazon Chime SDK で Amazon EventBridge の通知を使用する
Amazon Chime SDK Call Analytics では、メディアインサイトパイプラインの状態が変化した場合や、通話分析のリアルタイムアラート条件が満たされた場合に、デフォルトの EventBridge バスにイベントを送信できます。メディアインサイトパイプラインのエラーステータスの更新では、リソースでの障害が非同期に発生した場合に通知を受けられるよう、EventBridge のターゲットを設定することをお勧めします。通話分析の通知には、aws.chime ソースに加え、さまざまな詳細タイプがあります。この点については、次のセクションで説明します。詳細については、[Amazon EventBridge ユーザーガイド](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html)を参照してください。
**Topics**
+ [ステータスの更新](#status-updates)
+ [リアルタイムアラート](#realtime-alerts)
## ステータスの更新
メディアインサイトパイプラインでは、通話分析セッションが進み正常終了するか、エラーが発生すると、EventBridge 通知が送信されます。次の場合、「Media Insights State Change」という詳細タイプの 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`
メディアインサイトパイプライン内に要素が 1 つしかない場合は、次のイベントタイプが示されることがあります。詳細については、各セクションを展開してください。
### Amazon Chime SDK メディアインサイトは稼働している
次の例は、一般的なイベント構造を示しています。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": []
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsInProgress",
"version": "0",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string"
}
}
```
### Amazon Chime SDK メディアインサイトは一時停止している
次の例は、一般的なイベント構造を示しています。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": []
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsPaused",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string"
}
}
```
### Amazon Chime SDK メディアインサイトは停止している
次の例は、一般的なイベント構造を示しています。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": []
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsStopped",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string"
}
}
```
### Amazon Chime SDK メディアインサイトに一時的な障害が発生している
サービスに一時的な障害が発生し、再試行されることを示しています。ユーザーのアクションは必要ありません。
次の例は、一般的なイベント構造を示しています。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": []
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsTemporaryFailure",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string"
}
}
```
### Amazon Chime SDK メディアインサイトに永続的な障害が発生している
ユーザーのアクションが必要な障害を示しています。`failureReason` に基づいて、トラブルシューティングを行います。一般的な障害として、次の状況が挙げられます。
+ リソースアクセスロールの権限が不足している
+ リソースが見つからないか、削除されている
+ 分析を呼び出す AWS サービスからのスロットリングは、Amazon Transcribe や Amazon Kinesis など、ユーザーに代わって を呼び出します。
+ KVS ストリームのメディア形式に互換性がない
次の例は、一般的なイベント構造を示しています。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": []
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsPermanentFailure",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string",
"failureReason": "string"
}
}
```
**注記**
`failureReason` フィールドはオプションです。一般的な理由として `Access denied when assuming resource access role` が示されることがあります。
Amazon Chime SDK Voice Connector で開始した通話分析セッションでは、メディアインサイトパイプラインが作成されるか、作成の試行が失敗すると、次のイベントタイプが示される場合があります。詳細については、各セクションを展開してください。
### Amazon Chime SDK メディアインサイトが作成された
この例は、一般的な正常終了イベントを示しています。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": []
"detail":
{
"version": "0",
"mediaInsightsPipelineConfigurationArn": "string",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsCreated",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string",
}
}
```
### Amazon Chime SDK メディアインサイトの作成に失敗した
この例は、一般的な障害イベントを示しています。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": []
"detail":
{
"version": "0",
"mediaInsightsPipelineConfigurationArn": "string",
"eventType": "chime:MediaInsightsCreateFailed",
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string",
"failureOrigin": "Voice Connector",
"httpStatusCode": "string",
"failureReason": "string"
}
}
```
メディアインサイトパイプライン内に複数の要素がある場合は、次のイベントタイプが示されることがあります。この例は、`AmazonTranscribeProcessor` と `S3RecordingSink` を連携させた場合の通知を示しています。詳細については、各セクションを展開してください。
### AmazonTranscribeProcessor は稼働中だが、S3RecordingSink は起動していない
次の例は、一般的なイベント構造を示しています。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": [],
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsInProgress",
"mediaInsightsPipelineElementStatuses": [
{
"type": "AmazonTranscribeProcessor",
"status": "InProgress",
"updatedOn": 1686184070655
},
{
"type": "S3RecordingSink",
"status": "NotStarted",
"updatedOn": 1686184070655
}
]
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string"
}
}
```
### AmazonTranscribeProcessor が正常終了し、S3RecordingSink が稼働している
次の例は、一般的なイベント構造を示しています。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": [],
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsInProgress",
"mediaInsightsPipelineElementStatuses": [
{
"type": "AmazonTranscribeProcessor",
"status": "Stopped",
"updatedOn": 1686184070655
},
{
"type": "S3RecordingSink",
"status": "InProgress",
"updatedOn": 1686184070655
}
]
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string"
}
}
```
### AmazonTranscribeProcessor は正常稼働できなかったが、S3RecordingSink は稼働している
次の例は、一般的なイベント構造を示しています。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": [],
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsInProgress",
"mediaInsightsPipelineElementStatuses": [
{
"type": "AmazonTranscribeProcessor",
"status": "Failed",
"updatedOn": 1686184070655
},
{
"type": "S3RecordingSink",
"status": "InProgress",
"updatedOn": 1686184070655
}
]
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string"
}
}
```
### AmazonTranscribeProcessor は正常稼働できなかったが、S3RecordingSink は正常終了した
次の例は、一般的なイベント構造を示しています。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": [],
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsPermanentFailure",
"mediaInsightsPipelineElementStatuses": [
{
"type": "AmazonTranscribeProcessor",
"status": "Failed",
"updatedOn": 1686184070655
},
{
"type": "S3RecordingSink",
"status": "Stopped",
"updatedOn": 1686184070655
}
]
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string",
"failureReason": "string"
}
}
```
### AmazonTranscribeProcessor は正常終了したが、S3RecordingSink は処理に失敗した
次の例は、一般的なイベント構造を示しています。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": [],
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsPermanentFailure",
"mediaInsightsPipelineElementStatuses": [
{
"type": "AmazonTranscribeProcessor",
"status": "Stopped",
"updatedOn": 1686184070655
},
{
"type": "S3RecordingSink",
"status": "Failed",
"updatedOn": 1686184070655
}
]
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string",
"failureReason": "string"
}
}
```
### AmazonTranscribeProcessor が一時停止しており、S3RecordingSink が起動していない
次の例は、一般的なイベント構造を示しています。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": [],
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsPaused",
"mediaInsightsPipelineElementStatuses": [
{
"type": "AmazonTranscribeProcessor",
"status": "Paused",
"updatedOn": 1686184070655
},
{
"type": "S3RecordingSink",
"status": "NotStarted",
"updatedOn": 1686184070655
}
]
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string"
}
}
```
### AmazonTranscribeProcessor に一時的な障害が発生しており、S3RecordingSink が起動していない
次の例は、一般的なイベント構造を示しています。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": [],
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsTemporaryFailure",
"mediaInsightsPipelineElementStatuses": [
{
"type": "AmazonTranscribeProcessor",
"status": "TemporarilyFailed",
"updatedOn": 1686184070655
},
{
"type": "S3RecordingSink",
"status": "NotStarted",
"updatedOn": 1686184070655
}
]
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string"
}
}
```
### AmazonTranscribeProcessor と S3RecordingSink が正常終了した
次の例は、一般的なイベント構造を示しています。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"region": "string",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": [],
"detail": {
"version": "0",
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsStopped",
"mediaInsightsPipelineElementStatuses": [
{
"type": "AmazonTranscribeProcessor",
"status": "Stopped",
"updatedOn": 1686184070655
},
{
"type": "S3RecordingSink",
"status": "Stopped",
"updatedOn": 1686184070655
}
]
"callId": "string",
"transactionId": "string",
"fromNumber": "string",
"toNumber": "string",
"voiceConnectorId": "string",
"direction": "string"
}
}
```
### S3RecordingSink が正常終了し、VoiceEnhancement が稼働している
次の例は、一般的なイベント構造を示しています。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights State Change",
"source": "aws.chime",
"account": number,
"time": "yyyy-mm-ddThh:mm:ssZ",
"region": "string",
"detail": {
"mediaInsightsPipelineArn": "string",
"eventType": "chime:MediaInsightsInProgress",
"version": "0",
"mediaInsightsPipelineElementStatuses": [
{
"type": "VoiceEnhancementSink",
"status": "InProgress",
"updatedOn": 1686184070655
},
{
"type": "S3RecordingSink",
"status": "Stopped",
"updatedOn": 1686184070655
}
]
}
}
```
### S3RecordingSink は正常終了したが、通話が 30 分を超えたため 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
}
]
}
}
```
### S3RecordingSink は正常終了したが、通話が 30 分未満だったため 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 Call Analytics のプロセッサのみがリアルタイムアラートに対応しています。
Amazon Chime SDK 通話分析では、分析セッション中にプロセッサを介して、リアルタイムアラートの送信ルールを設定できます。これにより、`Media Insights Rules Matched` の詳細タイプを示すアラートが Amazon EventBridge に送信されます。EventBridge は、Lambda、Amazon SQS、Amazon SNS などのダウンストリームサービスにも対応しているため、エンドユーザーへの通知をトリガーしたり、他のカスタムビジネスロジックを開始したりできます。
リアルタイムアラートは、`MediaInsightsPipelineConfiguration` の `RealTimeAlertConfiguration` フィールドの一部として設定します。Amazon Chime SDK コンソールを使用してフィールドを設定するか、[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaInsightsPipelineConfiguration.html) または [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaInsightsPipelineConfiguration.html) API を呼び出すことができます。
次の例は、API を使用して、リアルタイムアラートを設定または更新する方法を示しています。
```
{
"MediaInsightsPipelineConfigurationName": "config_name",
"ResourceAccessRoleArn": "arn:aws:iam::account_id:role/role_name",
"RealTimeAlertConfiguration": {
"Disabled": false,
"Rules": [{
"Type": "KeywordMatch",
"KeywordMatchConfiguration": {
"RuleName": "rule_name_1",
"Keywords": [
"hello",
"thank you"
],
"Negate": false
}
},
{
"Type": "Sentiment",
"RuleName": "rule_name_2",
"SentimentType": "NEGATIVE",
"TimePeriod": 60
},
{
"Type": "IssueDetection",
"RuleName": "rule_name_3"
}
]
},
"Elements": [{
"Type": "AmazonTranscribeCallAnalyticsProcessor",
"AmazonTranscribeCallAnalyticsProcessorConfiguration": {
"LanguageCode": "en-US"
}
},
{
"Type": "KinesisDataStreamSink",
"KinesisDataStreamSinkConfiguration": {
"InsightsTarget": "arn:aws:kinesis:us-east-1:account_id:stream/stream_name"
}
}
]
}
```
リアルタイムアラート設定の各ルールは、個別にトリガーされます。複数のルール条件が同時に満たされると、複数の EventBridge 通知が届く場合があります。アラートルールリストの作成では、次のルールタイプを選択できます。
キーワードの一致
指定したキーワードまたはフレーズのセットが発話イベントまたは文字起こしイベントで一致したときにアラートが送信されます。次の場合にイベントが発行されるよう、アラートを設定できます。
+ `Negate` を `false` に設定しており、指定したキーワードが発話された。
+ `Negate` を `true` に設定しており、指定したいずれのキーワードも通話中に発話されなかった。
Amazon Transcribe と Amazon Transcribe Analytics は、このルールタイプに対応しています。
センチメント分析
特定のセンチメントタイプが、ローリングウィンドウの期間継続した場合にアラートが発行されます。Transcribe Call Analytics のみ、このルールに対応しています。
問題検出
発話イベントで、特定の問題が検出されるとアラートが発行されます。Transcribe Call Analytics のみ、このルールタイプに対応しています。
次の例は、`KeywordMatch` ルールのリアルタイムアラートイベントを示しています。
```
{
"version": "0",
"id": "string",
"detail-type": "Media Insights Rules Matched",
"source": "aws.chime",
"account": number,
"region": "us-east-1",
"time": "yyyy-mm-ddThh:mm:ssZ",
"resources": [],
"detail": {
"version": "0",
"sourceMetadata": {}
"ruleName": "string"
"utteranceId": "string",
"beginTimestamp": "yyyy-mm-ddThh:mm:ssZ",
}
}
```
EventBridge フィールドの中には、次のように、一致するルールタイプに固有のフィールドもあります。
**キーワード一致のフィールド**
`utteranceId`: 一致するキーワードが含まれる文字起こし文の ID (Amazon Transcribe Call Analytics を使用する場合)。発話されたキーワードの一致のみが対象。
`resultId`: 一致するキーワードが含まれる文字起こし文の ID (Amazon Transcribe を使用する場合)。発話されたキーワードの一致のみが対象。
`beginTimestamp`: 一致したキーワードが含まれる文字起こし文の開始時間。発話されたキーワードの一致のみが対象。
**センチメント分析のフィールド**
`beginTimestamp`: 一致したセンチメントのローリングウィンドウが開始した時間。
`endTimestamp`: 一致したセンチメントのローリングウィンドウが終了した時間。
# Amazon Chime SDK データレイクを作成する
Amazon Chime SDK 通話分析データレイクを使用すると、機械学習を活用したインサイトやメタデータを Amazon Kinesis Data Streams から Amazon S3 バケットにストリーミングできます。例えば、データレイクを使用して、記録用の URL にアクセスすることが可能です。データレイクを作成するには、Amazon Chime SDK コンソールから、または を使用してプログラムで AWS CloudFormation テンプレートのセットをデプロイします AWS CLI。データレイクを使用すると、Amazon Athena の AWS Glue データテーブルを参照することで、通話メタデータと音声分析データをクエリできます。
**Topics**
+ [前提条件](#data-lake-prereqs)
+ [データレイクの用語と概念](#data-lake-terms)
+ [複数のデータレイクを作成する](#creating-multiple-data-lakes)
+ [リージョン別に見たデータレイクの可用性](#data-lake-regions)
+ [データレイクのアーキテクチャ](#data-lake-architecture)
+ [データレイクをセットアップする](#data-lake-setup)
## 前提条件
Amazon Chime SDK データレイクを作成するには、次の機能が必要です。
+ 1 つの Amazon Kinesis Data Streams。詳細については、「*Amazon Kinesis Streams Developer Guide*」の「[Creating a Stream via the AWS Management Console](https://docs.aws.amazon.com/streams/latest/dev/how-do-i-create-a-stream.html)」を参照してください。
+ S3 バケット 詳細については、「Amazon S3 ユーザーガイド」の「[最初の 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 Data Catalog**
Amazon Athena のテーブルとデータベースには、基礎となるソースデータのスキーマを詳細に示すメタデータが格納されています。また、Athena では、データセットごとにテーブルが存在する必要があります。このテーブル内のメタデータによって Amazon S3 バケットの場所が判断されます。また、列名、データ型、テーブル名などのデータ構造も指定されます。データベースで保持されるのは、データセットのメタデータとスキーマ情報のみです。
## 複数のデータレイクを作成する
一意の Glue データベース名を指定して通話のインサイトを保存する場所を指定することで、複数のデータレイクを作成できます。特定の AWS アカウントでは、複数の通話分析設定があり、それぞれに対応するデータレイクがあります。つまり、特定のユースケースにデータ分離を適用することが可能です。例えば、保持ポリシーや、データの保存方法に関するアクセスポリシーなどをカスタマイズできます。インサイト、録音データ、メタデータへのアクセスに、さまざまなセキュリティポリシーを適用することも可能です。
## リージョン別に見たデータレイクの可用性
Amazon Chime SDK データレイクは、次のリージョンで利用できます。
| リージョン | Glue テーブル | Quick |
| --- | --- | --- |
| us–east–1 | 利用可能 | 使用可能 |
| us-west-2 | 利用可能 | 使用可能 |
| eu-central-1 | 利用可能 | 使用可能 |
## データレイクのアーキテクチャ
データレイクのアーキテクチャを次の図に示します。図の数字は、次の各説明の番号に対応しています。
![\[データレイクを使用するプログラムフローの図。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/call-analytics-data-lake-architecture.png)
この図では、 AWS コンソールを使用してメディアインサイトパイプライン設定ワークフローから CloudFormation テンプレートをデプロイすると、次のデータが Amazon S3 バケットに流れます。
1. Amazon Chime SDK 通話分析によって、顧客の Kinesis Data Stream に対しリアルタイムデータのストリーミングが開始されます。
1. Amazon Kinesis Firehose では、128 MB まで蓄積される、または 60 秒が経過するまで (どちらか早い方が適用される)、このリアルタイムデータをバッファリングします。次の Firehose では、Glue データカタログの `amazon_chime_sdk_call_analytics_firehose_schema` を使用して、データを圧縮し、JSON レコードを Parquet 形式のファイルに変換します。
1. Parquet ファイルは、パーティション形式で Amazon S3 バケットに格納されます。
1. リアルタイムデータの他に、Amazon Transcribe Call Analytics の通話後概要データ .wav ファイル (設定で指定している場合、編集済みと未編集のファイル) と、通話録音の .wav ファイルも Amazon S3 バケットに送信されます。
1. Amazon Athena と標準 SQL を使用して、Amazon S3 バケット内のデータをクエリすることができます。
1. CloudFormation テンプレートでは、Glue データカタログも作成して、この通話後概要データを Athena 経由でクエリすることができます。
1. Amazon S3 バケット上のすべてのデータは、Quick を使用して視覚化することもできます。QuickSight では、Amazon Athena を使用して Amazon 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 からパーケットへのデータ変換が有効になっています。
**パーティション射影**
Athena のこの機能では、パーティションを日ごとに自動作成することで、日付ベースのクエリのパフォーマンスを向上させます。
## データレイクをセットアップする
Amazon Chime SDK コンソールを使用して、次の手順を完了します。
1. Amazon Chime SDK コンソール ([https://console.aws.amazon.com/chime-sdk/home](https://console.aws.amazon.com/chime-sdk/home)) を起動し、ナビゲーションペインの **[通話分析]** で **[設定]** を選択します。
1. [ステップ 1] を完了して **[次へ]** を選択し、[ステップ 2] ページの **[音声分析]** チェックボックスを選択します。
1. **[出力の詳細]** で **[履歴による分析を行うためのデータウェアハウス]** チェックボックスを選択し、**[CloudFormation スタックをデプロイ]** リンクを選択します。
CloudFormation コンソールの **[スタックのクイック作成]** ページに画面が切り替わります。
1. スタックの名前を入力し、次のパラメータを入力します。
1. `DataLakeType` — **[通話分析のデータレイクを作成]** を選択します。
1. `KinesisDataStreamName` — 対象のストリームを選択します。通話分析ストリーミングに使用するストリームを指定する必要があります。
1. `S3BucketURI` — Amazon S3 バケットを選択します。URI にはプレフィックス `s3://bucket-name` が必要です。
1. `GlueDatabaseName` — 一意の AWS Glue データベース名を選択します。 AWS アカウント内の既存のデータベースは再利用できません。
1. 確認のチェックボックスを選択し、**[データレイクを作成]** を選択します。データレイクの作成には、10 分かかります。
### を使用したデータレイクのセットアップ AWS CLI
を使用して AWS CLI 、CloudFormation の create スタックを呼び出すアクセス許可を持つロールを作成します。次の手順に従って IAM ロールを作成しセットアップします。詳細については、「AWS CloudFormation ユーザーガイド」の「[スタックの作成](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-cli-creating-stack.html)」を参照してください。
1. *AmazonChimeSdkCallAnalytics-Datalake-Provisioning-Role* ロールを作成して信頼ポリシーをそれにアタッチし、CloudFormation にそのロールを持たせることを許可します。
1. 次のテンプレートを使用して IAM 信頼ポリシーを作成し、そのファイルを .json 形式で保存します。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "cloudformation.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {}
}
]
}
```
------
1. **aws iam create-role** コマンドを実行し、信頼ポリシーをパラメータとして渡します。
```
aws iam create-role \
--role-name AmazonChimeSdkCallAnalytics-Datalake-Provisioning-Role
--assume-role-policy-document file://role-trust-policy.json
```
1. レスポンスで返ったロール ARN を書き留めておきます。ロール ARN は次の手順で必要になります。
1. CloudFormation スタックの作成権限を持つポリシーを作成します。
1. 次のテンプレートを使用して IAM ポリシーを作成し、そのファイルを .json 形式で保存します。create-policy を呼び出すときに、このファイルが必要となります。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "DeployCloudFormationStack",
"Effect": "Allow",
"Action": [
"cloudformation:CreateStack"
],
"Resource": "*"
}
]
}
```
------
1. **aws iam create-policy** を実行し、スタック作成のポリシーをパラメータとして渡します。
```
aws iam create-policy --policy-name testCreateStackPolicy
--policy-document file://create-cloudformation-stack-policy.json
```
1. レスポンスで返ったロール ARN を書き留めておきます。ロール ARN は次の手順で必要になります。
1. **aws iam attach-role-policy** ポリシーをロールにアタッチします。
```
aws iam attach-role-policy --role-name {Role name created above}
--policy-arn {Policy ARN created above}
```
1. CloudFormation スタックを作成し、次に示す必要なパラメータを入力します: **aws cloudformation create-stack**。
ParameterValue を使用して、各 ParameterKey のパラメータ値を指定します。
```
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/ja_jp/chime-sdk/latest/dg/ca-data-lake.html)
# Amazon Chime SDK のクイックダッシュボードの設定
データレイクを設定したら、データを視覚化する事前定義されたメトリクスを使用してクイックダッシュボードを設定できます。利用可能なダッシュボードを次に示します。
+ **Transcribe Call Analytics と音声分析**。このメトリクスを使用すると、スピーカーごとのトランスクリプト、検出された問題、結果、エンティティ検出、音声プロファイル ID の一致について、大まかな視覚化と詳細な視覚化を行えます。
+ **Transcribe と音声分析**。このメトリクスを使用すると、スピーカーごとのトランスクリプト、語彙の一致、ボイストーン、音声プロファイル ID の一致について、大まかな視覚化と詳細な視覚化を行えます。
以下のトピックでは、クイックアカウントをまだ持っていない場合は設定する方法と、ダッシュボードを設定する方法について説明します。
**Topics**
+ [QuickSight アカウントを作成する](#create-quicksight-account)
+ [QuickSight アカウントを設定する](#configure-qs-acct)
+ [QuickSight ダッシュボードを作成する](#create-qs-dashboard)
## QuickSight アカウントを作成する
このセクションのステップでは、クイックアカウントを作成する方法について説明します。アカウントがある場合は、この手順をスキップして [QuickSight ダッシュボードを作成する](#create-qs-dashboard) に進んでください。
QuickSight アカウントの作成では、次の機能を使用できます。
+ Amazon CloudFormation テンプレート。
+ Amazon Chime SDK コンソール。
### 前提条件
アカウントの作成前に、次の情報を収集します。
+ 通話分析に使用する Amazon S3 バケットの名前。
+ 通知用のメールアドレス。QuickSight 通知は、このアドレスに配信されます。
### CloudFormation テンプレートを使用してアカウントを作成する
次の手順では、Amazon CloudFormation テンプレートをデプロイしてクイックアカウントを作成する方法について説明します。このプロセスでは、Enterprise アカウントのみ、サブスクライブします。料金の詳細については、[「クイック料金](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** で、Create **new AWS QuickSight アカウント**を選択します。
1. **[S3BucketName]** に Amazon S3 バケットの名前を入力します。
1. **[AWS CloudFormation によって IAM リソースが作成される場合があることを承認します]** チェックボックスを選択します。
1. **[スタックの作成]** を選択してください。
スタックの作成には約 10 分かかります。
1. ビルドが完了したら、**「クイックに移動**」を選択し、E メールアドレスを入力してアカウントにサインインします。
### コンソールを使用してアカウントを作成する
次の手順では、Amazon Chime SDK コンソールを使用してクイックアカウントを作成する方法について説明します。ここでは、エンタープライズ版またはエンタープライズ版 \$1 Q のアカウントを使用する必要があります。
**コンソールを使用するには**
1. [https://console.aws.amazon.com/chime-sdk/home](https://console.aws.amazon.com/chime-sdk/home) で Amazon Chime SDK コンソールを起動して「**QuickSight**」を検索し、検索結果で **[QuickSight]** を選択します。
![\[Quick にリンクする検索結果。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/quicksightsetup-1.png)
1. [**Sign up for QuickSight (QuickSight にサインアップする)**] を選択します。
1. **[エンタープライズ版]** または **[エンタープライズ版 \$1 Q]** を選択し、**[次へ]** を選択します。
1. 氏名、電話番号、先ほど収集したメールアドレスを入力して、**[次へ]** を選択します。
1. 以下の操作を実行します。
1. **[認証方法]** で、オプションを選択します。
**注記**
フェデレーションユーザーを使用するオプションの選択には、適切な IAM アクセス許可が必要です。詳細については、「 [クイックユーザーガイド」の「クイックサブスクリプションにサインアップ](https://docs.aws.amazon.com/quicksight/latest/user/signing-up.html)する」を参照してください。 **
1. **[QuickSight リージョン]** で、リージョンを選択します。
1. **[アカウント情報]** に、アカウントの名前と、先ほど収集したメールアドレスを入力します。
1. **[QuickSight の AWS のサービスへのアクセス]** で、デフォルトのロールを使用するか、**[既存のロールを使用]** を選択してリストからロールを選択します。
1. (オプション) 必要に応じて、**[これらのリソースへのアクセスと自動検出を許可]** で、追加のリソースを選択します。
1. 完了したら、**[完了]** を選択します。
1. ビルドが完了したら、Go **to Quick **を選択し、E メールアドレスを入力してアカウントにサインインします。
## QuickSight アカウントを設定する
QuickSight アカウントにログインしたら、セキュリティを設定して、セットアッププロセスで作成したグループに自分を追加する必要があります。
**セキュリティを設定するには**
1. 右上にあるプロファイルアイコンを選択し、表示されたメニューから **[QuickSight の管理]** を選択します。
![\[[QuickSight の管理] コマンドのあるメニューを示す画像。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/quicksightsetup-1-a.png)
1. ナビゲーションペインで、**[セキュリティとアクセス権限]** を選択します。
1. ** AWS サービスへの QuickSight アクセス**で、**管理**を選択し、次のサービスが選択されていることを確認します。
+ Amazon Redshift
+ Amazon RDS
+ Amazon S3
+ Amazon Athena
+ IAM
1. **[Amazon S3 バケットを選択]** リンクを選択します。
1. Amazon S3 バケットの横にあるチェックボックスを選択し、**[Athena Workgroup の書き込みアクセス許可]** 列の右側にあるチェックボックスを選択します。
1. [**Finish**] を選択してください。
1. **[保存]** を選択します。
**自分をグループに追加するには**
1. ナビゲーションペインで、**[グループの管理]** を選択し、名前に **[管理者]** が含まれるグループを選択します。例: *S3BucketName*–**[管理者]**。
1. **[ユーザーの追加]** を選択し、表示されているボックスにメールエイリアスを入力します。
自分の名前が次のように表示されます: **[管理者 – ]** 自分のエイリアス。
1. **[Add]** (追加) を選択します。
## QuickSight ダッシュボードを作成する
データレイクを作成したら、QuickSight ダッシュボードを作成して、データを視覚化できます。ダッシュボードの作成には、Amazon CloudFormation テンプレートまたは Amazon Chime SDK コンソールを使用できます。次の手順は、その 2 つの方法を示しています。
**テンプレートを使用するには**
1. Amazon CloudFormation コンソールを起動します。
1. 次のリンクをブラウザのアドレスバーに貼り付けます。`https://region.console.aws.amazon.com/cloudformation/home?region=region#/stacks/quickcreate?templateURL=https://chime-sdk-assets.s3.amazonaws.com/public_templates/AmazonChimeSDKQuickSightDashboards.yaml`
1. **[スタックのクイック作成]** ページの **[スタック名]** に、アカウントの名前を入力します。
1. **[ActiveQuickSightAccount]** で **[True]** を選択します。
1. **[QuicksightDashboardSelection]** で、**[通話分析 — Transcribe Call Analytics および音声分析ダッシュボード]** または **[通話分析 — Transcribe および音声分析ダッシュボード]** を選択します。
1. **[Amazon S3BucketName]** に、Amazon S3 バケットの URI を入力します。
1. **[GlueDatabaseName]** に、QuickSight ダッシュボードをデプロイする Glue データベースを入力します。
1. **[AWS CloudFormation によって IAM リソースが作成される場合があることを承認します]** チェックボックスを選択した後に、**[スタックの作成]** を選択します。
**QuickSight ダッシュボードを手動で設定するには**
1. 自分の QuickSight アカウントに移動します。
1. 右上にあるプロファイルアイコンを選択し、**[QuickSight の管理]** を選択します。
![\[QuickSight アカウントダイアログボックスと [QuickSight の管理] コマンドを示す画像。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/quicksightsetup-1-a.png)
1. ナビゲーションペインで **[グループの管理]** を選択し、セットアッププロセスで作成したグループを選択します。
1. **[ユーザーの追加]** を選択してメールアドレスを入力し、**[追加]** を選択します。
ページのデプロイには 10 分かかります。
1. Amazon Chime SDK コンソールから QuickSight アカウントにログインし、ダッシュボードを利用します。
# Amazon Chime SDK の通話分析のデータモデル
このセクションの情報は、 Glue データカタログ内のテーブルのセットである Amazon Chime SDK AWS コール分析データモデルを一覧表示して説明します。
**Topics**
+ [Amazon Chime SDK AWS Glue のデータカタログテーブル構造を理解する](ca-data-model-diagram.md)
+ [Amazon Chime SDK AWS Glue のデータカタログテーブルについて](glue-tables.md)
+ [Amazon Chime SDK コール分析用の AWS Glue データカタログ内のデータの抽出](ca-data-model-queries.md)
# Amazon Chime SDK AWS Glue のデータカタログテーブル構造を理解する
次の図は、Amazon Chime SDK AWS 通話分析および音声分析セッション用に作成された Glue データカタログのテーブル構造を示しています。
![\[通話分析の Glue データカタログのテーブル。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/glue-cat-diag-12-03.jpg)
次のセクションでは、カタログ内のテーブルとフィールドの一覧を示し、それぞれについて説明します。
# Amazon Chime SDK AWS Glue のデータカタログテーブルについて
次の表には、Amazon Chime SDK 通話分析の Glue データカタログの列、データ型、要素の一覧と説明が記載されています。
**Topics**
+ [call\$1analytics\$1metadata](#ca-glue-metadata)
+ [call\$1analytics\$1recording\$1metadata](#ca-glue-analytics-recording)
+ [transcribe\$1call\$1analytics](#ca-glue-transcribe-ca)
+ [transcribe\$1call\$1analytics\$1category\$1events](#ca-glue-transcribe-ca-events)
+ [transcribe\$1call\$1analytics\$1post\$1call](#ca-glue-transcribe)
+ [transcribe](#ca-glue-transcribe)
+ [voice\$1analytics\$1status](#ca-glue-va-status)
+ [speaker\$1search\$1status](#ca-glue-speaker-status)
+ [voice\$1tone\$1analysis\$1status](#ca-glue-tone-status)
## call\$1analytics\$1metadata
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/glue-tables.html)
## call\$1analytics\$1recording\$1metadata
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/glue-tables.html)
## transcribe\$1call\$1analytics
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/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/ja_jp/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/ja_jp/chime-sdk/latest/dg/glue-tables.html)
## transcribe
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/glue-tables.html)
## voice\$1analytics\$1status
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/glue-tables.html)
## speaker\$1search\$1status
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/glue-tables.html)
## voice\$1tone\$1analysis\$1status
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/glue-tables.html)
# Amazon Chime SDK コール分析用の AWS Glue データカタログ内のデータの抽出
これらのサンプルクエリを使用して、Amazon Chime SDK 通話分析の Glue データカタログのデータを抽出して整理します。
**注記**
Amazon Athena に接続し、Glue データカタログをクエリする方法については、「[ODBC を使用した Amazon Athena への接続](https://docs.aws.amazon.com/athena/latest/ug/connect-with-odbc.html)」を参照してください。
必要に応じて各セクションを展開してください。
## call\$1analytics\$1metadata テーブル内のメタデータ (STRING データ型) から値を抽出する
`call_analytics_metadata` には JSON 文字列形式の `metadata` フィールドがあります。Athena の [json\$1extract\$1scalar 関数](https://docs.aws.amazon.com/athena/latest/ug/extracting-data-from-JSON.html)を使用して、この文字列の要素をクエリします。
```
SELECT
json_extract_scalar(metadata,'$.voiceConnectorId') AS "VoiceConnector ID",
json_extract_scalar(metadata,'$.fromNumber') AS "From Number",
json_extract_scalar(metadata,'$.toNumber') AS "To Number",
json_extract_scalar(metadata,'$.callId') AS "Call ID",
json_extract_scalar(metadata,'$.direction') AS Direction,
json_extract_scalar(metadata,'$.transactionId') AS "Transaction ID"
FROM
"GlueDatabaseName"."call_analytics_metadata"
```
## call\$1analytics\$1metadata テーブル内の SIPRECMetadata の更新のクエリ
`call_analytics_metadata` フィールドには JSON 文字列形式のメタデータフィールドがあります。`metadata` には `oneTimeMetadata` というネストされた別のオブジェクトがあります。このオブジェクトには、元の XML 形式と変換された JSON 形式の SIPRec メタデータが含まれています。Athena の `json_extract_scalar` 関数を使用して、この文字列の要素をクエリします。
```
SELECT
json_extract_scalar(metadata,'$.voiceConnectorId') AS "VoiceConnector ID",
json_extract_scalar(metadata,'$.fromNumber') AS "From Number",
json_extract_scalar(metadata,'$.toNumber') AS "To Number",
json_extract_scalar(metadata,'$.callId') AS "Call ID",
json_extract_scalar(metadata,'$.direction') AS Direction,
json_extract_scalar(metadata,'$.transactionId') AS "Transaction ID",
json_extract_scalar(json_extract_scalar(metadata,'$.oneTimeMetadata'),'$.siprecMetadata') AS "siprec Metadata XML",
json_extract_scalar(json_extract_scalar(metadata,'$.oneTimeMetadata'),'$.siprecMetadataJson') AS "Siprec Metadata JSON",
json_extract_scalar(json_extract_scalar(metadata,'$.oneTimeMetadata'),'$.inviteHeaders') AS "Invite Headers"
FROM
"GlueDatabaseName"."call_analytics_metadata"
WHERE
callevent-type = "update";
```
## call\$1analytics\$1recording\$1metadata テーブル内のメタデータ (STRING データ型) から値を抽出する
`call_analytics_recording_metadata` には JSON 文字列形式のメタデータフィールドがあります。Athena の [json\$1extract\$1scalar 関数](https://docs.aws.amazon.com/athena/latest/ug/extracting-data-from-JSON.html)を使用して、この文字列の要素をクエリします。
```
SELECT
json_extract_scalar(metadata,'$.voiceConnectorId') AS "VoiceConnector ID",
json_extract_scalar(metadata,'$.fromNumber') AS "From Number",
json_extract_scalar(metadata,'$.toNumber') AS "To Number",
json_extract_scalar(metadata,'$.callId') AS "Call ID",
json_extract_scalar(metadata,'$.direction') AS Direction,
json_extract_scalar(metadata,'$.transactionId') AS "Transaction ID"
FROM
"GlueDatabaseName"."call_analytics_recording_metadata"
WHERE
detail-subtype = "Recording"
```
## voice\$1analytics\$1status テーブル内の詳細 (STRUCT データ型) から値を抽出する
`voice_analytics_status` には `struct` データ型の詳細フィールドがあります。次の例では、`struct` データ型フィールドをクエリする方法を示します。
```
SELECT
detail.transactionId AS "Transaction ID",
detail.voiceConnectorId AS "VoiceConnector ID",
detail.siprecmetadata AS "Siprec Metadata",
detail.inviteheaders AS "Invite Headers",
detail.streamStartTime AS "Stream Start Time"
FROM
"GlueDatabaseName"."voice_analytics_status"
```
## voice\$1analytics\$1status テーブルと call\$1analytics\$1metadata テーブルを結合する
次のクエリ例では、`call_analytics_metadata` と `voice_analytics_status` を結合します。
```
SELECT
a.detail.transactionId AS "Transaction ID",
a.detail.voiceConnectorId AS "VoiceConnector ID",
a.detail.siprecmetadata AS "Siprec Metadata",
a.detail.inviteheaders AS "Invite Headers",
a.detail.streamStartTime AS "Stream Start Time"
json_extract_scalar(b.metadata,'$.fromNumber') AS "From Number",
json_extract_scalar(b.metadata,'$.toNumber') AS "To Number",
json_extract_scalar(b.metadata,'$.callId') AS "Call ID",
json_extract_scalar(b.metadata,'$.direction') AS Direction
FROM
"GlueDatabaseName"."voice_analytics_status" a
INNER JOIN
"GlueDatabaseName"."call_analytics_metadata" b
ON a.detail.transactionId = json_extract_scalar(b.metadata,'$.transactionId')
```
## transcribe\$1call\$1analytics\$1post\$1call テーブルからトランスクリプトを抽出する
transcribe\$1call\$1analytics\$1post\$1call には、ネストされた配列を含む構造体形式のトランスクリプトフィールドがあります。次のクエリを使用して配列のネストを解除します。
```
SELECT
jobstatus,
languagecode,
IF(CARDINALITY(m.transcript)=0 OR CARDINALITY(m.transcript) IS NULL, NULL, e.transcript.id) AS utteranceId,
IF(CARDINALITY(m.transcript)=0 OR CARDINALITY(m.transcript) IS NULL, NULL, e.transcript.content) AS transcript,
accountid,
channel,
sessionid,
contentmetadata.output AS "Redaction"
FROM
"GlueDatabaseName"."transcribe_call_analytics_post_call" m
CROSS JOIN UNNEST
(IF(CARDINALITY(m.transcript)=0, ARRAY[NULL], transcript)) AS e(transcript)
```
## transcribe\$1call\$1analytics\$1post\$1call テーブルと call\$1analytics\$1metadata テーブルを結合する
次のクエリは、transcribe\$1call\$1analytics\$1post\$1call と call\$1analytics\$1metadata を結合します。
```
WITH metadata AS(
SELECT
from_iso8601_timestamp(time) AS "Timestamp",
date_parse(date_format(from_iso8601_timestamp(time), '%m/%d/%Y %H:%i:%s') , '%m/%d/%Y %H:%i:%s') AS "DateTime",
date_parse(date_format(from_iso8601_timestamp(time) , '%m/%d/%Y') , '%m/%d/%Y') AS "Date",
date_format(from_iso8601_timestamp(time) , '%H:%i:%s') AS "Time",
mediainsightspipelineid,
json_extract_scalar(metadata,'$.toNumber') AS "To Number",
json_extract_scalar(metadata,'$.voiceConnectorId') AS "VoiceConnector ID",
json_extract_scalar(metadata,'$.fromNumber') AS "From Number",
json_extract_scalar(metadata,'$.callId') AS "Call ID",
json_extract_scalar(metadata,'$.direction') AS Direction,
json_extract_scalar(metadata,'$.transactionId') AS "Transaction ID",
REGEXP_REPLACE(REGEXP_EXTRACT(json_extract_scalar(metadata,'$.oneTimeMetadata.s3RecordingUrl'), '[^/]+(?=\.[^.]+$)'), '\.wav$', '') AS "SessionID"
FROM
"GlueDatabaseName"."call_analytics_metadata"
),
transcript_events AS(
SELECT
jobstatus,
languagecode,
IF(CARDINALITY(m.transcript)=0 OR CARDINALITY(m.transcript) IS NULL, NULL, e.transcript.id) AS utteranceId,
IF(CARDINALITY(m.transcript)=0 OR CARDINALITY(m.transcript) IS NULL, NULL, e.transcript.content) AS transcript,
accountid,
channel,
sessionid,
contentmetadata.output AS "Redaction"
FROM
"GlueDatabaseName"."transcribe_call_analytics_post_call" m
CROSS JOIN UNNEST
(IF(CARDINALITY(m.transcript)=0, ARRAY[NULL], transcript)) AS e(transcript)
)
SELECT
jobstatus,
languagecode,
a.utteranceId,
transcript,
accountid,
channel,
a.sessionid,
"Redaction"
"Timestamp",
"DateTime",
"Date",
"Time",
mediainsightspipelineid,
"To Number",
"VoiceConnector ID",
"From Number",
"Call ID",
Direction,
"Transaction ID"
FROM
"GlueDatabaseName"."transcribe_call_analytics_post_call" a
LEFT JOIN
metadata b
ON
a.sessionid = b.SessionID
```
## 音声の拡張機能の通話録音用のメディアオブジェクト URL をクエリする
次のクエリ例では、`Voice enhancement call recording` URL を結合します。
```
SELECT
json_extract_scalar(metadata,'$.voiceConnectorId') AS "VoiceConnector ID",
json_extract_scalar(metadata,'$.fromNumber') AS "From Number",
json_extract_scalar(metadata,'$.toNumber') AS "To Number",
json_extract_scalar(metadata,'$.callId') AS "Call ID",
json_extract_scalar(metadata,'$.direction') AS Direction,
json_extract_scalar(metadata,'$.transactionId') AS "Transaction ID",
s3MediaObjectConsoleUrl
FROM
{GlueDatabaseName}."call_analytics_recording_metadata"
WHERE
detail-subtype = "VoiceEnhancement"
```
# Amazon Chime SDK 音声分析を使用する
Amazon Chime SDK 音声分析機能を使用すると、スピーカー検索と音声トーン分析を実装できます。スピーカー検索では、新規の発信者を特定して登録したり、リピート発信者を特定してその識別情報に信頼度スコアを割り当てたりできます。音声トーン分析では、発信者の感情 (`negative`、`neutral`、または `positive`) を予測します。
Amazon Chime SDK 通話分析セッションのオプションコンポーネントとして音声分析を実行します。
音声分析は、メディアインサイトパイプラインまたは Amazon Chime SDK Voice Connector の通話と連携します。タスクやタスクに関する情報をよりきめ細かく制御するには、[メディアパイプライン SDK](media-pipelines.md) を使用し、メディアインサイトパイプラインでタスクを呼び出すことをお勧めします。
Voice Connector を使用して下位互換性を確保することもできますが、更新されるのはメディアインサイトパイプライン API の新機能のみです。
Voice Connector の作成と使用の詳細については、「Amazon Chime SDK 管理者ガイド」の「[Amazon Chime Voice Connector の管理](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) API を呼び出すことで、音声分析を開始できます。
次のトピックでは、音声分析の使い方について説明します。
**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)
+ [音声 API を使用して Amazon Chime SDK の音声分析を実行する](va-in-voice-namespace.md)
# Amazon Chime SDK の音声分析アーキテクチャについて
このセクションのトピックでは、各機能のデータフローを含む、Amazon Chime SDK 音声分析アーキテクチャの概要について説明します。
この図は、音声分析におけるデータフローの概要を示しています。
![\[音声分析におけるデータフローの概要を示す図。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/va-architecture-kvs.png)
図中の手順を説明します。
1. 音声は、発信者とエージェントの Kinesis Video Streams にストリーミングされます。これを行うには、Kinesis Video Streams プロデューサーまたは Amazon Chime SDK Voice Connector のストリーミングを使用します。詳細については、本ガイドの「[Amazon Chime SDK の機械学習ベースの分析を目的としたワークフローについて](ml-based-analytics.md)」と、「Amazon Chime SDK 管理者ガイド」の「[Amazon Chime Voice Connector から Kinesis へのメディアストリーミング](https://docs.aws.amazon.com/chime-sdk/latest/ag/start-kinesis-vc.html)」を参照してください。
1. アプリケーションまたはビルダーは、発信者の同意後に音声ストリームのスピーカー検索、音声トーン分析、あるいはその両方をトリガーします。
1. 通話中、音声分析は、Amazon Simple Queue Service (SQS)、Amazon Simple Notification Service (SNS)、 AWS Lambda、または Amazon Kinesis Data Streams のいずれかのターゲットに通知を送信します。
さらに、音声分析には、生成したデータを管理するためのツールも用意されています。
**音声プロファイル**
音声埋め込み、埋め込みの一意の ID、有効期限を組み合わせた情報です。セキュリティ上の理由から、また時間の経過と共に音声が変化することから、音声プロファイルは 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 を呼び出します。有効期限の詳細については、「[Amazon Chime SDK 音声分析のデータ保持について](va-data-retention.md)」を参照してください。
音声埋め込みを登録したり、登録済みの音声埋め込みを更新したりするには、通話終了後 24 時間以内に [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfile.html) API または [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 のスピーカー検索ワークフローについて
このセクションでは、Amazon Chime SDK スピーカー検索分析のデータおよびプログラムフローの例を示します。
スピーカー検索機能では、音声埋め込みを作成し、それを使用して発信者の声を以前に保存した音声データと比較することができます。生体認証識別子と生体認証情報をデジタル声紋の形で収集、使用、保存、保持するには、書面による発信者の同意が必要な場合があります。このような同意は、イリノイ州、テキサス州、ワシントン州の生体認証法やその他の州のプライバシー法など、さまざまな州法で義務付けられています。スピーカー検索機能を使用する前に、適用法および機能の使用を規定する [AWS サービス条件](https://aws.amazon.com/service-terms/)に従って、すべての通知を行い、すべての同意を得る必要があります。
次の図は、スピーカー検索分析タスクでのデータフローの例を示しています。図の下の番号付き説明は、プロセスの各ステップを示しています。この図は、Amazon Chime SDK Voice Connector を、`VoiceAnalyticsProcessor` のある通話分析設定で既に設定していることを前提としています。詳細については、「[Voice Connector の通話を録音する](record-vc-calls.md)」を参照してください。
![\[スピーカー検索分析におけるデータフローを示す図。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/speaker-search-workflow-2.png)
1. ユーザーまたはシステム管理者は、音声埋め込みと音声プロファイルを保存するための音声プロファイルドメインを作成します。音声プロファイルドメインの作成の詳細については、「Amazon Chime SDK 管理者ガイド」の「[Creating voice profile domains](https://docs.aws.amazon.com/chime-sdk/latest/ag/create-vp-domain.html)」を参照してください。また、[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfileDomain.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfileDomain.html) API を使用することもできます。
1. 発信者は、Amazon Chime SDK Voice Connector に割り当てられた電話番号を使用してダイヤルインします。または、エージェントが Voice Connector 番号を使用して発信通話を行います。
1. Amazon Chime SDK Voice Connector サービスはトランザクション ID を作成し、それを通話に関連付けます。
1. アプリケーションが EventBridge イベントをサブスクライブしている場合、アプリケーションはメディアインサイトパイプライン設定と Voice Connector 通話用の Kinesis Video Streams 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 を呼び出します。
EventBridge の使用に関する詳細については、「[Amazon Chime SDK の機械学習ベースの分析を目的としたワークフローについて](ml-based-analytics.md)」を参照してください。
1. アプリケーション (自動音声応答システムなど) またはエージェントは、通話の録音や音声分析のための音声埋め込みの使用について発信者に通知し、参加の同意を求めます。
1. 発信者が同意すると、Voice Connector ID とトランザクション 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 を呼び出します。Voice Connector ID、トランザクション ID、音声プロファイルドメイン ID を API に渡す必要があります。非同期タスクを識別するためのスピーカー検索タスク ID が返されます。
**注記**
いずれかの SDK で `StartSpeakerSearchTask` API を呼び出す前に、法律および [AWS サービス条件](https://aws.amazon.com/service-terms/)に従って必要な通知を行い、必要な同意を得る必要があります。
1. システムには、発信者の音声が 10 秒分蓄積されます。発信者は少なくともその時間だけ話さなければなりません。システムは無音部分をキャプチャしたり分析したりしません。
1. メディアインサイトパイプラインは、音声をドメイン内の音声プロファイルと比較し、一致率の高い上位 10 件を一覧表示します。一致する音声プロファイルが見つからない場合、Voice Connector は音声プロファイルを作成します。
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) API または [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 を呼び出して、プロファイルを作成または更新します。
1. アプリケーションは必要に応じて [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetSpeakerSearchTask.html) API を呼び出し、スピーカー検索タスクの最新のステータスを取得します。
# Amazon Chime SDK の音声トーン分析ワークフローの例
**重要**
音声トーン分析では、言語およびトーンに関する情報に基づいてスピーカーの感情を予測します。感情分析は、法律で禁止されているいかなる方法でも使用してはなりません。これには、個人に対して法的な影響、または同様の重大な影響を与えるような意思決定 (雇用、住宅、信用、金銭的な申し出などに関するもの) における使用が含まれます。
音声トーン分析では、通話中のスピーカーの声を分析し、`positive`、`negative`、`neutral` のいずれかの感情を予測します。
次の図は、音声トーン分析のワークフローの例を示しています。画像の下にある番号付きの項目は、プロセスの各ステップを説明しています。
**注記**
この図は、Amazon Chime SDK Voice Connector を、`VoiceAnalyticsProcessor` のある通話分析設定で既に設定していることを前提としています。詳細については、「[Voice Connector の通話を録音する](record-vc-calls.md)」を参照してください。
![\[音声トーン分析におけるデータフローを示す図。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/voice-tone-workflow-v2.png)
図中の手順を説明します。
1. 発信者は、Amazon Chime SDK Voice Connector に割り当てられた電話番号を使用してダイヤルインします。または、エージェントが Voice Connector 番号を使用して発信通話を行います。
1. Voice Connector サービスはトランザクション ID を作成し、それを通話に関連付けます。
1. アプリケーション (自動音声応答システムなど) またはエージェントは、通話の録音や音声分析のための音声埋め込みの使用について発信者に通知し、参加の同意を求めます。
1. アプリケーションが EventBridge イベントをサブスクライブしている場合、アプリケーションはメディアインサイトパイプライン設定と Voice Connector 通話用の Kinesis Video Streams 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 を呼び出します。
EventBridge の使用に関する詳細については、「[Amazon Chime SDK の機械学習ベースの分析を目的としたワークフローについて](ml-based-analytics.md)」を参照してください。
1. 発信者が同意すると、Voice Connector ID とトランザクション 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 を呼び出します。Voice Connector 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 つ送信します。
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)」を参照してください。
音声分析では通常、各タスク結果が少なくとも 1 回は配信されます。ただし、ネットワークに問題がある場合、レイテンシーが増加する可能性があります。潜在的な問題を回避したい場合や、同期処理を行いたい場合は、[メディアパイプライン SDK](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Media_Pipelines.html) または[音声 SDK](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Voice.html) で次の API を使用できます。
+ [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetSpeakerSearchTask.html)
+ [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetVoiceToneAnalysisTask.html)
**重要**
`GetVoiceToneAnalysisTask` API はタスクのステータスのみを返します。タスクの結果は返しません。結果を表示するには、Amazon SQS、Amazon SNS、または AWS Lambda 通知ターゲットを使用します。
`GetSpeakerSearchTask` API は、タスク ID、遅延メッセージ、または順不同で届いたメッセージについて、最新の結果を同期的に取得します。ただし、通知ターゲットと非同期処理を使用することをお勧めします。そうすることで、コンピューティングリソースの消費量を抑えることができます。
# Amazon Chime SDK の通知について
音声分析では、スピーカー検索または音声トーン分析のタスクの開始時、実行中、および終了時に、自動的にターゲットにイベントが送信されます。通知ターゲットを使用してこれらのイベントを受信します。ワークフローやアプリケーションに高可用性が必要な場合は、複数の通知ターゲットを使用することをお勧めします。
また、通知ターゲットへのアクセスに必要なポリシーには IAM ロールを使用する必要があります。詳細については、「[Amazon Chime SDK で通話分析のリソースアクセスロールを使用する](call-analytics-resource-access-role.md)」を参照してください。
**注記**
Amazon SQS と Amazon SNS では、先入れ先出しキューはサポートされていません。そのため、メッセージが順不同で届く可能性があります。タイムスタンプを確認して必要に応じてメッセージを順序付け、メッセージを Amazon DynamoDB などのデータストアに保持することをお勧めします。「[Amazon Chime SDK のタスク結果のポーリング](va-task-result-poll.md)」で説明されている Get API を使用して最新の結果を取得することもできます。
次の表に、イベントとそれに対応する詳細タイプを示します。
| 通知イベント | Detail-type |
| --- | --- |
| 音声分析メタデータ | `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 Voice Connector は、以下のスピーカー検索イベントを送信します。
+ ID の一致
+ 音声埋め込みの生成
イベントには以下のステータスがあります。
+ `IdentificationSuccessful` - 特定の音声プロファイルドメイン内で、高い信頼度スコアで一致する音声プロファイル ID を少なくとも 1 つ正常に識別しました。
+ `IdentificationFailure` - 識別を実行できませんでした。原因: 発信者が 10 秒以上話していないか、音質が良くありません。
+ `IdentificationNoMatchesFound` - 指定された音声プロファイルドメインで、高い確率で一致する音声プロファイルが見つかりませんでした。発信者が新規であるか、声が変わっている可能性があります。
+ `VoiceprintGenerationSuccessful` - システムは、20 秒間の無音ではない音声を使用して音声埋め込みを生成しました。
+ `VoiceprintGenerationFailure` - システムは音声埋め込みを生成できませんでした。原因: 発信者が 20 秒以上話していないか、音質が良くありません。
### ID の一致
[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask) API が特定の `transactionId` に対して呼び出されると、Voice Connector サービスは、無音でない音声が 10 秒間聞こえた後、ID が一致したことを示す通知を返します。このサービスは、上位 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 秒間続くと、Voice Connector は通知ターゲットに音声埋め込み生成通知を送信します。音声プロファイルに新しい音声埋め込みを登録したり、音声プロファイルに既に登録されている声紋を更新したりできます。
次の例は、一致が見つかった場合の通知を示しています。この場合、関連する音声プロファイルを更新できます。
```
{
"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 分後に送信されます。これらのサマリーには、通話中に発生したスピーカー検索タスクの概要が記載されています。
次の例は、通話後のサマリーを示しています。これには、最も一致した音声プロファイル、確認済みのスピーカー ID、通話中に行われた `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 コードは、Voice Connector から受信した通知を処理します。 AWS Lambda 関数にコードを追加できます。また、これを使用して Amazon SQS キュー、Amazon SNS トピック、または Amazon Kinesis Data Streams をトリガーすることもできます。その後、通知を `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) API を呼び出す前に、同意を得る必要があります。同意が得られるまでは、Amazon DynamoDB などの保持エリアでイベントを保持することをお勧めします。
# Amazon Chime SDK のデータストレージ、オプトアウト、データ保持ポリシーについて
Amazon Chime SDK は、音声データを使用してスピーカー検索サービスを提供および改善しています。その一環として、登録オーディオ (音声埋め込みの作成に使用される録音されたスニペット) を使用して、機械学習モデルと人工知能モデルをトレーニングしています。モデルのトレーニングにデータが使用されることをオプトアウトすることができます。このセクションのトピックでは、その方法を説明します。
**Topics**
+ [Amazon Chime SDK のスピーカー検索用のデータストレージについて](speaker-search-data-storage.md)
+ [Amazon Chime SDK のスピーカー検索のオプトアウトの処理](va-handle-opt-outs.md)
+ [Amazon Chime SDK 音声分析のデータ保持について](va-data-retention.md)
# Amazon Chime SDK のスピーカー検索用のデータストレージについて
Amazon Chime SDK は、スピーカー検索用に以下のデータを保存します。
+ 音声プロファイルに添付されている音声埋め込み。スピーカー検索機能を提供するために使用されます。
+ 登録オーディオ。録音された音声スニペットで、各音声プロファイルの音声埋め込みに使用されます。登録オーディオの録音は、以下の目的で使用されます。
+ スピーカー検索モデルを最新の状態に保ちます。これは、スピーカー検索機能を提供する上できわめて重要です。
+ 機械学習モデルをトレーニングして、サービスを開発および改善します。トレーニングでの登録オーディオの使用は任意です。次のセクションで説明するように、オプトアウトポリシーを選択することで、この使用をオプトアウトできます。
# Amazon Chime SDK のスピーカー検索のオプトアウトの処理
エンドユーザーと組織全体のオプトアウトを処理できます。オプトアウトには次のような効果があります。
+ オプトアウトすると、音声分析のモデルトレーニングで新しい登録オーディオが使用されなくなり、オプトアウト前に収集、保存された登録音声も使用されなくなります。
+ オプトアウトすると、音声分析ではスピーカー検索サービスを提供するために登録オーディオが保存および使用されます。
**警告**
以下のオプトアウトアクションは元に戻すことはできません。また、削除したデータを復元することもできません。
**エンドユーザーのオプトアウト処理**
エンドユーザーがスピーカー検索をオプトアウトする場合は、[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_DeleteVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_DeleteVoiceProfile.html) API を呼び出します。このアクションにより、音声プロファイルに加えて、音声埋め込みと登録オーディオが削除されます。
音声埋め込みのグループを削除するには、[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_DeleteVoiceProfileDomain.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_DeleteVoiceProfileDomain.html) API を呼び出してドメインを削除します。このアクションにより、ドメイン内のすべての音声プロファイルが削除されます。
**組織レベルでのオプトアウト処理**
組織全体のオプトアウトを処理するには、 AWS Organizations のオプトアウトポリシーを使用します。`chimesdkvoiceanalytics` サービス名を使用します。ポリシーの詳細については、「AWS Organizations ユーザーガイド」の「[AI サービスオプトアウトポリシー](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_ai-opt-out.html)」を参照してください。
**注記**
オプトアウトポリシーを使用するには、 AWS アカウントが AWS Organizations によって一元管理されている必要があります。 AWS アカウントでまだ組織を作成していない場合は、「AWS Organizations ユーザーガイド」の「[組織の作成と管理](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_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask.html) および [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysisTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysisTask.html) の結果は、それぞれの [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_GetSpeakerSearchTask.html) 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 からも最大 7 日間利用できます。
[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask.html) から生成された音声埋め込みは、[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_CreateVoiceProfile.html) と [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_UpdateVoiceProfile.html) API を介して 24 時間利用できますが、その後は削除されて利用できなくなります。
結果を削除する方法、および顧客からの同意の取り消しを処理する方法については、前のセクションを参照してください。
# 音声 API を使用して Amazon Chime SDK の音声分析を実行する
下位互換性を保つため、Amazon Chime SDK 音声 API を使用して音声分析を開始および管理することは可能です。ただし、音声分析用のメディアインサイトパイプライン API のみが新機能を提供するため、代わりにこの API を使用することを強くお勧めします。
以下のセクションでは、音声 API とメディアインサイトパイプライン API の違いについて説明します。
## タスクの停止
Voice Connector を使用して音声分析タスクを開始し、[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) API を呼び出す必要があります。
## 通知の違いについて
音声 API を使用して音声分析を実行する場合、通知はメディアインサイトパイプラインによって生成される通知とは異なります。
+ 音声分析準備完了イベントは、音声 API を使用して開始されたタスクでのみ使用できます。
+ 音声分析タスクを通話に関連付けるには、`voiceConnectorId`、`transactionId`、または `callId` フィールドを使用する必要があります。メディアインサイトパイプラインを使用して音声分析を実行する場合は、`mediaInsightsPipelineId` および `streamArn` または `channelId` フィールドを使用してタスクを通話に関連付けます。
以下のトピックでは、音声 API で通知を使用する方法を説明します。
**Topics**
+ [音声分析準備完了イベント](#va-ready-events)
+ [スピーカー検索イベント](#va-speaker-search-events)
+ [音声トーン分析イベント](#va-tone-status)
### 音声分析準備完了イベント
音声分析準備完了イベントの詳細タイプは `VoiceAnalyticsStatus` です。
Amazon Chime SDK Voice Connector を使用して分析タスクを開始します。音声分析準備完了イベントを受信したら、次のプロパティで識別される通話のスピーカー検索または音声トーン分析タスクをトリガーできます。
+ `voiceConnectorId`
+ `transactionId`
**注記**
この通知は、音声分析が有効で、Voice Connector に関連付けられているメディアインサイトパイプライン設定がある場合にのみ提供されます。この通知は、顧客が `CreateMediaInsightsPipeline` API を呼び出し、メディアパイプライン SDK を介してスピーカー検索タスクまたは音声トーン分析タスクを起動した場合には提供されません。
Voice Connector から返される SIP ヘッダーには、`transactionId` が含まれます。SIP ヘッダーにアクセスできない場合、`AnalyticsReady` 通知イベントには `voiceConnectorId` と `transactionId` も含まれます。これによりプログラムで情報を受信し、[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask) または [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysis.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartVoiceToneAnalysis.html) API を呼び出すことができるようになります。
音声分析の処理準備が整うと、Voice Connector は `"detailStatus": "AnalyticsReady"` のイベントを JSON 本文として通知ターゲットに送信します。Amazon SNS または Amazon SQS を使用している場合、その本文は Amazon SNS または Amazon SQS ペイロードの「Records」フィールドに表示されます。
次の例は一般的な 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"
}
}
}
```
この通知により、音声分析タスク API を呼び出す前に、アプリケーションへの追加のコールバックをトリガーしたり、通知や同意などの法的要件を処理したりできます。
### スピーカー検索イベント
スピーカー検索イベントの詳細タイプは `SpeakerSearchStatus` です。
Amazon Chime SDK Voice Connector は、以下のスピーカー検索イベントを送信します。
+ ID の一致
+ 音声埋め込みの生成
イベントには以下のステータスがあります。
+ `IdentificationSuccessful` - 特定の音声プロファイルドメイン内で、高い信頼度スコアで一致する音声プロファイル ID を少なくとも 1 つ正常に識別しました。
+ `IdentificationFailure` - 識別を実行できませんでした。原因: 発信者が 10 秒以上話していないか、音質が良くありません。
+ `IdentificationNoMatchesFound` - 指定された音声プロファイルドメインで、高い確率で一致する音声プロファイルが見つかりませんでした。発信者が新規であるか、声が変わっている可能性があります。
+ `VoiceprintGenerationSuccessful` - システムは、20 秒間の無音ではない音声を使用して音声埋め込みを生成しました。
+ `VoiceprintGenerationFailure` - システムは音声埋め込みを生成できませんでした。原因: 発信者が 20 秒以上話していないか、音質が良くありません。
#### ID の一致
[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_voice-chime_StartSpeakerSearchTask) API が特定の `transactionId` に対して呼び出されると、Voice Connector サービスは、無音でない音声が 10 秒間聞こえた後、ID が一致したことを示す通知を返します。このサービスは、上位 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 秒間続くと、Voice Connector は通知ターゲットに音声埋め込み生成通知を送信します。音声プロファイルに新しい音声埋め込みを登録したり、音声プロファイルに既に登録されている声紋を更新したりできます。
次の例は、一致が見つかった場合の通知を示しています。この場合、関連する音声プロファイルを更新できます。
```
{
"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 | はい |
| リージョンあたりの音声分析機能を備えたアクティブな Voice Connector コール | 25 | はい |
| トランザクション ID あたりの各 Voice Connector 通話に対するアクティブなスピーカー検索タスク | 1 | いいえ |
| トランザクション ID あたりの各 Voice Connector コールに対するアクティブな音声トーン分析タスク | 1 | いいえ |
| 音声プロファイルドメインあたりの同時 API コールの最大数 | 1 | はい |
| 音声プロファイルあたりの同時 API コールの最大数 | 1 | はい |
| スピーカー検索タスクあたりの同時 API コールの最大数 | 1 | はい |
| 音声トーン分析タスクあたりの同時 API コールの最大数 | 1 | はい |
API のレートおよびクォータの詳細については、「AWS 全般リファレンス」の「[Amazon Chime SDK エンドポイントとクォータ](https://docs.aws.amazon.com/general/latest/gr/chime-sdk.html)」を参照してください。
**注記**
いずれかのリージョンでクォータを超えると、**リソースの制限を超えました**例外メッセージが表示されます。 AWS コンソールの **Service Quotas** ページを使用して引き上げをリクエストするか、[カスタマーサポート担当者](https://docs.aws.amazon.com/awssupport/latest/user/getting-started.html)にお問い合わせください。
コール分析 API の中には、リソースと他の AWS サービスへの API リクエストを作成するものもあります。これらの追加分はアカウントのクォータにカウントされます。コール分析からクォータまたは transactions-per-second数の増加をリクエストする場合は、他の AWS サービスの引き上げもリクエストする必要があります。そうしなかった場合、リクエストがスロットリングされて失敗する可能性があります。