从 Data QnA API 迁移到 Conversational Analytics API

本指南介绍了将应用从 Data QnA API (dataqna.googleapis.com) 迁移到 Conversational Analytics API (geminidataanalytics.googleapis.com) 的主要区别和步骤。

提供反馈

如果您在迁移过程中遇到任何差异，请致电 conversational-analytics-api-feedback@google.com。

主要变更概览

Conversational Analytics API 对 API 端点、API 使用的服务以及 API 请求的结构进行了更改。下表总结了 Data QnA API 与 Conversational Analytics API 之间的主要区别，并列出了迁移所需的步骤。

Data QnA API Conversational Analytics API 必需的更改
dataqna.googleapis.com 端点 geminidataanalytics.googleapis.com 端点 更新请求中的 API 端点。
服务“DataQuestionService” 服务“DataChatService” 更新请求中的服务名称。
AskQuestionRequest 消息中的 project 字段 ChatRequest 消息中的 parent 字段 在您的请求中，将 project 字段替换为 parent 字段。如需了解详情，请参阅将 project 替换为 parent 以进行请求路由。
datasource_ids 字段 studio_references 字段 在您的请求中，将 datasource_ids 字段替换为 studio_references 字段。如需了解详情，请参阅更新对 Looker Studio 数据源 ID 的引用。
AgentConfig 对象 ConversationOptions 对象 将请求中的 AgentConfig 对象替换为 ConversationOptions 对象。如需了解详情，请参阅使用 ConversationOptions 启用 Python 分析。
AskQuestionRequest 消息中的 context 字段 ChatRequest 消息中的 inline_context 字段 在您的请求中，将 context 字段替换为 inline_context 字段。如需了解详情，请参阅将 context 替换为 inline_context。

如需查看有关如何更新 API 请求结构的示例，请参阅示例：更新 API 请求结构。

将 project 替换为 parent 以进行请求路由

在 Data QnA API 中，您可以使用 AskQuestionRequest 消息中的 project 字段来指定 Google Cloud 项目。在 Conversational Analytics API 中，ChatRequest 消息中的 project 字段已被弃用。您可以使用 parent 字段同时指定项目和位置。

以下示例展示了指定 parent 字段的格式：

parent: "projects/your_project_name/locations/global"

在上面的示例中，将 your_project_name 替换为您的 Google Cloud 项目的名称。

更新对 Looker Studio 数据源 ID 的引用

在 Data QnA API 中，您可以使用 datasource_ids 字段提供 Looker Studio 数据源 ID 的列表。在 Conversational Analytics API 中，您可以使用 studio_references 字段提供 StudioDatasourceReference 对象列表，每个对象都包含一个数据源 ID。如需了解详情，请参阅 StudioDatasourceReferences。

使用 ConversationOptions 启用 Python 分析

Data QnA API 中用于启用工具的 AgentConfig 对象不会被 Conversational Analytics API 中的 DataChatService 服务使用。如需在 Conversational Analytics API 中启用 Python 分析等功能，请在创建或配置数据代理时使用 ConversationOptions 对象。如需了解详情，请参阅 ConversationOptions。

将 context 替换为 inline_context

在 Data QnA API 中，AskQuestionRequest 消息包含一个 context 字段，用于提供内嵌的上下文信息。在 Conversational Analytics API 中，context 字段在 ChatRequest 消息中重命名为 inline_context。此更改有助于区分内嵌上下文与可通过数据代理提供的其他类型的上下文。

示例：更新 API 请求结构

以下示例展示了在从 Data QnA API 迁移到 Conversational Analytics API 时，如何根据新的 API 结构调整请求。这些示例涵盖了 BigQuery、Looker 和 Looker Studio 数据源。

BigQuery 数据源

本部分提供了一个示例，说明如何更新针对 BigQuery 数据源的 API 请求。此示例展示了如何更新请求，以请求生成一个条形图，显示机场总数排在前 5 位的州。

以下代码示例展示了 Data QnA API 的请求结构：

project: "projects/your_project_name"
messages {
  user_message {
    text: "Create a bar graph showing the top 5 states by the total number of airports."
  }
}
context {
  datasource_references {
    bq {
      table_references {
        project_id: "your_project_id"
        dataset_id: "your_dataset_id"
        table_id: "your_table_id"
      }
    }
  }
}

以下代码示例展示了对话式分析 API 的更新后请求结构：

messages {
  user_message {
    text: "Create a bar graph showing the top 5 states by the total number of airports."
  }
}
parent: "projects/your_project_name/locations/global"
inline_context {
  datasource_references {
    bq {
      table_references {
        project_id: "your_project_id"
        dataset_id: "your_dataset_id"
        table_id: "your_table_id"
      }
    }
  }

对于前面的示例，您可以按如下方式替换示例值：

  • your_project_name：您的 Google Cloud 项目的名称。
  • your_project_id：BigQuery 项目的 ID。如需连接到公共数据集，请指定 bigquery-public-data。
  • your_dataset_id：BigQuery 数据集的 ID。例如 faa。
  • your_table_id：BigQuery 表的 ID。例如 us_airports。

Looker 数据源

本部分提供了一个示例，说明如何更新 Looker 数据源的 API 请求。此示例展示了如何更新请求，以按订单状态请求订单数量。

以下代码示例展示了 Data QnA API 的请求结构：

project: "projects/your_project_name"
messages {
  user_message {
    text: "Show the count of orders by order status."
  }
}
context {
  datasource_references {
    looker {
      explore_references {
        looker_instance_uri: "https://your_company.looker.com"
        lookml_model: "your_model"
        explore: "your_explore"
      }
      credentials {
        oauth {
          secret {
            client_id: "your_looker_client_id"
            client_secret: "your_looker_client_secret"
          }
        }
      }
    }
  }
}

以下代码示例展示了对话式分析 API 的更新后请求结构：

messages {
  user_message {
    text: "Show the count of orders by order status."
  }
}
parent: "projects/your_project_name/locations/global"
inline_context {
  datasource_references {
    looker {
      explore_references {
        lookml_model: "your_model"
        explore: "your_explore"
        looker_instance_uri: "https://your_company.looker.com"
      }
      credentials {
        oauth {
          secret {
            client_id: "your_looker_client_id"
            client_secret: "your_looker_client_secret"
          }
        }
      }
    }
  }
}

对于前面的示例，您可以按如下方式替换示例值：

  • your_project_name：您的 Google Cloud 项目的名称
  • https://your_company.looker.com：Looker 实例的 URI
  • your_model：LookML 模型的名称
  • your_explore：LookML Explore 的名称
  • your_looker_client_id：您的 Looker 客户端 ID
  • your_looker_client_secret：您的 Looker 客户端密钥

Looker Studio 数据源

本部分提供了一个示例，说明如何更新 Looker Studio 数据源的 API 请求。此示例展示了如何更新请求，以请求显示前五大运营商的条形图。

以下代码示例展示了 Data QnA API 的请求结构：

project: "projects/your_project_name"
messages {
  user_message {
    text: "Create a bar graph showing the top 5 carriers."
  }
}
context {
  datasource_references {
    studio {
      datasource_ids: "your_data_source_id"
    }
  }
}

以下代码示例展示了对话式分析 API 的更新后请求结构：

messages {
  user_message {
    text: "Create a bar graph showing the top 5 carriers."
  }
}
parent: "projects/your_project_name/locations/global"
inline_context {
  datasource_references {
    studio {
      datasource_ids: "your_data_source_id"
    }
  }
}

对于前面的示例，您可以按如下方式替换示例值：

  • your_project_name：您的 Google Cloud 项目的名称
  • your_data_source_id：Looker 数据洞察数据源的 ID