O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Pesquisar e recuperar documentos

Este guia mostra como usar a API Developer Knowledge para pesquisar e recuperar programaticamente a documentação pública para desenvolvedores do Google. Em vez de extrair páginas da Web manualmente, a API ajuda seus aplicativos a encontrar snippets de texto relevantes ou buscar documentos completos do Markdown.

Neste documento, você encontra exemplos das seguintes tarefas:

Pesquisar no corpus de documentação.
Paginar os resultados da pesquisa.
Aplicar filtros complexos à pesquisa.
Recuperar o conteúdo completo do documento.
Otimizar payloads de resposta para reduzir a latência.

Antes de começar, ative a API e gere uma chave da API Developer Knowledge. Em seguida, salve a chave em uma variável de ambiente:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Pesquisar documentos com `SearchDocumentChunks`

Use o documents.searchDocumentChunks método para encontrar blocos de documentos que correspondam a uma string de consulta. Os resultados incluem blocos de conteúdo de documentos correspondentes, além de uma referência parent que pode ser usada para recuperar o conteúdo completo desses documentos.

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

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

O resultado será assim:

{
  "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 na lista results inclui:

parent: o nome do recurso do documento (por exemplo, documents/docs.cloud.google.com/bigquery/docs/introduction).
id: o identificador do bloco no documento (por exemplo, chunk_0).
content: o snippet de texto correspondente do documento.
document: metadados sobre o documento de origem, como title, uri, dataSource e updateTime.
relevanceScore: a pontuação de relevância do bloco para a consulta de pesquisa, no intervalo [0.0, 1.0].

Para mais informações sobre o esquema de resposta e todos os campos de metadados disponíveis, consulte a referência da API documents.searchDocumentChunks.

Paginar resultados da pesquisa

Quando uma consulta de pesquisa retorna várias correspondências, é possível navegar pelo conjunto de resultados usando parâmetros de paginação:

pageSize (inteiro): especifica o número máximo de resultados a serem retornados por página. Se não for especificado, a API vai usar cinco resultados como padrão. O valor máximo permitido é 100. Valores maiores que 100 são forçados a 100.
pageToken (string): especifica o token recebido em uma resposta anterior para buscar a próxima página de resultados.

Solicitar a primeira página

Para definir o tamanho da página, transmita o parâmetro pageSize na solicitação:

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

Se outros resultados estiverem disponíveis, a resposta vai incluir um 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"
}

Recuperar páginas subsequentes

Transmita o valor de nextPageToken para o parâmetro pageToken na próxima solicitação:

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

Quando você chegar à última página de resultados, nextPageToken será omitido da resposta.

Filtrar resultados da pesquisa

Use o parâmetro filter para aplicar um filtro estrito aos resultados da pesquisa. A expressão de filtro é aplicada aos metadados do documento pai de cada bloco.

A expressão filter tem um limite de 500 caracteres.

Campos aceitos

É possível filtrar os resultados da pesquisa usando os seguintes campos de documento pai:

content_length_bytes (inteiro): o comprimento do campo content do documento em bytes.
data_source (string): o domínio de origem do documento, como docs.cloud.google.com ou firebase.google.com. Consulte a referência do corpus para conferir todas as fontes de dados compatíveis.
update_time (carimbo de data/hora): o carimbo de data/hora da última atualização do documento. Os valores precisam usar o formato RFC 3339 (por exemplo, "2025-01-01T00:00:00Z").
uri (string): o URI completo do documento (por exemplo, https://docs.cloud.google.com/bigquery/docs/tables).

Operadores compatíveis

O analisador de expressão de filtro oferece suporte a diferentes operadores, dependendo do tipo de dados do campo:

Campos de string (data_source, uri): oferecem suporte a = (igual a) e != (diferente de) para correspondência exata de strings. Não há suporte para correspondências parciais, de prefixo e de expressão regular.
Campos de carimbo de data/hora (update_time): oferecem suporte a =, <, <=, >, e >=.
Campos de números inteiros (content_length_bytes): oferecem suporte a =, !=, <, <=, >, e >=.
Operadores lógicos: combinam condições usando AND, OR e NOT (ou -).

Exemplos de filtros

Os exemplos a seguir demonstram como criar expressões de filtro. Ao chamar a API REST com curl, codifique o parâmetro de filtro por URL ou use --data-urlencode.

Corresponder a várias fontes de dados

Use OR para incluir documentos de várias fontes:

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

Solicitação 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"

Filtrar por carimbo de data/hora

Use operadores de comparação com carimbos de data/hora RFC 3339 para encontrar conteúdo atualizado após uma data específica:

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

Solicitação 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"

Filtrar por comprimento do conteúdo

Use operadores de comparação com content_length_bytes para encontrar documentos com base no tamanho do byte:

content_length_bytes < 5000

Solicitação 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"

Combinar fonte de dados, carimbo de data/hora e agrupamento

Combine AND, OR e parênteses (...) para restringir os resultados a fontes específicas atualizadas após uma determinada data:

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

Solicitação 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"

Excluir fontes de dados

Use NOT ou != para excluir resultados de uma fonte específica:

data_source != "firebase.google.com"

Solicitação 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"

Recuperar um documento com `GetDocument`

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

Nomes de recursos x URIs

Ao fazer referência a documentos na API Developer Knowledge, observe a diferença entre nomes de recursos e URIs da Web:

Nome do recurso (parent, name): formatado como documents/{uri_without_scheme} (por exemplo, documents/docs.cloud.google.com/storage/docs/creating-buckets). Transmita esse valor como o parâmetro de caminho em GetDocument ou no parâmetro names de BatchGetDocuments.
URI da Web (uri): URL da Web completo, incluindo o esquema (por exemplo, https://docs.cloud.google.com/storage/docs/creating-buckets). Use esse formato para o campo uri ao criar expressões filter (por exemplo, uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

O exemplo a seguir recupera um documento pelo nome do recurso:

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

A resposta é um Document recurso que contém metadados e o conteúdo completo do Markdown no campo content.

Recuperar vários documentos com `BatchGetDocuments`

Use o documents.batchGet método para recuperar até 20 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/docs.cloud.google.com/storage/docs/creating-buckets&names=documents/firebase.google.com/docs/firestore/quickstart&key=$DEVELOPERKNOWLEDGE_API_KEY"

A resposta contém uma lista dos recursos solicitados Document na ordem em que você os solicitou.

Otimizar payloads de resposta

O conteúdo do documento no formato Markdown pode ser grande. Se o aplicativo precisar apenas de metadados (como títulos de páginas, URIs ou carimbos de data/hora) ou campos específicos, você poderá otimizar os tamanhos de payload para reduzir a largura de banda e a latência.

Usar visualizações de documentos

O parâmetro view controla quais campos são preenchidos nas Document mensagens.

A DocumentView enum oferece suporte aos seguintes valores:

DOCUMENT_VIEW_BASIC: retorna apenas campos de metadados básicos (name, uri, data_source, title, description, update_time e view). O campo content é omitido.
DOCUMENT_VIEW_CONTENT: retorna campos de metadados junto com o campo content do Markdown. Esse é o padrão para GetDocument e BatchGetDocuments.
DOCUMENT_VIEW_FULL: retorna todos os campos do documento.

Para recuperar apenas os metadados do documento sem fazer o download de conteúdo grande do Markdown, defina 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"

Também é possível usar view=DOCUMENT_VIEW_BASIC com 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 ainda mais os payloads de resposta a campos específicos, use o parâmetro de consulta fields padrão das APIs do Google (máscara de campo).

Filtrar campos em `GetDocument`

Para recuperar apenas os campos title, uri e updateTime de um documento:

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 em `BatchGetDocuments`

Para recuperar apenas campos específicos de cada documento em um lote:

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 em `SearchDocumentChunks`

Para retornar apenas o id e o content do bloco, o title e o uri do documento pai e o nextPageToken de uma pesquisa:

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

Solucionar erros

A API Developer Knowledge retorna códigos de status HTTP padrão. Os exemplos funcionais a seguir mapeiam códigos de status HTTP e as causas deles na API Developer Knowledge:

400 INVALID_ARGUMENT:
- A string de expressão filter excede 500 caracteres.
- O carimbo de data/hora update_time é inválido (precisa usar o formato RFC 3339).
- Mais de 20 nomes de documentos foram fornecidos em uma solicitação BatchGetDocuments.
401 UNAUTHENTICATED: a solicitação não tem uma chave de API ou usa uma chave inválida. Consulte Autenticação.
404 NOT_FOUND: o nome do documento solicitado não existe ou pertence a um domínio que não está incluído no corpus.
429 RESOURCE_EXHAUSTED: o projeto excedeu a cota. Consulte Cota e limites.

A seguir

Consulte Responder a consultas com geração fundamentada.
Saiba como usar bibliotecas de cliente em Python, Node.js, Go ou Java.
Navegue pela referência do corpus para conferir todas as fontes de documentação compatíveis.
Consulte a referência da API REST para conferir as especificações completas do método.
Verifique a cota e os limites de taxas e cotas da API.

Pesquisar e recuperar documentos Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Pesquisar documentos com SearchDocumentChunks

Paginar resultados da pesquisa

Solicitar a primeira página

Recuperar páginas subsequentes

Filtrar resultados da pesquisa

Campos aceitos

Operadores compatíveis

Exemplos de filtros

Corresponder a várias fontes de dados

Filtrar por carimbo de data/hora

Filtrar por comprimento do conteúdo

Combinar fonte de dados, carimbo de data/hora e agrupamento

Excluir fontes de dados

Recuperar um documento com GetDocument

Nomes de recursos x URIs

Recuperar vários documentos com BatchGetDocuments

Otimizar payloads de resposta

Usar visualizações de documentos

Usar máscaras de campo

Filtrar campos em GetDocument

Filtrar campos em BatchGetDocuments

Filtrar campos em SearchDocumentChunks

Solucionar erros

A seguir

Pesquisar e recuperar documentos

Pesquisar documentos com `SearchDocumentChunks`

Recuperar um documento com `GetDocument`

Recuperar vários documentos com `BatchGetDocuments`

Filtrar campos em `GetDocument`

Filtrar campos em `BatchGetDocuments`

Filtrar campos em `SearchDocumentChunks`