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

搜索和检索文档

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

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

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

在开始之前，请为首选工具设置环境：

gcloud

安装并配置 gcloud CLI，然后启用 Developer Knowledge API。

REST

启用该 API 并生成 Developer Knowledge API 密钥。然后，将密钥保存到环境变量中：

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

将 YOUR_API_KEY 替换为您的 Developer Knowledge API 密钥。

搜索文档

使用 gcloud developer-knowledge documents search-chunks 命令或 documents.searchDocumentChunks REST 方法查找与查询字符串匹配的文档块。结果包含匹配文档中的内容块，以及可用于检索这些文档完整内容的 parent 参考。

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

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery"

REST

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]。

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

对搜索结果进行分页

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

--page-size (gcloud CLI) 或 pageSize（整数）：指定每页返回的最大结果数。如果未指定，则 API 默认为返回 5 个结果。允许的最大值为 100；大于 100 的值会被强制转换为 100。
--limit (gcloud CLI) 或 pageToken（字符串）：在 gcloud CLI 中，使用 --limit 控制跨页面返回的结果总数。在 REST 请求中，传递之前响应中收到的 pageToken 值，以提取下一页结果。

gcloud

传递 --page-size 和 --limit 标志，以控制每页的结果数和返回的结果总数：

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery" \
  --page-size=5 \
  --limit=10

REST

如需请求第一页，请在请求中传递 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。

过滤搜索结果

使用 gcloud CLI 中的 --query-filter 标志或 REST 请求中的 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（或 -）组合条件。

过滤条件示例

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

匹配单个数据源

将搜索结果限制为单个文档网域：

data_source = "docs.cloud.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="Cloud Functions deployment" \
  --query-filter='data_source = "docs.cloud.google.com"'

REST

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

匹配多个数据源

使用 OR 纳入来自多个来源的文档：

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

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="database" \
  --query-filter='data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"'

REST

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"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery" \
  --query-filter='update_time >= "2025-01-01T00:00:00Z"'

REST

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

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="Cloud Storage" \
  --query-filter='content_length_bytes < 5000'

REST

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"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="service worker" \
  --query-filter='(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"'

REST

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"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="authentication" \
  --query-filter='data_source != "firebase.google.com"'

REST

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"

检索文档

使用 gcloud developer-knowledge documents describe 命令或 documents.get REST 方法可检索单个文档的完整内容。

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

gcloud

gcloud developer-knowledge documents describe \
  documents/docs.cloud.google.com/storage/docs/creating-buckets

REST

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

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

资源名称与 URI

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

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

使用 `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 或时间戳）或特定字段，您可以优化载荷大小，以减少带宽和延迟时间。

使用文档视图

gcloud CLI 中的 --view 标志或 REST 请求中的 view 参数用于控制在 Document 消息中填充哪些字段。

--view 标志和 DocumentView 枚举支持以下值：

--view=basic (gcloud CLI) 或 DOCUMENT_VIEW_BASIC：仅返回基本元数据字段（name、uri、dataSource、title、description、updateTime 和 view）。系统会省略 content 字段。
--view=content (gcloud CLI) 或 DOCUMENT_VIEW_CONTENT：返回元数据字段以及 Markdown content 字段。这是 gcloud developer-knowledge documents describe、GetDocument 和 BatchGetDocuments 的默认值。
--view=full (gcloud CLI) 或 DOCUMENT_VIEW_FULL：返回所有文档字段。

如需仅检索文档元数据而不下载大型 Markdown 内容，请指定基本文档视图：

gcloud

gcloud developer-knowledge documents describe \
  documents/docs.cloud.google.com/storage/docs/creating-buckets \
  --view=basic

REST

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：项目已超出其配额。请参阅配额和限制。

后续步骤

请参阅根据文档生成答案。
连接到开发者知识 MCP 服务器并安装 retrieving-developer-knowledge 智能体技能，以帮助 AI 编码助理搜索和阅读官方文档。
了解如何在 Python、Node.js、Go 或 Java 中使用客户端库。
了解如何使用 gcloud CLI。
浏览语料库参考，查看所有受支持的文档来源。
如需了解完整的方法规范，请参阅 REST API 参考文档。
查看配额和限制，了解 API 速率限制和配额。

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

gcloud

REST

搜索文档

gcloud

REST

对搜索结果进行分页

gcloud

REST

过滤搜索结果

支持的字段

支持的运算符

过滤条件示例

匹配单个数据源

gcloud

REST

匹配多个数据源

gcloud

REST

按时间戳过滤

gcloud

REST

按内容长度过滤

gcloud

REST

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

gcloud

REST

排除数据源

gcloud

REST

检索文档

gcloud

REST

资源名称与 URI

使用 BatchGetDocuments 检索多个文档

优化响应载荷

使用文档视图

gcloud

REST

使用字段掩码

GetDocument 中的过滤字段

BatchGetDocuments 中的过滤字段

SearchDocumentChunks 中的过滤字段

处理错误

后续步骤

搜索和检索文档

使用 `BatchGetDocuments` 检索多个文档

`GetDocument` 中的过滤字段

`BatchGetDocuments` 中的过滤字段

`SearchDocumentChunks` 中的过滤字段