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 documento mostra como usar a API Developer Knowledge para pesquisar e recuperar de maneira programática a documentação pública para desenvolvedores do Google. Em vez de fazer a raspagem manual de páginas da Web, a API ajuda seus aplicativos a encontrar snippets de texto relevantes ou buscar documentos Markdown completos.

Neste documento, você vai encontrar exemplos das seguintes tarefas:

Pesquisando no corpus de documentação.
Paginação nos resultados da pesquisa.
Aplicar filtros complexos à sua pesquisa.
Recuperando o conteúdo completo do documento.
Otimização de payloads de resposta para reduzir a latência.

Antes de começar, configure o ambiente para sua ferramenta preferida:

gcloud

Instale e configure a CLI gcloud e ative a API Developer Knowledge.

REST

Ative a API e gere uma chave de API do Developer Knowledge. Em seguida, salve a chave em uma variável de ambiente:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Substitua YOUR_API_KEY pela sua chave de API Developer Knowledge.

Pesquisar documentos

Use o comando gcloud developer-knowledge documents search-chunks ou o método REST documents.searchDocumentChunks para encontrar partes de documentos que correspondam a uma string de consulta. Os resultados incluem partes 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 correspondem a "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"

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 de documento (por exemplo, documents/docs.cloud.google.com/bigquery/docs/introduction).
id: o identificador do trecho 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 trecho 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:

--page-size (CLI gcloud) ou pageSize (número 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 convertidos para 100.
--limit (CLI gcloud) ou pageToken (string): na CLI gcloud, use --limit para controlar o número total de resultados retornados em todas as páginas. Em solicitações REST, transmita o valor pageToken recebido em uma resposta anterior para buscar a próxima página de resultados.

gcloud

Transmita as flags --page-size e --limit para controlar o número de resultados por página e o número total de resultados retornados:

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

REST

Para solicitar a primeira página, transmita o parâmetro pageSize na sua solicitação:

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

Se houver mais resultados 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"
}

Para recuperar as 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ê chega à última página de resultados, nextPageToken é omitido da resposta.

Filtrar resultados da pesquisa

Use a flag --query-filter na CLI gcloud ou o parâmetro filter em solicitações REST para aplicar um filtro restrito aos resultados da pesquisa. A expressão de filtro é aplicada aos metadados do documento principal de cada parte.

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

Campos aceitos

É possível filtrar os resultados da pesquisa usando os seguintes campos do documento principal:

content_length_bytes (número 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 de corpus para 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ões de filtro é compatível com 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): compatíveis com =, <, <=, > e >=.
Campos de números inteiros (content_length_bytes): são compatíveis com =, !=, <, <=, > e >=.
Operadores lógicos: combinam condições usando AND, OR e NOT (ou -).

Exemplos de filtros

Os exemplos a seguir mostram como criar expressões de filtro. Ao usar a CLI gcloud, transmita a expressão para a flag --query-filter. Ao chamar a API REST com curl, codifique o URL do parâmetro filter ou use --data-urlencode.

Fazer a correspondência de uma única fonte de dados

Restringir os resultados da pesquisa a um único domínio de documentação:

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"

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

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ção de tempo

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"

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 duração do conteúdo

Use operadores de comparação com content_length_bytes para encontrar documentos com base no tamanho em 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 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"

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 fontes de dados

Use NOT ou != para excluir resultados de uma fonte 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 um documento

Use o comando gcloud developer-knowledge documents describe ou o método REST documents.get para recuperar o conteúdo completo de um único documento.

O exemplo a seguir recupera um documento pelo nome do 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"

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

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 argumento posicional em gcloud developer-knowledge documents describe, o parâmetro de caminho em GetDocument ou no parâmetro names de BatchGetDocuments.
URI da Web (uri): URL completo da Web, 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 --query-filter ou filter (por exemplo, uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

Recuperar vários documentos com `BatchGetDocuments`

Use o método documents.batchGet 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 Document solicitados na ordem em que você fez o pedido.

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, otimize os tamanhos de payload para reduzir a largura de banda e a latência.

Usar visualizações de documentos

A flag --view na CLI gcloud ou o parâmetro view em solicitações REST controlam quais campos são preenchidos em mensagens Document.

A flag --view e a enumeração DocumentView aceitam os seguintes valores:

--view=basic (CLI gcloud) ou DOCUMENT_VIEW_BASIC: retorna apenas campos de metadados básicos (name, uri, dataSource, title, description, updateTime e view). O campo content é omitido.
--view=content (CLI gcloud) ou DOCUMENT_VIEW_CONTENT: retorna campos de metadados junto com o campo content do Markdown. Esse é o padrão para gcloud developer-knowledge documents describe, GetDocument e BatchGetDocuments.
--view=full (CLI gcloud) ou DOCUMENT_VIEW_FULL: retorna todos os campos do documento.

Para recuperar apenas os metadados do documento sem baixar conteúdo grande do Markdown, especifique a visualização básica do 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"

Você também pode 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 os trechos id e content, os documentos principais title e uri 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. Use 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 Cotas e limites.

A seguir

Consulte Gerar respostas com base na documentação.
Conecte-se ao servidor MCP do Developer Knowledge e instale a habilidade do agente retrieving-developer-knowledge para ajudar seu assistente de programação de IA a pesquisar e ler documentação oficial.
Saiba como usar bibliotecas de cliente em Python, Node.js, Go ou Java.
Saiba como usar a CLI gcloud.
Navegue pela referência de corpus para conferir todas as fontes de documentação compatíveis.
Consulte a referência da API REST para ver as especificações completas do método.
Confira cotas e limites para limites de taxa 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.

gcloud

REST

Pesquisar documentos

gcloud

REST

Paginar resultados da pesquisa

gcloud

REST

Filtrar resultados da pesquisa

Campos aceitos

Operadores compatíveis

Exemplos de filtros

Fazer a correspondência de uma única fonte de dados

gcloud

REST

Corresponder várias fontes de dados

gcloud

REST

Filtrar por marcação de tempo

gcloud

REST

Filtrar por duração do conteúdo

gcloud

REST

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

gcloud

REST

Excluir fontes de dados

gcloud

REST

Recuperar um documento

gcloud

REST

Nomes de recursos x URIs

Recuperar vários documentos com BatchGetDocuments

Otimizar payloads de resposta

Usar visualizações de documentos

gcloud

REST

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

Recuperar vários documentos com `BatchGetDocuments`

Filtrar campos em `GetDocument`

Filtrar campos em `BatchGetDocuments`

Filtrar campos em `SearchDocumentChunks`