Utiliser l'interface HTTP de ClickHouse dans Azure Data Factory

La fonction de table azureBlobStorage est un moyen rapide et pratique d’ingérer des données depuis Azure Blob Storage dans ClickHouse. Son utilisation ne convient toutefois pas toujours, pour les raisons suivantes :

Il se peut que vos données ne soient pas stockées dans Azure Blob Storage ; par exemple, elles peuvent se trouver dans Azure SQL Database, Microsoft SQL Server ou Cosmos DB.
Des politiques de sécurité peuvent empêcher tout accès externe à Blob Storage — par exemple, si le compte de stockage est verrouillé et ne dispose d’aucun point de terminaison public.

Dans ce type de scénario, vous pouvez utiliser Azure Data Factory avec l’interface HTTP de ClickHouse pour envoyer des données depuis des services Azure vers ClickHouse. Cette méthode inverse le flux : au lieu que ClickHouse récupère les données depuis Azure, Azure Data Factory les envoie vers ClickHouse. Cette approche nécessite généralement que votre instance ClickHouse soit accessible depuis l’internet public.

Il est possible d’éviter d’exposer votre instance ClickHouse à internet en utilisant le runtime d’intégration auto-hébergé d’Azure Data Factory. Cette configuration permet d’envoyer les données via un réseau privé. Cela sort toutefois du cadre de cet article. Vous trouverez plus d’informations dans le guide officiel : Créer et configurer un runtime d’intégration auto-hébergé

Exposer ClickHouse comme un service REST

Azure Data Factory prend en charge l’envoi de données vers des systèmes externes en HTTP, au format JSON. Nous pouvons utiliser cette fonctionnalité pour insérer des données directement dans ClickHouse à l’aide de l’interface HTTP de ClickHouse. Vous trouverez plus d’informations dans la documentation de l’interface HTTP de ClickHouse. Pour cet exemple, il suffit de spécifier la table de destination, de définir le format des données d’entrée sur JSON et d’inclure des options pour permettre une analyse plus souple des horodatages.

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

Pour envoyer cette requête dans le cadre d’une requête HTTP, il vous suffit de la transmettre sous la forme d’une chaîne encodée dans l’URL au paramètre de requête de votre endpoint 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 peut gérer cet encodage automatiquement à l’aide de sa fonction intégrée encodeUriComponent, vous n’avez donc pas besoin de le faire manuellement.

Vous pouvez maintenant envoyer des données au format JSON à cette URL. Les données doivent correspondre à la structure de la table cible. Voici un exemple simple avec curl, en supposant une table comportant trois colonnes : col_1, col_2 et 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"}'

Vous pouvez également envoyer un tableau JSON d’objets, ou du JSON Lines (objets JSON délimités par des retours à la ligne). Azure Data Factory utilise le format de tableau JSON, qui fonctionne parfaitement avec l’entrée JSONEachRow de ClickHouse. Comme vous pouvez le constater, pour cette étape, vous n’avez rien de particulier à faire côté ClickHouse. L’interface HTTP fournit déjà tout le nécessaire pour servir d’endpoint de type REST — aucune configuration supplémentaire n’est requise. Maintenant que ClickHouse se comporte comme un endpoint REST, il est temps de configurer Azure Data Factory pour l’utiliser. Dans les étapes suivantes, nous allons créer une instance Azure Data Factory, configurer un Linked Service vers votre instance ClickHouse, définir un jeu de données pour le récepteur REST, et créer une activité Copy Data pour envoyer des données d’Azure vers ClickHouse.

Création d’une instance Azure Data Factory

Ce guide suppose que vous avez accès à un compte Microsoft Azure et que vous avez déjà configuré un abonnement et un groupe de ressources. Si vous avez déjà configuré une instance Azure Data Factory, vous pouvez passer cette étape sans problème et utiliser votre service existant pour la suite.

Connectez-vous au Microsoft Azure Portal et cliquez sur Créer une ressource.
Dans le volet Catégories à gauche, sélectionnez Analytics, puis cliquez sur Data Factory dans la liste des services populaires.
Sélectionnez votre abonnement et votre groupe de ressources, saisissez un nom pour la nouvelle instance Data Factory, choisissez la région et laissez la version sur V2.
Cliquez sur Vérifier + créer, puis sur Créer pour lancer le déploiement.

Une fois le déploiement terminé avec succès, vous pouvez commencer à utiliser votre nouvelle instance Azure Data Factory.

Création d’un nouveau service lié basé sur REST

Connectez-vous au Microsoft Azure Portal et ouvrez votre instance Data Factory.
Sur la page de vue d’ensemble de Data Factory, cliquez sur Launch Studio.
Dans le menu de gauche, sélectionnez Manage, puis accédez à Linked services, et cliquez sur + New pour créer un nouveau service lié.
Dans la barre de recherche New linked service, saisissez REST, sélectionnez REST et cliquez sur Continue pour créer une instance de connecteur REST.
Dans le volet de configuration du service lié, entrez un nom pour votre nouveau service, cliquez sur le champ Base URL, puis sur Add dynamic content (ce lien n’apparaît que lorsque le champ est sélectionné).
Dans le volet de contenu dynamique, vous pouvez créer une URL paramétrée, ce qui vous permet de définir la requête plus tard lors de la création de jeux de données pour différentes tables — le service lié est ainsi réutilisable.
Cliquez sur le ”+” à côté du champ de filtre et ajoutez un nouveau paramètre, nommez-le pQuery, définissez le type sur String et la valeur par défaut sur SELECT 1. Cliquez sur Save.
Dans le champ d’expression, saisissez ce qui suit et cliquez sur OK. Remplacez your-clickhouse-url.com par l’adresse réelle de votre instance ClickHouse.
@{concat('https://your-clickhouse-url.com:8443/?query=', encodeUriComponent(linkedService().pQuery))}
De retour dans le formulaire principal, sélectionnez l’authentification de base, saisissez le nom d’utilisateur et le mot de passe utilisés pour vous connecter à votre interface HTTP de ClickHouse, puis cliquez sur Test connection. Si tout est correctement configuré, un message de réussite s’affichera.
Cliquez sur Create pour finaliser la configuration.

Vous devriez maintenant voir votre nouveau service lié basé sur REST dans la liste.

Création d’un nouveau jeu de données pour l’interface HTTP de ClickHouse

Maintenant que nous avons configuré un service lié pour l’interface HTTP de ClickHouse, nous pouvons créer un jeu de données qu’Azure Data Factory utilisera pour envoyer des données vers ClickHouse. Dans cet exemple, nous allons insérer une petite partie du jeu de données Environmental Sensors Data.

Ouvrez la console de requêtes ClickHouse de votre choix — il peut s’agir de la web UI de ClickHouse Cloud, du client CLI ou de toute autre interface que vous utilisez pour exécuter des requêtes — puis créez la target table :
CREATE TABLE sensors ( sensor_id UInt16, lat Float32, lon Float32, timestamp DateTime, temperature Float32 ) ENGINE = MergeTree ORDER BY (timestamp, sensor_id);
Dans Azure Data Factory Studio, sélectionnez Author dans le volet de gauche. Survolez l’élément Dataset, cliquez sur l’icône à trois points, puis choisissez New dataset.
Dans la barre de recherche, saisissez REST, sélectionnez REST, puis cliquez sur Continue. Entrez un nom pour votre jeu de données et sélectionnez le service lié que vous avez créé à l’étape précédente. Cliquez sur OK pour créer le jeu de données.
Vous devriez maintenant voir votre jeu de données nouvellement créé dans la section Datasets du volet Factory Resources à gauche. Sélectionnez le jeu de données pour ouvrir ses propriétés. Vous verrez le paramètre pQuery défini dans le service lié. Cliquez sur le champ de texte Value. Cliquez ensuite sur Add dynamic content.

Dans le volet qui s’ouvre, collez la requête suivante :

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

Tous les single quotes ' dans la requête doivent être remplacés par deux single quotes ''. Cela est nécessaire pour le parser d’expressions d’Azure Data Factory. Si vous ne les échappez pas, aucune error ne s’affichera peut-être immédiatement — mais cela échouera plus tard lorsque vous tenterez d’utiliser ou d’enregistrer le jeu de données. Par exemple, 'best_effort' doit s’écrire ''best_effort''.

Cliquez sur OK pour enregistrer l’expression. Cliquez sur Test connection. Si tout est correctement configuré, le message Connection successful s’affichera. Cliquez sur Publish all en haut de la page pour enregistrer vos modifications.

Configuration d’un jeu de données d’exemple

Dans cet exemple, nous n’utiliserons pas l’intégralité du jeu de données Environmental Sensors, mais seulement un petit sous-ensemble disponible à l’adresse Échantillon du jeu de données Sensors.

Pour que ce guide reste ciblé, nous ne détaillerons pas les étapes exactes de création du jeu de données source dans Azure Data Factory. Vous pouvez téléverser les données d’exemple vers n’importe quel service de stockage de votre choix — par exemple, Azure Blob Storage, Microsoft SQL Server, ou même dans un autre format de fichier pris en charge par Azure Data Factory.

Téléversez le jeu de données dans Azure Blob Storage (ou dans un autre service de stockage de votre choix). Ensuite, dans Azure Data Factory Studio, ouvrez le volet Factory Resources. Créez un nouveau jeu de données pointant vers les données téléversées. Cliquez sur Publish all pour enregistrer vos modifications.

Création d’une activité de copie pour transférer des données vers ClickHouse

Maintenant que nous avons configuré les jeux de données d’entrée et de sortie, nous pouvons créer une activité Copy Data pour transférer les données de notre jeu de données d’exemple vers la table sensors dans ClickHouse.

Ouvrez Azure Data Factory Studio, puis accédez à l’onglet Author. Dans le volet Factory Resources, survolez Pipeline, cliquez sur l’icône à trois points, puis sélectionnez New pipeline.
Dans le volet Activities, développez la section Move and transform, puis faites glisser l’activité Copy data sur le canevas.
Sélectionnez l’onglet Source, puis choisissez le jeu de données source que vous avez créé précédemment.
Accédez à l’onglet Sink et sélectionnez le jeu de données ClickHouse créé pour votre table sensors. Définissez Request method sur POST. Assurez-vous que HTTP compression type est défini sur None.

La compression HTTP ne fonctionne pas correctement dans l’activité Copy Data d’Azure Data Factory. Lorsqu’elle est activée, Azure envoie une charge utile composée uniquement de zéro octet — il s’agit probablement d’un bug du service. Veillez à laisser la compression désactivée.

Nous vous recommandons de conserver la taille de lot par défaut de 10 000, voire de l’augmenter davantage. Pour plus de détails, consultez Selecting an Insert Strategy / Batch inserts if synchronous.

Cliquez sur Debug en haut du canevas pour exécuter le pipeline. Après un court instant, l’activité sera mise en file d’attente puis exécutée. Si tout est correctement configuré, la tâche devrait se terminer avec le statut Success.
Une fois l’opération terminée, cliquez sur Publish all pour enregistrer les modifications apportées à votre pipeline et à vos jeux de données.

​Exposer ClickHouse comme un service REST

​Création d’une instance Azure Data Factory

​Création d’un nouveau service lié basé sur REST

​Création d’un nouveau jeu de données pour l’interface HTTP de ClickHouse

​Configuration d’un jeu de données d’exemple

​Création d’une activité de copie pour transférer des données vers ClickHouse

​Ressources supplémentaires

Exposer ClickHouse comme un service REST

Création d’une instance Azure Data Factory

Création d’un nouveau service lié basé sur REST

Création d’un nouveau jeu de données pour l’interface HTTP de ClickHouse

Configuration d’un jeu de données d’exemple

Création d’une activité de copie pour transférer des données vers ClickHouse

Ressources supplémentaires