Developer Knowledge API

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

總覽

Developer Knowledge API 的設計宗旨是成為 Google 開發人員說明文件的正規來源，提供機器可讀取的存取權。提供搜尋及擷取文件，以及回答查詢的功能：

• SearchDocumentChunks 根據查詢內容找出相關網頁 URI 和內容摘要。
• GetDocument 或 BatchGetDocuments，擷取搜尋結果的完整內容。
• AnswerQuery，根據文件語料庫中的查詢生成答案。

Developer Knowledge API 支援搜尋及擷取文件頁面，並以非結構化 Markdown 內容的形式呈現。可搜尋內容的語料庫列於「語料庫參考資料」。

使用開發人員知識的多種方式

視工作流程而定，您可以透過下列介面存取開發人員知識：

• REST API 和 RPC API：直接呼叫 HTTP 或 gRPC 端點。如需方法規格，請參閱 REST 參考資料和 RPC 參考資料。
• 用戶端程式庫：使用 C#、Go、Java、Node.js 和 TypeScript、PHP、Python 和 Ruby 的官方用戶端程式庫，將 Developer Knowledge API 整合至應用程式。
• Google Cloud CLI (gcloud)：從終端機執行 gcloud developer-knowledge 指令，搜尋文件區塊、擷取 Markdown 內容及生成答案。
• Developer Knowledge MCP 伺服器：使用 Model Context Protocol (MCP) 工具 (search_documents、get_documents 和 answer_query)，將 AI 程式設計助理或代理連結至 Google 的說明文件。請參閱 MCP 參考資料。

提示： 如果您使用 AI 程式開發輔助，請執行 npx skills add google/skills --skill retrieving-developer-knowledge，安裝 retrieving-developer-knowledge 代理技能。這項技能會為助理提供內建指令，說明要選取哪個 Developer Knowledge MCP 伺服器工具、如何處理錯誤，以及在 MCP 伺服器無法使用時，如何使用 curl 呼叫 REST API。詳情請參閱「使用 Developer Knowledge 代理程式技能」。

選擇 API 或 MCP 伺服器

Developer Knowledge API 和 Developer Knowledge MCP 伺服器適用於不同的整合需求：

• 在下列情況下，請使用 Developer Knowledge API、用戶端程式庫或 gcloud CLI：
  • 專案未使用 AI 代理。
  • 您想為代理定義自訂工具或工具集。
  • 您想先處理或合併結果，再傳遞至模型 (例如，先檢查文件位元組長度，再擷取完整內容)。
  • 您必須篩選搜尋結果 (例如依 data_source 或 update_time 篩選)，或套用欄位遮罩。
• 在下列情況下，請使用 Developer Knowledge MCP 伺服器和代理技能：
  • 您想連結 AI 程式開發輔助或代理，但不想編寫自訂工具定義和說明。
  • 您希望 Developer Knowledge MCP 伺服器新增功能時，能自動更新。
  • 您不需要對搜尋結果進行自訂中繼資料篩選。

啟用 API

如要使用 Developer Knowledge API，您必須先為 Google Cloud 專案啟用該 API。

提示： 如果您沒有 Google Cloud 專案，請按照 Google Cloud 或 Firebase 的操作說明建立專案。

1. 在 Google API 程式庫中，開啟 Developer Knowledge API 頁面。
2. 確認您已選取要使用 API 的正確專案。
3. 按一下「啟用」。啟用或使用 API 時，不需要特定 IAM 角色。

驗證

您可以使用下列其中一種方法，驗證對 Developer Knowledge API 發出的要求：

• API 金鑰：使用 key 查詢參數或 X-Goog-Api-Key 標頭，驗證直接 REST 要求或開發人員知識 MCP 伺服器。
• 應用程式預設憑證 (ADC)、OAuth 2.0 或服務帳戶：使用官方用戶端程式庫或正式版工作流程時，驗證要求。如要進一步瞭解如何設定憑證，請參閱應用程式預設憑證說明文件。
• 使用者憑證 (gcloud CLI)：使用 gcloud auth login 登入 Google Cloud 帳戶，驗證 CLI 要求。如需設定操作說明，請參閱 gcloud CLI 快速入門導覽課程。

OAuth 範圍

使用 OAuth 2.0 或服務帳戶驗證時，Developer Knowledge API 和 Developer Knowledge MCP 伺服器接受下列 OAuth 範圍：

• https://www.googleapis.com/auth/cloud-platform：應用程式預設憑證 (ADC)、gcloud CLI 和官方 Google Cloud 用戶端程式庫使用的預設範圍。
• https://www.googleapis.com/auth/devprofiles.full_control：用於使用者 OAuth 2.0 同意流程和 MCP 伺服器整合的範圍。
• https://www.googleapis.com/auth/developerprofiles.readonly：服務帳戶和不需要使用者 OAuth 同意畫面的憑證支援唯讀範圍。

不記名權杖授權

如要使用服務帳戶或 OAuth 2.0 存取權杖驗證直接 REST 要求，請在 Authorization: Bearer 標頭中傳遞權杖，並在 X-Goog-User-Project 中指定帳單專案：

export ACCESS_TOKEN=$(gcloud auth print-access-token)
curl -X POST "https://developerknowledge.googleapis.com/v1:answerQuery" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Goog-User-Project: PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"query": "How do I create a BigQuery dataset?"}'

將 PROJECT_ID 替換為您的 Google Cloud 專案 ID。

如果是 Python、Node.js、Go 和 Java 應用程式，官方用戶端程式庫會自動處理應用程式預設憑證 (ADC) 和權杖重新整理作業。如需範例，請參閱「搭配使用用戶端程式庫與 Developer Knowledge API」。

隨附文件

如要瞭解 API 搜尋哪些文件，請參閱語料庫參考資料。

Developer Knowledge API 旨在提供最新的 Google 開發人員說明文件。我們的目標是在發布內容後 48 小時內重新建立索引，以便在 2 個工作天內提供新版或更新版文件。

已知限制

• Markdown 品質：Markdown 是從來源 HTML 產生。可能會有不一致或格式問題。
• 內容範圍：僅包含語料庫參考資料中的公開頁面。不包括來自 GitHub、OSS 網站、網誌或 YouTube 等其他來源的內容。