从 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 字段。如需了解详情，请参阅更新对数据洞察数据源 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 项目的名称。

更新对数据洞察数据源 ID 的引用

在 Data QnA API 中，您可以使用 datasource_ids 字段来提供数据洞察数据源 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 中，ChatRequest 消息中的 context 字段重命名为 inline_context。此更改有助于区分内嵌上下文与可通过数据智能体提供的其他类型的上下文。

示例：更新 API 请求结构

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

BigQuery 数据源

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

以下代码示例展示了 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"
      }
    }
  }
}

以下代码示例展示了 Conversational Analytics 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"
          }
        }
      }
    }
  }
}

以下代码示例展示了 Conversational Analytics 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 探索的名称
  • your_looker_client_id：Looker 客户端 ID
  • your_looker_client_secret：Looker 客户端密钥

数据洞察数据源

本部分提供了一个示例，说明如何更新针对数据洞察数据源的 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"
    }
  }
}

以下代码示例展示了 Conversational Analytics 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：数据洞察数据源的 ID