Package google.developers.knowledge.v1

索引

DeveloperKnowledge

透過 Developer Knowledge API，您可以透過程式輔助方式存取 Google 的公開開發人員說明文件，將這個知識庫整合至自己的應用程式和工作流程。

這項 API 的設計宗旨，是成為 Google 開發人員說明文件的標準來源，方便以機器可讀格式存取。

一般來說，使用案例是先透過 DeveloperKnowledge.SearchDocumentChunks 根據查詢內容尋找相關網頁 URI，然後使用 DeveloperKnowledge.GetDocument 或 DeveloperKnowledge.BatchGetDocuments 擷取熱門結果的完整內容。

所有文件內容都以 Markdown 格式提供。

BatchGetDocuments

rpc BatchGetDocuments(BatchGetDocumentsRequest) returns (BatchGetDocumentsResponse)

擷取多份文件，每份文件都包含完整的 Markdown 內容。

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/devprofiles.full_control
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱OAuth 2.0 Overview。
GetDocument

rpc GetDocument(GetDocumentRequest) returns (Document)

擷取單一文件及其完整 Markdown 內容。

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/devprofiles.full_control
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱OAuth 2.0 Overview。
SearchDocumentChunks

rpc SearchDocumentChunks(SearchDocumentChunksRequest) returns (SearchDocumentChunksResponse)

在 Google 的開發人員說明文件中搜尋開發人員知識。根據使用者的查詢傳回 DocumentChunk。同一個 Document 可能會有多個區塊。如要擷取完整文件，請搭配 SearchDocumentChunksResponse.results 中傳回的 DocumentChunk.parent 使用 DeveloperKnowledge.GetDocument 或 DeveloperKnowledge.BatchGetDocuments。

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/devprofiles.full_control
  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱OAuth 2.0 Overview。

BatchGetDocumentsRequest

DeveloperKnowledge.BatchGetDocuments 的要求訊息。

欄位
names[]

string

必填。指定要擷取的檔案名稱。批次作業最多可擷取 20 份文件。系統傳回文件的順序與要求中的 names 相同。

格式：documents/{uri_without_scheme} 範例：documents/docs.cloud.google.com/storage/docs/creating-buckets
view

DocumentView

(選用步驟) 指定文件的 DocumentView。如未指定，DeveloperKnowledge.BatchGetDocuments 預設為 DOCUMENT_VIEW_CONTENT。

BatchGetDocumentsResponse

DeveloperKnowledge.BatchGetDocuments 的回應訊息。

欄位
documents[]

Document

內含要求的文件。

文件

Document 代表開發人員知識主體中的一段內容。

欄位
name

string

ID。包含文件的資源名稱。格式：documents/{uri_without_scheme} 範例：documents/docs.cloud.google.com/storage/docs/creating-buckets
uri

string

僅供輸出。提供內容的 URI，例如 docs.cloud.google.com/storage/docs/creating-buckets。
content

string

僅供輸出。包含 Markdown 格式的文件完整內容。
description

string

僅供輸出。提供文件說明。
data_source

string

僅供輸出。指定文件的資料來源。資料來源範例：firebase.google.com
title

string

僅供輸出。提供文件標題。
update_time

Timestamp

僅供輸出。代表文件內容或中繼資料上次更新的時間戳記。
view

DocumentView

僅供輸出。指定文件的 DocumentView。

DocumentChunk

DocumentChunk 代表 DeveloperKnowledge 語料庫中的 Document 內容。如要擷取整份文件內容，請將 parent 傳遞至 DeveloperKnowledge.GetDocument 或 DeveloperKnowledge.BatchGetDocuments。

欄位
parent

string

僅供輸出。包含這個區塊所屬文件的資源名稱。格式：documents/{uri_without_scheme} 範例：documents/docs.cloud.google.com/storage/docs/creating-buckets
id

string

僅供輸出。指定文件內這個區塊的 ID。區塊 ID 在文件中不得重複，但不同文件可以重複使用。區塊 ID 不穩定，可能會隨著時間而改變。
content

string

僅供輸出。包含文件區塊的內容。
document

Document

僅供輸出。代表這個區塊所屬 Document 的中繼資料。這則 Document 訊息的 DocumentView 會設為 DOCUMENT_VIEW_BASIC。為方便起見，這裡也包含這項資訊，因此如果用戶端只需要中繼資料欄位，就不必呼叫 DeveloperKnowledge.GetDocument 或 DeveloperKnowledge.BatchGetDocuments。否則，用戶端應使用 DeveloperKnowledge.GetDocument 或 DeveloperKnowledge.BatchGetDocuments 擷取完整文件內容。

DocumentView

指定要納入 Document 的哪些欄位。

列舉
DOCUMENT_VIEW_UNSPECIFIED 預設 / 未設定值。如未指定 DocumentView，請參閱各個 API 方法的預設值。
DOCUMENT_VIEW_BASIC

僅包含基本中繼資料欄位：- name - uri - data_source - title - description - update_time - view

這是 DeveloperKnowledge.SearchDocumentChunks 的預設檢視畫面。
DOCUMENT_VIEW_FULL 包含所有 Document 欄位。
DOCUMENT_VIEW_CONTENT

包括 DOCUMENT_VIEW_BASIC 欄位和 content 欄位。

這是 DeveloperKnowledge.GetDocument 和 DeveloperKnowledge.BatchGetDocuments 的預設檢視畫面。

GetDocumentRequest

DeveloperKnowledge.GetDocument 的要求訊息。

欄位
name

string

必填。指定要擷取的文件名稱。格式：documents/{uri_without_scheme} 範例：documents/docs.cloud.google.com/storage/docs/creating-buckets
view

DocumentView

(選用步驟) 指定文件的 DocumentView。如未指定，DeveloperKnowledge.GetDocument 預設為 DOCUMENT_VIEW_CONTENT。

SearchDocumentChunksRequest

DeveloperKnowledge.SearchDocumentChunks 的要求訊息。

欄位
query

string

必填。提供使用者提供的原始查詢字串，例如「如何建立 Cloud Storage bucket？」。
page_size

int32

(選用步驟) 指定要傳回的結果數上限。服務傳回的產品數量可能會少於這個值。

如未指定，最多將傳回 5 個結果。

最大值為 20；超過 20 的值會導致 INVALID_ARGUMENT 錯誤。
page_token

string

(選用步驟) 包含接收自前一個 SearchDocumentChunks 呼叫的網頁權杖。提供此項目即可擷取後續網頁。
filter

string

(選用步驟) 對搜尋結果套用嚴格篩選器。運算式支援 https://google.aip.dev/160 中說明的語法子集。

雖然 SearchDocumentChunks 會傳回 DocumentChunk，但篩選器會套用至 DocumentChunk.document 欄位。

支援篩選的欄位：

  • data_source (STRING)：文件來源，例如 docs.cloud.google.com。如要查看語料庫中的完整資料來源清單，請前往 https://developers.google.com/knowledge/reference/corpus-reference。
  • update_time (TIMESTAMP)：文件上次有意義更新的時間戳記。有意義的更新是指變更文件的 Markdown 內容或中繼資料。
  • 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。使用括號明確分組，以決定優先順序。

範例：

  • data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"
  • data_source != "firebase.google.com"
  • update_time < "2024-01-01T00:00:00Z"
  • update_time >= "2025-01-22T00:00:00Z" AND (data_source = "developer.chrome.com" OR data_source = "web.dev")
  • uri = "https://docs.cloud.google.com/release-notes"

filter 字串不得超過 500 個字元，否則會導致 INVALID_ARGUMENT 錯誤。

SearchDocumentChunksResponse

DeveloperKnowledge.SearchDocumentChunks 的回應訊息。

欄位
results[]

DocumentChunk

包含指定查詢的搜尋結果。這份清單中的每個 DocumentChunk 都包含與搜尋查詢相關的內容摘要。使用每個結果的 DocumentChunk.parent 欄位搭配 DeveloperKnowledge.GetDocument 或 DeveloperKnowledge.BatchGetDocuments，即可擷取完整的文件內容。
next_page_token

string

(選用步驟) 提供可做為 page_token 傳送的權杖，用於擷取後續網頁。如果省略這個欄位，就不會有後續頁面。