Maîtriser la Web API Dynamics 365 avec Postman

Qu'est-ce que Postman ?

Postman est l'une des plateformes de développement et de test d'API les plus utilisées. Pour les consultants et développeurs Dynamics 365, c'est un outil indispensable pour explorer la Web API, tester des requêtes, déboguer des problèmes d'intégration et prototyper des appels API avant de les mettre en œuvre dans le code. Postman.

L'API Web Dynamics 365 est un endpoint RESTful OData v4.0 qui fournit un accès programmatique aux données et métadonnées de votre organisation. Utiliser Postman pour interagir avec cette API vous permet de tester rapidement des requêtes, valider des flux d'authentification et inspecter les structures de réponse sans écrire une seule ligne de code.

Pourquoi utiliser Postman avec Dynamics 365 ?

• Prototypage rapide : Tester les requêtes et opérations API avant de les mettre en œuvre dans des plugins ou applications externes
• Test d'authentification : Valider les flux OAuth et dépanner les problèmes liés aux tokens
• Découverte d'API : Explorer les entités, actions et fonctions disponibles via l'endpoint $metadata
• Débogage d'intégration : Reproduire et diagnostiquer les erreurs API signalées par les systèmes externes
• Analyse de performance : Mesurer les temps de réponse API et identifier les goulots d'étranglement
• Documentation : Créer et partager des collections comme documentation API vivante pour votre équipe

Démarrage : installation et configuration

Installation de Postman

Postman est disponible en application de bureau pour Windows, macOS et Linux. Une version web existe, mais l'application de bureau offre de meilleures performances et des fonctionnalités hors connexion.

Étapes d'installation :

1. Télécharger Postman depuis postman.com/downloads
2. Installer l'application en suivant les instructions
3. Créer un compte Postman gratuit ou se connecter avec Google/GitHub
4. Créer un workspace pour vos projets Dynamics 365
5. Se familiariser avec l'interface : collections, requêtes, environnements

Configuration de l'authentification avec OAuth 2.0

La Web API de Dynamics 365 exige une authentification OAuth 2.0 via Microsoft Entra ID (anciennement Microsoft Entra ID). Il est essentiel de bien configurer l'authentification : sans elle, toutes vos requêtes API échoueront avec des erreurs 401 Unauthorized. guide d'authentification OAuth.

Enregistrement d'Application Microsoft Entra ID

Avant de pouvoir vous authentifier depuis Postman, vous devez inscrire une application dans Microsoft Entra ID. Cette inscription fournit les identifiants client nécessaires à l'authentification OAuth.

Étapes d'enregistrement d'App :

1. Accédez au portail Azure et sélectionnez « Microsoft Entra ID »
2. Cliquez sur « Inscriptions d'applications » → « Nouvelle inscription »
3. Nom : « Postman Dynamics 365 Web API » (ou similaire)
4. Types de comptes pris en charge : « Comptes dans cet annuaire d'organisation uniquement »
5. URI de redirection : sélectionnez « Web » et entrez https://oauth.pstmn.io/v1/callback
6. Cliquez sur « Inscrire » et notez l'ID d'application (client)
7. Accédez à « Certificats et secrets » → « Nouveau secret client »
8. Ajoutez une description (p. ex. « Accès Postman ») et définissez l'expiration
9. Copiez la Valeur du secret immédiatement (elle ne sera plus affichée)
10. Accédez à « Autorisations d'API » → « Ajouter une autorisation »
11. Sélectionnez « Dynamics CRM » → « Autorisations déléguées »
12. Cochez « user_impersonation » → « Ajouter des autorisations »
13. Cliquez sur « Accorder le consentement administrateur » si vous avez les privilèges admin

Configuration OAuth 2.0 dans Postman

Une fois votre application inscrite dans Microsoft Entra ID, configurez Postman pour qu'il utilise ces identifiants. La prise en charge d'OAuth 2.0 dans Postman gère automatiquement l'obtention et le renouvellement des jetons.

Étapes de configuration :

1. Dans Postman, créez une nouvelle requête ou collection
2. Ouvrez l'onglet « Authorization »
3. Sélectionnez « OAuth 2.0 » dans la liste déroulante Type
4. Cliquez sur « Get New Access Token » pour configurer les paramètres OAuth
5. Renseignez les champs suivants :
   • Token Name : « D365 Access Token »
   • Grant Type : « Authorization Code »
   • Callback URL : https://oauth.pstmn.io/v1/callback
   • Auth URL : https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/authorize
   • Access Token URL : https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token
   • Client ID : l'ID d'application (client) de votre inscription d'application dans Microsoft Entra ID
   • Client Secret : la valeur secrète que vous avez copiée précédemment
   • Scope : https://YOUR_ORG.crm.dynamics.com/.default
6. Cliquez sur « Request Token » : une fenêtre de navigateur s'ouvre pour l'authentification
7. Connectez-vous avec votre compte Dynamics 365
8. Une fois connecté, cliquez sur « Use Token »

Opérations CRUD avec l'API web

L'API Web Dynamics 365 prend en charge les opérations CRUD RESTful standard utilisant les méthodes HTTP : GET (récupérer), POST (créer), PATCH (mettre à jour) et DELETE. documentation des opérations web API.

1. Créer (POST)

La création d'enregistrements nécessite une requête POST dont le corps JSON contient les données de l'entité. La réponse contient l'URI du nouvel enregistrement dans l'en-tête OData-EntityId.

Exemple : créer un compte

Content-Type: application/json
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{
  "name": "Contoso Corporation",
  "telephone1": "+1-555-0123",
  "emailaddress1": "info@contoso.com",
  "address1_city": "Seattle",
  "address1_stateorprovince": "WA",
  "industrycode": 1,
  "revenue": 5000000
}

2. Récupérer (GET)

Les requêtes GET récupèrent des données de Dynamics 365. Vous pouvez récupérer des enregistrements uniques, des collections ou utiliser des options de requête pour filtrer et trier.

Exemple : récupérer un compte avec $select et $expand

Options de requête courantes :

• $select: $select : Choisir les colonnes spécifiques à retourner (améliore la performance)
• $filter: $filter : Appliquer des conditions de filtre (p. ex. revenue gt 1000000)
• $orderby: $orderby : Trier les résultats (p. ex. createdon desc)
• $top: $top : Limiter le nombre de résultats (p. ex. $top=10)
• $expand: $expand : Inclure les enregistrements liés dans la réponse
• $count: $count : Inclure le nombre total d'enregistrements correspondants

3. Mettre à jour (PATCH)

Les requêtes PATCH mettent à jour les enregistrements existants. Incluez uniquement les champs que vous voulez mettre à jour.

Exemple : mettre à jour le chiffre d'affaires d'un compte

{
  "revenue": 7500000,
  "description": "Updated after Q1 review"
}

4. Supprimer (DELETE)

Les requêtes DELETE suppriment définitivement les enregistrements de Dynamics 365. Utilisez avec précaution, surtout dans les environnements de production.

Exemple : supprimer un compte

Opérations avancées

Requêtes batch

Les requêtes batch permettent de regrouper plusieurs opérations en une seule requête HTTP, réduisant significativement la surcharge réseau. opérations batch.

Structure d'une requête batch :

Content-Type: multipart/mixed;boundary=batch_AAA123
Accept: application/json

--batch_AAA123
Content-Type: application/http
Content-Transfer-Encoding: binary

POST /api/data/v9.2/accounts HTTP/1.1
Content-Type: application/json

{
  "name": "Account 1",
  "revenue": 100000
}

--batch_AAA123
Content-Type: application/http
Content-Transfer-Encoding: binary

POST /api/data/v9.2/accounts HTTP/1.1
Content-Type: application/json

{
  "name": "Account 2",
  "revenue": 200000
}

--batch_AAA123--

Bonnes pratiques batch :

• Limiter la taille du batch à 100 opérations pour une performance optimale
• Utiliser les change sets pour les opérations transactionnelles (tout ou rien)
• Mélanger les opérations de lecture et d'écriture dans le même batch
• Gérer proprement les échecs partiels : les réponses batch contiennent le résultat de chaque opération
• Surveiller les limites de protection du service API

Requêtes FetchXML

FetchXML est un langage de requête propriétaire pour Dynamics 365 qui prend en charge les requêtes complexes incluant agrégats, groupements et outer joins. référence FetchXML.

Exemple : exécuter une requête FetchXML

Conseils FetchXML :

• Encoder en URL les requêtes FetchXML lors du passage en paramètres
• Utiliser FetchXML Builder dans XrmToolBox pour concevoir visuellement des requêtes complexes
• Tirer parti des fonctions d'agrégation (sum, avg, count, min, max) pour le reporting
• Utiliser link-entity pour les jointures entre tables liées
• Ajouter la pagination aux grands ensembles de résultats

Actions et fonctions

Dynamics 365 expose la logique métier via des actions (opérations POST avec effets de bord) et des fonctions (opérations GET sans effets de bord). Il s'agit à la fois d'actions système (comme WinOpportunity ou QualifyLead) et des actions personnalisées que vous créez.

Exemple : appeler l'action WinOpportunity

{
  "OpportunityClose": {
    "subject": "Won the deal!",
    "opportunityid@odata.bind": "/opportunities(GUID)"
  },
  "Status": 3
}

Gestion des erreurs et dépannage

Comprendre les réponses d'erreur est essentiel pour déboguer les problèmes d'API. La Web API de Dynamics 365 renvoie des messages d'erreur détaillés au format JSON, selon les conventions d'erreur OData.

Codes de statut HTTP courants

• 200 OK: 200 OK : opération GET ou PATCH réussie
• 201 Created: 201 Created : opération POST réussie (nouvel enregistrement créé)
• 204 No Content: 204 No Content : Opération DELETE ou PATCH réussie sans valeur de retour
• 400 Bad Request: 400 Bad Request : Syntaxe de requête invalide ou erreurs de validation
• 401 Unauthorized: 401 Unauthorized : échec d'authentification ou token expiré
• 403 Forbidden: 403 Forbidden : privilèges insuffisants pour l'opération
• 404 Not Found: 404 Not Found : L'entité ou l'enregistrement n'existe pas
• 412 Precondition Failed: 412 Precondition Failed : Vérification de concurrence échouée
• 429 Too Many Requests: 429 Too Many Requests : Limites de protection du service API dépassées

Structure d'une réponse d'erreur

En cas d'erreur, le corps de la réponse indique précisément ce qui s'est mal passé :

{
  "error": {
    "code": "0x80040217",
    "message": "You do not have permission to access these records.",
    "innererror": {
      "message": "Principal user (Id=...) is missing prvReadAccount privilege",
      "type": "System.ServiceModel.FaultException",
      "stacktrace": "..."
    }
  }
}

Checklist de débogage

• Vérifier que le token OAuth est valide et non expiré
• S'assurer que les headers appropriés sont inclus (Content-Type, OData-MaxVersion, Prefer)
• Valider la syntaxe JSON dans le corps de la requête
• Vérifier que les noms logiques d'entités et attributs correspondent exactement (sensible à la casse)
• Confirmer que l'utilisateur a les privilèges suffisants pour l'opération
• Revoir les headers de limite de protection du service (x-ms-ratelimit-*) dans les réponses
• Utiliser la Console Postman pour inspecter les requêtes/réponses brutes

Bonnes pratiques pour l'usage en production

Optimisation de la performance

• Utiliser $select : Toujours spécifier uniquement les colonnes nécessaires – réduit la taille du payload
• Mettre en œuvre la pagination : Utiliser $top et $skiptoken pour les grands ensembles de résultats
• Tirer parti des requêtes batch : Regrouper plusieurs opérations pour réduire la surcharge HTTP
• Mettre en cache les métadonnées : Les définitions d'entités et option sets changent rarement – les mettre en cache côté client
• Utiliser les requêtes conditionnelles : Mettre en œuvre les headers If-Match pour le contrôle de concurrence optimiste
• Minimiser la Profondeur de $expand : Les expand imbriqués impactent la performance – récupérer les données liées séparément si besoin

Considérations de sécurité

• Principe du moindre privilège : Utiliser des comptes de service avec les permissions minimales requises
• Stockage sécurisé des identifiants : Ne jamais coder en dur les identifiants – utiliser Azure Key Vault
• Gestion des tokens : Mettre en œuvre une logique de rafraîchissement de token appropriée avant expiration
• Validation des entrées : Sanitizer toutes les entrées utilisateur pour prévenir les attaques par injection
• HTTPS uniquement : Toujours utiliser HTTPS pour les communications API
• Journalisation d'audit : Activer la journalisation d'audit dans Dynamics 365 pour suivre les changements de données via API

Test et documentation

• Créer des collections : Organiser les requêtes liées en collections Postman pour la réutilisabilité
• Utiliser les environnements : Créer des variables d'environnement pour DEV, TEST, PROD pour basculer les contextes facilement
• Écrire des tests : Ajouter des scripts de test Postman pour valider les réponses automatiquement
• Générer la documentation : Utiliser la fonctionnalité de documentation Postman pour partager les exemples API avec l'équipe
• Exporter les collections : Versionner vos collections Postman comme fichiers JSON dans Git
• Surveiller les API : Utiliser les Monitors Postman pour exécuter des health checks planifiés

Templates de collection Postman

Créer une collection Postman bien organisée économise du temps et standardise les interactions API.

Organisation de collection

• Authentification : Dossier avec exemples d'acquisition de token et flux de rafraîchissement
• Métadonnées : Requêtes pour explorer les entités, attributs et relations via $metadata
• Opérations CRUD : Sous-dossiers par entité avec exemples créer/lire/modifier/supprimer
• Requêtes : Exemples de filtrage avancé, tri et FetchXML
• Actions & fonctions : Actions système et actions personnalisées
• Opérations batch : Templates de requêtes batch pour opérations en masse
• Test & diagnostics : Endpoints de health check et requêtes de dépannage

Fonctionnalités avancées Postman

Scripts pre-request

Les scripts pre-request s'exécutent avant l'envoi d'une requête, permettant un comportement dynamique comme la génération de timestamps ou la vérification d'expiration de token.

// Check if token exists and is not expired
const tokenExpiry = pm.environment.get("token_expiry");
const now = Date.now();

if (!tokenExpiry || now >= tokenExpiry) {
    // Token expired - get new token
    console.log("Token expired, requesting new token...");
    // Trigger OAuth flow or refresh token logic
}

Scripts de test

Les scripts de test s'exécutent après réception d'une réponse, permettant de valider automatiquement les codes de statut, la structure de réponse et les valeurs de données.

pm.test("Status code is 201 Created", function () {
    pm.response.to.have.status(201);
});

pm.test("Response has OData-EntityId header", function () {
    pm.response.to.have.header("OData-EntityId");
});

// Extract account ID from response
const entityId = pm.response.headers.get("OData-EntityId");
const accountId = entityId.match(/\(([^)]+)\)/)[1];
pm.environment.set("new_account_id", accountId);
console.log("Created account ID: " + accountId);

Collection Runner

Collection Runner exécute toutes les requêtes d'une collection séquentiellement ou avec une logique d'itération personnalisée.

• Exécuter des collections entières pour valider des workflows de bout en bout
• Utiliser des fichiers de données (CSV, JSON) pour paramétrer les requêtes pour tests en masse
• Générer des rapports de test à partager avec les parties prenantes
• Planifier des exécutions avec Newman (CLI de Postman) dans les pipelines CI/CD

Intégrer Postman au workflow de développement

De Postman au code

Une des fonctionnalités les plus précieuses de Postman est la génération de code. Après avoir perfectionné une requête API dans Postman, générez le code équivalent en C#, JavaScript, Python ou d'autres langages.

Étapes de génération de code :

1. Créer et tester votre requête dans Postman jusqu'à ce qu'elle fonctionne correctement
2. Cliquer sur l'icône de code (</>) dans le panneau de requête
3. Sélectionner votre langage/framework cible
4. Copier le code généré dans votre application
5. Refactoriser selon votre architecture (gestion d'erreurs, logique de retry, etc.)

Contrôle de version et collaboration d'équipe

Traitez vos collections Postman comme des artefacts de code. Exportez les collections et environnements en fichiers JSON et committez-les dans votre repository.

• Exporter régulièrement les collections et committer dans le repository Git
• Utiliser les workspaces Postman pour la collaboration et le partage d'équipe
• Documenter les breaking changes dans les descriptions de collection
• Créer des branches séparées pour les changements API expérimentaux
• Revoir les changements de collection dans les pull requests

Conclusion

Maîtriser Postman pour le développement avec la Web API de Dynamics 365 accélère considérablement votre productivité de consultant ou de développeur. Du prototypage rapide d'appels API aux tests d'intégration complets, Postman fournit l'outillage nécessaire pour travailler efficacement avec la Web API.

Commencez par configurer correctement l'authentification, organisez votre travail en collections bien structurées, tirez parti des variables d'environnement pour la flexibilité et incorporez progressivement les fonctionnalités avancées.

N'oubliez pas de toujours tester dans les environnements de développement d'abord, de mettre en œuvre une gestion d'erreurs appropriée, de respecter les limites de protection du service et de documenter vos modèles API pour le partage de connaissances de l'équipe.