Перейти к основному содержимому
Перейти к основному содержимому

Конечные точки API запросов

Функция Конечные точки API запросов позволяет вам создавать конечную точку API прямо из любого сохраненного SQL-запроса в консоли ClickHouse Cloud. Вы сможете получать доступ к конечным точкам API через HTTP, чтобы выполнять ваши сохраненные запросы без необходимости подключаться к вашему сервису ClickHouse Cloud через нативный драйвер.

Быстрый старт​

Прежде чем продолжить, убедитесь, что у вас есть API ключ и роль администратора консоли. Вы можете следовать этому руководству, чтобы создать API ключ.

Создание сохраненного запроса​

Если у вас уже есть сохраненный запрос, вы можете пропустить этот шаг.

Откройте новую вкладку запроса. Для демонстрации мы будем использовать набор данных youtube, который содержит приблизительно 4,5 миллиарда записей. В качестве примера запроса мы вернем 10 лучших загружающих пользователей по среднему количеству просмотров на видео в параметре year, введенном пользователем:

Обратите внимание, что этот запрос содержит параметр (year). Редактор запросов SQL консоли автоматически обнаруживает выражения параметров запроса ClickHouse и предоставляет ввод для каждого параметра. Давайте быстро запустим этот запрос, чтобы убедиться, что он работает:

Проверить пример запроса

Следующий шаг — сохранить запрос:

Сохранить пример запроса

Дополнительную документацию по сохраненным запросам можно найти здесь.

Настройка конечной точки API запросов​

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

Настроить конечную точку запроса

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

Команда curl для конечной точки

Параметры API запроса​

Параметры запроса в запросе могут быть указаны с помощью синтаксиса {parameter_name: type}. Эти параметры будут автоматически обнаружены, и пример полезной нагрузки запроса будет содержать объект queryVariables, через который вы можете передавать эти параметры.

Тестирование и мониторинг​

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

тест curl для конечной точки

После того как вы отправите свой первый запрос, новая кнопка должна немедленно появиться справа от кнопки Поделиться. Нажав на нее, вы откроете всплывающее окно с данными мониторинга о запросе:

Мониторинг конечной точки

Подробности реализации​

Описание​

Этот маршрут выполняет запрос на указанной конечной точке запроса. Он поддерживает различные версии, форматы и переменные запроса. Ответ может быть передан как поток (версия 2 только) или возвращен как единая полезная нагрузка.

Аутентификация​

  • Обязательно: Да
  • Метод: Основная аутентификация через OpenAPI Key/Secret
  • Права доступа: Соответствующие права для конечной точки запроса.

URL Параметры​

  • queryEndpointId (обязательно): Уникальный идентификатор конечной точки запроса, которую необходимо выполнить.

Параметры запроса​

V1​

Нет

V2​

  • format (необязательно): Формат ответа. Поддерживает все форматы, поддерживаемые ClickHouse.
  • param_:name Переменные запроса, которые будут использоваться в запросе. name должен соответствовать имени переменной в запросе. Это следует использовать только когда тело запроса — это поток.
  • :clickhouse_setting Любую поддерживаемую настройку ClickHouse можно передать как параметр запроса.

Заголовки​

  • x-clickhouse-endpoint-version (необязательно): Версия конечной точки запроса. Поддерживаемые версии: 1 и 2. Если не предоставлено, версия по умолчанию — последняя сохраненная для конечной точки.
  • x-clickhouse-endpoint-upgrade (необязательно): Установите этот заголовок для обновления версии конечной точки. Это работает совместно с заголовком x-clickhouse-endpoint-version.

Тело запроса​

  • queryVariables (необязательно): Объект, содержащий переменные, которые будут использоваться в запросе.
  • format (необязательно): Формат ответа. Если конечная точка API запроса версии 2, любой поддерживаемый формат ClickHouse возможен. Поддерживаемые форматы для версии 1:
    • TabSeparated
    • TabSeparatedWithNames
    • TabSeparatedWithNamesAndTypes
    • JSON
    • JSONEachRow
    • CSV
    • CSVWithNames
    • CSVWithNamesAndTypes

Ответы​

  • 200 OK: Запрос был успешно выполнен.
  • 400 Bad Request: Запрос был неправильно сформирован.
  • 401 Unauthorized: Запрос был сделан без аутентификации или с недостаточными правами.
  • 404 Not Found: Указанная конечная точка запроса не найдена.

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

  • Убедитесь, что запрос включает действительные учетные данные аутентификации.
  • Проверьте queryEndpointId и queryVariables, чтобы убедиться, что они корректны.
  • Обрабатывайте любые ошибки сервера корректно, возвращая соответствующие сообщения об ошибках.

Обновление версии конечной точки​

Чтобы обновить версию конечной точки с v1 до v2, включите заголовок x-clickhouse-endpoint-upgrade в запрос и установите его значение на 1. Это инициирует процесс обновления и позволит вам использовать функции и улучшения, доступные в v2.

Примеры​

Основной запрос​

SQL конечной точки API запроса:

Версия 1​

cURL:

JavaScript:

Ответ:

Версия 2​

cURL:

JavaScript:

Ответ:

Запрос с переменными запроса и версией 2 в формате JSONCompactEachRow​

SQL конечной точки API запроса:

cURL:

JavaScript:

Ответ:

Запрос с массивом в переменных запроса, который вставляет данные в таблицу​

SQL таблицы:

SQL конечной точки API запроса:

cURL:

JavaScript:

Ответ:

Запрос с настройкой ClickHouse max_threads, установленной на 8​

SQL конечной точки API запроса:

cURL:

JavaScript:

Запрос и парсинг ответа как поток​

SQL конечной точки API запроса:

Typescript:

Вывод

Вставка потока из файла в таблицу​

Создайте файл ./samples/my_first_table_2024-07-11.csv со следующим содержимым:

SQL Создания Таблицы:

SQL конечной точки API запроса:

cURL: