使用 API 导入对话

了解如何使用 API 导入音频文件和转写文件及其元数据。您可以使用 UploadConversation API 导入单个文件，也可以使用 IngestConversations API 从 Cloud Storage 存储桶批量导入所有文件。

两个请求命令 UploadConversation 和 IngestConversations 支持以下函数：

请求命令	文件数	Speech-to-Text	隐去	元数据注入	自动分析
UploadConversation	1	✔	✔	✔	通过分析规则或项目中的上传对话分析百分比 [设置](/contact-center/insights/docs/reference/rest/v1alpha1/Settings#analysisconfig)
IngestConversations	存储桶中的所有文件	✔	✔	✔	仅限分析规则

前提条件

1. 在您用于 Dialogflow 的 Google Cloud 项目中启用 Cloud Storage、Speech-to-Text、Cloud Data Loss Prevention 和 Customer Experience Insights API。
2. 使用标准存储类别将对话数据（双声道音频和转写文件）保存在 Cloud Storage 存储桶中。
   1. 按照 Cloud Storage 快速入门中的说明创建存储桶。
   2. 将存储桶位置设置为离您最近的位置。
   3. 请注意，提供对话数据时需要提供以下信息：
      • 存储桶名称
      • 位置 ID，格式：us-west1
      • 对象路径，格式：gs://<bucket>/<object>
3. 向 Speech-to-Text 和 Customer Experience Insights 服务代理授予对 Cloud Storage 存储桶中对象的访问权限。如需有关服务账号的帮助，请参阅此问题排查页面。

4. 如果您选择导入对话元数据，请确保元数据文件位于自己的存储桶中，并且元数据文件名与其对应的对话文件名一致。

   例如，如果对话的 Cloud Storage URI 为 gs://transcript-bucket-name/conversation.mp3，则必须有相应的元数据文件（例如 gs://metadata-bucket-name/conversation.json）。

注意： 与 UploadConversation API 不同，IngestConversations API 不支持同时导入转写和音频，也不支持将音频与转写相关联。如果您同时拥有对话音频和转写内容，请务必将它们保存在不同的存储分区中。

对话数据

对话数据包括语音或聊天转写文稿和音频。

转录内容

Chat 记录必须以 JSON 格式文件提供，其中每个文件包含单个对话的数据。您的 JSON 格式文本文件包含对话数据格式。

语音转写可以采用对话数据格式提供，也可以作为 Speech-to-Text API 转写的返回语音识别结果提供。对于所有 Speech-to-Text API 版本，同步识别和异步识别的响应都是相同的。

音频

客户体验分析洞见使用 Cloud Speech-to-Text 的批量识别功能来转写音频。CX 数据洞见使用 Recognizer 资源配置 Speech-to-Text 转写设置。您可以在请求中创建自定义识别器，也可以在设置或请求中不提供识别器，这样 CX Insights 会在您的项目中创建默认的 ccai-insights-recognizer。

CX Insights 识别器使用电话模型转写英语语音，默认语言为 en-US。如需查看 Speech-to-Text 在不同区域、语言、模型和识别功能方面的支持情况的完整列表，请参阅 Speech-to-Text 语言支持文档。

注意： CX Insights 需要存在字词时间偏移量，这是一种 Speech-to-Text 识别功能。

在首次将音频导入 CX Insights 之前，请评估您是否希望：

• 使用自定义 Speech-to-Text 转写配置。
• 分析（可选）经过遮盖处理的对话。

您可以在项目设置资源中设置适当的字段，以配置这些操作在每个 UploadConversation 或 IngestConversation 请求中默认运行。您还可以根据具体请求替换语音和隐去设置。如果您未指定任何语音设置，CX Insights 将使用默认语音设置，并且不会对转写内容进行模糊处理。

注意： 音频注入操作会跳过您提供的 Cloud Storage 存储桶中的所有 JSON 文件。

隐去

除非您在项目设置、UploadConversationRequest 或 IngestConversationsRequest 中明确提供隐去配置，否则 Cloud Data Loss Prevention 不会隐去转写内容。Cloud Data Loss Prevention 支持使用检查模板和去标识化模板进行遮盖。

注意： 为确保您不会将任何个人身份信息导入到 CX Insights，您应在导入数据之前自行清理数据。

配置项目设置

执行此任务所需的权限

您必须拥有以下权限才能执行此任务：

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

注意： 如果您设置了其他字段，则可以将 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 字段中提供对象路径。

注意： 为批量导入而存储在存储桶中的元数据文件的名称应与其对应的对话对象名称一致，例如 gs://conversations/conversation.mp3 将与 gs://metadata/conversation.json 相匹配。

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

注意： 已提取到 CX 数据分析中的对话会在后续批量导入尝试中被跳过。系统不会扫描文件内容以进行重复比较。

注意： CX Insights 只允许执行一次批量导入操作。

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 方法和网址：

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 配额

客户体验分析洞见使用两种不同的 Speech-to-Text API：BatchRecognize 和 GetOperation。客户体验数据分析会发出 BatchRecognize 请求来开始 Speech-to-Text 转写，并发出 GetOperation 请求来监控转写是否完成。若要启动 BatchRecognize 操作，系统会发出 BatchRecognize 请求，以使用每分钟每区域配额。为了监控操作，系统会发出 GetOperation 请求，以使用按分钟计的每个区域配额。

对于单个 UploadConversation 调用，客户体验数据分析会消耗一个 BatchRecognize，但可能会消耗更多 GetOperation 请求，具体取决于任务的持续时间。对于批量导入，Customer Experience Insights 会消耗每种类型的 100 个请求。