Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Buscar y recuperar documentos

En este documento, se muestra cómo usar la API de Developer Knowledge para buscar y recuperar de forma programática la documentación para desarrolladores pública de Google. En lugar de extraer páginas web de forma manual, la API ayuda a tus aplicaciones a encontrar fragmentos de texto relevantes o recuperar documentos completos de Markdown.

En este documento, encontrarás ejemplos para las siguientes tareas:

Buscar en el corpus de documentación
Paginación en los resultados de la búsqueda
Aplicar filtros complejos a tu búsqueda
Recuperar el contenido completo del documento
Optimizar las cargas útiles de respuesta para reducir la latencia

Antes de comenzar, configura tu entorno para la herramienta que prefieras:

gcloud

Instala y configura la CLI de gcloud, y habilita la API de Developer Knowledge.

REST

Habilita la API y genera una clave de API de Developer Knowledge. Luego, guarda la clave en una variable de entorno:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Reemplaza YOUR_API_KEY por tu clave de API de Developer Knowledge.

Buscar documentos

Usa el gcloud developer-knowledge documents search-chunks comando o el documents.searchDocumentChunks método REST para encontrar fragmentos de documentos que coincidan con una cadena de consulta. Los resultados incluyen fragmentos de contenido de documentos coincidentes, junto con una referencia parent que puedes usar para recuperar el contenido completo de esos documentos.

En el siguiente ejemplo, se buscan documentos que coincidan con "BigQuery":

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery"

REST

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&key=$DEVELOPERKNOWLEDGE_API_KEY"

El resultado es similar a este:

{
  "results": [
    {
      "parent": "documents/docs.cloud.google.com/bigquery/docs/introduction",
      "id": "chunk_0",
      "content": "BigQuery is a fully managed enterprise data warehouse...",
      "document": {
        "name": "documents/docs.cloud.google.com/bigquery/docs/introduction",
        "uri": "https://docs.cloud.google.com/bigquery/docs/introduction",
        "title": "BigQuery overview",
        "dataSource": "docs.cloud.google.com",
        "updateTime": "2025-01-15T12:00:00Z"
      },
      "relevanceScore": 0.92
    }
  ]
}

Cada resultado de la lista results incluye lo siguiente:

parent: el nombre del recurso del documento (por ejemplo, documents/docs.cloud.google.com/bigquery/docs/introduction).
id: el identificador del fragmento dentro del documento (por ejemplo, chunk_0).
content: el fragmento de texto coincidente del documento.
document: metadatos sobre el documento de origen, como su title, uri, dataSource y updateTime.
relevanceScore: la puntuación de relevancia del fragmento para la consulta de búsqueda, en el rango [0.0, 1.0].

Para obtener más información sobre el esquema de respuesta y todos los campos de metadatos disponibles, consulta la referencia de la API de documents.searchDocumentChunks.

Paginar los resultados de la búsqueda

Cuando una consulta de búsqueda muestra varias coincidencias, puedes navegar por el conjunto de resultados con los parámetros de paginación:

--page-size (CLI de gcloud) o pageSize (entero): especifica la cantidad máxima de resultados que se mostrarán por página. Si no se especifica, la API establece de forma predeterminada cinco resultados. El valor máximo permitido es 100; los valores superiores a 100 se fuerzan a 100.
--limit (gcloud CLI) o pageToken (cadena): en la gcloud CLI, usa --limit para controlar la cantidad total de resultados que se muestran en las páginas. En las solicitudes de REST, pasa el valor pageToken recibido en una respuesta anterior para recuperar la siguiente página de resultados.

gcloud

Pasa las marcas --page-size y --limit para controlar la cantidad de resultados por página y la cantidad total de resultados que se muestran:

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery" \
  --page-size=5 \
  --limit=10

REST

Para solicitar la primera página, pasa el parámetro pageSize en tu solicitud:

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&key=$DEVELOPERKNOWLEDGE_API_KEY"

Si hay resultados adicionales disponibles, la respuesta incluye un nextPageToken:

{
  "results": [
    {
      "parent": "documents/docs.cloud.google.com/bigquery/docs/introduction",
      "id": "chunk_0",
      "content": "BigQuery is a fully managed enterprise data warehouse...",
      "document": {
        "name": "documents/docs.cloud.google.com/bigquery/docs/introduction",
        "uri": "https://docs.cloud.google.com/bigquery/docs/introduction",
        "title": "What is BigQuery?",
        "dataSource": "docs.cloud.google.com",
        "updateTime": "2025-01-15T12:00:00Z",
        "view": "DOCUMENT_VIEW_BASIC"
      },
      "relevanceScore": 0.88
    }
  ],
  "nextPageToken": "CAUQABgB"
}

Para recuperar las páginas posteriores, pasa el valor de nextPageToken al parámetro pageToken en tu próxima solicitud:
```
curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&pageToken=CAUQABgB&key=$DEVELOPERKNOWLEDGE_API_KEY"
```
Cuando llegues a la última página de resultados, se omitirá nextPageToken de la respuesta.

Filtrar resultados de la búsqueda

Usa la marca --query-filter en la CLI de gcloud o el filter parámetro en las solicitudes de REST para aplicar un filtro estricto a los resultados de la búsqueda. La expresión de filtro se aplica a los metadatos del documento superior para cada fragmento.

La expresión de filtro tiene un límite de 500 caracteres.

Campos disponibles

Puedes filtrar los resultados de la búsqueda con los siguientes campos del documento superior:

content_length_bytes (entero): la longitud del campo content del documento en bytes.
data_source (cadena): el dominio de origen del documento, como docs.cloud.google.com o firebase.google.com. Consulta la referencia del corpus para ver todas las fuentes de datos compatibles.
update_time (marca de tiempo): la marca de tiempo cuando se actualizó el documento por última vez. Los valores deben usar el formato RFC 3339 (por ejemplo, "2025-01-01T00:00:00Z").
uri (cadena): el URI completo del documento (por ejemplo, https://docs.cloud.google.com/bigquery/docs/tables).

Operadores admitidos

El analizador de expresiones de filtro admite diferentes operadores según el tipo de datos del campo:

Campos de cadena (data_source, uri): admiten = (igual) y != (no igual) para la coincidencia exacta de cadenas. No se admiten coincidencias parciales, de prefijo ni de expresiones regulares.
Campos de marca de tiempo (update_time): admiten =, <, <=, >, y >=.
Campos enteros (content_length_bytes): admiten =, !=, <, <=, >, y >=.
Operadores lógicos: combina condiciones con AND, OR y NOT (o -).

Filtra ejemplos

En los siguientes ejemplos, se muestra cómo construir expresiones de filtro. Cuando uses la gcloud CLI, pasa la expresión a la marca --query-filter. Cuando llames a la API de REST con curl, asegúrate de codificar la URL del parámetro filter o usar --data-urlencode.

Coincide con una sola fuente de datos

Restringe los resultados de la búsqueda a un solo dominio de documentación:

data_source = "docs.cloud.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="Cloud Functions deployment" \
  --query-filter='data_source = "docs.cloud.google.com"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=Cloud Functions deployment" \
  --data-urlencode 'filter=data_source = "docs.cloud.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Coincide con varias fuentes de datos

Usa OR para incluir documentos de varias fuentes:

data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="database" \
  --query-filter='data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=database" \
  --data-urlencode 'filter=data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Filtrar por marca de tiempo

Usa operadores de comparación con marcas de tiempo RFC 3339 para encontrar contenido actualizado después de una fecha específica:

update_time >= "2025-01-01T00:00:00Z"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery" \
  --query-filter='update_time >= "2025-01-01T00:00:00Z"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=BigQuery" \
  --data-urlencode 'filter=update_time >= "2025-01-01T00:00:00Z"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Filtrar por longitud del contenido

Usa operadores de comparación con content_length_bytes para encontrar documentos según su tamaño en bytes:

content_length_bytes < 5000

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="Cloud Storage" \
  --query-filter='content_length_bytes < 5000'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=Cloud Storage" \
  --data-urlencode 'filter=content_length_bytes < 5000' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Combina fuente de datos, marca de tiempo y agrupación

Combina AND, OR y paréntesis (...) para restringir los resultados a fuentes específicas actualizadas después de una fecha determinada:

(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="service worker" \
  --query-filter='(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=service worker" \
  --data-urlencode 'filter=(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Excluir fuentes de datos

Usa NOT o != para excluir los resultados de una fuente específica:

data_source != "firebase.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="authentication" \
  --query-filter='data_source != "firebase.google.com"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=authentication" \
  --data-urlencode 'filter=data_source != "firebase.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Recuperar un documento

Usa el gcloud developer-knowledge documents describe comando o el documents.get método REST para recuperar el contenido completo de un solo documento.

En el siguiente ejemplo, se recupera un documento por su nombre de recurso:

gcloud

gcloud developer-knowledge documents describe \
  documents/docs.cloud.google.com/storage/docs/creating-buckets

REST

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?key=$DEVELOPERKNOWLEDGE_API_KEY"

La respuesta es un Document recurso que contiene metadatos y el contenido completo de Markdown en el campo content.

Nombres de recursos en comparación con URIs

Cuando hagas referencia a documentos en la API de Developer Knowledge, ten en cuenta la diferencia entre los nombres de recursos y los URIs web:

Nombre del recurso (parent, name): tiene el formato documents/{uri_without_scheme} (por ejemplo, documents/docs.cloud.google.com/storage/docs/creating-buckets). Pasa este valor como el argumento posicional en gcloud developer-knowledge documents describe, el parámetro de ruta de acceso en GetDocument o en el parámetro names de BatchGetDocuments.
URI web (uri): URL web completa, incluido el esquema (por ejemplo, https://docs.cloud.google.com/storage/docs/creating-buckets). Usa este formato para el campo uri cuando construyas --query-filter o filter expresiones (por ejemplo, uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

Recupera varios documentos con `BatchGetDocuments`

Usa el documents.batchGet método para recuperar hasta 20 documentos por nombre en una sola llamada a la API. Esto es más eficiente que realizar varias solicitudes GetDocument.

En el siguiente ejemplo, se recuperan dos documentos por nombre:

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&names=documents/firebase.google.com/docs/firestore/quickstart&key=$DEVELOPERKNOWLEDGE_API_KEY"

La respuesta contiene una lista de los recursos solicitados Document en el orden en que los solicitaste.

Optimizar las cargas útiles de respuesta

El contenido del documento en formato Markdown puede ser grande. Si tu aplicación solo necesita metadatos (como títulos de la página, URIs o marcas de tiempo) o campos específicos, puedes optimizar los tamaños de carga útil para reducir el ancho de banda y la latencia.

Usar vistas de documentos

La marca --view en la gcloud CLI o el parámetro view en las solicitudes de REST controla qué campos se propagan en los mensajes Document.

La marca --view y la DocumentView enumeración admiten los siguientes valores:

--view=basic (CLI de gcloud) o DOCUMENT_VIEW_BASIC: muestra solo los campos de metadatos básicos (name, uri, dataSource, title, description, updateTime y view). Se omite el campo content.
--view=content (CLI de gcloud) o DOCUMENT_VIEW_CONTENT: muestra los campos de metadatos junto con el campo content de Markdown. Este es el valor predeterminado para gcloud developer-knowledge documents describe, GetDocument, y BatchGetDocuments.
--view=full (CLI de gcloud) o DOCUMENT_VIEW_FULL: muestra todos los campos del documento.

Para recuperar solo los metadatos del documento sin descargar contenido grande de Markdown, especifica la vista básica del documento:

gcloud

gcloud developer-knowledge documents describe \
  documents/docs.cloud.google.com/storage/docs/creating-buckets \
  --view=basic

REST

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?view=DOCUMENT_VIEW_BASIC&key=$DEVELOPERKNOWLEDGE_API_KEY"

También puedes usar view=DOCUMENT_VIEW_BASIC con BatchGetDocuments:

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&names=documents/firebase.google.com/docs/firestore/quickstart&view=DOCUMENT_VIEW_BASIC&key=$DEVELOPERKNOWLEDGE_API_KEY"

Usar máscaras de campo

Para limitar aún más las cargas útiles de respuesta a campos específicos, usa el parámetro de consulta fields estándar de las APIs de Google (máscara de campo).

Filtrar campos en `GetDocument`

Para recuperar solo los campos title, uri y updateTime de un documento, haz lo siguiente:

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?fields=title,uri,updateTime&key=$DEVELOPERKNOWLEDGE_API_KEY"

Filtrar campos en `BatchGetDocuments`

Para recuperar solo campos específicos para cada documento en un lote, haz lo siguiente:

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&fields=documents(name,title,uri)&key=$DEVELOPERKNOWLEDGE_API_KEY"

Filtrar campos en `SearchDocumentChunks`

Para mostrar solo el id y el content del fragmento, el title y el uri del documento superior, y el nextPageToken de una búsqueda, haz lo siguiente:

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&fields=results(id,content,document(title,uri)),nextPageToken&key=$DEVELOPERKNOWLEDGE_API_KEY"

Soluciona errores

La API de Developer Knowledge muestra códigos de estado HTTP estándar. En los siguientes ejemplos funcionales, se asignan códigos de estado HTTP y sus causas en la API de Developer Knowledge:

400 INVALID_ARGUMENT:
- La cadena de expresión filter supera los 500 caracteres.
- La marca de tiempo update_time no es válida (debe usar el formato RFC 3339).
- Se proporcionaron más de 20 nombres de documentos en una solicitud BatchGetDocuments.
401 UNAUTHENTICATED: La solicitud no tiene una clave de API o un token de portador, o usa credenciales no válidas. Consulta Autenticación.
404 NOT_FOUND: El nombre del documento solicitado no existe o pertenece a un dominio que no está incluido en el corpus.
429 RESOURCE_EXHAUSTED: El proyecto superó su cuota. Consulta Cuotas y límites.

¿Qué sigue?

Consulta Genera respuestas a partir de la documentación.
Conéctate al servidor MCP de Developer Knowledge y, luego, instala la retrieving-developer-knowledge habilidad del agente para ayudar a tu asistente de programación de IA a buscar y leer la documentación oficial.
Explora cómo usar bibliotecas cliente en Python, Node.js, Go o Java.
Explora cómo usar la CLI de gcloud.
Navega por la referencia del corpus para ver todas las fuentes de documentación compatibles.
Revisa la referencia de la API de REST para obtener especificaciones completas del método.
Verifica la cuota y los límites de las cuotas y los límites de frecuencia de la API.

Buscar y recuperar documentos Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

gcloud

REST

Buscar documentos

gcloud

REST

Paginar los resultados de la búsqueda

gcloud

REST

Filtrar resultados de la búsqueda

Campos disponibles

Operadores admitidos

Filtra ejemplos

Coincide con una sola fuente de datos

gcloud

REST

Coincide con varias fuentes de datos

gcloud

REST

Filtrar por marca de tiempo

gcloud

REST

Filtrar por longitud del contenido

gcloud

REST

Combina fuente de datos, marca de tiempo y agrupación

gcloud

REST

Excluir fuentes de datos

gcloud

REST

Recuperar un documento

gcloud

REST

Nombres de recursos en comparación con URIs

Recupera varios documentos con BatchGetDocuments

Optimizar las cargas útiles de respuesta

Usar vistas de documentos

gcloud

REST

Usar máscaras de campo

Filtrar campos en GetDocument

Filtrar campos en BatchGetDocuments

Filtrar campos en SearchDocumentChunks

Soluciona errores

¿Qué sigue?

Buscar y recuperar documentos

Recupera varios documentos con `BatchGetDocuments`

Filtrar campos en `GetDocument`

Filtrar campos en `BatchGetDocuments`

Filtrar campos en `SearchDocumentChunks`