Package google.developers.knowledge.v1

Índice

DeveloperKnowledge

A API Developer Knowledge oferece acesso programático à documentação para desenvolvedores pública do Google, permitindo que você integre essa base de conhecimento aos seus próprios aplicativos e fluxos de trabalho.

A API foi projetada para ser a fonte canônica de acesso legível por máquina à documentação para desenvolvedores do Google.

Um caso de uso típico é usar primeiro DeveloperKnowledge.SearchDocumentChunks para encontrar trechos de documentos relevantes com base em uma consulta e, em seguida, usar DeveloperKnowledge.GetDocument ou DeveloperKnowledge.BatchGetDocuments com nomes de recursos de documentos (como DocumentChunk.parent ou documents/{uri_without_scheme}) para buscar o conteúdo completo dos principais resultados.

Todo o conteúdo do documento é fornecido no formato Markdown.

AnswerQuery

rpc AnswerQuery(AnswerQueryRequest) returns (AnswerQueryResponse)

Responde a uma consulta usando a geração fundamentada.

Escopos de autorização

Requer um dos seguintes escopos do OAuth:

  • https://www.googleapis.com/auth/devprofiles.full_control
  • https://www.googleapis.com/auth/developerprofiles.readonly
  • https://www.googleapis.com/auth/cloud-platform

Para mais informações, consulte OAuth 2.0 Overview.
BatchGetDocuments

rpc BatchGetDocuments(BatchGetDocumentsRequest) returns (BatchGetDocumentsResponse)

Recupera vários documentos, cada um com o conteúdo completo em Markdown.

Escopos de autorização

Requer um dos seguintes escopos do OAuth:

  • https://www.googleapis.com/auth/devprofiles.full_control
  • https://www.googleapis.com/auth/developerprofiles.readonly
  • https://www.googleapis.com/auth/cloud-platform

Para mais informações, consulte OAuth 2.0 Overview.
GetDocument

rpc GetDocument(GetDocumentRequest) returns (Document)

Recupera um único documento com todo o conteúdo em Markdown.

Escopos de autorização

Requer um dos seguintes escopos do OAuth:

  • https://www.googleapis.com/auth/devprofiles.full_control
  • https://www.googleapis.com/auth/developerprofiles.readonly
  • https://www.googleapis.com/auth/cloud-platform

Para mais informações, consulte OAuth 2.0 Overview.
SearchDocumentChunks

rpc SearchDocumentChunks(SearchDocumentChunksRequest) returns (SearchDocumentChunksResponse)

Pesquisa conhecimento para desenvolvedores na documentação para desenvolvedores do Google. Retorna DocumentChunks com base na consulta do usuário. Pode haver muitos blocos do mesmo Document. Para recuperar documentos completos, use DeveloperKnowledge.GetDocument ou DeveloperKnowledge.BatchGetDocuments com o DocumentChunk.parent retornado no SearchDocumentChunksResponse.results.

Escopos de autorização

Requer um dos seguintes escopos do OAuth:

  • https://www.googleapis.com/auth/devprofiles.full_control
  • https://www.googleapis.com/auth/developerprofiles.readonly
  • https://www.googleapis.com/auth/cloud-platform

Para mais informações, consulte OAuth 2.0 Overview.

Resposta

Uma resposta a uma consulta.

Campos
answer_text

string

Contém o texto da resposta.
citations[]

AnswerCitation

Apenas saída. Contém citações para a resposta.
references[]

AnswerReference

Apenas saída. Contém referências para a resposta.

AnswerCitation

Informações de citação de um segmento.

Campos
start_index

int32

Apenas saída. Indica o início do segmento, medido em bytes (Unicode UTF-8), inclusive. Se houver caracteres de vários bytes, como caracteres não ASCII, a medição do índice será maior que o comprimento da string.
end_index

int32

Apenas saída. Indica o fim do segmento, medido em bytes (UTF-8 unicode), exclusivo. Se houver caracteres de vários bytes, como caracteres não ASCII, a medição do índice será maior que o comprimento da string.
sources[]

CitationSource

Apenas saída. Contém fontes de citação para o segmento atribuído.

AnswerReference

Representa uma referência a uma fonte.

Campos
Campo de união content. Contém o conteúdo da referência. content pode ser apenas de um dos tipos a seguir:
document_reference

DocumentReference

Apenas saída. O documento de referência.

CitationSource

Fonte da citação.

Campos
reference_index

int32

Apenas saída. Contém o índice do Answer.AnswerReference no campo repetido references.

DocumentReference

Representa uma referência a um documento.

Campos
document_chunk

DocumentChunk

Apenas saída. Contém o fragmento do documento. O campo document_chunk.id não está definido e vai ficar vazio.

AnswerQueryRequest

Mensagem de solicitação para DeveloperKnowledge.AnswerQuery.

Campos
query

string

Obrigatório. A consulta a ser respondida.
filter

string

Opcional. Aplica um filtro rigoroso aos resultados da pesquisa usados para embasar a resposta. A expressão é compatível com um subconjunto da sintaxe descrita em https://google.aip.dev/160.

Campos compatíveis com a filtragem:

  • content_length_bytes (INTEGER): o comprimento do campo Document.content em bytes.
  • data_source (STRING): a origem do documento, por exemplo, docs.cloud.google.com. Consulte https://developers.google.com/knowledge/reference/corpus-reference para ver a lista completa de fontes de dados no corpus.
  • update_time (TIMESTAMP): o carimbo de data/hora de quando o documento foi atualizado de forma significativa pela última vez. Uma atualização significativa é aquela que muda o conteúdo de markdown ou os metadados do documento.
  • uri (STRING): o URI do documento, por exemplo, https://docs.cloud.google.com/bigquery/docs/tables.

Os campos INTEGER são compatíveis com os operadores =, <, <=, > e >=.

Os campos STRING são compatíveis com os operadores = (igual) e != (diferente) para correspondência exata em toda a string. Não há suporte para correspondência parcial, correspondência de prefixo e correspondência de regexp.

Os campos TIMESTAMP são compatíveis com os operadores =, <, <=, > 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 -). OR tem precedência maior que AND. Use parênteses para agrupamento de precedência explícita.

Exemplos:

  • Filtrar por Document.content_length_bytes: content_length_bytes < 50000
  • data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"
  • data_source != "firebase.google.com"
  • update_time < "2024-01-01T00:00:00Z"
  • update_time >= "2025-01-22T00:00:00Z" AND (data_source = "developer.chrome.com" OR data_source = "web.dev")
  • uri = "https://docs.cloud.google.com/release-notes"

A string filter não pode exceder 500 caracteres. Valores maiores que 500 caracteres vão resultar em um erro INVALID_ARGUMENT.

AnswerQueryResponse

Mensagem de resposta para DeveloperKnowledge.AnswerQuery.

Campos
answer

Answer

A resposta à consulta.

BatchGetDocumentsRequest

Mensagem de solicitação para DeveloperKnowledge.BatchGetDocuments.

Campos
names[]

string

Obrigatório. Especifica os nomes dos documentos a serem recuperados. É possível recuperar no máximo 20 documentos em um lote. Os documentos são retornados na mesma ordem que os names na solicitação.

Formato: documents/{uri_without_scheme} Exemplo: documents/docs.cloud.google.com/storage/docs/creating-buckets

Cada nome não pode exceder 500 caracteres. Valores maiores que 500 caracteres vão resultar em um erro INVALID_ARGUMENT.
view

DocumentView

Opcional. Especifica o DocumentView do documento. Se não for especificado, DeveloperKnowledge.BatchGetDocuments vai usar DOCUMENT_VIEW_CONTENT como padrão.

BatchGetDocumentsResponse

Mensagem de resposta para DeveloperKnowledge.BatchGetDocuments.

Campos
documents[]

Document

Contém os documentos solicitados.

Documento

Um Documento representa uma página de documentação no corpus de Conhecimento do Desenvolvedor, como a página em https://docs.cloud.google.com/storage/docs/creating-buckets.

Campos
name

string

Identificador. Contém o nome do recurso do documento. Formato: documents/{uri_without_scheme} Exemplo: documents/docs.cloud.google.com/storage/docs/creating-buckets
uri

string

Apenas saída. Fornece o URI do conteúdo, como https://docs.cloud.google.com/storage/docs/creating-buckets.
content

string

Apenas saída. Contém o conteúdo completo do documento no formato Markdown.
description

string

Apenas saída. Fornece uma descrição do documento.
data_source

string

Apenas saída. Especifica a fonte de dados do documento. Exemplo de fonte de dados: firebase.google.com
title

string

Apenas saída. Informa o título do documento.
update_time

Timestamp

Apenas saída. Representa o carimbo de data/hora da última atualização do conteúdo ou dos metadados do documento.
view

DocumentView

Apenas saída. Especifica o DocumentView do documento.
content_length_bytes

int32

Apenas saída. O tamanho do campo content em bytes.

DocumentChunk

Um DocumentChunk representa um conteúdo de um Document no corpus DeveloperKnowledge. Para buscar todo o conteúdo do documento, transmita o parent para DeveloperKnowledge.GetDocument ou DeveloperKnowledge.BatchGetDocuments.

Campos
parent

string

Apenas saída. Contém o nome do recurso do documento de origem do fragmento. Formato: documents/{uri_without_scheme} Exemplo: documents/docs.cloud.google.com/storage/docs/creating-buckets
id

string

Apenas saída. Especifica o ID desse fragmento no documento. O ID do fragmento é exclusivo em um documento, mas não globalmente em todos os documentos. O ID do bloco não é estável e pode mudar com o tempo.
content

string

Apenas saída. Contém o conteúdo do bloco de documento.
document

Document

Apenas saída. Representa metadados sobre o Document de origem desse fragmento. O DocumentView desta mensagem de Document será definido como DOCUMENT_VIEW_BASIC. Ele é incluído aqui para que os clientes não precisem chamar DeveloperKnowledge.GetDocument ou DeveloperKnowledge.BatchGetDocuments se precisarem apenas dos campos de metadados. Caso contrário, os clientes precisam usar DeveloperKnowledge.GetDocument ou DeveloperKnowledge.BatchGetDocuments para buscar o conteúdo completo do documento.
relevance_score

double

Apenas saída. Representa a pontuação de relevância do bloco para a consulta de pesquisa. Uma pontuação mais alta indica maior relevância do bloco. A pontuação está no intervalo [0.0, 1.0].

DocumentView

Especifica quais campos do Document estão incluídos.

Tipos enumerados
DOCUMENT_VIEW_UNSPECIFIED O valor padrão / não definido. Consulte cada método de API para saber o valor padrão se DocumentView não for especificado.
DOCUMENT_VIEW_BASIC

Inclui apenas os campos de metadados básicos:

  • name
  • uri
  • data_source
  • title
  • description
  • update_time
  • view
  • content_length_bytes

Essa é a visualização padrão de DeveloperKnowledge.SearchDocumentChunks.
DOCUMENT_VIEW_FULL Inclui todos os campos Document.
DOCUMENT_VIEW_CONTENT

Inclui os campos DOCUMENT_VIEW_BASIC e content.

Essa é a visualização padrão para DeveloperKnowledge.GetDocument e DeveloperKnowledge.BatchGetDocuments.

GetDocumentRequest

Mensagem de solicitação para DeveloperKnowledge.GetDocument.

Campos
name

string

Obrigatório. Especifica o nome do documento a ser recuperado. Formato: documents/{uri_without_scheme} Exemplo: documents/docs.cloud.google.com/storage/docs/creating-buckets

O nome não pode exceder 500 caracteres. Valores mais longos vão resultar em um erro INVALID_ARGUMENT.
view

DocumentView

Opcional. Especifica o DocumentView do documento. Se não for especificado, DeveloperKnowledge.GetDocument vai usar DOCUMENT_VIEW_CONTENT como padrão.

SearchDocumentChunksRequest

Mensagem de solicitação para DeveloperKnowledge.SearchDocumentChunks.

Campos
query

string

Obrigatório. Fornece a string de consulta bruta fornecida pelo usuário, como "Como criar um bucket do Cloud Storage?". A consulta não pode exceder 500 caracteres. Valores maiores que 500 caracteres vão resultar em um erro INVALID_ARGUMENT.
page_size

int32

Opcional. Especifica o número máximo de resultados a serem retornados. O serviço pode retornar um valor inferior a este.

Se não for especificado, serão retornados no máximo 5 resultados.

O valor máximo é 100. Valores maiores serão convertidos para 100.
page_token

string

Opcional. Contém um token de página recebido de uma chamada SearchDocumentChunks anterior. Forneça isso para recuperar a página subsequente.
filter

string

Opcional. Aplica um filtro rigoroso aos resultados da pesquisa. A expressão é compatível com um subconjunto da sintaxe descrita em https://google.aip.dev/160.

Enquanto SearchDocumentChunks retorna DocumentChunks, o filtro é aplicado aos campos DocumentChunk.document.

Campos compatíveis com a filtragem:

  • content_length_bytes (INTEGER): o comprimento do campo Document.content em bytes.
  • data_source (STRING): a origem do documento, por exemplo, docs.cloud.google.com. Consulte https://developers.google.com/knowledge/reference/corpus-reference para ver a lista completa de fontes de dados no corpus.
  • update_time (TIMESTAMP): o carimbo de data/hora de quando o documento foi atualizado de forma significativa pela última vez. Uma atualização significativa é aquela que muda o conteúdo de markdown ou os metadados do documento.
  • uri (STRING): o URI do documento, por exemplo, https://docs.cloud.google.com/bigquery/docs/tables.

Os campos INTEGER são compatíveis com os operadores =, <, <=, > e >=.

Os campos STRING são compatíveis com os operadores = (igual) e != (diferente) para correspondência exata em toda a string. Não há suporte para correspondência parcial, correspondência de prefixo e correspondência de regexp.

Os campos TIMESTAMP são compatíveis com os operadores =, <, <=, > e >=. Os carimbos de data/hora precisam estar no formato RFC-3339, por exemplo, "2025-01-01T00:00:00Z".

Observação: os nomes de campo precisam estar em snake_case (por exemplo, data_source). Os valores no lado direito das expressões de filtragem precisam ser strings literais entre aspas duplas (por exemplo, "docs.cloud.google.com").

É possível combinar expressões usando os operadores lógicos AND, OR e NOT (ou -). OR tem precedência maior que AND. Use parênteses para agrupamento de precedência explícita.

Exemplos:

  • Filtrar por Document.content_length_bytes: content_length_bytes < 50000
  • data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"
  • data_source != "firebase.google.com"
  • update_time < "2024-01-01T00:00:00Z"
  • update_time >= "2025-01-22T00:00:00Z" AND (data_source = "developer.chrome.com" OR data_source = "web.dev")
  • uri = "https://docs.cloud.google.com/release-notes"

A string filter não pode exceder 500 caracteres. Valores maiores que 500 caracteres vão resultar em um erro INVALID_ARGUMENT.

SearchDocumentChunksResponse

Mensagem de resposta para DeveloperKnowledge.SearchDocumentChunks.

Campos
results[]

DocumentChunk

Contém os resultados da pesquisa para a consulta indicada. Cada DocumentChunk nessa lista contém um snippet de conteúdo relevante para a consulta de pesquisa. Use o campo DocumentChunk.parent de cada resultado com DeveloperKnowledge.GetDocument ou DeveloperKnowledge.BatchGetDocuments para recuperar o conteúdo completo do documento.
next_page_token

string

Fornece um token que pode ser enviado como page_token para recuperar a próxima página. Se esse campo for omitido, não haverá páginas subsequentes.