Package google.developers.knowledge.v1alpha

索引

DeveloperKnowledge

Developer Knowledge API 可让您以程序化方式访问 Google 的公开开发者文档，从而将此知识库集成到您自己的应用和工作流中。

该 API 旨在成为以机器可读格式访问 Google 开发者文档的规范来源。

一个典型的使用场景是，先使用 DeveloperKnowledge.SearchDocumentChunks 根据查询内容查找相关网页 URI，然后使用 DeveloperKnowledge.GetDocument 或 DeveloperKnowledge.BatchGetDocuments 获取热门结果的完整内容。

所有文档内容均以 Markdown 格式提供。

AnswerQuery

rpc AnswerQuery(AnswerQueryRequest) returns (AnswerQueryResponse)

使用有依据的生成功能回答查询。

授权范围

需要以下 OAuth 范围之一：

  • https://www.googleapis.com/auth/devprofiles.full_control
  • https://www.googleapis.com/auth/cloud-platform

如需了解详情，请参阅 OAuth 2.0 Overview。
BatchGetDocuments

rpc BatchGetDocuments(BatchGetDocumentsRequest) returns (BatchGetDocumentsResponse)

检索多个文档，每个文档都包含完整的 Markdown 内容。

授权范围

需要以下 OAuth 范围之一：

  • https://www.googleapis.com/auth/devprofiles.full_control
  • https://www.googleapis.com/auth/cloud-platform

如需了解详情，请参阅 OAuth 2.0 Overview。
GetDocument

rpc GetDocument(GetDocumentRequest) returns (Document)

检索包含完整 Markdown 内容的单个文档。

授权范围

需要以下 OAuth 范围之一：

  • https://www.googleapis.com/auth/devprofiles.full_control
  • https://www.googleapis.com/auth/cloud-platform

如需了解详情，请参阅 OAuth 2.0 Overview。
SearchDocumentChunks

rpc SearchDocumentChunks(SearchDocumentChunksRequest) returns (SearchDocumentChunksResponse)

在 Google 的开发者文档中搜索开发者知识。根据用户查询返回 DocumentChunk。同一 Document 中可能包含多个块。如需检索完整文档，请使用 DeveloperKnowledge.GetDocument 或 DeveloperKnowledge.BatchGetDocuments 以及 SearchDocumentChunksResponse.results 中返回的 DocumentChunk.parent。

授权范围

需要以下 OAuth 范围之一：

  • https://www.googleapis.com/auth/devprofiles.full_control
  • https://www.googleapis.com/auth/cloud-platform

如需了解详情，请参阅 OAuth 2.0 Overview。

答案

对查询的回答。

字段
answer_text

string

回答的文本。

AnswerQueryRequest

DeveloperKnowledge.AnswerQuery 的请求消息。

字段
query

string

必需。要回答的查询。

AnswerQueryResponse

DeveloperKnowledge.AnswerQuery 的响应消息。

字段
answer

Answer

查询的答案。

BatchGetDocumentsRequest

DeveloperKnowledge.BatchGetDocuments 的请求消息。

字段
names[]

string

必需。指定要检索的文档的名称。一个批次最多可以检索 20 个文档。返回的文档与请求中的 names 顺序相同。

格式：documents/{uri_without_scheme} 示例：documents/docs.cloud.google.com/storage/docs/creating-buckets
view

DocumentView

可选。指定文档的 DocumentView。如果未指定，则 DeveloperKnowledge.BatchGetDocuments 默认为 DOCUMENT_VIEW_CONTENT。

BatchGetDocumentsResponse

DeveloperKnowledge.BatchGetDocuments 的响应消息。

字段
documents[]

Document

包含所请求的文档。

文档

Document 表示开发者知识语料库中的一段内容。

字段
name

string

标识符。包含文档的资源名称。格式：documents/{uri_without_scheme} 示例：documents/docs.cloud.google.com/storage/docs/creating-buckets
uri

string

仅限输出。提供内容的 URI，例如 docs.cloud.google.com/storage/docs/creating-buckets。
content

string

仅限输出。包含文档的完整内容（采用 Markdown 格式）。
description

string

仅限输出。提供文档的说明。
data_source

string

仅限输出。指定文档的数据源。数据源示例：firebase.google.com
title

string

仅限输出。提供文档的标题。
update_time

Timestamp

仅限输出。表示文档的内容或元数据上次更新时的时间戳。
view

DocumentView

仅限输出。指定文档的 DocumentView。

DocumentChunk

DocumentChunk 表示 DeveloperKnowledge 语料库中 Document 的一部分内容。如需提取整个文档内容，请将 parent 传递给 DeveloperKnowledge.GetDocument 或 DeveloperKnowledge.BatchGetDocuments。

字段
parent

string

仅限输出。包含相应块所来自的文档的资源名称。格式：documents/{uri_without_scheme} 示例：documents/docs.cloud.google.com/storage/docs/creating-buckets
id

string

仅限输出。指定相应块在文档中的 ID。块 ID 在文档中是唯一的，但在不同文档之间并不具有全局唯一性。块 ID 不稳定，可能会随时间而变化。
content

string

仅限输出。包含文档块的内容。
document

Document

仅限输出。表示相应块所属 Document 的元数据。相应 Document 消息的 DocumentView 将设置为 DOCUMENT_VIEW_BASIC。此处包含该字段是为了方便起见，以便客户端在只需要元数据字段时无需调用 DeveloperKnowledge.GetDocument 或 DeveloperKnowledge.BatchGetDocuments。否则，客户端应使用 DeveloperKnowledge.GetDocument 或 DeveloperKnowledge.BatchGetDocuments 来提取完整文档内容。

DocumentView

指定要包含 Document 的哪些字段。

枚举
DOCUMENT_VIEW_UNSPECIFIED 默认值 / 未设置的值。如果未指定 DocumentView，请参阅每个 API 方法的默认值。
DOCUMENT_VIEW_BASIC

仅包含基本元数据字段：- name - uri - data_source - title - description - update_time - view

这是 DeveloperKnowledge.SearchDocumentChunks 的默认视图。
DOCUMENT_VIEW_FULL 包含所有 Document 字段。
DOCUMENT_VIEW_CONTENT

包含 DOCUMENT_VIEW_BASIC 字段和 content 字段。

这是 DeveloperKnowledge.GetDocument 和 DeveloperKnowledge.BatchGetDocuments 的默认视图。

GetDocumentRequest

DeveloperKnowledge.GetDocument 的请求消息。

字段
name

string

必需。指定要检索的文档的名称。格式：documents/{uri_without_scheme} 示例：documents/docs.cloud.google.com/storage/docs/creating-buckets
view

DocumentView

可选。指定文档的 DocumentView。如果未指定，则 DeveloperKnowledge.GetDocument 默认为 DOCUMENT_VIEW_CONTENT。

SearchDocumentChunksRequest

DeveloperKnowledge.SearchDocumentChunks 的请求消息。

字段
query

string

必需。提供用户提供的原始查询字符串，例如“如何创建 Cloud Storage 存储分区？”。
page_size

int32

可选。指定要返回的结果数上限。服务返回的值可能小于此值。

如果未指定，则最多返回 5 个结果。

最大值为 20；大于 20 的值将导致 INVALID_ARGUMENT 错误。
page_token

string

可选。包含从之前的 SearchDocumentChunks 调用接收的页面令牌。利用其进行后续页面检索。
filter

string

可选。对搜索结果应用严格过滤条件。该表达式支持 https://google.aip.dev/160 中所述的部分语法。

虽然 SearchDocumentChunks 返回 DocumentChunk，但过滤条件会应用于 DocumentChunk.document 字段。

支持过滤的字段：

  • data_source（字符串）：文档来源，例如 docs.cloud.google.com。如需查看语料库中数据源的完整列表，请访问 https://developers.google.com/knowledge/reference/corpus-reference。
  • update_time (TIMESTAMP)：文档上次有意义的更新时间的时间戳。有意义的更新是指会更改文档的 Markdown 内容或元数据的更新。
  • uri（STRING）：文档 URI，例如 https://docs.cloud.google.com/bigquery/docs/tables。

对于整个字符串，STRING 字段支持 =（等于）和 !=（不等于）运算符，以进行完全匹配。不支持部分匹配、前缀匹配和正则表达式匹配。

TIMESTAMP 字段支持 =、<、<=、> 和 >= 运算符。时间戳必须采用 RFC-3339 格式，例如 "2025-01-01T00:00:00Z"。

您可以使用 AND、OR 和 NOT（或 -）逻辑运算符组合表达式。OR 的优先级高于 AND。使用括号明确指定优先级分组。

示例：

  • data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"
  • data_source != "firebase.google.com"
  • update_time < "2024-01-01T00:00:00Z"
  • update_time >= "2025-01-22T00:00:00Z" AND (data_source = "developer.chrome.com" OR data_source = "web.dev")
  • uri = "https://docs.cloud.google.com/release-notes"

filter 字符串不得超过 500 个字符；如果值超过 500 个字符，系统会返回 INVALID_ARGUMENT 错误。

SearchDocumentChunksResponse

DeveloperKnowledge.SearchDocumentChunks 的响应消息。

字段
results[]

DocumentChunk

包含给定查询的搜索结果。此列表中的每个 DocumentChunk 都包含与搜索查询相关的内容摘要。将每个结果的 DocumentChunk.parent 字段与 DeveloperKnowledge.GetDocument 或 DeveloperKnowledge.BatchGetDocuments 搭配使用，即可检索完整的文档内容。
next_page_token

string

可选。提供可作为 page_token 发送并用于检索下一页的令牌。如果省略此字段，则不存在后续页面。