Composer des demandes HTTP et traiter les erreurs

Article
09/26/2023

Vous interagissez avec l’API Web en composant et en envoyant des demandes 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.

URL et versions d’API Web

Rechercher l’URL de l’API web pour votre environnement

Connectez-vous à Power Apps et sélectionnez votre environnement dans le coin supérieur droit.
Cliquez sur le bouton Paramètres dans le coin supérieur droit, puis sélectionnez Ressources du développeur.

À partir de là, vous pouvez copier la valeur de l’API web. Plus d’informations : Afficher les ressources du développeur

Le tableau suivant décrit les éléments de l’URL :

Partie	Description
Protocole	`https://`
Nom de l’environnement	Nom unique qui s’applique à votre environnement. Si le nom de votre société est Contoso, il peut donc être `contoso`.
Région	Votre environnement est généralement dans un centre de données à proximité d’un point de vue géographique. Pour l’Amérique du Nord, il s’agit de `crm`. Pour l’Amérique du Sud`crm2`, Pour le Japon `crm7`. Pour la liste complète, voir Régions du centre de données
URL de base	C’est généralement`dynamics.com.`, mais certains centres de données utilisent des valeurs différentes. Consultez la section Régions des centres de données.
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]/`. La version actuelle est `v9.2`.
Ressource	Le `EntitySetName` de la table, ou le nom de la fonction ou de l’action que vous souhaitez utiliser.

L’URL que vous utilisez est composée des parties suivantes :

Protocole + Nom de l’environnement + Région + URL de base + Chemin de l’API Web + Version + Ressource.

Longueur maximale de l’URL

La longueur maximale de l’URL est de 32 Ko (32 768 caractères). Cela devrait convenir à la plupart des types de requêtes, à l’exception de certaines GET opérations qui nécessitent des paramètres de requête de chaîne très longue, telles que les requêtes utilisant FetchXml. Si vous envoyez des requêtes dans le corps d’une $batch requête, vous pouvez envoyer des requêtes avec des URL allant jusqu’à 64 Ko (65 536 caractères). En savoir plus sur l’envoi de FetchXml dans une requête $batch.

Compatibilité de version

Cette version introduit des fonctionnalités qui ne sont pas disponibles dans les versions précédentes. 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 v9.0 continuera à fonctionner dans les versions futures si vous référencez v9.0 dans l’URL que vous utilisez.

Comme de nouvelles fonctionnalités sont introduites, elles peuvent entrer en conflit avec les versions antérieures. Ces changements cassants sont nécessaires pour améliorer le service. La plupart du temps, les fonctionnalités resteront les mêmes entre les versions, mais vous ne devez pas supposer qu’elles le seront.

Notes

Contrairement aux versions secondaires v8.x, les nouvelles fonctionnalités ou les autres modifications ajoutées aux versions futures ne seront pas appliquées aux versions précédentes. Faites attention à la version du service que vous utilisez et tester votre code si vous modifiez la version utilisée.

Méthodes HTTP

La table suivante répertorie les méthodes HTTP que vous pouvez utiliser avec l’API web Dataverse.

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 pas recommandée en mettant à jour la plupart des entités. Utilisez `PUT` lors de la mise à jour des définitions de table. Pour plus d’informations : Utiliser l’API web avec les définitions de table

En-têtes HTTP

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

Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
If-None-Match: null

Bien que le protocole OData autorise les deux formats, JSON et ATOM, l’API Web prend en charge uniquement le format JSON. 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 est 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 par la suite, vous devez toujours inclure un énoncé explicite de la version OData actuelle et de la version maximale à appliquer dans votre code. Utilisez les en-têtes OData-Version et OData-MaxVersion définis sur la valeur 4.0.

Les requêtes qui développent les propriétés de navigation à valeur de collection peuvent renvoyer des données mises en cache pour les propriétés qui ne reflètent pas des modifications récentes. Incluez l’en-tête If-None-Match: null dans le corps de la demande pour remplacer la mise en cache du navigateur de la demande de l’API Web. Pour plus d’informations, voir Hypertext Transfer Protocol (HTTP/1.1) : requêtes conditionnelles 3.2 : If-None-Match.

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.

En-tête de préférence

Vous pouvez utiliser l’en-tête Préférer avec les valeurs ci-dessous pour spécifier les préférences.

Valeur de préférence	Description
`return=representation`	Pour retourner des données lors des opérations de création (`POST`) ou de mise à jour (`PATCH`) pour les entités, incluez cette préférence . 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. Plus d’information : Créer avec des données retournées & Mettre à jour avec des données retournées
`odata.include-annotations`	Voir Demander des annotations
`odata.maxpagesize`	Utilisez cette préférence pour spécifier le nombre de pages que vous souhaitez renvoyer dans une requête. Pour plus d’informations, voir : Résultats sur la page
`odata.track-changes`	La fonctionnalité de suivi des modifications vous permet de préserver la synchronisation des données efficacement en détectant les données qui ont changé depuis leur extraction initiale ou leur dernière synchronisation. Plus d’informations : Utiliser le suivi des modifications pour synchroniser les données avec les systèmes externes
`respond-async`	Spécifie que la demande doit être traitée de manière asynchrone. Plus d’informations : Opérations en arrière-plan (version préliminaire)

Notes

Plusieurs en-têtes de préférence peuvent être spécifiés à l’aide de valeurs séparées par des virgules ; par exemple : Prefer: respond-async,odata.include-annotations="*"

Demander des annotations

Vous pouvez demander que différentes données d’annotation OData soient renvoyées avec les résultats en utilisant l’en-tête de requête Prefer: odata.include-annotations. Vous pouvez choisir de renvoyer toutes les annotations ou de spécifier des annotations particulières. Le tableau suivant décrit les annotations prises en charge par l’API web Dataverse :

Annotation	Description
`OData.Community.Display.V1.FormattedValue`	Renvoie des valeurs de chaînes mises en forme que vous pouvez utiliser dans votre application. Pour plus d’informations : Valeurs mises en forme
`Microsoft.Dynamics.CRM.associatednavigationproperty` `Microsoft.Dynamics.CRM.lookuplogicalname`	Renvoie des informations sur les colonnes de recherche associées. Informations complémentaires : Données de propriétés de recherche
`Microsoft.Dynamics.CRM.totalrecordcount` `Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded`	Lorsque vous utilisez l’option de requête `$count`, l’annotation `@odata.count` indique le nombre d’enregistrements, mais seuls 5 000 enregistrements peuvent être renvoyés à la fois. Demandez la valeur `Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded` pour obtenir une valeur booléenne qui vous dira si le nombre total d’enregistrements correspondant à la requête dépasse 5 000. Plus d’informations : Compter le nombre de lignes
`Microsoft.Dynamics.CRM.globalmetadataversion`	Cette annotation est renvoyée lors de la demande et vous pouvez la mettre en cache dans votre application. La valeur change lorsqu’un changement de schéma se produit, indiquant que vous devrez peut-être actualiser les données de schéma que votre application a mises en cache. Plus d’informations : Mettre en cache les données du schéma
`Microsoft.PowerApps.CDS.ErrorDetails.OperationStatus` `Microsoft.PowerApps.CDS.ErrorDetails.SubErrorCode` `Microsoft.PowerApps.CDS.HelpLink` `Microsoft.PowerApps.CDS.TraceText` `Microsoft.PowerApps.CDS.InnerError.Message`	Ces annotations fournissent plus de détails lorsque des erreurs sont renvoyées. Plus d′informations : Inclure des détails supplémentaires avec des erreurs

Si vous ne souhaitez que des annotations spécifiques, vous pouvez les demander sous forme de valeurs séparées par des virgules. Vous pouvez également utiliser le caractère ’*’ comme caractère générique. Par exemple, l’en-tête de requête Prefer suivant n’inclut que les valeurs mises en forme et toutes les annotations de détails d’erreurs supplémentaires :

Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue,Microsoft.PowerApps.CDS.ErrorDetails*"

Conseil

Il est courant d’utiliser simplement l’en-tête de requête Prefer: odata.include-annotations="*" pour renvoyer toutes les annotations.

Autres en-têtes

En-tête	active	Description
`CallerObjectId`	ID d’objet utilisateur Microsoft Entra ID	Utilisez cet en-tête pour usurper l’identité d’un autre utilisateur lorsque l’appelant a les privilèges pour le faire. Définir la valeur de l’ID d’objet utilisateur Microsoft Entra ID à qui emprunter l’identité. Ces données sont dans l’attribut Table/entité (SystemUser) de l’utilisateur AzureActiveDirectoryObjectId (colonne). Pour plus d’informations : Emprunter l’identité d’un autre utilisateur à l’aide de l’API Web
`If-Match`	Valeur `Etag` ou `*`	Utilisez cet en-tête pour appliquer la concurrence optimiste afin de vous assurer que vous n’écrasez pas les modifications que quelqu’un d’autre a appliquées sur le serveur depuis que vous avez récupéré un enregistrement. Pour plus d’informations : Appliquer une concurrence optimiste et Si correspondance Vous pouvez également utiliser cet en-tête avec`*` pour empêcher une`PATCH` opération de création d’un enregistrement. Pour plus d’informations : Empêcher la création dans upsert
`If-None-Match`	`null` ou `*`	Cet en-tête doit être utilisé dans toutes les requêtes avec une valeur de`null` comme décrit dans En-têtes HTTP, mais il peut également être utilisé pour prévenir une`POST` opération d’effectuer une mise à jour. Plus d’informations : Empêcher la mise à jour dans upsert et If-None-Match
`MSCRM.SolutionUniqueName`	Nom unique de la solution	Utilisez cet en-tête lorsque vous souhaitez créer un composant de solution et l’associer à une solution non gérée. Pour plus d’informations :Créer et mettre à jour les définitions de table à l’aide de l’API web
`MSCRM.SuppressDuplicateDetection`	`false`	Utilisez cet en-tête avec la valeur `false` pour activer détection des doublons lors de la création ou de la mise à jour d’un enregistrement. Pour plus d’informations : Rechercher des doublons
`MSCRM.BypassCustomPluginExecution`	`true`	Utilisez cet en-tête lorsque vous souhaitez contourner le code de plug-in personnalisé et que l’appelant a le privilège `prvBypassCustomPlugins`. Pour plus d’informations : Contourner la logique métier personnalisée
`Consistency`	`Strong`	Utilisez cet en-tête lorsque vous devez disposer de la version la plus récente d’un élément mis en cache. Les éléments mis en cache incluent : les définitions de métadonnées, les étiquettes, les autorisations utilisateur et les autorisations d’équipe. Par exemple, si vous appliquez une modification à une définition, une étiquette ou une autorisation de métadonnées et que votre code doit utiliser la dernière définition dans les 30 secondes suivant la modification, vous pouvez utiliser cet en-tête pour vous assurer d’obtenir la dernière version. Cela entraîne une légère pénalité de performance, il ne doit donc pas être utilisé tout le temps.

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. La table suivante décrit les codes de statut renvoyés par l’API Web Microsoft Dataverse.

Code	Description	Type
`200 OK`	Code de statut généré lorsque votre opération renvoie des données dans le corps de réponse.	Opération réussie
`201 Created`	Code de statut 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.	Opération réussie
`204 No Content`	Code de statut généré lorsque votre opération aboutit mais ne renvoie pas de données dans le corps de réponse.	Opération réussie
`304 Not Modified`	Code de statut 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`	Code de statut généré pour les types d’erreurs suivants : - `AccessDenied` - `AttributePermissionReadIsMissing` - `AttributePermissionUpdateIsMissingDuringUpdate` - `AttributePrivilegeCreateIsMissing` - `CannotActOnBehalfOfAnotherUser` - `CannotAddOrActonBehalfAnotherUserPrivilege` - `CrmSecurityError` - `InvalidAccessRights` - `PrincipalPrivilegeDenied` - `PrivilegeCreateIsDisabledForOrganization` - `PrivilegeDenied` - `unManagedinvalidprincipal` - `unManagedinvalidprivilegeedepth`	Erreur client
`401 Unauthorized`	Code de statut généré pour les types d’erreurs suivants : - `BadAuthTicket` - `ExpiredAuthTicket` - `InsufficientAuthTicket` - `InvalidAuthTicket` - `InvalidUserAuth` - `MissingCrmAuthenticationToken` - `MissingCrmAuthenticationTokenOrganizationName` - `RequestIsNotAuthenticated` - `TamperedAuthTicket` - `UnauthorizedAccess` - `UnManagedInvalidSecurityPrincipal`	Erreur client
`413 Payload Too Large`	Code de statut lorsque la longueur de la demande est trop grande.	Erreur client
`400 BadRequest`	Code de statut généré lorsqu’un argument n’est pas valide.	Erreur client
`404 Not Found`	Code de statut généré 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 : - `CannotDeleteDueToAssociation` - `InvalidOperation` - `NotSupported`	Erreur client
`412 Precondition Failed`	Code de statut généré pour les types d’erreurs suivants : - `ConcurrencyVersionMismatch` - `DuplicateRecord`	Erreur client
`429 Too Many Requests`	Code de statut généré lorsque les limites de l’API sont dépassées. Plus d’information : Limites de l’API de protection des services	Erreur client
`501 Not Implemented`	Code de statut généré lorsqu’une opération demandée n’est pas implémentée.	Erreur du serveur
`503 Service Unavailable`	Code de statut généré lorsque le service API web n’est pas disponible.	Erreur du serveur

Analyse des erreurs relatives à la réponse

Les détails sur les erreurs sont inclus au format JSON dans la réponse au format suivant.

{  
 "error":{  
  "code": "<This code is not related to the http status code and is frequently empty>",  
  "message": "<A message describing the error>"  
 }  
}

Inclure des détails supplémentaires avec les erreurs

Certaines erreurs peuvent inclure des détails supplémentaires en utilisant des annotations. Lorsqu’une requête comprend l’en-tête Prefer: odata.include-annotations="*", la réponse comprendra toutes les annotations, lesquelles comprennent des détails supplémentaires sur les erreurs et une URL dirigeant vers des conseils spécifiques à l’erreur.

Certains de ces détails peuvent être définis par les développeurs qui rédigent les plug-ins. Par exemple, imaginons que vous avez un plug-in qui génère une erreur en utilisant le constructeur InvalidPluginExecutionException (OperationStatus, Int32, Chaîne). Cela vous permet de transmettre une valeur OperationStatus, un code d’erreur entier personnalisé et un message d’erreur.

Un plug-in simple peut ressembler à ceci :

namespace MyNamespace
{
    public class MyClass : IPlugin
    {
        public void Execute(IServiceProvider serviceProvider)
        {

            // Obtain the tracing service
            ITracingService tracingService =
            (ITracingService)serviceProvider.GetService(typeof(ITracingService));

            tracingService.Trace("Entering MyClass plug-in.");

             try
            {
                throw new InvalidPluginExecutionException(OperationStatus.Canceled, 12345, "Example Error Message.");
            }
            catch (InvalidPluginExecutionException ex)
            {
                tracingService.Trace("StackTrace:");
                tracingService.Trace(ex.StackTrace);
                throw ex;
            }
        }
    }
}

Lorsque ce plug-in est enregistré lors de la création d’un message d’une entité account (compte), et que la requête de création d’un compte inclut la préférence odata.include-annotations="*", la requête et la réponse ressembleront à ceci :

Demande :

POST https://yourorg.api.crm.dynamics.com/api/data/v9.1/accounts HTTP/1.1
Content-Type: application/json;
Prefer: odata.include-annotations="*"
{
    "name":"Example Account"
}

Réponse :

HTTP/1.1 400 Bad Request
Content-Type: application/json; odata.metadata=minimal
{
    "error": {
        "code": "0x80040265",
        "message": "Example Error Message.",
        "@Microsoft.PowerApps.CDS.ErrorDetails.OperationStatus": "1",
        "@Microsoft.PowerApps.CDS.ErrorDetails.SubErrorCode": "12345",
        "@Microsoft.PowerApps.CDS.HelpLink": "http://go.microsoft.com/fwlink/?LinkID=398563&error=Microsoft.Crm.CrmException%3a80040265&client=platform",
        "@Microsoft.PowerApps.CDS.TraceText": "\r\n[MyNamespace: MyNamespace.MyClass ]\r\n[52e2dbb9-85d3-ea11-a812-000d3a122b89: MyNamespace.MyClass : Create of account] \r\n\r\n Entering MyClass plug-in.\r\nStackTrace:\r\n   at MyNamespace.MyClass.Execute(IServiceProvider serviceProvider)\r\n\r\n"
        "@Microsoft.PowerApps.CDS.InnerError.Message": "Example Error Message."
    }
}

La table suivante décrit l’annotation de la réponse.

Annotation et description	active
`@Microsoft.PowerApps.CDS.ErrorDetails.OperationStatus` La valeur du OperationStatus défini par le constructeur InvalidPluginExecutionException (OperationStatus, Int32, Chaîne).	`1`
`@Microsoft.PowerApps.CDS.ErrorDetails.SubErrorCode` La valeur du `SubErrorCode` défini par le constructeur InvalidPluginExecutionException (OperationStatus, Int32, Chaîne).	`12345`
`@Microsoft.PowerApps.CDS.HelpLink` Une URL contenant des informations sur l’erreur qui peut vous rediriger vers des conseils sur la façon de résoudre l’erreur.	`http://go.microsoft.com/fwlink/?LinkID=398563&error=Microsoft.Crm.CrmException%3a80040265&client=platform`
`@Microsoft.PowerApps.CDS.TraceText` Le contenu écrit dans le journal de suivi du plug-in à l’aide de la méthode ITracingService.Trace(String, Object[]). Cette annotation inclut la trace de la pile du plug-in, car l’auteur du plug-in l’a consignée.	`[MyNamespace: MyNamespace.MyClass ]` `[52e2dbb9-85d3-ea11-a812-000d3a122b89: MyNamespace.MyClass :Create of account]` `Entering MyClass plug-in.` `StackTrace:` `at MyNamespace.MyClass.Execute(IServiceProvider serviceProvider)`
`@Microsoft.PowerApps.CDS.InnerError.Message` Le message d’erreur trouvé dans InnerError concernant l’exception. Ce message doit être le même que le message d’erreur, sauf dans certains cas particuliers qui sont réservés à un usage interne.	`Example Error Message.`

Notes

Le @Microsoft.PowerApps.CDS.HelpLink ne garantit pas de fournir des conseils pour chaque erreur. Les conseils peuvent être fournis de manière proactive mais le plus souvent, il sont fournis de manière réactive en fonction de la fréquence d’utilisation du lien. Utilisez le lien. S’il ne fournit aucune indication, votre utilisation du lien nous permet de savoir si les utilisateurs ont besoin de davantage de conseils sur l’erreur. Nous pouvons alors donner la priorité aux directives concernant les erreurs les plus fréquentes. Les ressources vers lesquelles le lien peut vous diriger peuvent être de la documentation, des liens vers des ressources communautaires ou des sites externes.

Si vous ne souhaitez pas recevoir toutes les annotations dans la réponse, vous pouvez spécifier celles que vous souhaitez recevoir. Plutôt que d’utiliser Prefer: odata.include-annotations="*", vous pouvez utiliser ce qui suit pour recevoir uniquement les valeurs formatées pour les opérations qui récupèrent des données et le lien d’assistance en cas d’erreur :Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue,Microsoft.PowerApps.CDS.HelpLink".

Pour pus d’informations, voir : Demander des annotations

Ajouter une variable partagée à partir de l’API web

Vous pouvez définir une valeur de chaîne qui sera disponible pour les plug-ins dans ExecutionContext dans la collection SharedVariables. Pour plus d’informations :

Voir aussi

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).

Composer des demandes HTTP et traiter les erreurs

URL et versions d’API Web

Longueur maximale de l’URL

Compatibilité de version

Méthodes HTTP

En-têtes HTTP

En-tête de préférence

Demander des annotations

Autres en-têtes

Identifier les codes de statut

Analyse des erreurs relatives à la réponse

Inclure des détails supplémentaires avec les erreurs

Ajouter une variable partagée à partir de l’API web

Voir aussi

Commentaires

Ressources supplémentaires