Amazon Connectのコンタクト追跡レコード（個々の通話詳細情報）をS3ストレージへ保持、活用するための設定方法の紹介です。

概要

Amazon Connectでは、通話詳細情報を「コンタクト追跡レコード」として保持しています。
管理画面では「問い合わせの検索」（または「コンタクトの検索」）メニューから検索、表示、CSV形式でダウンロードする機能が提供されています。
ただし、保存期間が2年間であることや、画面上からの検索期間・件数に上限がある、また、現状では取得APIが未提供だったりするため、
長期間の統計を求めたり分析をするには運用が難しいと感じる場面があるかもしれません。

そこで、「コンタクト追跡レコード」をS3ストレージへ保持し、活用するための設定方法をご紹介します。

おおまかな構成

Amazon Connectにて、コンタクト追跡レコード（Contact Trace Records、以下CTR）をKinesis Data Firehoseへ出力する設定を行います
Firehoseは受け取ったCTRをParquet形式へ変換してS3へ保存します
利用者はAmazon Athenaを使用し、S3に格納されたParquet形式のデータへクエリ実行し、結果セットを分析などに利用します

設定手順

Amazon Connectは設定済み／利用中で、S3やKinesis Data Firehoseなどのリソース設定は全くされていない状態への設定を想定します。
トレースすれば動作する手順とするため、説明が長く、少し冗長になってしまいましたが、ご了承ください。

手順1. S3バケット作成

CTRデータファイルや関連するファイルを配置するS3バケットを作成します。既存のバケットを利用する場合は作成不要です。
バケット名はAWS全体で一意である必要がありますので、試される場合は任意の名称に変更してください。

項目	設定値
Bucket name	my-ctr-bucket
AWS Region	ap-northeast-1

手順2. Athena設定

手順2-1. Query editor:Settings

クエリ結果などの保存バケットを指定します。手順1で作成したS3バケットへプレフィックス athena付きで指定します。

項目	設定値
Location of query result	s3://my-ctr-bucket/athena/

手順2-1. Table Create

テーブル定義を作成します。ここではウィザード形式の手順を実施します。理解されている場合はDDLを作成しても良いです。
まず、Query editor画面から「Tables and views」→「Create」→「S3 bucket data」を操作します。

次に、各項目を入力／指定します。

項目	設定値	補足
Table name	ctr	クエリする際のテーブル名を指定します
Database	default	ここでは既存の default データベースを指定しました
Dataset	s3://my-ctr-bucket/contact-trace-records/	データ取得元となるバケット・プレフィックスになります。手順1で作成したS3バケットへ contact-trace-records プレフィックス付きで指定しました
Data format	Parquet
Column details	Bulk add columnsボタンを操作	一括で指定します

続いて、カラム情報を指定します。下記テキストをコピーペーストします。
カラム名+型をカンマ区切りで指定したテキストで一括指定できます。
ポップアップダイアログで「Add」を操作すると元の画面へ戻り、カラム情報が設定された状態になっています。

awsaccountid string,
awscontacttracerecordformatversion string,
agent string,
agentconnectionattempts string,
attributes string,
campaign string,
channel string,
connectedtosystemtimestamp string,
contactid string,
customerendpoint string,
disconnectreason string,
disconnecttimestamp string,
initialcontactid string,
initiationmethod string,
initiationtimestamp string,
instancearn string,
lastupdatetimestamp string,
mediastreams string,
nextcontactid string,
previouscontactid string,
queue string,
recording string,
recordings string,
references string,
scheduledtimestamp string,
systemendpoint string,
transfercompletedtimestamp string,
transferredtoendpoint string,
voiceIdresult string

最後に、画面を最下部までスクロールし、「Create table」を操作します。
上記で指定した内容に基づいて作成されたクエリ(DDL)が確認できます。

カラム仕様についてはドキュメント参照:

docs.aws.amazon.com

手順3. Kinesis Data Firehose設定

Amazon Connectから出力されるCTRデータをS3へ保存するための設定です。
「Amazon Kinesis」→「Delivery streams」→「Create delivery stream」を操作します。
このページは設定項目が多いので、分割して説明します。

手順3-1. Firehose:Create a delivery stream-1

データソースと送信先の設定、ストリーム名の指定です。

項目	設定値
Source	Direct PUT
Destination	Amazon S3 を指定します
Delivery stream name	PUT-S3-CTR

手順3-2. Firehose:Create a delivery stream-2

レコード変換設定です。

項目	設定値
Record format conversion	Enabled
Output format	Apache Parquet
AWS Glue region	Asia Pacific(Tokyo)
AWS Glue database	default
AWS Glue table	ctr

※Glue部分は手順2で指定した内容になります

手順3-3. Firehose:Create a delivery stream-3

レコードの送信先設定です。

項目	設定値	補足
S3 bucket	my-ctr-bucket	手順1で作成したS3バケットです
S3 bucket prefix	contact-trace-records/	手順2でAthenaのデータソースとして指定した値になります
S3 bucket error output prefix	error/	実行時にエラーが発生した場合はこのプレフィックス付きのオブジェクトが作成されます

手順3-4. Firehose:Create a delivery stream-4

レコード送信先設定のオプション部分です。
今回は動作確認しやすくするために、Buffer intervalを最小値である60秒に設定しました。

項目	設定値
Buffer Interval	60

手順3-5. Firehose:Create a delivery stream-5

バックアップ設定です。
オプションですが、フォーマットを変換するということで、元のデータを担保したいと考え、バックアップ設定します。

項目	設定値	補足
Source record backup in Amazon S3	Enabled
S3 backup bucket	my-ctr-bucket	手順1で作成したS3バケットです
S3 backup bucket prefix	source_records/	デフォルト表示されるので、そのまま設定します

上記設定後、最下部の「Create delivery stream」をクリックします。数分で作成完了しました。

手順4. Amazon Connect設定

Amazon ConnectからFire hoseへCTR出力するための設定を行います。
Amazon Connectの設定画面、左の設定項目から「Data streaming」をクリックし、設定します。
設定後、「Save」をクリックして設定を保存します。

項目	設定値	補足
Enable data streaming	チェックON
Contact Trace Records部分	Kinesis Firehoseを選択
ストリームプルダウン	PUT-S3-CTR	手順3で作成したストリーム名です

動作確認

長い設定手順、お疲れさまでした。動作を確認してみます。

CTR作成

Amazon Connectへ電話を架けるなどしてCTRが作成される状況にします。
今回は続けて2回ほどコールし、数分待つとS3へデータ出力されました。

Athenaでクエリ

Athenaでクエリすると期待通り、2件取得できました。

カラム内容が jsonの場合は json_extract 関数などを使用することで、プロパティ値を取得できます。

docs.aws.amazon.com

AWS CLIでクエリ

AWS CLIで実行する場合の手順です。

クエリ実行

$ aws athena start-query-execution \
--query-string 'SELECT contactid,disconnecttimestamp,initiationtimestamp FROM ctr;' \
--result-configuration OutputLocation=s3://my-ctr-bucket/athena/
{
    "QueryExecutionId": "106bc90b-3ad6-41a7-9e3a-66d6d100a3db"
}

結果取得

結果はjsonで返っきます。
jq コマンドでCSVフォーマットに整形したところ

$ aws athena get-query-results \
--query-execution-id 106bc90b-3ad6-41a7-9e3a-66d6d100a3db \
| jq -rc '.ResultSet.Rows[] | [.Data[0].VarCharValue, .Data[1].VarCharValue, .Data[2].VarCharValue] | @csv'
"contactid","disconnecttimestamp","initiationtimestamp"
"3a05a808-0dde-410b-8d82-77.......","2021-11-18T04:09:28Z","2021-11-18T04:09:11Z"
"33fdc486-853e-4751-9079-f4.......","2021-11-18T04:09:53Z","2021-11-18T04:09:34Z"

実際に使うなら何かしらの言語を利用して結果をパースし、データ活用する感じになると思います。

最後に

CTRをS3へ保存し、Athenaクエリする部分までの紹介でした。
ここまで準備できれば、インタラクティブにビジュアライズして分析するならAmazon QuickSightへの接続も容易ですし、
定時処理でAthenaクエリを実行、結果を外部のBIツールへ連携するなどの柔軟な活用も可能になります。

また、S3に保存することでデータ保持期限の制御、たとえば「通話履歴情報は5年で削除」といった要求にも簡単な設定で応えることができそうです。

ご参考になれば幸いです。

【Amazon Connect】通話詳細情報（CTR）をS3へ保存、活用するための準備

概要