API Developer Knowledge

A API Developer Knowledge oferece acesso programático à documentação para desenvolvedores pública do Google, permitindo que você integre essa base de conhecimento aos seus aplicativos e fluxos de trabalho.

Visão geral

A API Developer Knowledge foi projetada para ser a fonte canônica de acesso legível por máquina à documentação para desenvolvedores do Google. Ela oferece funções para pesquisar e recuperar documentos e responder a consultas:

• SearchDocumentChunks para encontrar URIs de páginas e snippets de conteúdo relevantes com base em uma consulta.
• GetDocument ou BatchGetDocuments para buscar o conteúdo completo dos resultados da pesquisa.
• AnswerQuery para gerar respostas a consultas extraídas do corpus de documentação.

A API Developer Knowledge oferece suporte à pesquisa e recuperação de páginas de documentação como conteúdo Markdown não estruturado. O corpus de conteúdo pesquisável está listado em a referência do corpus.

Maneiras de usar o Developer Knowledge

Você pode acessar o Developer Knowledge pelas seguintes plataformas, dependendo do seu fluxo de trabalho:

• API REST e API RPC: chame os endpoints HTTP ou gRPC diretamente. Consulte a referência REST e a referência RPC para especificações de método.
• Bibliotecas de cliente: integre a API Developer Knowledge aos seus aplicativos usando bibliotecas de cliente oficiais para C#, Go, Java, Node.js e TypeScript, PHP, Python e Ruby.
• Google Cloud CLI (gcloud): execute gcloud developer-knowledge comandos no terminal para pesquisar blocos de documentos, buscar conteúdo Markdown e gerar respostas.
• Servidor MCP de conhecimento do desenvolvedor: conecte seu agente ou assistência de programação de IA à documentação do Google usando ferramentas do Protocolo de Contexto de Modelo (MCP) (search_documents, get_documents, e answer_query). Consulte a referência do MCP.

Dica: Se você estiver usando um assistente de assistência de programação de IA, instale a habilidade do agente retrieving-developer-knowledge executando npx skills add google/skills --skill retrieving-developer-knowledge. Essa habilidade oferece ao assistente instruções integradas sobre qual ferramenta do servidor MCP do Developer Knowledge escolher, como lidar com erros e como chamar a API REST com curl se o servidor MCP não estiver disponível. Para saber mais, consulte Usar a habilidade do agente Developer Knowledge.

Escolher entre a API e o servidor MCP

A API Developer Knowledge e o servidor MCP do Developer Knowledge foram projetados para diferentes necessidades de integração:

• Use a API Developer Knowledge, as bibliotecas de cliente ou a CLI gcloud quando:
  • Seu projeto não usa um agente de IA.
  • Você quer definir ferramentas ou conjuntos de ferramentas personalizados para seu agente.
  • Você quer processar ou combinar resultados antes de transmiti-los a um modelo (por exemplo, verificar o comprimento do byte do documento antes de buscar o conteúdo completo).
  • Você precisa filtrar os resultados da pesquisa (como por data_source ou update_time) ou aplicar máscaras de campo.
• Use o servidor MCP do Developer Knowledge e a habilidade do agente quando:
  • Você quer conectar um agente ou assistente de programação de IA sem escrever definições e descrições de ferramentas personalizadas.
  • Você quer atualizações automáticas à medida que o servidor MCP do Developer Knowledge adiciona novos recursos.
  • Você não precisa de filtragem de metadados personalizados nos resultados da pesquisa.

Ativar a API

Para usar a API Developer Knowledge, primeiro ative-a para seu projeto na nuvem do Google.

Dica :se você não tiver um projeto na nuvem do Google Cloud, crie um usando as instruções do Google Cloud ou do Firebase.

1. Abra a página da API Developer Knowledge na biblioteca de APIs do Google.
2. Verifique se você selecionou o projeto correto em que pretende usar a API.
3. Clique em Ativar. Não é necessário ter funções específicas do IAM para ativar ou usar a API.

Autenticação

Você pode autenticar solicitações para a API Developer Knowledge usando um dos seguintes métodos:

• Chave de API: autentique solicitações REST diretas ou o servidor MCP do Developer Knowledge usando o parâmetro de consulta key ou o cabeçalho X-Goog-Api-Key.
• Application Default Credentials (ADC), OAuth 2.0 ou contas de serviço: autentique solicitações ao usar as bibliotecas de cliente oficiais ou fluxos de trabalho de produção. Para saber mais sobre como configurar credenciais, consulte a documentação do Application Default Credentials.
• Credenciais do usuário (CLI gcloud): autentique solicitações da CLI fazendo login na sua conta do Google Cloud com gcloud auth login. Consulte o guia de início rápido da CLI gcloud para instruções de configuração.

Escopos do OAuth

Ao autenticar com o OAuth 2.0 ou contas de serviço, a API Developer Knowledge e o servidor MCP do Developer Knowledge aceitam os seguintes escopos do OAuth:

• https://www.googleapis.com/auth/cloud-platform: escopo padrão usado pelo Application Default Credentials (ADC), pela CLI gcloud e pelas bibliotecas de cliente oficiais do Google Cloud.
• https://www.googleapis.com/auth/devprofiles.full_control: escopo usado para fluxos de consentimento do usuário OAuth 2.0 e integrações do servidor MCP.
• https://www.googleapis.com/auth/developerprofiles.readonly: escopo somente leitura com suporte para contas de serviço e qualificações que não exigem uma tela de permissão do OAuth do usuário final.

Autorização do token do portador

Para autenticar solicitações REST diretas com uma conta de serviço ou um token de acesso do OAuth 2.0, transmita o token no cabeçalho Authorization: Bearer e especifique o projeto de faturamento em 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?"}'

Substitua PROJECT_ID pelo ID do projeto na nuvem do Google Cloud.

Para aplicativos Python, Node.js, Go e Java, as bibliotecas de cliente oficiais processam o Application Default Credentials (ADC) e as atualizações de token automaticamente. Para exemplos, consulte Usar bibliotecas de cliente com a API Developer Knowledge.

Documentação incluída

Consulte a referência do corpus para informações sobre quais documentos são pesquisados pela API.

A API Developer Knowledge tem como objetivo fornecer acesso à documentação mais recente para desenvolvedores do Google. Nosso objetivo é reindexar o conteúdo em até 48 horas após a publicação para que a documentação nova ou atualizada esteja disponível em até dois dias úteis.

Limitações conhecidas

• Qualidade do Markdown:o Markdown é gerado a partir do HTML de origem. Pode haver algumas discrepâncias ou problemas de formatação.
• Escopo do conteúdo: apenas páginas públicas na referência do corpus são incluídas. O conteúdo de outras fontes, como GitHub, sites de OSS, blogs ou YouTube, não está incluído.