Référence du connecteur Microsoft Dynamics 365
Cette référence couvre l’authentification, le comportement du curseur et des schémas, les types de données Dataverse pris en charge, l’évolution des schémas et les paramètres de pipeline pour le connecteur Microsoft Dynamics 365 dans Lakeflow Connect.
Paramètres d'authentification
Le connecteur Dynamics 365 utilise l'authentification OAuth de Microsoft Entra ID (anciennement Azure Active Directory). Pour plus de détails, consultez Comment le connecteur accède-t-il aux données D365 ?.
Champs d'authentification requis
Lorsque vous créez une connexion Unity Catalog pour D365, fournissez ces paramètres :
parameter | Description | Exemple |
|---|---|---|
| Identifiant du tenant Microsoft Entra (ID de répertoire) |
|
| L'ID d'application (client) de votre application Entra ID |
|
| La valeur du secret client créée pour votre application Entra ID |
|
| Le nom de votre compte de stockage ADLS Gen2 |
|
| Le conteneur où Synapse Link exporte les données |
|
| Le champ d’application OAuth pour l’accès au stockage Azure |
|
Champ de curseur
Le connecteur Dynamics 365 utilise le champ versionnumber des journaux de modifications Azure Synapse Link comme curseur pour l'ingestion incrémentielle.
Comportement du curseur
- Source : Synapse Link génère automatiquement des valeurs
versionnumberlors de l'exportation des modifications. - Format : Timestamp entier représentant la séquence de modification.
- Portée : Curseur par table. Chaque table maintient sa propre position de curseur.
- Stockage : les curseurs sont stockés dans les métadonnées du pipeline et n’apparaissent pas dans les tables Delta cibles.
Exigences du curseur
Pour que l'ingestion incrémentielle fonctionne :
- Synapse Link doit exporter les journaux de modifications avec le champ
versionnumber. versionnumberdoit être présent dans tous les fichiers de journal des modifications.- Les dossiers de journal des modifications doivent suivre la convention de nommage basée sur le Timestamp de Synapse Link.
Si versionnumber est manquant, l’importation incrémentielle échoue et vous devez effectuer une full refresh.
Format d’exportation source
Azure Synapse Link peut exporter les données Dataverse vers ADLS Gen2 au format CSV ou Parquet . Le connecteur Dynamics 365 prend en charge les deux et détecte automatiquement le format écrit par Synapse Link ; vous n'avez donc pas à spécifier le format d'exportation dans la définition du pipeline. Le format est déterminé par votre configuration Synapse Link. L'exportation au format Parquet nécessite la connexion d'un workspace Azure Synapse Analytics (voir Configurer une source de données Parquet pour l'ingestion Microsoft Dynamics 365), tandis que l'exportation CSV utilise la configuration standard (voir Configurer une source de données pour l'ingestion Microsoft Dynamics 365).
- CSV : Synapse Link écrit des fichiers CSV directement dans ADLS Gen2 sans workspace Azure Synapse Analytics.
- Parquet : l’ingestion Parquet est en version bêta. Synapse Link écrit chaque table sous forme de table Delta au format Parquet sous
<profileRoot>/deltalake/<tableName>/. Ce chemin nécessite un Workspace Azure Synapse Analytics et un Pool Apache Spark, et Databricks le recommande pour les instances volumineuses ou à haut débit.
Découverte de schémas
Le connecteur Dynamics 365 découvre automatiquement les schémas de table à partir des métadonnées Dataverse.
Processus de découverte
Lorsque vous créez un pipeline :
- Le connecteur lit les fichiers de métadonnées Synapse Link à partir d'ADLS Gen2.
- Le connecteur extrait les schémas de table des fichiers JSON de métadonnées.
- Les noms de colonnes, les types de données et la nullabilité sont déduits des métadonnées.
- Les tables cibles sont créées avec les schémas découverts.
Évolution des schémas pour l’ingestion de fichiers CSV
Aperçu
Cette fonctionnalité est en aperçu privé. Pour l’essayer, veuillez contacter votre conseiller Databricks.
L’évolution des schémas maintient automatiquement vos tables Delta cibles synchronisées à mesure que le schéma Dataverse source change, y compris les ajouts, suppressions et renommages de colonnes depuis Azure Synapse Link.
Prérequis
- L'évolution des schémas est disponible sur demande pendant la version préliminaire privée. Pour l'activer pour votre pipeline, contactez votre conseiller Databricks.
- Le Service Principal de la connexion doit disposer du rôle Storage Blob Data Contributor sur le compte de stockage ADLS Gen2. L'évolution des schémas réécrit le point de contrôle du schéma dans votre stockage ; par conséquent, tout rôle n'accordant qu'une autorisation de lecture ne fonctionnera pas. Une connexion en lecture seule échoue avec une erreur vous demandant d'accorder un accès en écriture ou de désactiver l'évolution des schémas. Pour la configuration de la connexion, voir Créer une connexion Dynamics 365.
Modifications prises en charge et non prises en charge
L’évolution des schémas gère les changements de schéma source suivants :
Changer | Pris en charge |
|---|---|
Ajout de colonne | Pris en charge |
Suppression de colonne | Pris en charge |
Renommage de colonne | Pris en charge |
Ajout de table | Pris en charge |
Suppression de table | Pris en charge |
Suppression d'une colonne et ajout ultérieur d'une colonne portant le même nom | Non pris en charge |
Suppression d’une table et ajout ultérieur d’une table portant le même nom | Non pris en charge |
Types de données Dataverse pris en charge
Le connecteur Dynamics 365 mappe les types de données Dataverse aux types de données Delta Lake.
Mappage des types de données
Type de Dataverse | Type de Delta Lake | Notes |
|---|---|---|
|
| Longueur maximale préservée en tant que métadonnées |
|
| |
|
| |
|
| |
|
| Précision et échelle conservées |
|
| |
|
| Stocké sous forme décimale avec 4 décimales |
|
| |
|
| Information de fuseau horaire préservée |
|
| |
|
| Spark n'a pas de type |
|
| Stocké sous forme de représentation textuelle |
|
| Clé étrangère GUID stockée en tant que chaîne |
|
| Valeur entière, pas libellé |
|
| Nombres entiers séparés par des virgules |
|
| URL ou métadonnées, pas de données binaires |
|
| Métadonnées uniquement, pas le contenu des fichiers |
Types de données complexes
Certains types de Dataverse nécessitent un traitement spécial :
Type de Dataverse | Ingéré en tant que | Comment le gérer |
|---|---|---|
| Codes entiers | Effectuez une jointure avec la table |
| Chaînes GUID | Joindre à la table référencée pour obtenir des données associées |
| Chaînes d’entiers séparées par des virgules, telles que | Analyser la chaîne pour extraire des valeurs individuelles |
Les exemples suivants analysent un ensemble d'options à sélection multiple, en divisant d'abord les valeurs séparées par des virgules en un tableau, puis en les éclatant en lignes distinctes :
-- Split comma-separated values into array
SELECT
accountid,
accountname,
SPLIT(industrycodes, ',') AS industry_array
FROM main.d365_data.account;
-- Explode into separate rows
SELECT
accountid,
accountname,
CAST(code AS INT) AS industry_code
FROM main.d365_data.account
LATERAL VIEW EXPLODE(SPLIT(industrycodes, ',')) AS code;
Compatibilité des versions d'API
Le connecteur Dynamics 365 est compatible avec :
- Dataverse API : Version 9.2 et ultérieure
- Azure Synapse Link for Dataverse : version 1.0 et ultérieure
- **Azure Storage REST API** : Version 2021-08-06 et versions ultérieures
- Microsoft Entra ID : flux d'informations d'identification client OAuth 2.0
Les anciennes versions d'API peuvent fonctionner, mais elles ne sont pas officiellement prises en charge. Maintenez vos services D365 et Azure à jour pour une compatibilité optimale.
Comportement d'ingestion incrémentielle
La manière dont le connecteur applique chaque modification détectée dépend du type de SCD que vous choisissez pour le pipeline, et le fait que les suppressions atteignent ou non Databricks dépend de votre configuration Synapse Link.
Détection des changements
Le connecteur détecte chaque modification à partir des journaux de modifications de Synapse Link. Il traite la présence d'un enregistrement dans un journal de modifications comme une insertion, un versionnumber modifié comme une mise à jour, et un marqueur de suppression comme une suppression. Les marqueurs de suppression n'apparaissent que si Synapse Link est configuré pour exporter les suppressions.
Comportement du SCD de type 1
Pour les pipelines SCD de Type 1, les enregistrements sont mis à jour sur place sans conserver l'historique. Les mises à jour écrasent les lignes existantes en fonction de la clé primaire, et les suppressions suppriment les lignes (si le suivi des suppressions est activé).
L'interrogation d'une table cible renvoie une ligne par enregistrement, reflétant uniquement son état le plus récent :
SELECT * FROM main.d365_data.account ORDER BY accountid;
-- Result: Latest state only
-- accountid | accountname | modifiedon
-- 123 | Acme Corp | 2025-12-03 10:00:00
-- 456 | TechCo | 2025-12-03 09:30:00
Comportement SCD de type 2
Pour les pipelines SCD de type 2, toutes les modifications sont conservées comme de nouvelles versions de lignes. Le connecteur ajoute les colonnes __START_AT, __END_AT et __CURRENT pour suivre l'historique des versions.
L'interrogation d'une table cible renvoie chaque version de chaque enregistrement. __START_AT et __END_AT délimitent la fenêtre pendant laquelle chaque version était actuelle, et la version active a un NULL __END_AT et __CURRENT défini sur true:
SELECT * FROM main.d365_data.account ORDER BY accountid, __START_AT;
-- Result: All historical versions
-- accountid | accountname | __START_AT | __END_AT | __CURRENT
-- 123 | Acme Inc | 2025-11-01 08:00:00 | 2025-12-03 10:00:00 | false
-- 123 | Acme Corp | 2025-12-03 10:00:00 | NULL | true
-- 456 | TechCo | 2025-12-01 14:00:00 | NULL | true
Lorsque Synapse Link effectue des exportations au format Parquet, les anciens points de contrôle Delta sont périodiquement compactés en points de contrôle plus récents, ce qui peut rendre certaines versions d'enregistrements historiques indisponibles pour le traitement. Pour les pipelines SCD de type 2, cela peut produire un historique incomplet, mais ne provoque pas de perte de données : le pipeline reflète toujours correctement le dernier instantané de chaque enregistrement, et seules certaines versions intermédiaires peuvent être manquantes. Pour réduire le risque d'historique incomplet, Databricks recommande d'exécuter le pipeline plus d'une fois toutes les 24 heures, ce qui réduit la fenêtre pendant laquelle le compactage peut supprimer des modifications historiques.
Gestion de la suppression
La gestion de la suppression dépend de votre configuration Synapse Link :
- Suppressions définitives : si Synapse Link exporte les enregistrements de suppression, le connecteur supprime (SCD de type 1) ou marque (SCD de type 2) les enregistrements supprimés.
- Pas de suivi des suppressions : Si Synapse Link n'exporte pas les suppressions, les enregistrements supprimés restent dans les tables cibles jusqu'à ce que vous effectuiez un refresh complet.
Vérifiez que votre configuration Synapse Link exporte les suppressions si vous avez besoin d'un suivi précis des suppressions.
Paramètres du pipeline
Lors de la création d'un pipeline d'ingestion D365, spécifiez ces paramètres :
Paramètres requis
Ces paramètres doivent être spécifiés pour que le pipeline puisse s'exécuter.
parameter | Type | Description | Exemple |
|---|---|---|---|
| Chaîne | Doit être |
|
| Chaîne | Nom de votre connexion Unity Catalog |
|
| Chaîne | Nom du schéma logique Synapse Link, généralement |
|
| Chaîne | Nom logique de la table D365, avec une entrée par objet |
|
| Chaîne | Catalogue Unity Catalog cible |
|
| Chaîne | Schéma Unity Catalog cible |
|
| Chaîne |
|
|
Parameters facultatifs
Ces paramètres peuvent être définis en option lors de la création de votre pipeline.
parameter | Type | Description | Exemple |
|---|---|---|---|
| Objet | Paramètres par table, tels que la sélection de colonnes |
Exemple de configuration de pipeline
Ceci est un exemple de configuration de pipeline complète utilisant le SDK Python.
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.pipelines import IngestionPipelineDefinition
w = WorkspaceClient()
pipeline = w.pipelines.create(
name="d365_comprehensive_ingestion",
ingestion_definition=IngestionPipelineDefinition(
channel="PREVIEW",
connection_name="d365_connection",
source_schema="objects",
source_table="account",
destination_catalog="main",
destination_schema="d365_sales",
scd_type="SCD_TYPE_2",
table_configuration={
"account": {
"columns": [
"accountid",
"accountnumber",
"name",
"emailaddress1",
"telephone1"
]
}
}
)
)
Recherche de noms logiques de table
Pour identifier les noms logiques de table pour le paramètre source_table :
- **Portail Power Apps maker** : accédez à **Tables** et affichez la colonne **Nom logique**.
- API Dataverse : interrogez les métadonnées à l'aide de
https://yourorg.api.crm.dynamics.com/api/data/v9.2/EntityDefinitions. - **Stockage ADLS Gen2** : Liste les dossiers dans votre conteneur Synapse Link (les noms de dossiers correspondent aux noms logiques).
Utilisez des noms logiques en minuscules dans les configurations de pipeline (par exemple, "account" plutôt que "Account"). Le connecteur est sensible à la casse.
Optimisation des performances
Le connecteur offre un réglage limité, car Synapse Link contrôle lui-même l’exportation. Ce que vous pouvez contrôler, c’est la quantité de données que chaque pipeline déplace et la manière dont vous distribuez les tables entre les pipelines.
Sélection de colonne
La sélection des seules colonnes dont vous avez besoin réduit le transfert de données depuis ADLS Gen2, les coûts de stockage dans Delta Lake et le temps de traitement des query. Voir la sélection de colonnes pour les détails de configuration.
Regroupement de tables
Regroupez les tables qui se comportent de la même manière, afin que la planification d'un pipeline convienne à tout ce qu'il contient : les tables associées ensemble pour une gestion plus facile, et les tables ayant des modèles de mise à jour similaires ensemble afin que vous puissiez planifier chaque pipeline pour qu'il corresponde à son volume de modification. Attribuez aux tables à volume élevé leurs propres pipelines, afin qu'une seule grande table ne ralentisse pas les autres.
Chaque pipeline est limité à 250 tables. Pour les environnements plus vastes, créez plusieurs pipelines.
Dépannage
Pour les problèmes courants et les solutions lors de l'utilisation du connecteur Dynamics 365, consultez Dépannage de l'ingestion Microsoft Dynamics 365.