Aller au contenu
Intégration API

SDK Dataverse sous Symfony pour reprendre une synchronisation CRM

Jérémy Chomel Dawap
  • Publié le : 27 janvier 2025
  • Mis à jour le : 12 novembre 2026
  • Temps de lecture : 12 minutes
Portrait de Jérémy Chomel

Un worker Symfony vient d’appliquer la deuxième page de comptes Dynamics 365 CRM quand son processus s’arrête. Le système cible a déjà reçu les modifications, mais le worker ignore si le point de reprise a été enregistré. Au redémarrage, quelle URL doit-il rappeler et comment éviter de transmettre deux fois les mêmes changements ?

Le risque est de sauter une page ou de réappliquer des changements dans le désordre. La Web API Dataverse fournit deux liens pour reprendre la synchronisation. @odata.nextLink permet de finir la lecture en cours. @odata.deltaLink permet de démarrer le cycle suivant à partir d’un état synchronisé. Symfony HttpClient transmet ces liens au traitement, qui les enregistre avec les données appliquées.

Le scénario utilise une réplique en lecture seule des noms de comptes. Pour déterminer quels champs d’un flux d’intégration Dynamics 365 CRM peuvent être copiés, commencez par définir le système propriétaire de chaque champ.

Dans quels cas suivre les changements Dataverse

Le suivi convient à une réplique de données qui doit rattraper les créations, mises à jour et suppressions depuis sa dernière lecture réussie. Les comptes de la table accounts alimentent ici un référentiel de consultation. L’identifiant accountid relie la fiche source à son exemplaire dans la réplique. Le nom affiché peut évoluer sans créer un nouveau compte local.

Vérifiez que vous êtes sur la Web API Dataverse de Dynamics 365 CRM. Les flux Finance and Operations et Business Central ont leurs propres interfaces. Retrouvez les interfaces et les responsabilités d’écriture dans notre guide d’intégration Dynamics 365 CRM et Dataverse.

Activer le suivi et lire la première page

Vérifiez que le suivi des modifications est activé sur la table et que l’utilisateur d’application peut lire les lignes du périmètre attendu. Démarrez la lecture de accounts avec Prefer: odata.track-changes. L’exemple sélectionne accountid,name. Avec cette préférence, Dataverse refuse $filter, $orderby, $expand et $top. Si la réplique exclut certaines lignes, faites appliquer cette règle par le traitement en aval, suppressions comprises. Documentation Microsoft sur le suivi des changements Dataverse.

Suivez chaque URL de pagination telle qu’elle est reçue, avec la même préférence odata.maxpagesize. Les paramètres du lien représentent l’état de la lecture côté Dataverse. Les réencoder ou les compléter peut invalider la reprise. Attendez la dernière page avant d’enregistrer le lien delta qui démarrera le cycle suivant. Documentation Microsoft sur la pagination OData.

Consignez l’organisation, la table et la liste de champs avec l’état de synchronisation. Pour étendre la réplique à une autre table ou changer la projection, établissez une nouvelle lecture initiale avec sa propre position. L’ancien lien correspond à la projection qui l’a produit.

Authentifier le traitement avec Microsoft Entra ID

Créez un utilisateur d’application Dataverse associé à l’application Microsoft Entra et attribuez-lui un rôle de lecture adapté à la réplique. Pour un flux d’identifiants client, demandez le jeton pour l’URL de l’environnement suivie de /.default. La recette doit confirmer qu’un compte témoin attendu apparaît avec les droits de cet utilisateur. Un résultat vide peut aussi refléter la portée de ses droits. Documentation Microsoft sur l’authentification OAuth.

Le worker fournit un jeton courant au lecteur. Il gère son renouvellement et la décision de retenter la page. L’adresse d’organisation est fixée dans la configuration du déploiement. Les liens de continuation doivent viser le même endpoint, et les redirections sont désactivées avant d’envoyer le jeton.

Lire une page avec Symfony HttpClient

Le lecteur ci-dessous utilise PHP 8.2 ou supérieur et un client Symfony sans relance automatique. first() ouvre la lecture initiale, next() suit une page intermédiaire et delta() part du lien obtenu à la fin du dernier cycle. Les paramètres du lien restent opaques. Pour un delta qui renvoie un objet JSON vide, le worker peut conserver son dernier lien validé.

<?php

use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;
use Symfony\Contracts\HttpClient\HttpClientInterface;

final class DataversePageFailure extends RuntimeException
{
    public function __construct(int $status, public readonly ?string $retryAfter)
    {
        parent::__construct("Lecture Dataverse refusée (HTTP {$status}).", $status);
    }
}

final class DataverseAccountPages
{
    private const PAGE_SIZE = 'odata.maxpagesize=200';
    private readonly string $accountsUrl;

    public function __construct(
        private readonly HttpClientInterface $client,
        string $origin,
    ) {
        if (!preg_match('~\Ahttps://[a-z0-9-]+(?:\.[a-z0-9-]+)+\z~i', $origin)) {
            throw new InvalidArgumentException('URL d’organisation Dataverse invalide.');
        }
        $this->accountsUrl = $origin . '/api/data/v9.2/accounts';
    }

    public function first(#[\SensitiveParameter] string $token): array
    {
        return $this->read(
            $this->accountsUrl . '?$select=accountid,name',
            $token,
            'odata.track-changes, ' . self::PAGE_SIZE,
        );
    }

    public function next(string $url, #[\SensitiveParameter] string $token): array
    {
        return $this->read($url, $token, self::PAGE_SIZE);
    }

    public function delta(string $url, #[\SensitiveParameter] string $token): array
    {
        return $this->read($url, $token, self::PAGE_SIZE, allowEmptyDelta: true);
    }

    /** @return array{rows: array, next: ?string, delta: ?string} */
    private function read(
        string $url,
        #[\SensitiveParameter] string $token,
        string $preference,
        bool $allowEmptyDelta = false,
    ): array {
        $this->requireAccountUrl($url);
        try {
            $response = $this->client->request('GET', $url, [
                'auth_bearer' => $token,
                'max_redirects' => 0,
                'timeout' => 10,
                'max_duration' => 30,
                'headers' => [
                    'Accept' => 'application/json',
                    'OData-Version' => '4.0',
                    'OData-MaxVersion' => '4.0',
                    'Prefer' => $preference,
                ],
            ]);
            $status = $response->getStatusCode();
            if ($status !== 200) {
                $retryAfter = $status === 429
                    ? ($response->getHeaders(false)['retry-after'][0] ?? null)
                    : null;
                throw new DataversePageFailure($status, $retryAfter);
            }
            $data = json_decode($response->getContent(false), flags: JSON_THROW_ON_ERROR);
        } catch (TransportExceptionInterface) {
            throw new RuntimeException('Transport Dataverse interrompu.');
        } catch (JsonException) {
            throw new UnexpectedValueException('JSON Dataverse invalide.');
        }

        if ($allowEmptyDelta && $data instanceof stdClass && get_object_vars($data) === []) {
            return ['rows' => [], 'next' => null, 'delta' => $url];
        }

        $next = $data->{'@odata.nextLink'} ?? null;
        $delta = $data->{'@odata.deltaLink'} ?? null;
        if (!is_array($data->value ?? null) || ($next === null) === ($delta === null)) {
            throw new UnexpectedValueException('Page Dataverse incomplète.');
        }

        $this->requireAccountUrl($next ?? $delta);

        return ['rows' => $data->value, 'next' => $next, 'delta' => $delta];
    }

    private function requireAccountUrl(mixed $url): void
    {
        if (!is_string($url) || !str_starts_with($url, $this->accountsUrl . '?')
            || preg_match('/[\x00-\x20\x7f#]/', $url)) {
            throw new UnexpectedValueException('URL Dataverse inattendue.');
        }
    }
}

Cette classe valide l’enveloppe de la page. Le worker valide les champs de chaque ligne et décide comment interpréter les suppressions. Injectez un client dédié à ce flux. En recette, essayez le lien fourni par votre environnement avec ses paramètres d’origine. Une URL rejetée demande un examen de la configuration ou de la réponse avant de reprendre.

Dans Symfony Messenger, sérialisez uniquement l’identifiant local du flux dans le message. Le handler lit la position dans sa base et récupère un jeton avant le GET. Le corps de la réponse JSON reste dans le traitement de la page. Il est possible de différer le même message après un 429 sans copier le lien de pagination ni le secret dans le transport Messenger.

Enregistrer les pages et leur point de reprise

Utilisez un seul worker actif par couple organisation et table, ou verrouillez l’avancement de sa position. Pour une réplique dans la même base, ouvrez une transaction qui applique les lignes de la page puis enregistre la prochaine URL. Une page intermédiaire avance la position du cycle en cours. La dernière page enregistre le nouveau lien delta et clôt le cycle. Si la transaction échoue, le worker retrouve la position précédente au redémarrage.

Si le système cible est distant, enregistrez les opérations à envoyer et la position de lecture dans la même transaction. Un autre worker expédie ces opérations depuis cette file persistante. L’état de livraison reste suivi jusqu’à confirmation. Utilisez un identifiant d’opération stable dans la file et faites respecter l’ordre par compte, ou protégez la cible avec un contrôle de version. Un rejeu tardif peut rétablir un ancien nom même si le traitement retrouve le même accountid.

Paradoxalement, une synchronisation peut finir sa lecture avec des opérations encore en attente de livraison. Par exemple, si la file a accepté les lignes de la dernière page alors que le service distant répond 503, le lien delta peut être enregistré avec la file. Le délai de publication reste en cours côté cible. Suivez les deux positions dans le support pour éviter de relancer une lecture source déjà terminée.

Traiter les suppressions dans la réplique

Une suppression reçue dans le delta peut être identifiée par le contexte /$deletedEntity et les champs id et reason. Utilisez cet id pour retrouver l’accountid déjà enregistré. Dans l’exemple, le worker désactive uniquement l’entrée de consultation. La suppression d’un client dans un ERP relève d’une décision séparée, notamment s’il a des commandes ou des factures rattachées.

Si une suppression désigne un compte déjà absent, alors l’état local attendu est atteint. Consignez ce résultat sans créer de fiche vide. Si le GUID est invalide, alors bloquez l’avancement de la page et corrigez le traitement ou l’écart de contrat. Compter ces deux cas de la même façon ferait passer une ligne impossible à traiter pour une suppression réussie.

Erreurs fréquentes et décisions de reprise

Dans les cas d’échec ci-dessous, conservez la position durable et reprenez à partir de celle-ci lorsque la cause est résolue. Documentation Microsoft sur les limites de l’API Dataverse.

Décisions de reprise d’une lecture Dataverse
SignalDécision
401 ou 403Pour un jeton expiré, renouveler le jeton et relire une fois la même page. Pour un refus de droits, vérifier l’utilisateur d’application et sa portée avant de relancer.
429Respecter le délai en secondes de Retry-After. Coordonner les workers qui partagent l’utilisateur Dataverse.
Coupure ou 5xxRetenter le même GET avec une temporisation bornée. Si la file vieillit malgré les relances, escalader l’incident.
Lien expiré ou refuséVérifier le diagnostic et l’environnement. Si le delta est périmé, reconstruire une réplique temporaire et la rapprocher de l’ancienne avant bascule.
JSON invalide, lien inattendu ou pagination en boucleArrêter le cycle. Si une page renvoie une URL de pagination déjà suivie, signaler la répétition et garder la dernière position vérifiée.

Pour le diagnostic, relevez la table, l’environnement, l’identifiant du cycle, le numéro local de page, le statut HTTP et l’âge du dernier cycle terminé. Gardez les liens complets dans le stockage privé du traitement. Dans les journaux, les exceptions et le traçage HTTP, masquez le jeton d’accès, les paramètres des liens et les données de compte.

Rejouer une interruption en recette

Dans un scénario fictif, la réplique est déjà en service. Le worker ouvre un nouveau cycle avec le lien delta enregistré. La première page met à jour le nom du compte FR01 / 004208 et renvoie une seconde page. Après validation de la première transaction, le worker conserve l’URL de la seconde page. Un appel à cette URL reçoit un 429 à 09:14:20 avec Retry-After: 30. Le prochain appel autorisé part à 09:14:50 au plus tôt, sur la même URL.

Au deuxième essai, la seconde page désactive un autre compte dans la réplique et fournit un lien delta. Interrompez le traitement juste avant la validation de sa transaction. Au redémarrage, le worker doit relire cette seconde page. Interrompez-le ensuite juste après la validation. Il doit retrouver le lien delta enregistré, avec la première mise à jour et la désactivation toujours visibles, chacune appliquée une fois.

Si le worker transmet les lignes à un service distant, faites aussi tomber la connexion après l’envoi de la désactivation mais avant réception de la confirmation. Vérifiez que la file renvoie la même opération et que le service cible sait reconnaître cet envoi.

Plan d’action pour recetter le traitement

  1. Simuler la lecture initiale en deux pages avec MockHttpClient. Vérifier la conservation de l’URL de continuation et de la préférence de taille de page.
  2. Simuler un cycle delta avec une mise à jour, une suppression, puis une lecture sans changement. Contrôler l’état final de la réplique et le lien conservé.
  3. Simuler la limitation 429, une redirection et un lien vers un autre environnement. Contrôler que la position reste intacte et que le client refuse d’envoyer le jeton à l’autre adresse.
  4. Comparer les comptes témoins et provoquer une interruption avec l’utilisateur d’application de recette. Demander au support d’expliquer la décision prise à partir du journal.

Avant de modifier le rôle d’accès ou d’ouvrir une deuxième table, comparez de nouveau le périmètre lu avec le métier. Une recette qui compte seulement les lignes peut manquer un compte d’une autre entité juridique ou une désactivation attendue.

Guides sur l’intégration Dynamics 365 CRM

Si le référentiel est alimenté par plusieurs systèmes, décidez lequel garde la main sur chaque champ avant d’ouvrir les écritures. Choisir entre le CRM, l’ERP et le middleware comme propriétaire.

Pour mettre plusieurs imports en file, contrôlez le débit de l’identité qu’ils partagent. Diagnostiquer les erreurs 429 avec plusieurs workers Dataverse.

Conclusion sur la reprise de la synchronisation

Avant d’ouvrir le flux, retrouvez la dernière page appliquée, la prochaine URL et le compte témoin dans la cible. Refaites le contrôle après une coupure au milieu d’un cycle et après la validation du dernier lot. Si les positions correspondent à l’état des données, le support dispose d’un point de reprise vérifiable.

Pour un système distant, vérifiez aussi qu’une opération enregistrée dans la file reste visible après un redémarrage. La recette se termine quand le système cible confirme sa prise en compte.

Dawap accompagne le développement et la recette d’un connecteur Dynamics 365 CRM, depuis les droits Dataverse jusqu’à la reprise du flux.

Portrait de Jérémy Chomel

Transformez ce besoin en flux API fiable.

Dawap clarifie les systèmes concernés, les risques, le premier lot livrable et les conditions d’exploitation avant de construire le flux.

Vous préférez échanger ? Planifier un rendez-vous

Articles recommandés

Synchronisation des comptes Dynamics 365 CRM et ERP avec Dataverse Intégration API Intégrer Dynamics 365 CRM avec Dataverse et votre ERP Lire l'article
  • 5 septembre 2024
  • Lecture ~13 min

Deux sociétés utilisent le même numéro de client ERP. Le guide montre comment retrouver le bon compte dans Dataverse, choisir l’interface adaptée au produit Dynamics 365 et réserver les écritures à leur système responsable. Les cas de recette couvrent le conflit de version, le quota et la réponse perdue.

Répartition des droits d’écriture entre Dynamics 365 CRM, ERP et middleware Intégration API Dynamics 365 CRM et ERP : qui peut modifier chaque champ ? Lire l'article
  • 12 mars 2024
  • Lecture ~12 min

L’ERP bloque le crédit d’un client tandis que Dynamics 365 CRM affiche encore le statut précédent. Une matrice attribue les droits d’écriture au commerce, à la finance et à l’intégration. Le cas fictif montre comment traiter une mise à jour concurrente, une réponse perdue et un ancien statut remis en file par erreur.

Illustration de la coordination des workers d’un import ERP vers Dataverse sous une même identité Intégration API Dataverse : trop de workers pour l’import Lire l'article
  • 18 août 2025
  • Lecture ~16 minutes

Le nombre de workers augmente, mais l’import ERP ralentit et les erreurs 429 se multiplient. Identifiez les consommateurs d’une même identité Dataverse, puis testez une admission et une pause partagées dans SQLite. Les 41 contrôles locaux distinguent capacité, retries du SDK et appels sans issue confirmée.