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ément |
Description |
|---|---|
Protocole |
Le protocole correspondant, https:// ou http://. |
L'URL de base |
Il s'agit de l'URL que vous utilisez normalement pour ouvrir l'application Web.
|
Chemin d'accès de l'API Web |
Le chemin d'accès à l'API Web est /api/data/. |
Version |
La version est exprimée comme suit : v[Major_version].[Minor_version][PatchVersion]/. Les versions valides de cette version sont :
La valeur spécifique que vous utilisez n'est pas importante avec cette version tant vous avez appliqué les mises à jour ou les Service Packs correspondants. Pour plus d'informations, voir Compatibilité de version |
Ressource |
Le nom de l'entité, de la fonction ou de l'action que vous souhaitez utiliser. |
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.
Notes
La prochaine version majeure (v9) introduit des capacités qui seront uniquement disponibles avec cette version. Les versions mineures suivantes peuvent fournir des fonctionnalités supplémentaires qui ne seront pas reportées aux versions mineures précédentes. Votre code écrit pour v8.x continuera à fonctionner dans v9.x si vous référencez v8.2 dans l'URL que vous utilisez.
Pour la version v8.x, utilisez la dernière version que vous pouvez et sachez quelles mises à jour ou quels Service Packs de cette version principale n'introduiront pas de modifications importantes. Toutefois, cela sera différent dans les prochaines versions où vous devrez être particulièrement attentifs à la version du service que vous adressez.
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.
Méthode |
Utilisation |
|---|---|
GET |
À utiliser lors de la récupération des données, notamment les fonctions d'appel. Le code de statut destiné à une récupération réussie est 200 OK. |
POST |
À utiliser lors de la création d'entités ou d'actions d'appel. |
PATCH |
À utiliser lors de la mise à jour d'entités ou l'exécution d'opérations de type upsert. |
DELETE |
À utiliser lors de la suppression des entités ou des propriétés individuelles des entités. |
PUT |
À utiliser dans des situations limitées pour mettre à jour différentes propriétés d'entités. Cette méthode n'est par recommandée en mettant à jour la plupart des entités. À utiliser lors de la mise à jour des entités de modèles. |
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 :
Code |
Description |
Type |
|---|---|---|
200 OK |
Est généré lorsque votre opération renvoie des données dans le corps de réponse. |
Succès |
201 Created |
Est généré lorsque votre opération POST réussit et que vous avez spécifié la préférence return-representation dans votre demande. Notes Cette fonctionnalité a été ajoutée avec la Mise à jour de décembre 2016 pour Dynamics 365 (en ligne et local). |
Succès |
204 No Content |
Est généré lorsque votre opération aboutit mais ne renvoie pas de données dans le corps de réponse. |
Succès |
304 Not Modified |
Est généré lors du test pour voir si une entité a été modifiée depuis sa dernière récupération.Pour plus d'informations :Récupérations conditionnelles |
Redirection |
403 Forbidden |
Est généré pour les types d'erreurs suivants :
|
Erreur client |
401 Unauthorized |
Est généré pour les types d'erreurs suivants :
|
Erreur client |
413 Payload Too Large |
Générée lorsque la longueur de la demande est trop grande. |
Erreur client |
400 BadRequest |
Générée lorsqu'un argument n'est pas valide. |
Erreur client |
404 Not Found |
Générée lorsque la ressource n'existe pas. |
Erreur client |
405 Method Not Allowed |
Cette erreur se produit pour les combinaisons de méthodes et de ressources incorrectes. Par exemple, vous ne pouvez pas utiliser DELETE ou PATCH sur une collection d'entités. Est généré pour les types d'erreurs suivants :
|
Erreur client |
412 Precondition Failed |
Est généré pour les types d'erreurs suivants :
|
Erreur client |
500 Internal Server Error |
Erreur attendue si une demande POST de création d'une entité active la détection des doublons et que l'entité à créer est un doublon.Pour plus d'informations :244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection |
Erreur du serveur |
501 Not Implemented |
Générée lorsqu'une opération demandée n'est pas implémentée. |
Erreur serveur |
503 Service Unavailable |
Générée lorsque le service API Web n'est pas disponible. |
Erreur serveur |
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