Buscar y recuperar documentos

En esta guía, se muestra cómo usar la API de Developer Knowledge para buscar y recuperar de forma programática la documentación pública para desarrolladores 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 a través de 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, asegúrate de haber habilitado la API y generado una clave de API de Developer Knowledge. Luego, guarda la clave en una variable de entorno:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Cómo buscar documentos con SearchDocumentChunks

Usa el documents.searchDocumentChunks método 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":

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 fuente, 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.

Cómo 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:

  • pageSize (número entero): especifica la cantidad máxima de resultados que se mostrarán por página. Si no se especifica, la API usa de forma predeterminada cinco resultados. El valor máximo permitido es 100; los valores superiores a 100 se fuerzan a 100.
  • pageToken (cadena): especifica el token recibido en una respuesta anterior para recuperar la siguiente página de resultados.

Cómo solicitar la primera página

Para establecer el tamaño de la 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"
}

Cómo recuperar 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.

Cómo filtrar los resultados de la búsqueda

Usa el parámetro filter 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 filter 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 (número entero): la longitud del campo content del documento en bytes.
  • data_source (cadena): el dominio fuente 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 en la que 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 es 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 de números enteros (content_length_bytes): admiten =, !=, <, <=, >, y >=.
  • Operadores lógicos: combinan condiciones con AND, OR y NOT (o -).

Filtra ejemplos

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

Cómo hacer coincidir varias fuentes de datos

Usa OR para incluir documentos de varias fuentes:

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

Solicitud curl:

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"

Cómo 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"

Solicitud curl:

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"

Cómo filtrar por longitud de contenido

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

content_length_bytes < 5000

Solicitud curl:

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"

Cómo combinar 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"

Solicitud curl:

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"

Cómo excluir fuentes de datos

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

data_source != "firebase.google.com"

Solicitud curl:

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"

Cómo recuperar un documento con GetDocument

Usa el documents.get método para recuperar el contenido completo de un solo documento.

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 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 expresiones filter (por ejemplo, uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

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

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.

Cómo recuperar 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.

Cómo 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 páginas, URIs o marcas de tiempo) o campos específicos, puedes optimizar los tamaños de las cargas útiles para reducir el ancho de banda y la latencia.

Cómo usar vistas de documentos

El parámetro view controla qué campos se propagan en los mensajes Document.

La DocumentView enumeración admite los siguientes valores:

  • DOCUMENT_VIEW_BASIC: muestra solo los campos de metadatos básicos (name, uri, data_source, title, description, update_time y view). Se omite el campo content.
  • DOCUMENT_VIEW_CONTENT: muestra los campos de metadatos junto con el campo content de Markdown. Este es el valor predeterminado para GetDocument y BatchGetDocuments.
  • DOCUMENT_VIEW_FULL: muestra todos los campos del documento.

Para recuperar solo los metadatos del documento sin descargar contenido grande de Markdown, establece view=DOCUMENT_VIEW_BASIC:

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"

Cómo 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).

Cómo 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"

Cómo 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"

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 usa una clave no válida. 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?