Developer Knowledge REST API 回退指南在 MCP 工具不可用时如何可靠检索 Google 官方开发者文档【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills导读本文是retrieving-developer-knowledgeSkill 的 REST API 回退方案完整指南。当运行环境中 Developer Knowledge MCP 服务器的search_documents、get_documents、answer_query工具未被声明或不可用时必须改用 Developer Knowledge REST APIhttps://developerknowledge.googleapis.com检索并获取官方文档。读完本文你将掌握两种认证方式OAuth 2.0 令牌与 API Key的优先级与切换时机、四个核心端点answerQuery、searchDocumentChunks、get、batchGet的请求格式与适用场景以及如何对返回的 JSON 响应进行权威性排序与安全合成从而在 Agent 环境中实现不猜测命令、不依赖未经核验的预训练记忆的可靠文档检索。为什么需要 REST API 回退在 retrieving-developer-knowledge Skill 的正常工作流中首选路径是调用 Developer Knowledge MCP 服务器提供的三个工具answer_query(query...)面向概念讲解、架构对比、产品选型概览和多步骤工作流search_documents(query..., page_size5)面向细粒度 CLI 标志、精确语法、参数名和 IAM 权限service.resource.verb格式get_documents(names[documents/{uri_without_scheme}])按资源名获取完整文档页面。然而MCP 服务器的已声明并不等于已连接。部分客户端无法与该服务器完成 MCP 握手尽管插件声明了工具运行时却完全暴露不出任何工具。此时不应假设检索失败而应把工具缺失视为正常情况改用 REST API 回退。这正是本文档存在的意义。从仓库中的插件配置可以印证 MCP 服务器的真实形态mcp.json将其声明为streamable-http类型URL 为https://developerknowledge.googleapis.com/mcp见 mcp.jsongemini-extension.json进一步标注了authProviderType: google_credentials见 gemini-extension.json说明该服务的认证与 Google Cloud 凭据体系深度绑定。mcp_config.json中则记录了通用的serverUrl配置见 mcp_config.json。服务概览Base URL、版本与输出格式在使用任何端点之前先明确服务的三个基本事实项目值说明Base URLhttps://developerknowledge.googleapis.com所有 REST 请求的服务根地址API 版本v1GA与v1alpha生产环境使用v1v1alpha用于预发布能力验证输出格式JSON内容块为 Markdown检索到的文档内容以 Markdown 片段返回便于直接嵌入回答REST API 检索的语料范围与 MCP 服务器完全一致覆盖 Google Cloud 与基础设施docs.cloud.google.com、cloud.google.com、docs.apigee.com、firebase.google.com、AI 与机器学习ai.google.dev、adk.dev、antigravity.google、geminicli.com、www.tensorflow.org、移动/Web/客户端平台developer.android.com、docs.flutter.dev、dart.dev、developer.chrome.com、web.dev以及语言与生态go.dev、developers.google.com等。完整域列表见 supported-domains.md。认证协议按优先级解析凭据发起 REST 请求之前必须按以下优先级解析认证凭据。1. OAuth 2.0 访问令牌推荐如果环境中存在gcloud或 ambient Google Cloud 凭据无需安装或配置任何额外组件# 获取访问令牌 ACCESS_TOKEN$(gcloud auth print-access-token) # 通过 Authorization 头传递 -H Authorization: Bearer ${ACCESS_TOKEN} # 同时传递配额项目quota project -H X-Goog-User-Project: $(gcloud config get-value project 2/dev/null)401/403 失败时的切换策略如果认证失败收到 401、403 或任何凭据错误说明当前账号持有的令牌是 API 不接受的那一种。此时应将gcloud auth print-access-token替换为gcloud auth application-default print-access-token后重试。API 接受哪种令牌取决于环境当初的认证方式——把认证错误当作切换凭据来源的触发条件而不是当作检索失败。2. API Key如果环境中已配置 API Key检查DEVELOPERKNOWLEDGE_API_KEY或GOOGLE_API_KEY环境变量。两种传递方式等价# 方式一查询参数 ?key${DEVELOPERKNOWLEDGE_API_KEY} # 方式二请求头 -H X-Goog-Api-Key: ${DEVELOPERKNOWLEDGE_API_KEY}两种凭据的尝试顺序是确定的先用 OAuth 令牌推荐、零配置失败后再切换 Application Default Credential最后才考虑 API Key。SKILL.md 中给出的完整 OAuth 示例命令见 SKILL.md同时携带Authorization、X-Goog-User-Project与Content-Type三个请求头是生产环境的标准写法。四个核心端点与操作详解1.answerQuery宽泛概念问答与多步骤指南适用场景概念指南、架构对比、产品总览、how-to 工作流。方法 路径POST https://developerknowledge.googleapis.com/v1:answerQuery请求头Content-Type: application/json认证使用X-Goog-Api-Key: ${DEVELOPERKNOWLEDGE_API_KEY}或查询参数?key...请求体{ query: How do I configure public read access on a Cloud Storage bucket? }curl 示例curl -s -X POST https://developerknowledge.googleapis.com/v1:answerQuery?key${DEVELOPERKNOWLEDGE_API_KEY} \ -H Content-Type: application/json \ -d {query: How do I create a custom metric in Cloud Logging?}从响应结构看answerQuery执行的是服务端 RAG检索增强生成返回的 JSON 中包含合成后的answer字段与来源引用相当于把searchDocumentChunks的检索能力和大模型合成能力封装在一个请求中。2.searchDocumentChunks精确语法、IAM 权限与 CLI 标志适用场景查找具体的 CLI 标志、IAM 权限service.resource.verb格式、API 参数名或代码片段。这是与 MCP 工具search_documents对应的 REST 形态。方法 路径GET https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks查询参数参数必选说明query是URL 编码的搜索词例如gcloudloggingmetricscreatefilter否按域过滤例如data_source docs.cloud.google.compageSize否返回的块数量上限默认 10key是Key 认证时API Keycurl 示例curl -s https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?querygcloudloggingmetricscreatekey${DEVELOPERKNOWLEDGE_API_KEY}查询技巧与 MCP 工具的使用规范一致应使用 25 个聚焦关键词如cloud run filestore nfs mount gcloud而不是完整的对话式句子检索精度更高。每个返回块包含content字段Markdown 文本块和parentURI 字段指向所属文档页parent可直接用于后续的get请求。3.get按资源名获取完整文档适用场景已经知道文档的 parent 资源名或已知 URI 时获取该文档页的完整 Markdown 内容。方法 路径GET https://developerknowledge.googleapis.com/v1/documents/{URI_WITHOUT_SCHEME}资源名格式documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run即去掉https://前缀后的完整路径curl 示例curl -s https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run?key${DEVELOPERKNOWLEDGE_API_KEY}资源名的构造规则与 MCP 工具get_documents完全一致例如对于 parent URIhttps://cloud.google.com/run/docs/deploying资源名为documents/cloud.google.com/run/docs/deploying见 mcp-usage.md。注意路径中的域名部分要保留docs.cloud.google.com与cloud.google.com的区别它们指向不同的文档语料。4.batchGet单次往返批量获取多个文档适用场景一次请求同时获取多个文档页面减少往返次数。方法 路径POST https://developerknowledge.googleapis.com/v1/documents:batchGet请求体{ names: [ documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run, documents/docs.cloud.google.com/run/docs/configuring/services/environment-variables ] }curl 示例curl -s -X POST https://developerknowledge.googleapis.com/v1/documents:batchGet?key${DEVELOPERKNOWLEDGE_API_KEY} \ -H Content-Type: application/json \ -d {names: [documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run]}names数组可同时携带多个资源名适合回答需要交叉引用多篇文档的复合技术问题。响应处理与合成准则拿到 REST 响应后遵循三条处理准则1. 提取内容Extract Content解析返回的 JSON 载荷按端点不同提取对应字段answerQuery→answer字段searchDocumentChunks→documentChunks[].content字段get/batchGet→document.content字段。2. 权威性优先Authoritative Precedence将检索到的官方文档视为 100% 权威凌驾于任何预训练记忆之上。文档中的 CLI 标志、复合键如locationIP:PATH、IAM 权限字符串等一律按官方格式输出不得用记忆中的默认值替代。3. 上下文防御Context Defense只合成解决当前问题所需的技术方案代码片段、配置或 CLI 命令不要原样倾倒原始 API 响应包。最终回答应当是完整、自包含、可执行的解决方案命令带齐所需标志与占位符如PROJECT_ID、SERVICE_NAME、REGION。检索失败的处理纪律检索失败是一个必须显式处理的边界情况而非静默忽略的异常。以下情形即使工具本身未报错也属于失败的查找FAILED lookupPERMISSION_DENIEDUNAUTHENTICATEDHTTP 401 或 403空结果集任何错误载荷。处理规则见 SKILL.md收到响应≠得到答案先确认查找是否成功查找失败时不得假装成功后再作答换另一种传输方式MCP → REST 或 REST → MCP再试一次如果两种方式都失败向用户明确说明无法连接到 Developer Knowledge正在不带它作答最糟糕的结局是把自己回忆出的文档当作检索结果呈现——因为回复中没有任何东西能将它与真实查找区分开。总结回退流程速查完整回退流程可归纳为一条决策链检查工具可用性MCP 工具search_documents、get_documents、answer_query是否真实暴露已声明但未连接时视为缺失。选择端点概念问答/多步骤指南 →answerQuery精确语法/IAM/标志 →searchDocumentChunks已知资源名取全文 →get多文档一次性获取 →batchGet。选择认证优先gcloud auth print-access-tokenX-Goog-User-Project失败则换gcloud auth application-default print-access-token最后用?key${DEVELOPERKNOWLEDGE_API_KEY}。验证并合成确认查找成功无 401/403/空结果解析对应 JSON 字段以文档为权威输出完整可执行方案。延伸阅读REST API 回退指南本文档原始出处Skill 主文档与工作流定义MCP 工具使用与 API 细节支持的开发者文档域列表google-cloud-developer 插件 MCP 服务器声明【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考