Pesquisar e recuperar documentos

Este guia mostra exemplos de como usar as funções da API Developer Knowledge: pesquisar documentos, recuperar um único documento e recuperar vários documentos em lote.

Antes de começar, verifique se você ativou a API e gerou uma chave da API Developer Knowledge. Salve a chave em uma variável de ambiente:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Pesquisar documentos com SearchDocumentChunks

Use o método documents.searchDocumentChunks para encontrar partes de documentos que correspondam a uma string de consulta. Os resultados incluem pedaços de conteúdo do documento e uma referência parent que você pode usar para recuperar o conteúdo completo do documento.

O exemplo a seguir pesquisa documentos que correspondem a "BigQuery":

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

É possível refinar os resultados da pesquisa usando parâmetros como pageSize para limitar o número de resultados por página e pageToken para recuperar as páginas subsequentes.

Filtrar resultados da pesquisa

Use o parâmetro filter para aplicar um filtro restrito aos resultados da pesquisa. O filtro é aplicado aos metadados dos documentos associados aos blocos de resultados da pesquisa.

Campos compatíveis com a filtragem:

  • data_source (STRING): a origem do documento, por exemplo, docs.cloud.google.com.
  • update_time (TIMESTAMP): o carimbo de data/hora da última atualização do documento.
  • uri (STRING): o URI do documento, por exemplo, https://docs.cloud.google.com/bigquery/docs/tables.

Operadores compatíveis:

  • Os campos STRING são compatíveis com = (igual a) e != (diferente de) para correspondências exatas em toda a string.
  • Os campos TIMESTAMP aceitam =, <, <=, > e >=. Os carimbos de data/hora precisam estar no formato RFC-3339 (por exemplo, "2025-01-01T00:00:00Z").

É possível combinar expressões usando os operadores lógicos AND, OR e NOT (ou -). Observe que OR tem precedência maior que AND.

O exemplo a seguir pesquisa documentos que correspondem a "BigQuery" e restringe os resultados aos de docs.cloud.google.com:

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&filter=data_source%3D%22docs.cloud.google.com%22&key=$DEVELOPERKNOWLEDGE_API_KEY"

Recuperar um documento com GetDocument

Use o método documents.get para recuperar todo o conteúdo de um único documento.

O exemplo a seguir recupera um documento com o nome documents/DOCUMENT_ID:

curl "https://developerknowledge.googleapis.com/v1/documents:get?name=documents/DOCUMENT_ID&key=$DEVELOPERKNOWLEDGE_API_KEY"

A resposta é o recurso completo Document, incluindo o campo content.

Recuperar vários documentos com BatchGetDocuments

Use o método documents.batchGet para recuperar até 100 documentos por nome em uma única chamada de API. Isso é mais eficiente do que fazer várias solicitações GetDocument.

O exemplo a seguir recupera dois documentos por nome:

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/DOCUMENT_ID_1&names=documents/DOCUMENT_ID_2&key=$DEVELOPERKNOWLEDGE_API_KEY"

A resposta contém uma lista dos recursos Document solicitados.