API を使用して会話をインポートする

API を使用して音声ファイルと文字起こしファイルをメタデータとともにインポートする方法について説明します。UploadConversation API を使用して 1 つのファイルをインポートすることも、IngestConversations API を使用して Cloud Storage バケットからすべてのファイルを一括でインポートすることもできます。

2 つのリクエストコマンド UploadConversation と IngestConversations は、次の関数をサポートしています。

リクエストコマンド	ファイル数	Speech-to-Text	秘匿化	メタデータの取り込み	自動分析
UploadConversation	1	✔	✔	✔	プロジェクトの [設定]（/contact-center/insights/docs/reference/rest/v1alpha1/Settings#analysisconfig）で分析ルールまたは会話分析のアップロードの割合を指定する
IngestConversations	バケット内のすべてのファイル	✔	✔	✔	分析ルールのみ

前提条件

Dialogflow で使用する Google Cloud プロジェクトで、Cloud Storage、Speech-to-Text、Cloud Data Loss Prevention、Customer Experience Insights の各 API を有効にします。
会話データ（デュアルチャネル音声ファイルと文字起こしファイル）を、標準ストレージクラスを使用して Cloud Storage のバケットに保存します。
1. Cloud ストレージクイックスタートの手順に沿って、バケットを作成します。
2. バケットのロケーションを現在地に最も近い場所に設定します。
3. 会話データを提供するときに必要な情報は次のとおりです。
  - バケット名
  - ロケーション ID、形式: us-west1
  - オブジェクトパス、形式: gs://<bucket>/<object>
Speech-to-Text と Customer Experience Insights のサービスエージェントに、Cloud Storage バケット内のオブジェクトへのアクセス権を付与します。サービスアカウントについては、こちらのトラブルシューティングページをご覧ください。
会話メタデータのインポートを選択した場合は、メタデータファイルが独自のバケットにあり、メタデータファイル名が対応する会話ファイル名と一致していることを確認してください。

たとえば、Cloud Storage URI gs://transcript-bucket-name/conversation.mp3 を含む会話には、対応するメタデータファイル（gs://metadata-bucket-name/conversation.json など）が必要です。

会話データ

会話データは、音声またはチャットの文字起こしと音声で構成されます。

成績証明

チャットの文字起こしは JSON 形式のファイルで指定する必要があります。各ファイルには 1 つの会話のデータが含まれています。JSON 形式のテキストファイルには、会話データの形式が含まれています。

音声文字起こしは、会話データ形式で提供することも、Speech-to-Text API の文字起こしで返される音声認識結果として提供することもできます。レスポンスは、すべての Speech-to-Text API バージョンで同期認識と非同期認識で同じです。

音声

Customer Experience Insights は、Cloud Speech-to-Text のバッチ認識を使用して音声を文字に変換します。CX インサイトは、認識ツールリソースを使用して Speech-to-Text の文字起こし設定を構成します。リクエストでカスタム認識ツールを作成できます。また、[設定] またはリクエストで認識ツールを指定しない場合、CX Insights はプロジェクトにデフォルトの ccai-insights-recognizer を作成します。

CX Insights 認識ツールは、テレフォニーモデルを使用して英語の音声を文字起こしします。デフォルトの言語は en-US です。地域、言語、モデル、認識機能ごとの Speech-to-Text のサポートの一覧については、Speech-to-Text の言語サポートに関するドキュメントをご覧ください。

CX Insights に音声を初めてインポートする前に、次のいずれを行うか検討してください。

カスタムの Speech-to-Text 文字起こし構成を使用します。
（必要に応じて）編集された会話を分析します。

これらのアクションは、プロジェクトの設定リソースで適切なフィールドを設定することで、各 UploadConversation リクエストまたは IngestConversation リクエストでデフォルトで実行するように構成できます。音声と秘匿化の設定は、リクエストごとにオーバーライドすることもできます。音声設定を指定しない場合、CX Insights はデフォルトの音声設定を使用し、文字起こしを編集しません。

秘匿化

Cloud Data Loss Prevention は、プロジェクトの [設定]、UploadConversationRequest、または IngestConversationsRequest で明示的に秘匿化構成を指定しない限り、文字起こしを秘匿化しません。Cloud Data Loss Prevention は、秘匿化用の検査テンプレートと匿名化テンプレートの両方をサポートしています。

プロジェクトの構成

このタスクに必要な権限

このタスクを行うには、次の権限が必要です。

contactcenterinsights.settings.update

UploadConversation リクエストと IngestConversations リクエストの墨消しと音声は、対応するプロジェクト設定パラメータを設定することで構成できます。これらの構成は、リクエストごとに個別に設定することもできます。この場合、プロジェクト設定がオーバーライドされます。分析ルールで構成された analysis_percentage は、プロジェクトの設定で構成された upload_conversation_analysis_percentage をオーバーライドします。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/settings?updateMask=redaction_config,speech_config,analysis_config.upload_conversation_analysis_percentage"

メタデータ

メタデータを単一ファイルとしてインポートするか、一括インポートとしてインポートします。

リクエストにメタデータを直接含める

単一ファイルのインポートの場合のみ、品質メタデータを UploadConversationsRequest の curl コマンドに直接含めることができます。

curl --request POST \
  'https://contactcenterinsights.googleapis.com/v1/projects/project-id/locations/location-id/conversations:upload' \
   --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
   --header 'Accept: application/json' \
   --header 'Content-Type: application/json' \
   --data '{
           "conversation":{
            "qualityMetadata":{
               "agentInfo":[{"agentId":"agent-id","displayName":"agent-name"}]
             },
            "dataSource":{"gcsSource":{"transcriptUri":"transcript-uri"}}}
          }'

Cloud Storage ファイルからメタデータをインポートする

会話メタデータファイルは JSON 形式のファイルとして指定します。一括インポートの場合は、IngestConversationsRequest の gcs_source.metadata_bucket_uri フィールドで指定されたバケットを指定します。単一のインポートの場合は、UploadConversationRequest の data_source.metadata_uri フィールドにオブジェクトパスを指定します。

CX Insights は、ファイル内の会話品質メタデータを入力しますが、カスタムメタデータを作成することもできます。

たとえば、データセット内の各会話にカスタム会話 ID を指定するには、Cloud Storage 内の会話オブジェクトにカスタムメタデータを指定します。キーを ccai_insights_conversation_id に設定します。値はカスタム会話 ID です。カスタムの会話 ID は、メタデータファイル内で指定することもできます。

IngestConversationsRequest の custom_metadata_keys フィールドにカスタムメタデータを指定すると、CX Insights はそのカスタムメタデータを会話のラベルに保存します。最大 100 個のラベルをサポートします。

Conversation.quality_metadata リソース、カスタム会話 ID、会話の開始時間を含む有効なメタデータファイルの例を次に示します。

{
  "customer_satisfaction_rating": 5,
  "agent_info": [
    {
      "agent_id": "123456",
      "display_name": "Agent Name",
      "team": "Agent Team",
      "disposition_code": "resolved"
    }
  ],
  "custom_key": "custom value"
  "conversation_id": "custom-conversation-id"
  "start_time": "%Y-%m-%d%ET%H:%M:%E*S%Ez"
}

単一の音声ファイルをインポートする

このタスクに必要な権限

このタスクを行うには、次の権限が必要です。

contactcenterinsights.conversations.upload

UploadConversation API は、会話の文字起こしと、必要に応じて会話の秘匿を行う長時間実行オペレーションを作成します。会話の DataSource に audio_uri のみが含まれている場合、音声ファイルは文字起こしされます。それ以外の場合は、指定された transcript_uri が読み取られて使用されます。

リクエストの本文（JSON）:

{ 
  "conversation": { 
    "data_source": { 
      "gcs_source": { "audio_uri": AUDIO_URI }
    }
  },
  "redaction_config": {
    "deidentify_template": DEIDENTIFY_TEMPLATE,
    "inspect_template": INSPECT_TEMPLATE
  },
  "speech_config": {
    "speech_recognizer": RECOGNIZER_NAME
  }
}

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/conversations:upload"

一括インポート

このタスクに必要な権限

このタスクを行うには、次の権限が必要です。

contactcenterinsights.conversations.create

REST

詳細については、conversations:ingest API エンドポイントをご覧ください。

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: Google Cloud Platform プロジェクト ID。
GCS_BUCKET_URI: 会話の文字起こしを含むバケットを指す Cloud Storage URI。接頭辞を含む場合があります。たとえば、gs://BUCKET_NAME や gs://BUCKET_NAME/PREFIX です。ワイルドカードはサポートされていません。
MEDIUM: データ型に応じて PHONE_CALL または CHAT に設定します。指定しない場合、デフォルト値は PHONE_CALL です。
AGENT_ID: 省略可。バケット全体のエージェント ID。

HTTP メソッドと URL:

POST https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations:ingest

リクエストの本文（JSON）:

{
  "gcsSource":  {
    "bucketUri": "GCS_BUCKET_URI",
    "bucketObjectType": "AUDIO"
  },
  "transcriptObjectConfig": { "medium": "PHONE_CALL" },
  "conversationConfig": {
    "agentId": "AGENT_ID",
    "agentChannel": "AGENT_CHANNEL",
    "customerChannel": "CUSTOMER_CHANNEL"
  }
}

Or

{
  "gcsSource":  {
    "bucketUri": "GCS_BUCKET_URI",
    "bucketObjectType": "TRANSCRIPT"
  },
  "transcriptObjectConfig": { "medium": "MEDIUM" },
  "conversationConfig": {"agentId": "AGENT_ID"}
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations:ingest"

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations:ingest" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。


{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.contactcenterinsights.v1main.IngestConversationsMetadata",
    "createTime": "...",
    "request": {
      "parent": "projects/PROJECT_ID/locations/us-central1",
      "gcsSource": {
        "bucketUri": "GCS_BUCKET_URI",
        "bucketObjectType": "BUCKET_OBJECT_TYPE"
      },
      "transcriptObjectConfig": {
        "medium": "MEDIUM"
      },
      "conversationConfig": {
        "agentId": "AGENT_ID"
      }
    }
  }
}

オペレーションをポーリングする

UploadConversation リクエストと IngestConversation リクエストの両方で、長時間実行オペレーションが返されます。長時間実行メソッドは非同期で、メソッドがレスポンスを返すときにオペレーションがまだ完了していない場合があります。オペレーションをポーリングして、そのステータスを確認できます。詳細とコードサンプルについては、長時間実行オペレーションのページをご覧ください。

Speech-to-Text の割り当て

Customer Experience Insights では、BatchRecognize と GetOperation の 2 つの異なる Speech-to-Text API が使用されます。Customer Experience Insights は、Speech-to-Text の文字起こしを開始する BatchRecognize リクエストと、文字起こしが完了したかどうかをモニタリングする GetOperation リクエストを行います。BatchRecognize オペレーションを開始するには、1 分あたり、リージョンごとの割り当てを使用する BatchRecognize リクエストが行われます。オペレーションをモニタリングするために、1 分あたり、リージョンごとの割り当てを使用する GetOperation リクエストが発行されます。

1 回の UploadConversation 呼び出しで、Customer Experience Insights は 1 つの BatchRecognize を消費しますが、タスクの所要時間によっては、より多くの GetOperation リクエストを消費する可能性があります。一括インポートの場合、Customer Experience Insights は各タイプのリクエストを 100 件消費します。

API を使用して会話をインポートする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

前提条件

会話データ

成績証明

音声

秘匿化

プロジェクトの構成

このタスクに必要な権限

メタデータ

リクエストにメタデータを直接含める

Cloud Storage ファイルからメタデータをインポートする

単一の音声ファイルをインポートする

このタスクに必要な権限

一括インポート

このタスクに必要な権限

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

オペレーションをポーリングする

Speech-to-Text の割り当て

API を使用して会話をインポートする