Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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

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

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

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

前提条件

Dialogflow で使用する Google Cloud プロジェクトで、Cloud Storage、Speech-to-Text、Sensitive Data Protection、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 Insights は、Recognizer リソースを使用して Speech-to-Text の文字起こし設定を構成します。リクエストでカスタム認識ツールを作成できます。また、[設定] またはリクエストで認識ツールを指定しない場合、CX Insights はプロジェクトにデフォルトの ccai-insights-recognizer を作成します。

CX Insights 認識ツールは、テレフォニーモデルを使用して英語の音声を文字に変換します。デフォルトの言語は en-US です。リージョン、言語、モデル、認識機能ごとの Speech-to-Text のサポートの完全なリストについては、Speech-to-Text の言語サポートドキュメントをご覧ください。

CX Insights に音声を初めてインポートする前に、次のことを行うかどうかを評価します。

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

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

秘匿化

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

プロジェクト設定の構成

このタスクに必要な権限

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

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"

メタデータ

メタデータを 1 つのファイルでインポートするか、一括インポートします。

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

1 つのファイルのみをインポートする場合は、品質メタデータを 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"
}

1 つの音声ファイルをインポートする

このタスクに必要な権限

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

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 オペレーションを開始するには、BatchRecognize リクエストを行って、1 分あたりのリージョンごとの割り当てを使用します。オペレーションをモニタリングするには、GetOperation リクエストを行って、1 分あたりのリージョンごとの割り当てを使用します。

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

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

前提条件

会話データ

成績証明

音声

秘匿化

プロジェクト設定の構成

このタスクに必要な権限

メタデータ

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

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

1 つの音声ファイルをインポートする

このタスクに必要な権限

一括インポート

このタスクに必要な権限

REST

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

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

Speech-to-Text の割り当て

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