В этом руководстве приведены примеры использования функций API базы знаний для разработчиков: поиск документов, получение одного документа и получение нескольких документов одновременно.
Прежде чем начать, убедитесь, что вы включили 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"
Вы можете уточнить результаты поиска, используя такие параметры, как pageSize , чтобы ограничить количество результатов на странице, и pageToken чтобы получить доступ к последующим страницам.
Фильтрация результатов поиска
Используйте параметр filter , чтобы применить строгий фильтр к результатам поиска. Фильтр применяется к метаданным документов, связанных с фрагментами результатов поиска.
Поддерживаемые поля для фильтрации:
-
data_source(STRING): Источник документа, например,docs.cloud.google.com. -
update_time(TIMESTAMP): Отметка времени последнего обновления документа. -
uri(STRING): URI документа, например,https://docs.cloud.google.com/bigquery/docs/tables.
Поддерживаемые операторы:
- Строковые поля поддерживают операторы
=(равно) и!=(не равно) для точного совпадения со всей строкой. - Поля TIMESTAMP поддерживают символы
=,<,<=,>и>=. Временные метки должны быть в формате RFC-3339 (например,"2025-01-01T00:00:00Z").
Выражения можно комбинировать с помощью логических операторов AND , OR и NOT (или - ). Обратите внимание, что OR имеет более высокий приоритет, чем AND
В следующем примере выполняется поиск документов, соответствующих запросу "BigQuery", и результаты ограничиваются документами с сайта docs.cloud.google.com :
curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&filter=data_source%3D%22docs.cloud.google.com%22&key=$DEVELOPERKNOWLEDGE_API_KEY"
Получите документ с помощью GetDocument
Для получения полного содержимого отдельного документа используйте метод documents.get .
В следующем примере извлекается документ с именем documents/DOCUMENT_ID :
curl "https://developerknowledge.googleapis.com/v1/documents:get?name=documents/DOCUMENT_ID&key=$DEVELOPERKNOWLEDGE_API_KEY"
В ответе вы получите полный Document , включая поле content .
Получение нескольких документов одновременно с помощью BatchGetDocuments
Используйте метод documents.batchGet для получения до 100 документов по имени за один вызов API. Это эффективнее, чем выполнение нескольких запросов GetDocument .
В следующем примере извлекаются два документа по имени:
curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/DOCUMENT_ID_1&names=documents/DOCUMENT_ID_2&key=$DEVELOPERKNOWLEDGE_API_KEY"
В ответе содержится список запрошенных ресурсов Document .