Использование 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 в интернет, используя Self-hosted Integration Runtime в Azure Data Factory. Такая конфигурация позволяет передавать данные по частной сети. Однако это выходит за рамки данной статьи. Более подробную информацию можно найти в официальном руководстве: Create and configure a self-hosted integration runtime

Превращение 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, настроим Linked Service к вашему экземпляру ClickHouse, определим Dataset для REST sink и создадим действие Copy Data для отправки данных из Azure в ClickHouse.

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

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

1. Войдите в Microsoft Azure Portal и нажмите Create a resource.

   

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

   

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

   

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

   
   

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

Создание новой связанной службы на основе REST

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

   

2. На странице обзора Data Factory нажмите Launch Studio.

   

3. В левом меню выберите Manage, затем перейдите в Linked services и нажмите + New, чтобы создать новую связанную службу.

   

4. В New linked service search bar введите REST, выберите REST и нажмите Continue, чтобы создать экземпляр REST-коннектора.

   

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

   

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

   

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

   

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

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

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

   

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

    

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

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

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

В этом примере мы вставим небольшую часть набора данных Environmental Sensors Data.

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 выберите Author в левой панели. Наведите курсор на элемент Dataset, нажмите значок с тремя точками и выберите New dataset.

   

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

   

4. Теперь вы должны увидеть вновь созданный набор данных в разделе Datasets в панели Factory Resources слева. Выберите набор данных, чтобы открыть его свойства. Вы увидите параметр pQuery, который был определён в linked service. Щёлкните текстовое поле Value, затем нажмите Add dynamic content.

   

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, чтобы сохранить выражение. Нажмите Test connection. Если всё настроено правильно, вы увидите сообщение Connection successful. Нажмите Publish all в верхней части страницы, чтобы сохранить изменения.

   

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

В этом примере мы не будем использовать полный набор данных Environmental Sensors Dataset, а только небольшой поднабор, доступный по ссылке Sensors Dataset Sample.

Справочные материалы

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

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

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

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

1. Откройте Azure Data Factory Studio и перейдите на вкладку Author. В области Factory Resources наведите указатель на Pipeline, нажмите значок с тремя точками и выберите New pipeline.

   

2. В области Activities разверните раздел Move and transform и перетащите действие Copy data на рабочую область.

   

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

   

4. Перейдите на вкладку Sink и выберите набор данных ClickHouse, созданный для вашей таблицы sensors. Установите Request method в значение POST. Убедитесь, что HTTP compression type имеет значение None.

   Примечание

   HTTP-сжатие работает некорректно в действии Copy Data в Azure Data Factory. При его включении Azure отправляет полезную нагрузку размером 0 байт — вероятно, это ошибка в сервисе. Обязательно оставьте сжатие отключённым.

   Справочные материалы

   Рекомендуем оставить размер пакета по умолчанию — 10 000, или даже увеличить его. Подробности см. в разделе Selecting an Insert Strategy / Batch inserts if synchronous.

   

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

   

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

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

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