开发者可以使用通过 geminidataanalytics.googleapis.com 或区域级端点访问的 Conversational Analytics API 构建由人工智能 (AI) 提供支持的对话界面或数据代理。该 API 使用自然语言回答有关 BigQuery、Looker 和数据洞察中结构化数据的问题，还支持通过 QueryData 方法查询 AlloyDB、GoogleSQL for Spanner、Cloud SQL 和 Cloud SQL for PostgreSQL 中的数据。
借助 Conversational Analytics API，您可以向数据代理提供商家信息和数据（上下文），以及 SQL、Python 和可视化库等工具的访问权限。这些代理回答会呈现给用户，并且可以由客户端应用记录日志，从而打造无缝且可审核的数据对话体验。
了解 Gemini for Google Cloud 如何以及何时使用您的数据。
Conversational Analytics API 使用入门
如需开始使用 Conversational Analytics API，请查看以下文档，了解可用的集成方法和核心概念：
- 架构和关键概念：了解数据智能体如何处理请求、智能体创建者和用户的工作流、对话模式以及所需的 Identity and Access Management (IAM) 角色。
- 数据代理的集成模式：比较各种架构方法，以确定最适合您应用的连接方法。
- 状态管理：了解有状态和无状态对话模式、API 如何管理对话历史记录以及 ADK 会话状态范围。
- 安全性、隐私权、风险和合规性：了解 Conversational Analytics API 的安全性和合规性选项。
- Conversational Analytics API 位置：概述了区域级或多区域 API 端点，可让您控制代理的资源、配置和数据的地理位置。
如需开始构建数据代理，请完成设置和前提条件文档中的步骤。如需了解引导式演练、示例应用、SDK 和其他开发工具，请参阅 Conversational Analytics API 教程、演示和工具。
设置和前提条件
在使用 API 或示例之前，请完成以下步骤：
- 启用 Conversational Analytics API：介绍了启用 Conversational Analytics API 的前提条件。
- 使用 IAM 进行访问权限控制：介绍如何使用 Identity and Access Management 来共享和管理对数据代理的访问权限。
- 对数据源进行身份验证并连接到数据源：提供有关向 API 进行身份验证以及配置与 BigQuery、Lakehouse、Looker、数据洞察和 Cloud Databases 数据（AlloyDB、GoogleSQL for Spanner、Cloud SQL 和 Cloud SQL for PostgreSQL）的连接的说明。
- 客户管理的加密密钥 (CMEK)：介绍如何在 Cloud Key Management Service 中使用自己的加密密钥来保护使用 Looker 数据源的数据代理和对话。
- 组织政策限制条件：介绍如何使用预定义的组织政策限制条件来控制组织、文件夹或项目级别的资源。
构建数据代理并与之交互
完成上述步骤后，请使用 Conversational Analytics API 按照以下步骤构建数据代理并与之交互：
- 使用 HTTP 构建数据代理：提供一个完整的示例，展示如何使用 Python 通过直接 HTTP 请求构建数据代理并与之交互。
- 使用 Python SDK 构建数据代理：提供一个完整的示例，展示如何使用 Python SDK 构建数据代理并与之交互。
- 使用编写的上下文来引导代理行为：了解如何提供编写的上下文来引导代理行为并提高回答准确性。您还可以在 BigQuery 数据源和 Looker 数据源中查看编写的上下文示例。
- 将 Conversational Analytics API 代理回答呈现为可视化图表：提供一个示例，展示如何使用 Python SDK 和 Vega-Altair 库处理 API 响应中的图表规范，并将其呈现为可视化图表。
最佳做法
请查看以下指南，了解使用 Conversational Analytics API 的最佳实践：
- 管理智能体的 BigQuery 费用：了解如何通过设置项目级、用户级和查询级开支限额来监控和管理 Conversational Analytics API 智能体的 BigQuery 费用。
- 提出有效的问题：了解如何为代理精心设计有效的问题，以便充分利用 Conversational Analytics API。
- 数据保留和删除：了解 Conversational Analytics API 数据代理和对话的数据保留和删除。
- 配额和限制：了解 Conversational Analytics API 的配额和限制。
- 排查 Conversational Analytics API 错误：排查常见的 Conversation Analytics API 错误。
- 已知限制：详细介绍了 Conversational Analytics API 的已知限制，包括查询、数据、可视化图表和问题的限制。
- 呈现 Looker 数据源的代理回答：了解在使用 Looker 数据源时，在用户界面中呈现 Conversational Analytics API 回答的最佳实践。
API 参考文档和客户端库
- Gemini Data Analytics REST 参考文档：详细介绍了 API 版本、方法、端点和类型定义。
- SDK 和开发工具：列出了特定语言的客户端库。
关键 API 操作
该 API 提供了以下用于管理数据代理和对话的核心端点。构建这些路径（或其对应的 SDK 资源名称）时，请将通配符 (*) 替换为您的项目 ID、位置标识符（例如 global 或 us）以及资源 ID（例如代理 ID 或对话 ID，如适用）。
| 操作 | HTTP 方法 | 端点 | 说明 |
|---|---|---|---|
| 创建代理 | POST |
/v1/projects/*/locations/*/dataAgents |
创建新的数据代理。 |
| 同步创建代理 | POST |
/v1/projects/*/locations/*/dataAgents:createSync |
同步创建新的数据代理。 |
| 获取智能体 | GET |
/v1/projects/*/locations/*/dataAgents/* |
检索特定数据智能体的详细信息。 |
| 获取 Identity and Access Management 政策 | POST |
/v1/projects/*/locations/*/dataAgents/*:getIamPolicy |
获取为特定数据智能体分配给每个用户的 Identity and Access Management 权限。具有 Data Agent Owner 角色的用户可以调用此端点查看数据智能体的 Identity and Access Management 策略，再使用 setIAMpolicy 端点与其他用户共享数据智能体。 |
| 设置 Identity and Access Management 政策 | POST |
/v1/projects/*/locations/*/dataAgents/*:setIamPolicy |
为特定数据智能体设置 Identity and Access Management 政策。具有 Data Agent Owner 角色的用户应调用此端点，与其他用户共享数据智能体，从而更新这些用户的 Identity and Access Management 权限。 |
| 更新智能体 | PATCH |
/v1/projects/*/locations/*/dataAgents/* |
修改现有数据代理。 |
| 同步更新代理 | PATCH |
/v1/projects/*/locations/*/dataAgents/*:updateSync |
同步修改现有数据代理。 |
| 列出代理 | GET |
/v1/projects/*/locations/*/dataAgents |
列出项目中的可用数据代理。 |
| 列出可访问的代理 | GET |
/v1/projects/*/locations/*/dataAgents:listaccessible |
列出项目中可访问的数据代理。如果调用此 API 的用户对数据代理具有 get 权限，则该数据代理被视为可访问。您可以使用 creator_filter 字段来管理此方法返回哪些代理：
|
| 删除代理 | DELETE |
/v1/projects/*/locations/*/dataAgents/* |
移除数据代理。 |
| 同步删除代理 | DELETE |
/v1/projects/*/locations/*/dataAgents/*:deleteSync |
同步移除数据代理。 |
| 创建对话 | POST |
/v1/projects/*/locations/*/conversations |
启动新的永久性对话。 |
| 使用对话引用进行对话 | POST |
/v1/projects/*/locations/*:chat |
通过发送引用现有对话及其关联代理上下文的对话消息，继续进行有状态对话。对于多轮对话， Google Cloud 会存储和管理对话记录。 |
| 使用数据代理引用进行对话 | POST |
/v1/projects/*/locations/*:chat |
发送引用已保存的数据代理以获取上下文的无状态对话消息。对于多轮对话，您的应用必须管理对话记录，并在每次请求中提供该记录。 |
| 使用内嵌上下文进行对话 | POST |
/v1/projects/*/locations/*:chat |
通过直接在请求中提供所有上下文来发送无状态对话消息，而不使用已保存的数据代理。对于多轮对话，您的应用必须管理对话记录，并在每次请求中提供该记录。 |
| 获取对话 | GET |
/v1/projects/*/locations/*/conversations/* |
检索特定对话的详细信息。 |
| 列出对话 | GET |
/v1/projects/*/locations/*/conversations |
列出特定项目中的对话。 |
| 列出对话中的消息 | GET |
/v1/projects/*/locations/*/conversations/*/messages |
列出特定对话中的消息。 |
| 删除对话 | DELETE |
/v1/projects/*/locations/*/conversations/* |
删除特定对话。调用此端点需要 Topic Admin Identity and Access Management 角色或至少 cloudaicompanion.topics.delete Identity and Access Management 权限。
|
| 查询数据 | POST |
/v1beta/projects/*/locations/*/conversations:queryData |
使用自然语言查询 AlloyDB、GoogleSQL for Spanner、Cloud SQL 和 Cloud SQL for PostgreSQL 数据库中的数据。 |
支持与反馈
如需获取帮助或报告问题，请与客户服务团队联系。按照创建和管理支持请求中的指南打开支持请求。创建支持服务工单时，请遵循以下准则：
- 如需获得有关将 Conversational Analytics API 与 BigQuery 搭配使用的支持，请在选择产品列表中选择 BigQuery，然后在功能字段中选择 AI 和机器学习::BigQuery 中的 Conversational Analytics API。
- 如需获得 Looker 的 Conversational Analytics API 支持，请在选择产品列表中选择 Looker（原始版本），然后在功能字段中选择 Gemini in Looker::Conversational Analytics API。
如果您对 Conversational Analytics API 有一般性反馈或疑问，请发送电子邮件至 conversational-analytics-api-feedback@google.com。我们不保证会回复电子邮件，但我们会阅读电子邮件，并在制定路线图时参考这些反馈。
您还可以提交功能请求，请求添加新的 Conversational Analytics API 功能。