使用 API 分析对话

在创建相应的对话对象后，您可以在“客户体验数据洞见”中查看对话。本操作指南将引导您完成使用 REST API 分析对话的过程。如果您愿意，还可以使用 CX Insights 控制台执行这些操作。

前提条件

1. 在您的 Google Cloud 项目中启用 Cloud Storage 和 Insights API。
2. 导入对话数据。

Chat 对话

1. 将对话的聊天记录作为 object 导入到 Cloud Storage 存储桶中。

2. 记下对象路径，格式为 gs://<bucket>/<object>。

聊天记录文件必须以 JSON 格式的文件提供，且符合 CCAI 对话数据格式。

语音对话

1. 导入 Cloud Storage 存储桶中的所有文件。音频文件和转写文件必须作为 Cloud Storage 存储桶中的对象进行导入。

2. 记下这两个对象路径，格式为 gs://<bucket>/<object>。

转写文件必须是 Cloud Speech-to-Text API 转写的返回结果。具体而言，它们必须与音频识别返回的响应相匹配，该响应在所有 Speech-to-Text API 版本中对于同步识别和异步识别都是相同的。其他转写格式不受支持，会导致在对话分析期间出现错误。

注意： 仅支持双声道音频。否则，在对话分析期间会发生错误。

分析对话

在 CX Insights 中创建 Conversation 对象后，必须对其进行分析才能生成有用的结果。单个对话可以多次分析，每次单独的分析都会创建一个新的 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` 响应中返回的。

注意：所有示例均使用全球客户体验数据分析实例。如需了解如何使用区域实例，请参阅区域化。

HTTP 方法和网址：

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() {
  const [operation] = await client.createAnalysis({
    parent: conversationName,
  });

  // Wait for the operation to complete.
  const [analysis] = await operation.promise();
  console.info(`Created ${analysis.name}`);
}
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 个已部署的模型。

注意：所有示例均使用全球客户体验数据分析实例。如需了解如何使用区域实例，请参阅区域化。

HTTP 方法和网址：

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"
}

轮询操作

创建分析会返回长时间运行的操作。长时间运行的方法是异步执行的，当方法返回响应时，操作可能尚未完成。您可以轮询操作以查看其状态。如需了解详情和代码示例，请参阅长时间运行的操作页面。