Azure Data FactoryにおけるClickHouse HTTPインターフェースの使用

azureBlobStorage テーブル関数は、Azure Blob StorageからClickHouseにデータを取り込むための迅速かつ便利な方法です。しかし、以下の理由から常に適切であるとは限りません。

データがAzure Blob Storageに保存されていない場合 — 例えば、Azure SQL Database、Microsoft SQL Server、またはCosmos DBにある可能性があります。
セキュリティポリシーにより、Blob Storageへの外部アクセスが完全に制限される場合があります — 例えば、ストレージアカウントに公共のエンドポイントがない場合です。

このようなシナリオでは、Azure Data Factoryを使用して ClickHouse HTTP インターフェースを利用し、AzureサービスからClickHouseにデータを送信することができます。

この方法は流れを逆転させます：ClickHouseがAzureからデータを引き出すのではなく、Azure Data FactoryがデータをClickHouseにプッシュします。このアプローチは通常、ClickHouseインスタンスが公共のインターネットからアクセス可能である必要があります。

参考

Azure Data FactoryのSelf-hosted Integration Runtimeを使用することで、 ClickHouseインスタンスをインターネットにさらすことなく、プライベートネットワークを介してデータを送信することが可能です。この設定はこの記事の範囲を超えますが、公式ガイドでさらに詳しい情報が得られます：セルフホスト統合ランタイムの作成と構成

ClickHouseをRESTサービスに変える

Azure Data Factoryは、HTTPを介して外部システムにデータをJSONフォーマットで送ることをサポートしています。この機能を利用して、ClickHouse HTTPインターフェースを使って直接ClickHouseにデータを挿入することができます。詳細はClickHouse HTTPインターフェースのドキュメントを参照してください。

この例では、宛先テーブルを指定し、入力データフォーマットをJSONとして定義し、より柔軟なタイムスタンプ解析を許可するオプションを含めるだけで済みます。

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

このクエリをHTTPリクエストの一部として送信するには、クエリパラメータに URLエンコードされた文字列として渡します：

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に送信できます。データは対象のテーブルの構造に合致する必要があります。以下は、3つのカラムcol_1、col_2、col_3を持つテーブルを仮定した簡単なcurlの例です。

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配列形式を使用しており、これはClickHouseのJSONEachRow入力と完全に互換性があります。

このステップでは、ClickHouse側で特別な操作を行う必要はありません。HTTPインターフェース自体がRESTのようなエンドポイントとして機能するために必要なものをすでに提供しています — 追加の設定は不要です。

ClickHouseをRESTエンドポイントのように振る舞わせたので、Azure Data Factoryをそれを使用するように設定する時が来ました。

次のステップでは、Azure Data Factoryインスタンスを作成し、ClickHouseインスタンスへのLinked Serviceを設定し、 REST出力のためのDatasetを定義し、データをAzureからClickHouseに送信するためのCopy Dataアクティビティを作成します。

Azure Data Factoryインスタンスの作成

このガイドでは、Microsoft Azureアカウントにアクセスでき、すでにサブスクリプションとリソースグループが構成されていることを前提としています。もしすでにAzure Data Factoryが設定されている場合は、このステップをスキップして既存のサービスを利用できます。

Microsoft Azureポータルにログインし、リソースの作成をクリックします。
左側のカテゴリペインで分析を選択し、その後一般的なサービスのリストからData Factoryをクリックします。
サブスクリプションとリソースグループを選択し、新しいData Factoryインスタンスの名前を入力し、リージョンを選択し、バージョンはV2のままにします。
確認 + 作成をクリックし、次に作成をクリックしてデプロイを開始します。

デプロイが正常に完了したら、新しいAzure Data Factoryインスタンスの使用を開始できます。

新しいRESTベースのリンクサービスの作成

Microsoft Azure Portalにログインし、Data Factoryインスタンスを開きます。
Data Factoryの概要ページで、スタジオを起動をクリックします。
左側のメニューで管理を選択し、Linked servicesに移動し、+ 新規をクリックして新しいリンクサービスを作成します。
新規リンクサービス検索バーにRESTと入力し、RESTを選択し、続行をクリックしてRESTコネクタインスタンスを作成します。
リンクサービス設定ペインで新しいサービスの名前を入力し、ベースURLフィールドをクリックして動的コンテンツの追加をクリックします（このリンクはフィールドが選択されているときのみ表示されます）。
動的コンテンツペインで、パラメータ化されたURLを作成できます。これにより、異なるテーブルのデータセットを作成する際にクエリを後で定義できるため、リンクサービスを再利用可能にします。
フィルター入力の横にある**"+"**をクリックして新しいパラメータを追加し、名前をpQueryとし、型をStringに設定して、デフォルト値をSELECT 1に設定します。保存をクリックします。
式フィールドに以下を入力し、OKをクリックします。your-clickhouse-url.comを実際のClickHouseインスタンスのアドレスに置き換えます。
```
@{concat('https://your-clickhouse-url.com:8443/?query=', encodeUriComponent(linkedService().pQuery))}
```
メインフォームに戻って基本認証を選択し、ClickHouse HTTPインターフェースに接続するために使用するユーザー名とパスワードを入力し、接続テストをクリックします。すべてが正しく設定されていれば、成功メッセージが表示されます。
作成をクリックして設定を完了します。

新たに登録されたRESTベースのリンクサービスがリストに表示されるはずです。

ClickHouse HTTPインターフェース用の新しいデータセットの作成

ClickHouse HTTPインターフェース用のリンクサービスが設定されたので、Azure Data FactoryがClickHouseにデータを送信するために使用するデータセットを作成できます。

この例では、環境センサーデータの一部を挿入します。

お好みのClickHouseクエリコンソールを開いてください — これはClickHouse CloudのWeb UI、CLIクライアント、またはクエリを実行するために使用する他のインターフェースでも構いません — そしてターゲットテーブルを作成します：
```
CREATE TABLE sensors
(
    sensor_id UInt16,
    lat Float32,
    lon Float32,
    timestamp DateTime,
    temperature Float32
)
ENGINE = MergeTree
ORDER BY (timestamp, sensor_id);
```
Azure Data Factory Studioで、左側のペインで作成を選択します。データセット項目にマウスを乗せ、三点アイコンをクリックして新しいデータセットを選択します。
検索バーにRESTと入力し、RESTを選択して続行をクリックします。データセットの名前を入力し、前のステップで作成したリンクサービスを選択します。OKをクリックしてデータセットを作成します。
左側のファクトリリソースペインのデータセットセクションに、新しく作成したデータセットが表示されるはずです。そのデータセットを選択して、プロパティを開きます。リンクサービスで定義されたpQueryパラメータが表示されます。値のテキストフィールドをクリックし、次に動的内容の追加をクリックします。
開いたペインに次のクエリを貼り付けます：
```
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''と書かれる必要があります。
式を保存するためにOKをクリックします。接続テストをクリックします。すべてが正しく設定されていれば、接続成功メッセージが表示されます。ページ上部のすべてを公開をクリックして変更を保存します。

例データセットの設定

この例では、完全な環境センサーのデータセットを使用するのではなく、センサーデータセットのサンプルの小さな部分を使用します。

参考

このガイドを集中させるために、Azure Data Factoryでソースデータセットを作成するための正確な手順には触れません。サンプルデータをお好きなストレージサービスにアップロードできます — 例えば、Azure Blob Storage、Microsoft SQL Server、またはAzure Data Factoryがサポートする別のファイル形式です。

データセットをAzure Blob Storage（または他の好みのストレージサービス）にアップロードしたら、Azure Data Factory Studioでファクトリリソースペインに移動します。アップロードしたデータを指す新しいデータセットを作成します。すべてを公開をクリックして変更を保存します。

ClickHouseへのデータ転送のためのCopyアクティビティの作成

入力データセットと出力データセットの両方が設定されたので、データのコピーアクティビティを設定して、例のデータセットからClickHouseのsensorsテーブルにデータを転送できます。

Azure Data Factory Studioを開き、作成タブに移動します。ファクトリリソースペインでパイプラインにマウスを乗せ、三点アイコンをクリックして新しいパイプラインを選択します。
アクティビティペインで、移動と変換セクションを展開し、データのコピーアクティビティをキャンバスにドラッグします。
ソースタブを選択し、先に作成したソースデータセットを選択します。
シンクタブに移動し、センサーテーブル用に作成したClickHouseデータセットを選択します。リクエストメソッドをPOSTに設定します。HTTP圧縮タイプはなしに設定されていることを確認してください。

注意
HTTP圧縮はAzure Data Factoryのデータコピーアクティビティで正しく機能しません。有効にすると、Azureはゼロバイトのみを含むペイロードを送信する — サービスのバグの可能性が高いです。圧縮を無効のままにしてください。

参考
デフォルトのバッチサイズ10,000を維持することをお勧めします。さらに増やすこともできます。詳細については、挿入戦略の選択 / 同期的なバッチ挿入を参照してください。
キャンバスの上部でデバッグをクリックしてパイプラインを実行します。少し待った後、アクティビティはキューに追加され、実行されます。すべてが正しく設定されていれば、タスクは成功の状態で終了するはずです。
完了したら、すべてを公開をクリックしてパイプラインとデータセットの変更を保存します。