本指南提供了有关如何使用 Developer Knowledge API 的函数的示例：搜索文档、检索单个文档以及批量检索多个文档。
在开始之前，请确保您已启用该 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"
您可以使用 pageSize 等参数来优化搜索结果，以限制每页的结果数，并使用 pageToken 来检索后续页面。
过滤搜索结果
使用 filter 参数对搜索结果应用严格的过滤条件。过滤条件应用于与搜索结果块关联的文档的元数据。
支持过滤的字段：
data_source(STRING)：文档的来源，例如docs.cloud.google.com。update_time(TIMESTAMP)：文档上次更新时的时间戳。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。
以下示例搜索与“BigQuery”匹配的文档，并将结果限制为来自 docs.cloud.google.com 的文档：
curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&filter=data_source%3D%22docs.cloud.google.com%22&key=$DEVELOPERKNOWLEDGE_API_KEY"
使用 GetDocument 检索文档
使用 documents.get
方法检索单个文档的完整内容。
以下示例检索名称为 documents/DOCUMENT_ID 的文档：
curl "https://developerknowledge.googleapis.com/v1/documents:get?name=documents/DOCUMENT_ID&key=$DEVELOPERKNOWLEDGE_API_KEY"
响应是完整的
Document
资源，包括 content 字段。
使用 BatchGetDocuments 检索多个文档
使用 documents.batchGet
方法，通过单个 API 调用按名称检索最多 100 个文档。这比发出多个 GetDocument 请求更高效。
以下示例按名称检索两个文档：
curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/DOCUMENT_ID_1&names=documents/DOCUMENT_ID_2&key=$DEVELOPERKNOWLEDGE_API_KEY"
响应包含所请求的
Document
资源列表。
请求部分响应
检索文档（GetDocument、BatchGetDocuments）或搜索
（SearchDocumentChunks）时，文档内容可能很大。如果您只需要元数据，则可以请求部分响应，以减少网络有效负载和延迟时间。
使用 DocumentView
对于 GetDocument 和 BatchGetDocuments，您可以使用 view 参数来
控制是返回完整内容还是仅返回元数据。
将 view=DOCUMENT_VIEW_BASIC 设置为仅返回基本元数据字段（name、
uri、data_source、title、description、update_time、view），并排除
content 字段。
以下示例仅检索文档的元数据：
curl "https://developerknowledge.googleapis.com/v1/documents/DOCUMENT_ID?view=DOCUMENT_VIEW_BASIC&key=$DEVELOPERKNOWLEDGE_API_KEY"
使用字段掩码
如需更精细地控制返回哪些字段，您可以使用字段掩码。按照 AIP-157，
您可以传递 fields 查询参数来指定要包含在响应中的
字段的逗号分隔列表。
示例：对 GetDocument 请求特定元数据字段
以下示例仅检索文档的 name、title 和 uri：
curl "https://developerknowledge.googleapis.com/v1/documents/DOCUMENT_ID?fields=name,title,uri&key=$DEVELOPERKNOWLEDGE_API_KEY"
示例：在 SearchDocumentChunks 中请求特定字段
以下示例搜索与“BigQuery”匹配的文档，并仅返回每个块的 id、父文档的 name、title 和 uri，以及 nextPageToken：
curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&fields=results(id,document(name,title,uri)),nextPageToken&key=$DEVELOPERKNOWLEDGE_API_KEY"