Чтобы переводить контент на ваш предпочитаемый язык, 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 (строка) – исходный домен документа, например docs.cloud.google.com или firebase.google.com. Все поддерживаемые источники данных перечислены в справочнике по корпусам.
update_time (временная метка) – временная метка последнего обновления документа. Значения должны быть указаны в формате RFC 3339 (например, "2025-01-01T00:00:00Z").
uri (строка) – полный 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 CLI) или 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"

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

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

Фильтровать поля в `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"

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

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

400 INVALID_ARGUMENT:
- Длина строки выражения filter превышает 500 символов.
- Временная метка update_time недействительна (необходимо использовать формат RFC 3339).
- В запросе указано более 20 названий документов.BatchGetDocuments
401 UNAUTHENTICATED – в запросе отсутствует ключ API или токен Bearer либо используются недействительные учетные данные. Подробнее об аутентификации…
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`