Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Поиск и получение документов

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

В этом документе приведены примеры для следующих задач:

Поиск в корпусе документации.
Переход между страницами результатов поиска.
Применение сложных фильтров к поисковому запросу.
Получение полного содержимого документа.
Оптимизация полезной нагрузки ответов для уменьшения задержки.

Прежде чем начать, настройте среду для предпочитаемого инструмента:

gcloud

Установите и настройте gcloud CLI и включите Developer Knowledge API.

REST

Включите API и создайте ключ Developer Knowledge API. Затем сохраните ключ в переменной среды:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Замените YOUR_API_KEY ключом Developer Knowledge API.

Как искать документы

Используйте gcloud developer-knowledge documents search-chunks команду или documents.searchDocumentChunks метод REST , чтобы найти фрагменты документов, соответствующие строке запроса. В результатах поиска будут показаны фрагменты контента из подходящих документов и parentссылки, по которым можно перейти к полному тексту этих документов.

В следующем примере выполняется поиск документов, содержащих слово "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"

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

{
  "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
    }
  ]
}

Каждый результат в списке results включает:

parent – название ресурса документа (например, documents/docs.cloud.google.com/bigquery/docs/introduction).
id – идентификатор фрагмента в документе (например, chunk_0).
content – фрагмент текста из документа, который соответствует запросу.
document – метаданные исходного документа, например его title, uri, dataSource и updateTime.
relevanceScore – оценка релевантности фрагмента поисковому запросу в диапазоне [0.0, 1.0].

Дополнительную информацию о схеме ответа и всех доступных полях метаданных можно найти в справочной документации по API documents.searchDocumentChunks.

Как переходить между страницами результатов поиска

Если по запросу найдено несколько результатов, вы можете переходить между ними с помощью параметров разбивки на страницы:

--page-size (gcloud CLI) или pageSize (целое число): максимальное количество результатов, возвращаемых на странице. Если значение не указано, API по умолчанию возвращает пять результатов. Максимальное допустимое значение – 100. Если указать большее значение, оно будет приведено к 100.
--limit (gcloud CLI) или pageToken (строка): в gcloud CLI используйте --limit, чтобы управлять общим количеством результатов, возвращаемых на разных страницах. В запросах REST передайте значение pageToken, полученное в предыдущем ответе, чтобы получить следующую страницу результатов.

gcloud

Используйте флаги --page-size и --limit, чтобы задать количество результатов на странице и общее количество возвращаемых результатов:

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

REST

Чтобы запросить первую страницу, передайте параметр pageSize в запросе:

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

Если доступны дополнительные результаты, ответ содержит объект 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"
}

Чтобы получить следующие страницы, передайте значение параметра nextPageToken параметру pageToken в следующем запросе:
```
curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&pageToken=CAUQABgB&key=$DEVELOPERKNOWLEDGE_API_KEY"
```
Когда вы переходите на последнюю страницу результатов, nextPageToken удаляется из ответа.

Как фильтровать результаты поиска

Используйте флаг --query-filter в gcloud CLI или параметр filter в запросах REST, чтобы применить строгий фильтр к результатам поиска. Выражение фильтра применяется к метаданным родительского документа для каждого фрагмента.

Выражение фильтра может содержать не более 500 символов.

Поддерживаемые поля

Вы можете отфильтровать результаты поиска по следующим полям родительского документа:

content_length_bytes (целое число) – длина поля content документа в байтах.
data_source (string): исходный домен документа, например docs.cloud.google.com или firebase.google.com. Все поддерживаемые источники данных перечислены в справочнике по корпусу.
update_time (временная метка) – временная метка последнего обновления документа. Значения должны быть указаны в формате RFC 3339 (например, "2025-01-01T00:00:00Z").
uri (string): полный URI документа (например, https://docs.cloud.google.com/bigquery/docs/tables).

Поддерживаемые операторы

В зависимости от типа данных поля парсер выражений фильтра поддерживает разные операторы:

Строковые поля (data_source, uri) поддерживают операторы = (равно) и != (не равно) для точного строкового соответствия. Частичные совпадения, совпадения префиксов и регулярных выражений не поддерживаются.
Поля временных меток (update_time) поддерживают =, <, <=, > и >=.
Целочисленные поля (content_length_bytes) поддерживают =, !=, <, <=, > и >=.
Логические операторы позволяют объединять условия с помощью операторов AND, OR и NOT (или -).

Примеры фильтров

В следующих примерах показано, как создавать выражения фильтров. При использовании gcloud CLI передайте выражение в параметр --query-filter. При вызове REST API с помощью curl убедитесь, что параметр filter закодирован в URL, или используйте --data-urlencode.

Как сопоставить один источник данных

Чтобы ограничить результаты поиска одним доменом документации:

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"

Как сопоставлять несколько источников данных

Используйте OR, чтобы включить документы из нескольких источников:

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"

Фильтрация по временной метке

Используйте операторы сравнения с временными метками RFC 3339, чтобы найти контент, обновленный после определенной даты:

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"

Как фильтровать видео по длительности

Используйте операторы сравнения с оператором content_length_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"

Как объединить источник данных, временную метку и группировку

Используйте операторы AND, OR и скобки (...), чтобы ограничить результаты поиска определенными источниками, обновленными после указанной даты:

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

Как исключить источники данных

Используйте оператор NOT или !=, чтобы исключить результаты из определенного источника:

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"

Как найти документ

Чтобы получить полный контент одного документа, используйте команду gcloud developer-knowledge documents describe или метод REST documents.get.

В следующем примере показано, как получить документ по названию ресурса:

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"

Ответ представляет собой ресурс Document, содержащий метаданные и полный контент в формате Markdown в поле content.

Названия ресурсов и URI

При работе с документами в Developer Knowledge API учитывайте разницу между названиями ресурсов и URI:

Название ресурса (parent, name) в формате documents/{uri_without_scheme} (например, documents/docs.cloud.google.com/storage/docs/creating-buckets). Передайте это значение в качестве позиционного аргумента в gcloud developer-knowledge documents describe, параметра пути в GetDocument или параметра names в BatchGetDocuments.
Веб-URI (uri) – полный веб-URL, включающий схему (например, https://docs.cloud.google.com/storage/docs/creating-buckets). Используйте этот формат для поля uri при создании выражений --query-filter или filter (например, uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

Как получить несколько документов с помощью `BatchGetDocuments`

Используйте метод documents.batchGet, чтобы получить до 20 документов по названию за один вызов API. Это эффективнее, чем отправлять несколько запросов GetDocument.

В следующем примере показано, как получить два документа по названию:

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"

Ответ содержит список запрошенных ресурсов Document в том порядке, в котором вы их запросили.

Как оптимизировать полезную нагрузку ответов

Контент документа в формате Markdown может быть большим. Если приложению нужны только метаданные (например, заголовки страниц, URI или временные метки) или определенные поля, вы можете оптимизировать размер полезной нагрузки, чтобы уменьшить пропускную способность и задержку.

Как использовать режимы просмотра документов

Флаг --view в gcloud CLI или параметр view в запросах REST определяет, какие поля заполняются в сообщениях Document.

Флаг --view и перечисление DocumentView поддерживают следующие значения:

--view=basic (командная строка gcloud) или DOCUMENT_VIEW_BASIC: возвращает только основные поля метаданных (name, uri, dataSource, title, description, updateTime и view). Поле content не возвращается.
--view=content (gcloud CLI) или DOCUMENT_VIEW_CONTENT: возвращает поля метаданных вместе с полем Markdown content. Это значение по умолчанию для gcloud developer-knowledge documents describe, GetDocument и BatchGetDocuments.
--view=full (gcloud CLI) или DOCUMENT_VIEW_FULL: возвращает все поля документа.

Чтобы получить только метаданные документа без скачивания большого контента в формате Markdown, укажите базовый режим просмотра документа:

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"

Вы также можете использовать view=DOCUMENT_VIEW_BASIC с 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"

Используйте маски полей

Чтобы ещё больше ограничить полезную нагрузку ответа определенными полями, используйте стандартный параметр запроса fields (маска поля) API Google.

Как фильтровать поля в `GetDocument`

Чтобы получить только поля title, uri и updateTime документа:

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?fields=title,uri,updateTime&key=$DEVELOPERKNOWLEDGE_API_KEY"

Как фильтровать поля в `BatchGetDocuments`

Чтобы получить только определенные поля для каждого документа в пакете:

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"

Как фильтровать поля в `SearchDocumentChunks`

Чтобы вернуть только фрагменты id и content, родительский документ title и uri и nextPageToken из поиска:

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

Обработка ошибок

API Developer Knowledge возвращает стандартные коды статуса HTTP. Ниже приведены примеры того, как коды статуса HTTP и их причины представлены в Developer Knowledge API.

400 INVALID_ARGUMENT:
- Длина строки выражения filter превышает 500 символов.
- Временная метка update_time недействительна (необходимо использовать формат RFC 3339).
- В запросе указано более 20 названий документов.BatchGetDocuments
401 UNAUTHENTICATED – в запросе отсутствует ключ API или используется недействительный ключ. Подробнее об аутентификации…
404 NOT_FOUND – запрошенного документа не существует или он относится к домену, не включенному в корпус.
429 RESOURCE_EXHAUSTED – квота проекта превышена. Подробнее о квотах и ограничениях…

Дальнейшие действия

Подробнее о том, как генерировать ответы на основе документации…
Подключитесь к MCP-серверу Developer Knowledge и установите навык агента retrieving-developer-knowledge, чтобы ваш ИИ-помощник по написанию кода мог искать и читать официальную документацию.
Узнайте, как использовать клиентские библиотеки на языках Python, Node.js, Go или Java.
Узнайте, как использовать gcloud CLI.
Чтобы посмотреть все поддерживаемые источники документации, ознакомьтесь с корпусом.
Полные спецификации методов приведены в справочной документации по REST API.
Проверьте квоты и ограничения для лимитов и квот на использование API.

Поиск и получение документов Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

gcloud

REST

Как искать документы

gcloud

REST

Как переходить между страницами результатов поиска

gcloud

REST

Как фильтровать результаты поиска

Поддерживаемые поля

Поддерживаемые операторы

Примеры фильтров

Как сопоставить один источник данных

gcloud

REST

Как сопоставлять несколько источников данных

gcloud

REST

Фильтрация по временной метке

gcloud

REST

Как фильтровать видео по длительности

gcloud

REST

Как объединить источник данных, временную метку и группировку

gcloud

REST

Как исключить источники данных

gcloud

REST

Как найти документ

gcloud

REST

Названия ресурсов и URI

Как получить несколько документов с помощью BatchGetDocuments

Как оптимизировать полезную нагрузку ответов

Как использовать режимы просмотра документов

gcloud

REST

Используйте маски полей

Как фильтровать поля в GetDocument

Как фильтровать поля в BatchGetDocuments

Как фильтровать поля в SearchDocumentChunks

Обработка ошибок

Дальнейшие действия

Поиск и получение документов

Как получить несколько документов с помощью `BatchGetDocuments`

Как фильтровать поля в `GetDocument`

Как фильтровать поля в `BatchGetDocuments`

Как фильтровать поля в `SearchDocumentChunks`