使用 API 分析對話

建立相應的對話物件後，即可在 Customer Experience Insights 中查看對話。本操作指南將逐步說明如何使用 REST API 分析對話。您也可以使用 CX Insights 控制台執行這些動作。

必要條件

在 Google Cloud 專案中啟用 Cloud Storage 和 Insights API。
匯入對話資料。

即時通訊對話

將對話的即時通訊記錄匯入 Cloud Storage bucket 做為物件。
記下物件路徑，格式為 gs://<bucket>/<object>。

聊天記錄檔案必須以 JSON 格式提供，且符合 CCAI 對話資料格式。

語音對話

從 Cloud Storage bucket 匯入所有檔案。音訊和轉錄稿檔案必須以物件形式匯入 Cloud Storage 值區。
請記下這兩個物件路徑，格式為 gs://<bucket>/<object>。

轉錄稿檔案必須是 Cloud Speech-to-Text API 轉錄作業傳回的結果。具體來說，這些值必須與語音辨識傳回的 response 相符，且在所有 Speech-to-Text API 版本中，同步辨識和非同步辨識的 response 都相同。系統不支援其他轉錄格式，因此在分析對話時會發生錯誤。

分析對話

在 CX Insights 中建立 Conversation 物件後，必須進行分析才能產生實用結果。單一對話可多次分析，每次分析都會建立新的 Analysis 物件。

分析會對話資料執行一系列註解器，並在回應中傳回結果。根據預設，分析會執行所有可用的註解工具。您也可以選擇設定分析，只執行特定註解者。

分析作業是長時間執行的作業。呼叫 CreateAnalysis 方法會建立代表長時間執行程序的 Operation 物件。作業完成後，Operation 物件會包含結果。您可以輪詢 Operation 物件，檢查是否完成。

建立新的分析

這項工作需要的權限

如要執行這項工作，您必須具備以下權限：

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)

將要求主體儲存在名為 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"
}

輪詢作業

建立分析會傳回長時間執行的作業。長時間執行的作業是非同步作業，方法傳回回應時，作業可能尚未完成。您可以輪詢作業來查看狀態。詳情和程式碼範例請參閱長時間執行的作業頁面。

使用 API 分析對話 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

必要條件

即時通訊對話

語音對話

分析對話

建立新的分析

這項工作需要的權限

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

Python

Java

Node.js

(選用) 設定分析

這項工作需要的權限

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

輪詢作業

使用 API 分析對話