--- title: "Connecter Azure Data Explorer (Kusto)" description: "Connectez Datarelix à Azure Data Explorer (Kusto) pour des requêtes KQL en lecture seule, avec Entra OBO ou une application authentifiée par certificat." canonical: https://docs.datarelix.ai/fr/guides/connections/kusto/ --- # Connecter Azure Data Explorer (Kusto) Datarelix se connecte à Azure Data Explorer (aussi appelé Kusto, ou ADX) via un service de requêtes en lecture seule. Les requêtes KQL passent par le point de terminaison de requête ; les commandes d'introspection `.show` passent par le point de terminaison de gestion, jamais sur vos données. Contrairement aux autres dialectes pris en charge, Kusto utilise **KQL** (Kusto Query Language), pas SQL. La génération de requêtes tient compte du dialecte — les requêtes générées utilisent la syntaxe à pipes de KQL (`|`), `take` au lieu de `LIMIT`, `project` au lieu de `SELECT`, `summarize` au lieu de `GROUP BY`. ## Prérequis - Un [cluster Azure Data Explorer](https://learn.microsoft.com/en-us/azure/data-explorer/create-cluster-and-database). - Une **base de données** Kusto (un cluster peut en héberger plusieurs ; choisissez-en une par connexion). - Le principal utilisé pour l'authentification doit avoir au minimum le rôle `Database Viewer` sur la base de données — voir [Manage database security roles](https://learn.microsoft.com/en-us/kusto/management/manage-database-security-roles). ## Trouver vos informations de connexion Dans le portail Azure : 1. Ouvrez votre **cluster Azure Data Explorer**. 2. Copiez l'**URI** depuis le panneau Overview. Format : `https://..kusto.windows.net`. 3. Dans le panneau **Databases** du cluster, copiez le nom de la base de données. ### ADX, Fabric et Log Analytics Collez le **Query URI** correspondant à votre moteur — ils diffèrent : - **Cluster Azure Data Explorer** — `https://..kusto.windows.net` (panneau Overview). - **Microsoft Fabric Eventhouse / base KQL** (Real-Time Intelligence) — c'est Kusto en dessous ; copiez le [**Query URI**](https://learn.microsoft.com/en-us/fabric/real-time-intelligence/access-database-copy-uri) depuis la carte **Database details** de la base. - **Azure Monitor / Log Analytics / Application Insights** — ce sont des proxys de requête, **pas** des clusters ADX autonomes, et ce connecteur ne les prend pas en charge. ## Formulaire de connexion ```ini Cluster URI: https://your-cluster.eastus.kusto.windows.net Database: your-kusto-db Auth mode: one of the two below ``` ## Modes d'authentification ### Entra OBO (par défaut) Rattache la connexion à **l'utilisateur actuellement connecté**. La couche d'exécution échange le jeton bearer de l'utilisateur contre un jeton d'audience Kusto via le [flux On-Behalf-Of](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-on-behalf-of-flow) d'Azure AD. Aucun secret à longue durée de vie n'est stocké. Le cluster Kusto voit l'identité de l'utilisateur : les attributions `Database Viewer` par utilisateur s'appliquent donc au moment de la requête. **Configuration** 1. Accordez le rôle `Database Viewer` sur la base Kusto à l'utilisateur connecté (ou à son groupe Entra). Exécutez ceci dans l'**interface web Azure Data Explorer** (https://dataexplorer.azure.com) sur votre base : ```kql .add database viewers ('aaduser=user@yourtenant.onmicrosoft.com') ``` Ou, pour un groupe : ```kql .add database viewers ('aadgroup=;') ``` 2. L'inscription d'application Entra de Datarelix doit avoir `https://kusto.kusto.windows.net/user_impersonation` configuré comme autorisation déléguée. Contactez votre administrateur si votre locataire (tenant) exige un consentement administrateur. **Où trouver vos identifiants** Aucun identifiant à saisir — la connexion utilise automatiquement l'identité de l'utilisateur connecté. **Tenant ID** est facultatif lorsque le locataire d'origine du cluster Kusto est celui de l'utilisateur. Renseignez-le explicitement lorsqu'ils diffèrent (accès inter-locataires). **À saisir** ```ini Cluster URI: https://your-cluster.eastus.kusto.windows.net Database: your-kusto-db Auth mode: Entra OBO Tenant ID: (optional — required only for cross-tenant access) ``` --- ### Application + certificat Authentification par principal de service à l'aide d'un certificat. Kusto exige des certificats (pas des secrets clients) pour l'accès application seule. L'empreinte du certificat et la clé privée PEM sont stockées chiffrées. **Configuration** 1. [Inscrivez une application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) dans Microsoft Entra ID (par ex. `datarelix-kusto-reader`). 2. Générez un certificat : ```bash openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -nodes -days 365 \ -subj "/CN=datarelix-kusto" ``` 3. Dans l'inscription d'application → **Certificates & secrets → Certificates**, [téléversez `cert.pem`](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials) (le certificat public, **pas** la clé). Azure affiche l'empreinte après le téléversement — copiez-la (40 caractères hexadécimaux). 4. Accordez à l'application le rôle `Database Viewer` sur la base Kusto. Dans l'interface web Azure Data Explorer : ```kql .add database viewers ('aadapp=;') ``` **Où trouver vos identifiants** | Champ | Où le trouver | |-------|----------------| | Tenant ID | Azure AD → votre inscription d'application → **Overview** → Directory (tenant) ID | | Client ID | Azure AD → votre inscription d'application → **Overview** → Application (client) ID | | Certificate thumbprint (empreinte) | Azure AD → inscription d'application → **Certificates & secrets → Certificates** → 40 caractères hexadécimaux après le téléversement | | Certificate PEM | Le fichier `key.pem` que vous avez généré — collez le bloc complet `-----BEGIN PRIVATE KEY-----` … `-----END PRIVATE KEY-----` | > **Empreinte et PEM** — l'empreinte indique *quel* certificat Entra doit attendre ; le PEM est la clé privée que Datarelix utilise pour signer l'assertion JWT. La clé privée n'est pas téléversée dans Entra. **À saisir** ```ini Cluster URI: https://your-cluster.eastus.kusto.windows.net Database: your-kusto-db Auth mode: App + Certificate Tenant ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Client ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Certificate thumbprint: AABBCCDDEEFF... Certificate PEM: -----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY----- ``` --- ## Sémantique de la portée Kusto a un espace de noms plat à l'intérieur d'une base de données — pas de schémas. Le champ **Database** (base de données) définit la portée. Pour analyser plusieurs bases, créez plusieurs connexions. ## Découverte Entièrement prise en charge via les commandes de contrôle Kusto (`.show tables`, `.show table schema as json`). Elles s'exécutent sur le point de terminaison de gestion, jamais sur vos données. - Kusto n'a pas de notion de PK/FK — les relations issues de l'introspection sont donc toujours vides ; la passe d'enrichissement par le modèle déduit les liens à partir des conventions de nommage des colonnes. - Toutes les colonnes sont signalées comme nullables (Kusto n'a pas de contrainte `NOT NULL` au niveau du stockage). - Les colonnes polymorphes (type `dynamic`) sont signalées comme du JSON. ## Petit guide KQL Les requêtes générées sont en KQL. Vous n'écrivez pas de KQL vous-même — Datarelix le génère. Pour le contexte : ```kql StormEvents | where State == "FLORIDA" | summarize Count=count() by EventType | order by Count desc | take 10 ``` - `|` transmet la sortie de l'étape précédente à l'opérateur suivant. - `take` limite le nombre de lignes. - `project` sélectionne des colonnes. - `where` filtre les lignes. - `summarize` agrège. - `order by` / `sort by` trie les lignes. Voir la [référence rapide KQL](https://learn.microsoft.com/en-us/kusto/query/) pour l'ensemble du langage. ## Limites - **Aucune mutation** — le validateur rejette `.create`, `.alter`, `.drop`, `.ingest`, `.set`, `.append`, `.purge`, `.delete` et les commandes de contrôle sous forme d'injection. - **Pas de jointures entre bases** — une base de données par connexion. - **Limite de lignes** — plafond côté serveur de 5 000 lignes. ## Dépannage | Symptôme | Cause probable | Solution | |---------|--------------|-----| | `401 Unauthorized` / audience du jeton incohérente | Portée incorrecte sur le jeton utilisateur | Vérifiez que l'application Entra a `https://kusto.kusto.windows.net/user_impersonation` comme autorisation déléguée. | | `Forbidden: Principal ... is not authorized` | Rôle Kusto manquant | Exécutez `.add database viewers ('aadapp=;')` dans l'interface web Azure Data Explorer. | | `Certificate not found` | Faute de frappe dans l'empreinte | Recopiez l'empreinte depuis Azure AD — 40 caractères hexadécimaux, sans espaces. | | `Cluster not found` | Faute de frappe dans l'URI ou mauvaise région | Vérifiez l'URI dans le panneau Overview du cluster. | | La découverte renvoie 0 table | Le principal n'a pas `Database Viewer` | Attribuez le rôle et relancez la découverte. | | `Semantic error: 'table not found'` (KQL) | Requête sur une table d'une autre base | Une base de données par connexion ; créez une autre connexion pour l'autre base. |