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 forma programática a documentação para desenvolvedores pública 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 Markdown completos.

Neste documento, você encontra exemplos das seguintes tarefas:

Pesquisar o 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, configure seu ambiente para a 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 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 chave de API Developer Knowledge.

Pesquisar documentos

Use o gcloud developer-knowledge documents search-chunks comando ou o documents.searchDocumentChunks método REST 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 correspondam 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 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:

--page-size (CLI gcloud) ou 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 convertidos para 100.
--limit (CLI gcloud) ou pageToken (string): na CLI gcloud, use --limit para controlar o número total de resultados retornados nas 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 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ê chegar à última página de resultados, nextPageToken será omitido da resposta.

Filtrar resultados da pesquisa

Use a flag --query-filter na CLI gcloud ou o filter parâmetro em solicitações REST 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 de filtro 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 todas as fontes de dados aceitas.
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 != (não igual a) 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 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 construir 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.

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

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

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

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 the gcloud developer-knowledge documents describe command or the documents.get REST method to retrieve the full content of a single document.

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 Document recurso que contém metadados e o conteúdo completo do 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 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 construir --query-filter ou filter expressões (por exemplo, uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

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

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

A flag --view e a DocumentView enumeração oferecem suporte aos 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 fazer o download de conteúdo Markdown grande, 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"

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 um token de portador, ou usa credenciais inválidas. 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 Gerar respostas da documentação.
Conecte-se ao servidor MCP da Developer Knowledge e instale a retrieving-developer-knowledge habilidade do agente para ajudar seu assistente de programação de IA a pesquisar e ler a 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 do corpus para conferir todas as fontes de documentação aceitas.
Consulte a referência da API REST para conferir as especificações completas do método.
Verifique a cota e os limites para limitação 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

Corresponder a uma única fonte de dados

gcloud

REST

Corresponder a várias fontes de dados

gcloud

REST

Filtrar por carimbo de data/hora

gcloud

REST

Filtrar por comprimento 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`