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

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

將搜尋結果分頁

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

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

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

以下範例會依資源名稱擷取文件：

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"

您也可以搭配 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：專案超出配額。請參閱「配額與限制」。

後續步驟

請參閱「根據資料生成內容來回答查詢」。
瞭解如何使用 Python、Node.js、Go 或 Java 的用戶端程式庫。
瀏覽語料庫參考資料，查看所有支援的文件來源。
如需完整的方法規格，請參閱 REST API 參考資料。
查看 API 速率限制和配額的配額與限制。

搜尋及擷取文件 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

使用「SearchDocumentChunks」搜尋文件

將搜尋結果分頁

要求第一頁

擷取後續頁面

篩選搜尋結果

支援的欄位

支援的運算子

篩選器範例

比對多個資料來源

依時間戳記篩選

依內容長度篩選

合併資料來源、時間戳記和分組

排除資料來源

使用 GetDocument 擷取文件

資源名稱與 URI

使用 BatchGetDocuments 擷取多份文件

最佳化回應酬載

使用文件檢視畫面

使用欄位遮罩

GetDocument 中的篩選欄位

BatchGetDocuments 中的篩選欄位

SearchDocumentChunks 中的篩選欄位

處理錯誤

後續步驟

搜尋及擷取文件

使用「`SearchDocumentChunks`」搜尋文件

使用 `GetDocument` 擷取文件

使用 `BatchGetDocuments` 擷取多份文件

`GetDocument` 中的篩選欄位

`BatchGetDocuments` 中的篩選欄位

`SearchDocumentChunks` 中的篩選欄位