Composer des demandes HTTP et gérer les erreurs

Date de publication : janvier 2017

S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Vous interagissez avec l'API Web en composant et en envoyant des requêtes HTTP. Vous devez savoir comment définir les en-têtes HTTP appropriés et gérer toutes les erreurs incluses dans la réponse.

Contenu de la rubrique

URL et versions d'API Web

Méthodes HTTP

En-têtes HTTP

Identifier les codes de statut

Analyse des erreurs relatives à la réponse

URL et versions d'API Web

Pour accéder à l'API Web, vous devez composer une URL à l'aide des composants du tableau suivant.

L'URL que vous utiliserez sera composée des parties suivantes : Protocole + URL de base + chemin d'accès de l'API Web + Version + Ressource.

Compatibilité de version

Dans cette version, nous avons appliqué un certain nombre de changements additionnels à chaque mise à jour ou service pack. Lorsque ces mises à jour sont appliquées, elles ajoutent les mêmes capacités aux versions mineures suivantes. Ainsi, si vous pouvez utiliser la version 8.2, les versions 8.1 et 8.0 auront les mêmes capacités. Cela est rendu possible car les changements ont été additionnels ou étaient résolutions de bogues traitant les éléments répertoriés dans Limitations relatives aux API Web Microsoft Dynamics 365. Aucun changement majeur n'a été introduit.

Méthodes HTTP

Les demandes HTTP peuvent appliquer une variété de méthodes différentes. Lorsque vous utilisez l'API Web, vous n'utilisez que les méthodes répertoriées dans le tableau suivant.

En-têtes HTTP

Bien que le protocole OData autorise les deux formats, JSON et ATOM, l'API Web prend en charge uniquement le format JSON. Par conséquent, les en-têtes suivants peuvent être appliqués.

Chaque demande doit inclure la valeur d'en-tête Accept de application/json, même lorsqu'aucun corps de réponse n'est prévu. Toute erreur retournée dans la réponse doit être retournée au format JSON. Lorsque votre code doit fonctionner même si cet en-tête n'est pas inclus, nous vous conseillons de l'ajouter comme recommandation

La version OData actuelle est 4.0, mais les futures versions peuvent autoriser de nouvelles fonctionnalités. Pour garantir qu'il n'y a aucune ambiguïté sur la version OData qui sera appliquée à votre code à ce point par la suite, vous devez toujours inclure un énoncé significatif de la version OData actuelle et la version maximale à appliquer dans votre code. Utilisez les deux en-têtes OData-Version et OData-MaxVersion définis sur la valeur 4.0.

Tous les en-têtes HTTP doivent inclure au moins les en-têtes suivants.

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

Chaque demande contenant des données JSON dans le corps de la demande doit inclure un en-tête Content-Type contenant une valeur application/json.

Content-Type: application/json

Vous pouvez utiliser des en-têtes supplémentaires pour activer des fonctionnalités spécifiques.

• Pour retourner des données lors des opérations de création (POST) ou de mise à jour (PATCH) pour les entités, incluez la préférence return=representation. Lorsque cette préférence est appliquée à une requête POST, une réponse réussie a le statut 201 (Created). Pour une requête PATCH, une réponse réussie a le statut 200 (OK). Si cette préférence n'est pas appliquée, les deux opérations retournent le statut 204 (No Content) pour indiquer qu'aucune donnée n'est retournée dans le corps de la réponse par défaut.

  Notes

  Cette fonctionnalité a été ajoutée avec la Mise à jour de décembre 2016 pour Dynamics 365 (en ligne et local).

• Pour retourner des valeurs mises en forme avec une requête, ajoutez la préférence odata.include-annotations définie sur Microsoft.Dynamics.CRM.formattedvalue à l'aide de l'en-tête de préférence.Pour plus d'informations :Inclure des valeurs mises en forme

• Vous utilisez également l'en-tête Prefer avec l'option odata.maxpagesize pour spécifier le nombre de pages que vous souhaitez consulter.Pour plus d'informations :Spécifiez le nombre d'entités à renvoyer dans une page

• Pour emprunter l'identité d'un autre utilisateur lorsque l'appelant dispose de privilèges pour le faire, ajoutez l'en-tête MSCRMCallerID avec la valeur systemuserid de l'utilisateur concerné par l'emprunt d'identité.Pour plus d'informations :Emprunter l'identité d'un autre utilisateur à l'aide de l'API Web.

• Pour appliquer l'accès concurrentiel optimiste, vous pouvez appliquer l'en-tête If-Match avec une valeur Etag.Pour plus d'informations :Appliquer l'accès concurrentiel optimiste.

• Pour activer la détection de doublons pour une demande POST, vous pouvez utiliser l'en-tête MSCRM.SuppressDuplicateDetection: false.Pour plus d'informations :244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection

• Pour contrôler si une opération upsert doit créer ou mettre une entité à jour, vous pouvez aussi utiliser les en-têtes If-Match et If-None-Match.Pour plus d'informations :Utilisation de Upsert avec une entité.

• Lorsque vous exécutez des opérations par lots, vous devez appliquer un certain nombre d'en-têtes différents dans la demande et avec chaque partie envoyée dans le corps.Pour plus d'informations :Exécuter des opérations par lots à l'aide de l'API Web.

Identifier les codes de statut

Si une demande http aboutit ou échoue, la réponse contiendra un code de statut. Les codes de statut sont renvoyés par l'API Web Microsoft Dynamics 365 avec ce qui suit :

Analyse des erreurs relatives à la réponse

Les détails sur les erreurs sont affichés au format JSON dans la réponse. Les erreurs apparaissent dans ce format.

    { "error":{ "code": "
            <This code is not related to the http status code and is frequently empty>", "message": "
            <A message describing the error>", "innererror": { "message": "
            <A message describing the error, this is frequently the same as the outer message>", "type": "Microsoft.Crm.CrmHttpException", "stacktrace": "
            <Details from the server about where the error occurred>" } } }

Voir aussi

Effectuer des opérations à l'aide de l'API Web
Interroger les données à l'aide de l'API Web
Créer une entité à l'aide de l'API Web
Récupérer une entité à l'aide de l'API Web
Mettre à jour et supprimer des entités à l'aide de l'API Web
Associer et dissocier les entités à l'aide de l'API Web
Utiliser des fonctions API Web
Utiliser des actions API Web
Exécuter des opérations par lots à l'aide de l'API Web
Emprunter l'identité d'un autre utilisateur à l'aide de l'API Web
Effectuer les opérations conditionnelles à l'aide de l'API Web

Microsoft Dynamics 365

© 2017 Microsoft. Tous droits réservés. Copyright