Référence du connecteur Microsoft Dynamics 365
Cette page fournit des informations de référence techniques 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.
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.
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 :
- **Ensembles d'options (listes de sélection)** : Ingérés comme codes entiers. Pour mapper aux étiquettes, faites une jointure avec la table
OptionSetMetadataou maintenez une table de mappage de référence. - Recherches : Ingérées sous forme de chaînes GUID. Pour obtenir les données associées, effectuez une jointure avec la table référencée.
- Ensembles d'options à sélection multiple : ingérés comme des chaînes d'entiers séparées par des virgules (par exemple,
"1,3,5"). Analysez la chaîne pour extraire les valeurs individuelles.
Exemple : analyse des ensembles d'options à sélection multiple
-- 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
L'ingestion incrémentielle du connecteur Dynamics 365 suit les règles suivantes :
Détection des changements
- Insertions : nouveaux enregistrements détectés par leur présence dans les journaux de modifications.
- Mises à jour : enregistrements modifiés identifiés par des changements dans
versionnumber. - Suppressions : Enregistrements supprimés identifiés par des marqueurs de suppression dans les journaux des modifications (s'ils sont exportés par Synapse Link).
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é).
Exemple de structure de table :
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.
Exemple de structure de table :
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
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
parameter | Type | Description | Exemple |
|---|---|---|---|
| Chaîne | Doit être |
|
| Chaîne | Nom de votre connexion Unity Catalog |
|
| Chaîne | Nom de schéma logique Synapse Link (généralement |
|
| Chaîne | Nom logique de la table D365 (une entrée par objet |
|
| Chaîne | Catalogue Unity Catalog cible |
|
| Chaîne | Schéma Unity Catalog cible |
|
| Chaîne |
|
|
Parameters facultatifs
parameter | Type | Description | Exemple |
|---|---|---|---|
| Objet | Paramètres par table (sélection de colonne, etc.) |
Exemple de configuration de pipeline
Terminer la configuration du pipeline à l'aide du 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 Dynamics 365 offre des options d’optimisation des performances limitées :
Sélection de colonne
Sélectionnez uniquement les colonnes requises pour réduire :
- Transfert de données depuis ADLS Gen2
- Coûts de stockage dans Delta Lake
- temps de traitement des query
Consultez la sélection de colonnes pour les détails de configuration.
Regroupement de tables
Pour les environnements avec de nombreuses tables :
- Tables associées : Regroupez les tables associées dans le même pipeline pour une gestion facilitée.
- **Basé sur le volume** : séparez les tables à volume élevé dans des pipelines dédiés.
- Fréquence de mise à jour : regroupez les tables avec des modèles de mise à jour similaires.
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.