Google 會運用 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：文件中的區塊 ID (例如 chunk_0)。
content：文件中相符的文字片段。
document：來源文件的中繼資料，例如 title、uri、dataSource 和 updateTime。
relevanceScore：區塊與搜尋查詢的相關分數，範圍為 [0.0, 1.0]。

如要進一步瞭解回覆結構定義和所有可用的中繼資料欄位，請參閱 documents.searchDocumentChunks API 參考資料。

搜尋結果分頁

如果搜尋查詢傳回多個相符結果，您可以使用分頁參數瀏覽結果集：

--page-size (gcloud CLI) 或 pageSize (整數)：指定每頁要傳回的結果數量上限。如未指定，API 預設會傳回五個結果。允許的最大值為 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 中參照文件時，請注意資源名稱和網頁 URI 的差異：

資源名稱 (parent、name)：格式為 documents/{uri_without_scheme} (例如 documents/docs.cloud.google.com/storage/docs/creating-buckets)。在 gcloud developer-knowledge documents describe 中將這個值做為位置引數傳遞，或在 GetDocument 中做為路徑參數，或在 BatchGetDocuments 的 names 參數中傳遞。
網頁 URI (uri)：完整網頁網址，包括配置 (例如 https://docs.cloud.google.com/storage/docs/creating-buckets)。建構 --query-filter 或 filter 運算式時，請使用 uri 欄位的這個格式 (例如 uri = "https://docs.cloud.google.com/storage/docs/creating-buckets")。

使用 `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：傳回所有文件欄位。

如要只擷取文件 metadata，而不下載大型 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"

你也可以搭配 BatchGetDocuments 使用 view=DOCUMENT_VIEW_BASIC：

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 格式)。
- 要求中提供超過 20 個文件名稱。BatchGetDocuments
401 UNAUTHENTICATED：要求缺少 API 金鑰或使用無效金鑰。請參閱「驗證」。
404 NOT_FOUND：要求的檔案名稱不存在，或屬於語料庫未收錄的網域。
429 RESOURCE_EXHAUSTED：專案超出配額。請參閱「配額與限制」。

後續步驟

請參閱「根據說明文件生成答案」。
連線至 Developer Knowledge 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`」中的欄位