Package google.developers.knowledge.v1

Содержание

DeveloperKnowledge

Developer Knowledge API предоставляет программный доступ к общедоступной документации Google для разработчиков, позволяя интегрировать эту базу знаний в ваши приложения и рабочие процессы.

API предназначен для того, чтобы быть каноническим источником для машиночитаемого доступа к документации Google для разработчиков.

Типичный вариант использования – сначала использовать DeveloperKnowledge.SearchDocumentChunks, чтобы найти релевантные фрагменты документов на основе запроса, а затем использовать DeveloperKnowledge.GetDocument или DeveloperKnowledge.BatchGetDocuments с именами ресурсов документов (например, DocumentChunk.parent или documents/{uri_without_scheme}), чтобы получить полное содержимое лучших результатов.

Все содержимое документа представлено в формате Markdown.

AnswerQuery

rpc AnswerQuery(AnswerQueryRequest) returns (AnswerQueryResponse)

Отвечает на запрос, используя обоснованную генерацию.

Области авторизации

Требует одной из следующих областей применения OAuth:

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

Дополнительную информацию вы найдете в OAuth 2.0 Overview.
BatchGetDocuments

rpc BatchGetDocuments(BatchGetDocumentsRequest) returns (BatchGetDocumentsResponse)

Извлекает несколько документов, каждый из которых содержит полный контент Markdown.

Области авторизации

Требует одной из следующих областей применения OAuth:

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

Дополнительную информацию вы найдете в OAuth 2.0 Overview.
GetDocument

rpc GetDocument(GetDocumentRequest) returns (Document)

Извлекает один документ с полным содержимым Markdown.

Области авторизации

Требует одной из следующих областей применения OAuth:

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

Дополнительную информацию вы найдете в OAuth 2.0 Overview.
SearchDocumentChunks

rpc SearchDocumentChunks(SearchDocumentChunksRequest) returns (SearchDocumentChunksResponse)

Поиск по документации Google для разработчиков. Возвращает DocumentChunk на основе запроса пользователя. Из одного Document может быть получено много фрагментов. Чтобы получить полные документы, используйте DeveloperKnowledge.GetDocument или DeveloperKnowledge.BatchGetDocuments с DocumentChunk.parent, возвращенным в SearchDocumentChunksResponse.results.

Области авторизации

Требует одной из следующих областей применения OAuth:

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

Дополнительную информацию вы найдете в OAuth 2.0 Overview.

Ответ

Ответ на запрос.

Поля
answer_text

string

Содержит текст ответа.
citations[]

AnswerCitation

Только для вывода. Содержит цитаты для ответа.
references[]

AnswerReference

Только для вывода. Содержит ссылки на источники ответа.

AnswerCitation

Информация о цитировании для сегмента.

Поля
start_index

int32

Только для вывода. Указывает на начало сегмента, измеряемого в байтах (UTF-8 unicode), включительно. Если в строке есть многобайтовые символы, например не входящие в набор ASCII, то индекс будет больше длины строки.
end_index

int32

Только для вывода. Указывает на конец сегмента, измеряется в байтах (UTF-8 unicode), не включительно. Если в строке есть многобайтовые символы, например не входящие в набор ASCII, то индекс будет больше длины строки.
sources[]

CitationSource

Только для вывода. Содержит источники цитат для сегмента с атрибуцией.

AnswerReference

Представляет ссылку на источник.

Поля
Объединенное поле content. Содержит контент цифрового отпечатка. content может иметь одно из следующих значений:
document_reference

DocumentReference

Только для вывода. Используемый документ.

CitationSource

Источник цитаты.

Поля
reference_index

int32

Только для вывода. Содержит индекс Answer.AnswerReference в повторяющемся поле references.

DocumentReference

Представляет ссылку на документ.

Поля
document_chunk

DocumentChunk

Только для вывода. Содержит фрагмент документа. Поле document_chunk.id не задано и будет пустым.

AnswerQueryRequest

Сообщение с запросом для DeveloperKnowledge.AnswerQuery.

Поля
query

string

Обязательно. Запрос, на который нужно ответить.
filter

string

Необязательное поле. Применяет строгий фильтр к результатам поиска, используемым для обоснования ответа. Выражение поддерживает подмножество синтаксиса, описанного на странице https://google.aip.dev/160.

Поддерживаемые поля для фильтрации:

  • content_length_bytes (INTEGER). Длина поля Document.content в байтах.
  • data_source (STRING): источник документа, например docs.cloud.google.com. Полный список источников данных в корпусе можно найти на странице https://developers.google.com/knowledge/reference/corpus-reference.
  • update_time (TIMESTAMP). Временная метка, указывающая, когда документ был в последний раз существенно обновлен. Значимым считается обновление, которое меняет контент или метаданные документа.
  • uri (STRING): URI документа, например https://docs.cloud.google.com/bigquery/docs/tables.

Поля INTEGER поддерживают операторы =, <, <=, > и >=.

Поля STRING поддерживают операторы = (равно) и != (не равно) для точного соответствия по всей строке. Частичное соответствие, соответствие префиксу и регулярному выражению не поддерживаются.

Поля TIMESTAMP поддерживают операторы =, <, <=, > и >=. Временные метки должны быть указаны в формате RFC-3339, например "2025-01-01T00:00:00Z".

Выражения можно комбинировать с помощью логических операторов AND, OR и NOT (или -). OR имеет более высокий приоритет, чем AND. Для явного указания приоритета используйте скобки.

Примеры:

  • Применить фильтр "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"

Строка filter не должна превышать 500 символов. Если она длиннее, возникнет ошибка INVALID_ARGUMENT.

AnswerQueryResponse

Ответное сообщение для DeveloperKnowledge.AnswerQuery.

Поля
answer

Answer

Ответ на запрос.

BatchGetDocumentsRequest

Сообщение с запросом для DeveloperKnowledge.BatchGetDocuments.

Поля
names[]

string

Обязательно. Указывает названия документов, которые нужно получить. За один раз можно получить не более 20 документов. Документы возвращаются в том же порядке, что и names в запросе.

Формат: documents/{uri_without_scheme}. Пример: documents/docs.cloud.google.com/storage/docs/creating-buckets.

Каждое название должно содержать не более 500 символов. Если это ограничение будет превышено, возникнет ошибка INVALID_ARGUMENT.
view

DocumentView

Необязательное поле. Указывает DocumentView документа. Если значение DeveloperKnowledge.BatchGetDocuments не указано, по умолчанию используется DOCUMENT_VIEW_CONTENT.

BatchGetDocumentsResponse

Ответное сообщение для DeveloperKnowledge.BatchGetDocuments.

Поля
documents[]

Document

Содержит запрошенные документы.

Документ

Документ представляет собой страницу документации в корпусе знаний для разработчиков, например страницу https://docs.cloud.google.com/storage/docs/creating-buckets.

Поля
name

string

Идентификатор. Содержит название ресурса документа. Формат: documents/{uri_without_scheme}. Пример: documents/docs.cloud.google.com/storage/docs/creating-buckets.
uri

string

Только для вывода. URI контента, например https://docs.cloud.google.com/storage/docs/creating-buckets.
content

string

Только для вывода. Содержит полный контент документа в формате Markdown.
description

string

Только для вывода. Описание документа.
data_source

string

Только для вывода. Указывает источник данных документа. Пример источника данных: firebase.google.com
title

string

Только для вывода. Содержит название документа.
update_time

Timestamp

Только для вывода. Временная метка последнего обновления контента или метаданных документа.
view

DocumentView

Только для вывода. Указывает DocumentView документа.
content_length_bytes

int32

Только для вывода. Длина поля content в байтах.

DocumentChunk

DocumentChunk представляет собой фрагмент контента из Document в корпусе DeveloperKnowledge. Чтобы получить весь контент документа, передайте parent в DeveloperKnowledge.GetDocument или DeveloperKnowledge.BatchGetDocuments.

Поля
parent

string

Только для вывода. Содержит название ресурса документа, из которого взят этот фрагмент. Формат: documents/{uri_without_scheme}. Пример: documents/docs.cloud.google.com/storage/docs/creating-buckets.
id

string

Только для вывода. Указывает идентификатор этого фрагмента в документе. Идентификатор фрагмента уникален в пределах документа, но не во всех документах. Идентификатор фрагмента не является стабильным и может со временем меняться.
content

string

Только для вывода. Содержит контент фрагмента документа.
document

Document

Только для вывода. Представляет метаданные о Document, из которого взят этот фрагмент. Для параметра DocumentView этого сообщения (Document) будет задано значение DOCUMENT_VIEW_BASIC. Оно включено сюда для удобства, чтобы клиентам не нужно было вызывать DeveloperKnowledge.GetDocument или DeveloperKnowledge.BatchGetDocuments, если им нужны только поля метаданных. В противном случае клиенты должны использовать DeveloperKnowledge.GetDocument или DeveloperKnowledge.BatchGetDocuments, чтобы получить полное содержимое документа.
relevance_score

double

Только для вывода. Представляет оценку релевантности фрагмента поисковому запросу. Чем выше оценка, тем выше релевантность фрагмента. Оценка находится в диапазоне [0.0, 1.0].

DocumentView

Указывает, какие поля Document включены.

Перечисления
DOCUMENT_VIEW_UNSPECIFIED Значение по умолчанию или незаданное значение. Если значение DocumentView не указано, для каждого метода API используется значение по умолчанию.
DOCUMENT_VIEW_BASIC

Включает только основные поля метаданных:

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

Это представление по умолчанию для DeveloperKnowledge.SearchDocumentChunks.
DOCUMENT_VIEW_FULL Включает все поля Document.
DOCUMENT_VIEW_CONTENT

Включает поля DOCUMENT_VIEW_BASIC и поле content.

Это представление по умолчанию для DeveloperKnowledge.GetDocument и DeveloperKnowledge.BatchGetDocuments.

GetDocumentRequest

Сообщение с запросом для DeveloperKnowledge.GetDocument.

Поля
name

string

Обязательно. Указывает название документа, который нужно получить. Формат: documents/{uri_without_scheme}. Пример: documents/docs.cloud.google.com/storage/docs/creating-buckets.

Название не должно превышать 500 символов. Если оно длиннее, возникнет ошибка INVALID_ARGUMENT.
view

DocumentView

Необязательное поле. Указывает DocumentView документа. Если значение DeveloperKnowledge.GetDocument не указано, по умолчанию используется DOCUMENT_VIEW_CONTENT.

SearchDocumentChunksRequest

Сообщение с запросом для DeveloperKnowledge.SearchDocumentChunks.

Поля
query

string

Обязательно. Предоставляет необработанную строку запроса, введенную пользователем, например "Как создать сегмент Cloud Storage?". Запрос не должен превышать 500 символов. Если он будет длиннее, возникнет ошибка INVALID_ARGUMENT.
page_size

int32

Необязательное поле. Указывает максимальное количество результатов, которые нужно вернуть. Сервис может вернуть меньше результатов, чем указано в этом значении.

Если значение не указано, будет возвращено не более пяти результатов.

Максимальное значение – 100. Значения выше 100 будут принудительно заменены на 100.
page_token

string

Необязательное поле. Содержит токен страницы, полученный из предыдущего вызова SearchDocumentChunks. Укажите его, чтобы получить следующую страницу.
filter

string

Необязательное поле. К результатам поиска применяется строгий фильтр. Выражение поддерживает подмножество синтаксиса, описанного на странице https://google.aip.dev/160.

SearchDocumentChunks возвращает DocumentChunk, а фильтр применяется к полям DocumentChunk.document.

Поддерживаемые поля для фильтрации:

  • content_length_bytes (INTEGER). Длина поля Document.content в байтах.
  • data_source (STRING): источник документа, например docs.cloud.google.com. Полный список источников данных в корпусе можно найти на странице https://developers.google.com/knowledge/reference/corpus-reference.
  • update_time (TIMESTAMP). Временная метка, указывающая, когда документ был в последний раз существенно обновлен. Значимым считается обновление, которое меняет контент или метаданные документа.
  • uri (STRING): URI документа, например https://docs.cloud.google.com/bigquery/docs/tables.

Поля INTEGER поддерживают операторы =, <, <=, > и >=.

Поля STRING поддерживают операторы = (равно) и != (не равно) для точного соответствия по всей строке. Частичное соответствие, соответствие префиксу и регулярному выражению не поддерживаются.

Поля TIMESTAMP поддерживают операторы =, <, <=, > и >=. Временные метки должны быть указаны в формате RFC-3339, например "2025-01-01T00:00:00Z".

Примечание. Названия полей должны быть в формате snake_case (например, data_source). Значения в правой части выражений фильтрации должны быть строковыми литералами, заключенными в двойные кавычки (например, "docs.cloud.google.com").

Выражения можно комбинировать с помощью логических операторов AND, OR и NOT (или -). OR имеет более высокий приоритет, чем AND. Для явного указания приоритета используйте скобки.

Примеры:

  • Применить фильтр "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"

Строка filter не должна превышать 500 символов. Если она будет длиннее, возникнет ошибка INVALID_ARGUMENT.

SearchDocumentChunksResponse

Ответное сообщение для DeveloperKnowledge.SearchDocumentChunks.

Поля
results[]

DocumentChunk

Содержит результаты поиска по заданному запросу. Каждый DocumentChunk в этом списке содержит фрагмент контента, соответствующий поисковому запросу. Используйте поле DocumentChunk.parent каждого результата с DeveloperKnowledge.GetDocument или DeveloperKnowledge.BatchGetDocuments, чтобы получить полное содержимое документа.
next_page_token

string

Предоставляет токен, который можно отправить как page_token, чтобы получить следующую страницу. Если это поле отсутствует, значит последующих страниц нет.