API を使用して会話を分析する

会話オブジェクトが作成されると、Customer Experience Insights で会話を表示できます。この入門ガイドでは、REST API を使用して会話を分析するプロセスについて説明します。必要に応じて、CX Insights コンソールを使用してこれらの操作を行うこともできます。

前提条件

1. プロジェクトでCloud Storage API と Insights API を有効にします Google Cloud 。
2. 会話データをインポートします。

チャットの会話

1. 会話のチャット トランスクリプトを Cloud Storage バケット内の オブジェクトとしてインポートします。

2. オブジェクト パスをメモします。形式は gs://<bucket>/<object> です。

チャット トランスクリプト ファイルは、CCAI 会話データ形式に一致する JSON 形式のファイルとして指定する必要があります。

音声会話

1. Cloud Storage バケットからすべてのファイルをインポートします。音声ファイルとトランスクリプト ファイルは、Cloud Storage バケット内のオブジェクトとしてインポートする必要があります。

2. 2 つのオブジェクト パスをメモします。形式は gs://<bucket>/<object> です。

トランスクリプト ファイルは、Cloud Speech-to-Text API の文字起こし結果である必要があります。具体的には、音声認識から返されるレスポンスと一致する必要があります。これは、すべての Speech-to-Text API バージョンで同期認識と非同期認識で同じです。他の文字起こし形式はサポートされておらず、会話分析中にエラーが発生します。

注: 2 チャンネルの音声のみがサポートされています。それ以外の場合、会話分析中にエラーが発生します。

会話を分析する

CX Insights で Conversation オブジェクトが作成されたら、有用な結果を得るために分析する必要があります。1 つの会話を何度も分析できます。個別の分析ごとに新しい Analysis オブジェクトが作成されます。

分析では、会話データに対して一連のアノテーター が実行され、結果がレスポンスで返されます。デフォルトでは、使用可能なすべてのアノテーターが実行されます。必要に応じて、分析を構成して指定したアノテーターのみを実行できます。

分析は長時間実行オペレーションです。CreateAnalysis メソッドを呼び出すと、長時間実行プロセスを表す Operation オブジェクトが作成されます。オペレーションが完了すると、Operation オブジェクトに結果が含まれます。Operation オブジェクトをポーリングして、完了を確認できます。

注: ` languageCode ` フィールドが設定されていない場合、CX Insights は自動的に推測します。分析では英語（すべての言語）のみがサポートされています。

新しい分析を作成する

このタスクに必要な権限

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

• contactcenterinsights.analyses.create

REST

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

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

• PROJECT_ID: 実際の Google Cloud プロジェクト ID。
• CONVERSATION_ID: 分析する会話の ID。この値は `createConversation` レスポンスで返されました。

注: すべての例で、グローバル Customer Experience Insights インスタンスを使用しています。リージョン インスタンスの使用方法については、リージョン化をご覧ください。

HTTP メソッドと URL:

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

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

curl（Linux、macOS、Cloud Shell）

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

次のコマンドを実行します。

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

PowerShell（Windows）

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

次のコマンドを実行します。

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

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://contactcenterinsights.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/conversations/CONVERSATION_ID/analyses" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID"
}

Python

CX Insights への認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、 ローカル開発環境の認証の設定をご覧ください。

from google.cloud import contact_center_insights_v1


def create_analysis(conversation_name: str) -> contact_center_insights_v1.Analysis:
    """Creates an analysis.

    Args:
        conversation_name:
            The parent resource of the analysis.
            Format is 'projects/{project_id}/locations/{location_id}/conversations/{conversation_id}'.
            For example, 'projects/my-project/locations/us-central1/conversations/123456789'.

    Returns:
        An analysis.
    """
    # Construct an analysis.
    analysis = contact_center_insights_v1.Analysis()

    # Call the Insights client to create an analysis.
    insights_client = contact_center_insights_v1.ContactCenterInsightsClient()
    analysis_operation = insights_client.create_analysis(
        parent=conversation_name, analysis=analysis
    )
    analysis = analysis_operation.result(timeout=86400)
    print(f"Created {analysis.name}")
    return analysis

Java

CX Insights への認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、 ローカル開発環境の認証の設定をご覧ください。

import com.google.cloud.contactcenterinsights.v1.Analysis;
import com.google.cloud.contactcenterinsights.v1.ContactCenterInsightsClient;
import java.io.IOException;

public class CreateAnalysis {

  public static void main(String[] args) throws Exception, IOException {
    // TODO(developer): Replace this variable before running the sample.
    String conversationName =
        "projects/my_project_id/locations/us-central1/conversations/my_conversation_id";

    createAnalysis(conversationName);
  }

  public static Analysis createAnalysis(String conversationName) throws Exception, IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (ContactCenterInsightsClient client = ContactCenterInsightsClient.create()) {
      // Construct an analysis.
      Analysis analysis = Analysis.newBuilder().build();

      // Call the Insights client to create an analysis.
      Analysis response = client.createAnalysisAsync(conversationName, analysis).get();
      System.out.printf("Created %s%n", response.getName());
      return response;
    }
  }
}

Node.js

CX Insights への認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、 ローカル開発環境の認証の設定をご覧ください。

/**
 * TODO(developer): Uncomment this variable before running the sample.
 */
// const conversationName = 'projects/my_project_id/locations/us-central1/conversations/my_conversation_id';

// Imports the Contact Center Insights client.
const {
  ContactCenterInsightsClient,
} = require('@google-cloud/contact-center-insights');

// Instantiates a client.
const client = new ContactCenterInsightsClient();

async function createAnalysis() {
  try {
    const [operation] = await client.createAnalysis({
      parent: conversationName,
    });

    // Wait for the operation to complete.
    const [analysis] = await operation.promise();
    console.info(`Created ${analysis.name}`);
  } catch (err) {
    console.error(`createAnalysis failed: ${JSON.stringify(err, null, 2)}`);
    process.exitCode = 1;
  }
}
createAnalysis();

（省略可）分析を構成する

このタスクに必要な権限

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

• contactcenterinsights.analyses.create

REST

詳細については、 conversations.analyses:create API エンドポイントをご覧ください。実行するアノテーターを annotatorSelector オブジェクトに含めて、true に設定します。含まれていないアノテーターはデフォルトで false になります。annotatorSelector オブジェクトでアノテーターを指定しない場合、すべてのアノテーターが実行されます。

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

• PROJECT_ID: 実際の Google Cloud プロジェクト ID。
• PHRASE_MATCHER(s): フレーズ マッチャー アノテーターに使用するフレーズ マッチャーの完全修飾されたフレーズ マッチャー リソース名。空のままにすると、アクティブなフレーズ マッチャーがすべて実行されます。
• ISSUE_MODEL(s)：問題モデル アノテーターに使用する問題モデルの完全修飾されたリソース名。run_issue_model_annotator が true の場合にのみ機能します。空のままにすると、デプロイされた問題モデルがすべて実行されます。現在、デプロイできるモデルは 1 つに制限されています。

注: すべての例で、グローバル Customer Experience Insights インスタンスを使用しています。リージョン インスタンスの使用方法については、リージョン化をご覧ください。

HTTP メソッドと URL:

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

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

{
  "annotatorSelector": {
    "run_interruption_annotator": {true/false},
    "run_silence_annotator": {true/false},
    "run_phrase_matcher_annotator": {true/false},
    "phrase_matchers": PHRASE_MATCHER(s),
    "run_sentiment_annotator": {true/false},
    "run_entity_annotator": {true/false},
    "run_intent_annotator": {true/false},
    "run_issue_model_annotator": {true/false}
    "issue_models": ISSUE_MODEL(s)
  }
}

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

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/CONVERSATION_ID/analyses"

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/CONVERSATION_ID/analyses" | Select-Object -Expand Content

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

{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/OPERATION_ID"
}

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

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