Использование HTTP интерфейса ClickHouse в Azure Data Factory

azureBlobStorage табличная функция является быстрым и удобным способом загрузки данных из Azure Blob Storage в ClickHouse. Однако ее использование может оказаться не всегда подходящим по следующим причинам:

• Ваши данные могут не храниться в Azure Blob Storage — например, они могут находиться в Azure SQL Database, Microsoft SQL Server или Cosmos DB.
• Политики безопасности могут полностью запрещать внешний доступ к Blob Storage — например, если учетная запись хранения заблокирована без общедоступной конечной точки.

В таких сценариях вы можете использовать Azure Data Factory вместе с HTTP интерфейсом ClickHouse для отправки данных из Azure-сервисов в ClickHouse.

Этот метод меняет направление потока: вместо того, чтобы ClickHouse запрашивал данные из Azure, Azure Data Factory отправляет данные в ClickHouse. Этот подход обычно требует, чтобы ваш экземпляр ClickHouse был доступен из интернета.

к сведению

Можно избежать экспонирования вашего экземпляра ClickHouse в интернет, используя самоуправляемый интеграционный механизм Azure Data Factory. Эта настройка позволяет отправлять данные по частной сети. Однако это выходит за рамки данной статьи. Вы можете найти больше информации в официальном руководстве: Создайте и настройте самоуправляемый интеграционный механизм

Превращение ClickHouse в REST-сервис

Azure Data Factory поддерживает отправку данных во внешние системы по HTTP в формате JSON. Мы можем использовать эту возможность для вставки данных непосредственно в ClickHouse с помощью HTTP интерфейса ClickHouse. Вы можете узнать больше в документации HTTP интерфейса ClickHouse.

В этом примере нам нужно будет только указать целевую таблицу, определить формат входных данных как JSON и включить опции для более гибкого парсинга временных меток.

INSERT INTO my_table
SETTINGS 
    date_time_input_format='best_effort',
    input_format_json_read_objects_as_strings=1
FORMAT JSONEachRow

Чтобы отправить этот запрос как часть HTTP-запроса, вам просто нужно передать его в виде строки, закодированной в URL, в параметре query вашего конечного пункта ClickHouse:

https://your-clickhouse-url.com?query=INSERT%20INTO%20my_table%20SETTINGS%20date_time_input_format%3D%27best_effort%27%2C%20input_format_json_read_objects_as_strings%3D1%20FORMAT%20JSONEachRow%0A

к сведению

Azure Data Factory может обрабатывать это кодирование автоматически с помощью своей встроенной функции encodeUriComponent, так что вам не придется делать это вручную.

Теперь вы можете отправлять данные в формате JSON по этому URL. Данные должны соответствовать структуре целевой таблицы. Вот простой пример с использованием curl, предполагая, что таблица имеет три колонки: col_1, col_2 и col_3.

curl \
    -XPOST "https://your-clickhouse-url.com?query=<our_URL_encded_query>" \
    --data '{"col_1":9119,"col_2":50.994,"col_3":"2019-06-01 00:00:00"}'

Вы также можете отправлять массив объектов JSON или JSON Lines (JSON-объекты, разделенные новыми строками). Azure Data Factory использует формат JSON масссива, который идеально работает с JSONEachRow для ClickHouse.

Как видите, на этом этапе вам не нужно делать ничего особенного со стороны ClickHouse. HTTP интерфейс уже предоставляет все необходимое, чтобы функционировать как REST-подобная конечная точка — дополнительная конфигурация не требуется.

Теперь, когда мы сделали ClickHouse работающим как REST конечная точка, пришло время настроить Azure Data Factory для ее использования.

В следующих шагах мы создадим экземпляр Azure Data Factory, настроим связанных сервис для вашего экземпляра ClickHouse, определим набор данных для REST-вывода и создадим активность Копирование Данных для отправки данных из Azure в ClickHouse.

Создание экземпляра Azure Data Factory

Это руководство предполагает, что у вас есть доступ к учетной записи Microsoft Azure, и у вас уже настроена подписка и группа ресурсов. Если у вас уже есть настроенный Azure Data Factory, вы можете безопасно пропустить этот шаг и перейти к следующему, используя существующий сервис.

1. Войдите в Портал Microsoft Azure и кликните Создать ресурс.

   

2. В панели КATEGORIYSPANE слева выберите Аналитика, затем нажмите на Data Factory в списке популярных сервисов.

   

3. Выберите вашу подписку и группу ресурсов, введите имя для нового экземпляра Data Factory, выберите регион и оставьте версию как V2.

   

4. Нажмите Обзор + Создать, затем нажмите Создать, чтобы запустить развертывание.

   
   

После успешного завершения развертывания вы можете начать использовать ваш новый экземпляр Azure Data Factory.

Создание нового связанного сервиса на основе REST

1. Войдите в Портал Microsoft Azure и откройте ваш экземпляр Data Factory.

   

2. На странице обзора Data Factory нажмите Запустить Studio.

   

3. В левом меню выберите Управление, затем перейдите в Связанные сервисы, и нажмите + Новый, чтобы создать новый связанный сервис.

   

4. В строке поиска Новый связанный сервис введите REST, выберите REST и нажмите Продолжить для создания REST-коннектора.

   

5. В панели конфигурации связанного сервиса введите имя для вашего нового сервиса, нажмите на поле Базовый URL, затем нажмите Добавить динамическое содержимое (эта ссылка появляется только при выборе поля).

   

6. В панели динамического содержимого вы можете создать параметризованный URL, что позволяет вам позже определить запрос при создании наборов данных для разных таблиц — это делает связанный сервис повторно используемым.

   

7. Нажмите "+" рядом с полем фильтра и добавьте новый параметр, назовите его pQuery, установите тип на Строка и установите значение по умолчанию SELECT 1. Нажмите Сохранить.

   

8. В поле выражения введите следующее и нажмите OK. Замените your-clickhouse-url.com на фактический адрес вашего экземпляра ClickHouse.

@{concat('https://your-clickhouse-url.com:8443/?query=', encodeUriComponent(linkedService().pQuery))}

9. Вернитесь к основной форме, выберите основную аутентификацию, введите имя пользователя и пароль, используемые для подключения к вашему HTTP интерфейсу ClickHouse, нажмите Проверить соединение. Если всё настроено правильно, вы увидите сообщение об успехе.

   

10. Нажмите Создать, чтобы завершить настройку.

    

Теперь вы должны увидеть ваш вновь зарегистрированный связанный сервис на основе REST в списке.

Создание нового набора данных для HTTP интерфейса ClickHouse

Теперь, когда у нас настроен связанный сервис для HTTP интерфейса ClickHouse, мы можем создать набор данных, который Azure Data Factory будет использовать для отправки данных в ClickHouse.

В этом примере мы вставим небольшую порцию данных Датчиков окружающей среды.

1. Откройте консоль запросов ClickHouse по вашему выбору — это может быть веб-интерфейс ClickHouse Cloud, CLI клиент или любой другой интерфейс, который вы используете для выполнения запросов — и создайте целевую таблицу:

CREATE TABLE sensors
(
    sensor_id UInt16,
    lat Float32,
    lon Float32,
    timestamp DateTime,
    temperature Float32
)
ENGINE = MergeTree
ORDER BY (timestamp, sensor_id);

2. В Azure Data Factory Studio выберите Авторы в левой панели. Наведите курсор на элемент Набор данных, нажмите иконку с тремя точками и выберите Новый набор данных.

   

3. В строке поиска введите REST, выберите REST и нажмите Продолжить. Введите имя для вашего набора данных и выберите связанный сервис, который вы создали на предыдущем шаге. Нажмите OK, чтобы создать набор данных.

   

4. Теперь вы должны увидеть ваш вновь созданный набор данных, перечисленный в разделе Наборы данных в панели Ресурсы Фабрики слева. Выберите набор данных, чтобы открыть его свойства. Вы увидите параметр pQuery, который был определён в связанном сервисе. Щелкните текстовое поле Значение. Затем нажмите Добавить динамическое содержимое.

   

5. В открывшейся панели вставьте следующий запрос:

INSERT INTO sensors
SETTINGS 
    date_time_input_format=''best_effort'', 
    input_format_json_read_objects_as_strings=1 
FORMAT JSONEachRow

осторожно

Все одинарные кавычки ' в запросе должны быть заменены на две одинарные кавычки ''. Это требуется парсеру выражений Azure Data Factory. Если вы этого не сделаете, вы можете не увидеть ошибку сразу — но она возникнет позже, когда вы попытаетесь использовать или сохранить набор данных. Например, 'best_effort' должно быть записано как ''best_effort''.

6. Нажмите OK, чтобы сохранить выражение. Нажмите Проверить соединение. Если всё настроено правильно, вы увидите сообщение Объединение успешно. Нажмите Опубликовать всё в верхней части страницы, чтобы сохранить ваши изменения.
   

Настройка примера набора данных

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

к сведению

Чтобы сосредоточить это руководство, мы не будем углубляться в точные шаги для создания исходного набора данных в Azure Data Factory. Вы можете загрузить образцы данных в любое хранилище данных на ваш выбор — например, Azure Blob Storage, Microsoft SQL Server или даже в другой поддерживаемый Azure Data Factory формат файлов.

Загрузите набор данных в ваше хранилище Azure Blob (или в любой другой предпочтительный сервис хранения). Затем в Azure Data Factory Studio перейдите в панель Ресурсы Фабрики. Создайте новый набор данных, который указывает на загруженные данные. Нажмите Опубликовать все, чтобы сохранить ваши изменения.

Создание активности копирования для передачи данных в ClickHouse

Теперь, когда мы настроили как входные, так и выходные наборы данных, мы можем настроить активность Копирование Данных, чтобы передать данные из нашего примера набора данных в таблицу sensors в ClickHouse.

1. Откройте Azure Data Factory Studio, перейдите на вкладку Авторы. В панели Ресурсы Фабрики наведите курсор на Конвейер, нажмите иконку с тремя точками и выберите Новый конвейер.

   

2. В панели Активности разверните раздел Перемещение и преобразование и перетащите активность Копирование данных на холст.

   

3. Выберите вкладку Источник и выберите источник данных, который вы создали ранее.

   

4. Перейдите на вкладку Назначение и выберите набор данных ClickHouse, созданный для вашей таблицы датчиков. Установите Метод запроса на POST. Убедитесь, что Тип HTTP-сжатия установлен на Нет.

   предупреждение

   HTTP-сжатие не работает должным образом в активности Копирования Данных Azure Data Factory. Включив его, Azure отправляет полезную нагрузку, состоящую только из нулевых байтов — вероятно, это ошибка в сервисе. Убедитесь, что сжатие отключено.

   к сведению

   Мы рекомендуем оставлять размер пакета по умолчанию 10 000 или даже увеличить его. Для получения дополнительных сведений смотрите Выбор стратегии вставки / Пакетные вставки, если синхронные для более подробной информации.

   

5. Нажмите Отладка в верхней части холста, чтобы запустить конвейер. После короткого ожидания, активность будет поставлена в очередь и выполнена. Если всё настроено правильно, задача должна завершиться со статусом Успех.

   

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

Дополнительные ресурсы

• HTTP интерфейс
• Копирование и преобразование данных из и в конечную точку REST с помощью Azure Data Factory
• Выбор стратегии вставки
• Создайте и настройте самоуправляемый интеграционный механизм