Эта страница переведена с помощью Cloud Translation API.

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

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

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

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

Прежде чем начать, убедитесь, что вы включили API и сгенерировали ключ API для разработчиков . Затем сохраните свой ключ в переменной среды:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Поиск документов с помощью `SearchDocumentChunks`

Используйте метод documents.searchDocumentChunks для поиска фрагментов документа, соответствующих заданному запросу. Результаты включают фрагменты содержимого из соответствующих документов, а также ссылку parent , которую можно использовать для получения полного содержимого этих документов.

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

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 .

Постраничная разбивка результатов поиска

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

pageSize (целое число): указывает максимальное количество результатов, возвращаемых на странице. Если не указано, API по умолчанию возвращает пять результатов. Максимально допустимое значение — 100; значения больше 100 преобразуются в 100.
pageToken (строка): указывает токен, полученный в предыдущем ответе, для получения следующей страницы результатов.

Запросить первую страницу

Чтобы задать размер страницы, передайте параметр 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 будет опущен в ответе.

Фильтрация результатов поиска

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

Выражение filter имеет ограничение в 500 символов.

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

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

content_length_bytes (целое число): длина поля content документа в байтах.
data_source (строка): домен источника документа, например docs.cloud.google.com или firebase.google.com . См. справочник по корпусу для получения информации обо всех поддерживаемых источниках данных.
update_time (timestamp): метка времени последнего обновления документа. Значения должны соответствовать формату 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 (или - ).

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

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

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

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

data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"

Запрос curl :

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"

Запрос curl :

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

Запрос curl :

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"

Запрос curl :

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"

Запрос curl :

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"

Получите документ с помощью `GetDocument`

Для получения полного содержимого отдельного документа используйте метод documents.get .

Имена ресурсов против URI

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

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

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

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?key=$DEVELOPERKNOWLEDGE_API_KEY"

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

Получение нескольких документов одновременно с помощью `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 определяет, какие поля заполняются в сообщениях Document .

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

DOCUMENT_VIEW_BASIC : возвращает только основные поля метаданных ( name , uri , data_source , title , description , update_time и view ). Поле content опущено.
DOCUMENT_VIEW_CONTENT : возвращает поля метаданных вместе с полем content Markdown. Это значение по умолчанию для GetDocument и BatchGetDocuments .
DOCUMENT_VIEW_FULL : возвращает все поля документа.

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

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 базы знаний для разработчиков возвращает стандартные коды состояния HTTP. Следующие функциональные примеры отображают коды состояния HTTP и их причины в API базы знаний для разработчиков:

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

Что дальше?

См. Ответы на запросы с использованием обоснованной генерации .
Изучите, как использовать клиентские библиотеки в Python, Node.js, Go или Java.
Просмотрите каталог документов , чтобы увидеть все поддерживаемые источники документации.
Для получения полной информации о методах ознакомьтесь со справочником по REST API .
Проверьте квоты и лимиты для получения информации об ограничениях скорости и квотах API.

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

Поиск документов с помощью SearchDocumentChunks

Постраничная разбивка результатов поиска

Запросить первую страницу

Перейти к следующим страницам

Фильтрация результатов поиска

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

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

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

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

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

Фильтрация по длине контента

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

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

Получите документ с помощью GetDocument

Имена ресурсов против URI

Получение нескольких документов одновременно с помощью BatchGetDocuments

Оптимизация полезной нагрузки ответов

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

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

Фильтрация полей в GetDocument

Фильтрация полей в BatchGetDocuments

Фильтрация полей в SearchDocumentChunks

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

Что дальше?

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

Поиск документов с помощью `SearchDocumentChunks`

Получите документ с помощью `GetDocument`

Получение нескольких документов одновременно с помощью `BatchGetDocuments`

Фильтрация полей в `GetDocument`

Фильтрация полей в `BatchGetDocuments`

Фильтрация полей в `SearchDocumentChunks`