API de Developer Knowledge

La API de Developer Knowledge proporciona acceso programático a la documentación pública para desarrolladores de Google, lo que te permite integrar esta base de conocimiento en tus propias aplicaciones y flujos de trabajo.

Descripción general

La API de Developer Knowledge está diseñada para ser la fuente canónica de acceso legible por máquina a la documentación para desarrolladores de Google. Ofrece funciones para buscar y recuperar documentos, y responder consultas:

• SearchDocumentChunks para encontrar URIs de páginas y fragmentos de contenido relevantes según una consulta
• GetDocument o BatchGetDocuments para recuperar el contenido completo de los resultados de la búsqueda
• AnswerQuery para generar respuestas a las consultas extraídas del corpus de documentación

La API de Developer Knowledge admite la búsqueda y recuperación de páginas de documentación como contenido de Markdown no estructurado. El corpus de contenido que se puede buscar se muestra en la referencia del corpus.

Formas de usar Developer Knowledge

Puedes acceder a Developer Knowledge a través de las siguientes plataformas según tu flujo de trabajo:

• API de REST y API de RPC: Llama directamente a los extremos HTTP o gRPC. Consulta la referencia de REST y la referencia de RPC para obtener especificaciones de métodos.
• Bibliotecas cliente: integra la API de Developer Knowledge en tus aplicaciones con bibliotecas cliente oficiales para C#, Go, Java, Node.js y TypeScript, PHP, Python y Ruby.
• Google Cloud CLI (gcloud): ejecuta gcloud developer-knowledge comandos desde tu terminal para buscar fragmentos de documentos, recuperar contenido de Markdown y generar respuestas.
• Servidor de MCP de Developer Knowledge: Conecta tu agente o asistente de programación de IA a la documentación de Google con las herramientas del Protocolo de contexto del modelo (MCP) (search_documents, get_documents, y answer_query). Consulta la referencia de MCP.

Sugerencia: Si usas un asistente de programación de IA, instala la habilidad del agente retrieving-developer-knowledge ejecutando npx skills add google/skills --skill retrieving-developer-knowledge. Esta habilidad le brinda a tu asistente instrucciones integradas sobre qué herramienta del servidor de MCP de Developer Knowledge elegir, cómo controlar los errores y cómo llamar a la API de REST con curl si el servidor de MCP no está disponible. Para obtener más información, consulta Usa la habilidad del agente de Developer Knowledge.

Elige entre la API y el servidor de MCP

La API de Developer Knowledge y el servidor de MCP de Developer Knowledge están diseñados para diferentes necesidades de integración:

• Usa la API de Developer Knowledge, las bibliotecas cliente o la CLI de gcloud en los siguientes casos:
  • Tu proyecto no usa un agente de IA.
  • Quieres definir herramientas o conjuntos de herramientas personalizados para tu agente.
  • Quieres procesar o combinar resultados antes de pasarlos a un modelo (por ejemplo, verificar la longitud de bytes del documento antes de recuperar el contenido completo).
  • Necesitas filtrar los resultados de la búsqueda (por ejemplo, por data_source o update_time) o aplicar máscaras de campo.
• Usa el servidor de MCP de Developer Knowledge y la habilidad del agente en los siguientes casos:
  • Quieres conectar un agente o asistente de programación de IA sin escribir definiciones y descripciones de herramientas personalizadas.
  • Quieres actualizaciones automáticas a medida que el servidor de MCP de Developer Knowledge agrega nuevas capacidades.
  • No necesitas un filtrado de metadatos personalizado en los resultados de la búsqueda.

Habilita la API

Para usar la API de Developer Knowledge, primero debes habilitarla para tu proyecto de Google Cloud.

**Sugerencia:** Si no tienes un proyecto de Google Cloud, crea uno con las instrucciones de Google Cloud o Firebase.

1. Abre la página de la API de Developer Knowledge en la biblioteca de APIs de Google.
2. Verifica que tengas seleccionado el proyecto correcto en el que deseas usar la API.
3. Haz clic en Habilitar. No se requieren roles de IAM específicos para habilitar o usar la API.

Autenticación

Puedes autenticar solicitudes a la API de Developer Knowledge con uno de los siguientes métodos:

• Clave de API: Autentica las solicitudes directas de REST o el servidor de MCP de Developer Knowledge con el parámetro de consulta key o el X-Goog-Api-Key encabezado.
• Credenciales predeterminadas de la aplicación (ADC), OAuth 2.0 o cuentas de servicio: Autentica las solicitudes cuando usas las bibliotecas cliente oficiales o los flujos de trabajo de producción. Para obtener más información sobre la configuración de credenciales, consulta la documentación de las credenciales predeterminadas de la aplicación.
• Credenciales de usuario (gcloud CLI): Autentica las solicitudes de la gcloud CLI accediendo a tu cuenta de Google Cloud con gcloud auth login. Consulta la guía de inicio rápido de la CLI de gcloud para obtener instrucciones de configuración.

Alcances de OAuth

Cuando se autentican con OAuth 2.0 o cuentas de servicio, la API de Developer Knowledge y el servidor de MCP de Developer Knowledge aceptan los siguientes alcances de OAuth:

• https://www.googleapis.com/auth/cloud-platform: Es el alcance predeterminado que usan las credenciales predeterminadas de la aplicación (ADC), la gcloud CLI y las bibliotecas cliente oficiales de Google Cloud.
• https://www.googleapis.com/auth/devprofiles.full_control: Es el alcance que se usa para los flujos de consentimiento de OAuth 2.0 del usuario y las integraciones del servidor de MCP.
• https://www.googleapis.com/auth/developerprofiles.readonly: Es el alcance de solo lectura compatible con las cuentas de servicio y las credenciales que no requieren una pantalla de consentimiento de OAuth del usuario final.

Autorización de token del portador

Para autenticar solicitudes directas de REST con una cuenta de servicio o un token de acceso de OAuth 2.0, pasa el token en el encabezado Authorization: Bearer y especifica tu proyecto de facturación en 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?"}'

Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud.

En el caso de las aplicaciones de Python, Node.js, Go y Java, las bibliotecas cliente oficiales controlan las credenciales predeterminadas de la aplicación (ADC) y las actualizaciones de tokens de forma automática. Para obtener ejemplos, consulta Usa bibliotecas cliente con la API de Developer Knowledge.

Documentación incluida

Consulta la referencia del corpus para obtener información sobre qué documentos busca la API.

El objetivo de la API de Developer Knowledge es proporcionar acceso a la documentación para desarrolladores más reciente de Google. Nuestro objetivo es volver a indexar el contenido en un plazo de 48 horas después de la publicación para que la documentación nueva o actualizada esté disponible en un plazo de 2 días hábiles.

Limitaciones conocidas

• Calidad de Markdown: El Markdown se genera a partir del HTML fuente. Es posible que haya algunas discrepancias o problemas de formato.
• Alcance del contenido: Solo se incluyen las páginas públicas en la referencia del corpus. No se incluye contenido de otras fuentes, como GitHub, sitios de OSS, blogs o YouTube.