Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

搜索和检索文档

本指南介绍了如何使用 Developer Knowledge API 以编程方式搜索和检索 Google 的公开开发者文档。该 API 可帮助您的应用查找相关文本片段或提取完整的 Markdown 文档，而无需手动抓取网页。

在本文档中，您将找到以下任务的示例：

正在搜索文档语料库。
对搜索结果进行分页。
为搜索应用复杂的过滤条件。
检索完整文档内容。
优化了响应载荷以缩短延迟时间。

开始之前，请确保您已启用该 API 并生成 Developer Knowledge API 密钥。然后，将密钥保存到环境变量中：

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

使用 `SearchDocumentChunks` 搜索文档

使用 documents.searchDocumentChunks 方法查找与查询字符串匹配的文档块。结果包含匹配文档中的内容块，以及可用于检索这些文档完整内容的 parent 引用。

以下示例搜索与“BigQuery”匹配的文档：

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&key=$DEVELOPERKNOWLEDGE_API_KEY"

输出类似于以下内容：

{
  "results": [
    {
      "parent": "documents/docs.cloud.google.com/bigquery/docs/introduction",
      "id": "chunk_0",
      "content": "BigQuery is a fully managed enterprise data warehouse...",
      "document": {
        "name": "documents/docs.cloud.google.com/bigquery/docs/introduction",
        "uri": "https://docs.cloud.google.com/bigquery/docs/introduction",
        "title": "BigQuery overview",
        "dataSource": "docs.cloud.google.com",
        "updateTime": "2025-01-15T12:00:00Z"
      },
      "relevanceScore": 0.92
    }
  ]
}

results 列表中的每个结果都包含以下内容：

parent：文档资源名称（例如 documents/docs.cloud.google.com/bigquery/docs/introduction）。
id：文档中的块标识符（例如 chunk_0）。
content：文档中匹配的文本片段。
document：有关源文档的元数据，例如其 title、uri、dataSource 和 updateTime。
relevanceScore：块与搜索查询的相关性得分，范围为 [0.0, 1.0]。

如需详细了解响应架构和所有可用的元数据字段，请参阅 documents.searchDocumentChunks API 参考文档。

对搜索结果进行分页

当搜索查询返回多个匹配项时，您可以使用分页参数浏览结果集：

pageSize（整数）：指定每页返回的结果数量上限。如果未指定，API 默认返回 5 个结果。允许的最大值为 100；大于 100 的值会强制转换为 100。
pageToken（字符串）：指定在之前的响应中收到的令牌，以提取下一页结果。

请求第一页

如需设置每页大小，请在请求中传递 pageSize 参数：

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&key=$DEVELOPERKNOWLEDGE_API_KEY"

如果有更多结果，响应会包含 nextPageToken：

{
  "results": [
    {
      "parent": "documents/docs.cloud.google.com/bigquery/docs/introduction",
      "id": "chunk_0",
      "content": "BigQuery is a fully managed enterprise data warehouse...",
      "document": {
        "name": "documents/docs.cloud.google.com/bigquery/docs/introduction",
        "uri": "https://docs.cloud.google.com/bigquery/docs/introduction",
        "title": "What is BigQuery?",
        "dataSource": "docs.cloud.google.com",
        "updateTime": "2025-01-15T12:00:00Z",
        "view": "DOCUMENT_VIEW_BASIC"
      },
      "relevanceScore": 0.88
    }
  ],
  "nextPageToken": "CAUQABgB"
}

检索后续页面

在下一次请求中，将 nextPageToken 的值传递给 pageToken 参数：

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&pageToken=CAUQABgB&key=$DEVELOPERKNOWLEDGE_API_KEY"

当您到达最后一页结果时，响应中会省略 nextPageToken。

过滤搜索结果

使用 filter 参数可对搜索结果应用严格过滤条件。过滤表达式会应用于每个块的父文档的元数据。

filter 表达式的长度上限为 500 个字符。

支持的字段

您可以使用以下父文档字段过滤搜索结果：

content_length_bytes（整数）：文档的 content 字段的长度（以字节为单位）。
data_source（字符串）：文档的来源网域，例如 docs.cloud.google.com 或 firebase.google.com。如需查看所有支持的数据源，请参阅语料库参考文档。
update_time（时间戳）：相应文档上次更新时的时间戳。值必须采用 RFC 3339 格式（例如 "2025-01-01T00:00:00Z"）。
uri（字符串）：文档的完整 URI（例如 https://docs.cloud.google.com/bigquery/docs/tables）。

支持的运算符

过滤表达式解析器支持不同的运算符，具体取决于字段的数据类型：

字符串字段（data_source、uri）：支持 =（等于）和 !=（不等于）进行精确的字符串匹配。不支持部分匹配、前缀匹配和正则表达式匹配。
时间戳字段 (update_time)：支持 =、<、<=、> 和 >=。
整数字段 (content_length_bytes)：支持 =、!=、<、<=、> 和 >=。
逻辑运算符：使用 AND、OR 和 NOT（或 -）组合条件。

过滤条件示例

以下示例演示了如何构建过滤表达式。使用 curl 调用 REST API 时，请务必对过滤条件参数进行网址编码或使用 --data-urlencode。

匹配多个数据源

使用 OR 包含来自多个来源的文档：

data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"

curl 请求：

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=database" \
  --data-urlencode 'filter=data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

按时间戳过滤

将比较运算符与 RFC 3339 时间戳搭配使用，可查找在特定日期之后更新的内容：

update_time >= "2025-01-01T00:00:00Z"

curl 请求：

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=BigQuery" \
  --data-urlencode 'filter=update_time >= "2025-01-01T00:00:00Z"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

按内容长度过滤

将比较运算符与 content_length_bytes 搭配使用，可根据文档的字节大小查找文档：

content_length_bytes < 5000

curl 请求：

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=Cloud Storage" \
  --data-urlencode 'filter=content_length_bytes < 5000' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

组合数据源、时间戳和分组

结合使用 AND、OR 和括号 (...)，将结果限制为在指定日期之后更新的特定来源：

(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"

curl 请求：

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=service worker" \
  --data-urlencode 'filter=(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

排除数据源

使用 NOT 或 != 可排除特定来源的结果：

data_source != "firebase.google.com"

curl 请求：

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=authentication" \
  --data-urlencode 'filter=data_source != "firebase.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

使用 `GetDocument` 检索文档

使用 documents.get 方法检索单个文档的完整内容。

资源名称与 URI

在 Developer Knowledge API 中引用文档时，请注意资源名称和 Web URI 之间的区别：

资源名称（parent、name）：格式为 documents/{uri_without_scheme}（例如 documents/docs.cloud.google.com/storage/docs/creating-buckets）。在 GetDocument 中或 BatchGetDocuments 的 names 参数中，将此值作为路径参数传递。
Web URI (uri)：包含方案的完整网址（例如 https://docs.cloud.google.com/storage/docs/creating-buckets）。构建 filter 表达式（例如 uri = "https://docs.cloud.google.com/storage/docs/creating-buckets"）时，请对 uri 字段使用此格式。

以下示例按资源名称检索文档：

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?key=$DEVELOPERKNOWLEDGE_API_KEY"

响应是一个 Document 资源，其中包含元数据和 content 字段中的完整 Markdown 内容。

使用 `BatchGetDocuments` 检索多个文档

使用 documents.batchGet 方法可通过一次 API 调用按名称检索最多 20 个文档。这比发出多个 GetDocument 请求更高效。

以下示例按名称检索两个文档：

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&names=documents/firebase.google.com/docs/firestore/quickstart&key=$DEVELOPERKNOWLEDGE_API_KEY"

响应包含所请求的 Document 资源列表，按您请求的顺序排列。

优化响应载荷

采用 Markdown 格式的文档内容可能很大。如果您的应用只需要元数据（例如网页标题、URI 或时间戳）或特定字段，您可以优化载荷大小，以减少带宽和延迟时间。

使用文档视图

view 参数控制 Document 消息中填充哪些字段。

DocumentView 枚举支持以下值：

DOCUMENT_VIEW_BASIC：仅返回基本元数据字段（name、uri、data_source、title、description、update_time 和 view）。省略 content 字段。
DOCUMENT_VIEW_CONTENT：返回元数据字段以及 Markdown content 字段。这是 GetDocument 和 BatchGetDocuments 的默认值。
DOCUMENT_VIEW_FULL：返回所有文档字段。

如需仅检索文档元数据而不下载大型 Markdown 内容，请设置 view=DOCUMENT_VIEW_BASIC：

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?view=DOCUMENT_VIEW_BASIC&key=$DEVELOPERKNOWLEDGE_API_KEY"

您还可以将 view=DOCUMENT_VIEW_BASIC 与 BatchGetDocuments 搭配使用：

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&names=documents/firebase.google.com/docs/firestore/quickstart&view=DOCUMENT_VIEW_BASIC&key=$DEVELOPERKNOWLEDGE_API_KEY"

使用字段掩码

如需进一步将响应载荷限制为特定字段，请使用标准 Google API fields 查询参数（字段掩码）。

`GetDocument` 中的过滤字段

如需仅检索文档的 title、uri 和 updateTime 字段，请执行以下操作：

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?fields=title,uri,updateTime&key=$DEVELOPERKNOWLEDGE_API_KEY"

`BatchGetDocuments` 中的过滤字段

如需仅检索批次中每个文档的特定字段，请执行以下操作：

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&fields=documents(name,title,uri)&key=$DEVELOPERKNOWLEDGE_API_KEY"

`SearchDocumentChunks` 中的过滤字段

如需仅返回搜索结果中的块 id 和 content、父文档 title 和 uri 以及 nextPageToken，请执行以下操作：

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&fields=results(id,content,document(title,uri)),nextPageToken&key=$DEVELOPERKNOWLEDGE_API_KEY"

处理错误

Developer Knowledge API 会返回标准 HTTP 状态代码。以下功能示例展示了 Developer Knowledge API 中的 HTTP 状态代码及其原因：

400 INVALID_ARGUMENT:
- filter 表达式字符串超过了 500 个字符。
- update_time 时间戳无效（必须使用 RFC 3339 格式）。
- 在 BatchGetDocuments 请求中提供的文档名称超过 20 个。
401 UNAUTHENTICATED：请求缺少 API 密钥或使用的密钥无效。请参阅身份验证。
404 NOT_FOUND：所请求的文档名称不存在，或者属于未包含在语料库中的网域。
429 RESOURCE_EXHAUSTED：项目已超出其配额。请参阅配额和限制。

后续步骤

请参阅依托数据生成回答。
了解如何在 Python、Node.js、Go 或 Java 中使用客户端库。
浏览语料库参考，查看所有受支持的文档来源。
如需了解完整的方法规范，请参阅 REST API 参考文档。
查看配额和限制，了解 API 速率限制和配额。

搜索和检索文档 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

使用 SearchDocumentChunks 搜索文档

对搜索结果进行分页

请求第一页

检索后续页面

过滤搜索结果

支持的字段

支持的运算符

过滤条件示例

匹配多个数据源

按时间戳过滤

按内容长度过滤

组合数据源、时间戳和分组

排除数据源

使用 GetDocument 检索文档

资源名称与 URI

使用 BatchGetDocuments 检索多个文档

优化响应载荷

使用文档视图

使用字段掩码

GetDocument 中的过滤字段

BatchGetDocuments 中的过滤字段

SearchDocumentChunks 中的过滤字段

处理错误

后续步骤

搜索和检索文档

使用 `SearchDocumentChunks` 搜索文档

使用 `GetDocument` 检索文档

使用 `BatchGetDocuments` 检索多个文档

`GetDocument` 中的过滤字段

`BatchGetDocuments` 中的过滤字段

`SearchDocumentChunks` 中的过滤字段