Использование 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 был доступен из публичного интернета.

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

Теперь вы можете отправлять на этот URL данные в формате JSON. Данные должны соответствовать структуре целевой таблицы. Вот простой пример с использованием 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-приемника и создадим активность Copy Data для отправки данных из Azure в ClickHouse.

В этом руководстве предполагается, что у вас есть доступ к учётной записи 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.

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 connector.

   

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

   

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

   

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

   

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

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

   

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

   

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

    

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

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

   

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

   

4. Теперь в разделе наборов данных на панели Factory Resources слева должен отображаться только что созданный набор данных. Выберите его, чтобы открыть свойства. Вы увидите параметр pQuery, который был определён в связанной службе. Нажмите текстовое поле 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

6. Нажмите OK, чтобы сохранить выражение. Нажмите Test connection. Если всё настроено правильно, появится сообщение Connection successful. Нажмите Publish all в верхней части страницы, чтобы сохранить изменения.

   

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

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

Теперь, когда мы настроили входной и выходной наборы данных, можно настроить действие 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.

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

   

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

• HTTP-интерфейс
• Копирование и преобразование данных из REST-конечной точки и обратно с помощью Azure Data Factory
• Выбор стратегии вставки
• Создание и настройка Self-hosted Integration Runtime