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 manualmente información de las páginas web, la API ayuda a tus aplicaciones a encontrar fragmentos de texto relevantes o recuperar documentos completos en Markdown.

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

  • Se está buscando en el corpus de documentación.
  • Paginación de los resultados de la búsqueda
  • Aplicar filtros complejos a tu búsqueda
  • Se recupera el contenido completo del documento.
  • Se optimizaron las cargas útiles de las respuestas para reducir la latencia.

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

gcloud

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

REST

Habilita la API y genera una clave de API de Developer Knowledge. Luego, guarda tu 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 comando gcloud developer-knowledge documents search-chunks o el método de REST documents.searchDocumentChunks para encontrar fragmentos de documentos que coincidan con una cadena de consulta. Los resultados incluyen fragmentos de contenido de los 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: Es el nombre del recurso del documento (por ejemplo, documents/docs.cloud.google.com/bigquery/docs/introduction).
  • id: Es el identificador del fragmento dentro del documento (por ejemplo, chunk_0).
  • content: Es el fragmento de texto coincidente del documento.
  • document: Son los metadatos sobre el documento fuente, como su title, uri, dataSource y updateTime.
  • relevanceScore: Es la puntuación de relevancia del fragmento para la búsqueda, en el rango de [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 búsqueda devuelve varias coincidencias, puedes navegar por el conjunto de resultados con los parámetros de paginación:

  • --page-size (CLI de gcloud) o pageSize (número entero): Especifica la cantidad máxima de resultados que se devolverá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 convertirán en 100.

  • --limit (gcloud CLI) o pageToken (cadena): En la gcloud CLI, usa --limit para controlar la cantidad total de resultados que se devuelven en las páginas. En las solicitudes de REST, pasa el valor de pageToken que recibiste 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 devueltos:

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

REST

  1. 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"
}

  2. Para recuperar las páginas siguientes, 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 en la respuesta.

Cómo filtrar los resultados de la búsqueda

Usa la marca --query-filter en la gcloud CLI o el parámetro filter 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 principal 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 principal:

  • content_length_bytes (número entero): Es la longitud del campo content del documento en bytes.
  • data_source (cadena): Es el dominio de origen del documento, como docs.cloud.google.com o firebase.google.com. Consulta la referencia del corpus para conocer todas las fuentes de datos compatibles.
  • update_time (marca de tiempo): Es 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): Es 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 a) y != (no igual a) para la coincidencia exacta de cadenas. No se admiten las 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: 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 el parámetro filter en formato URL o usa --data-urlencode.

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

Correlaciona 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 duración 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"

Combinar la fuente de datos, la marca de tiempo y la 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"

Excluye 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"

Recupera un documento

Usa el comando gcloud developer-knowledge documents describe o el método de REST documents.get 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 recurso Document que contiene metadatos y el contenido completo en Markdown en el campo content.

Nombres de recursos frente a 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): Se formatea como 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 en GetDocument o en el parámetro names de BatchGetDocuments.
  • URI web (uri): Es la 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 --query-filter o filter (por ejemplo, uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

Recupera varios documentos con BatchGetDocuments

Usa el método documents.batchGet 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 Document solicitados en el orden en que los solicitaste.

Optimiza 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 las cargas útiles para reducir el ancho de banda y la latencia.

Cómo usar las vistas de documentos

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

La marca --view y el enum DocumentView admiten los siguientes valores:

  • --view=basic (CLI de gcloud) o DOCUMENT_VIEW_BASIC: Devuelve solo los campos de metadatos básicos (name, uri, dataSource, title, description, updateTime y view). Se omite el campo content.
  • --view=content (gcloud CLI) o DOCUMENT_VIEW_CONTENT: Devuelve 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 (gcloud CLI) o DOCUMENT_VIEW_FULL: Devuelve todos los campos del documento.

Para recuperar solo los metadatos del documento sin descargar contenido de Markdown grande, 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"

Usa 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 (máscara de campo) estándar de las APIs de Google.

Campos de filtro 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"

Campos de filtro en BatchGetDocuments

Para recuperar solo campos específicos de 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 devolver solo el fragmento id y content, el documento principal title y uri, 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 devuelve 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 de BatchGetDocuments.
  • 401 UNAUTHENTICATED: La solicitud no incluye 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 se incluye en el corpus.
  • 429 RESOURCE_EXHAUSTED: El proyecto excedió su cuota. Consulta Cuotas y límites.

¿Qué sigue?