Composer des demandes HTTP et traiter les erreurs

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

1. Connectez-vous à Power Apps, puis sélectionnez votre environnement dans le coin supérieur droit.

2. 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 du point de terminaison de l'API Web. Pour plus d’informations, consultez Afficher les ressources du développeur.

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

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

Protocole + Nom + Région + URL + de baseChemin d’accès de + l’API webVersion + Ressource.

Longueur maximale de l’URL

La longueur maximale de l’URL acceptée est de 32 Ko (32 768 caractères). Cette longueur convient à 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 longs, tels que des 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.

Longueur maximale du segment OData

La longueur maximale d’un segment individuel dans une requête OData est de 260 caractères. Si un segment unique de la requête OData est de plus de 260 caractères, la requête retourne 400 Bad Request - Invalid URL. Le segment est la partie « Ressource » de l’URL et inclut tous les caractères nécessaires pour décrire le point de terminaison et tous les paramètres inline.

Par exemple, si la requête est api/data/v9.2/MyApi(MyParameter='longvalue'), MyApi(MyParameter='longvalue') est le segment qui ne peut pas dépasser 260 caractères. Utilisez toujours des alias de paramètre avec des fonctions OData. Par exemple, la composition de votre fonction comme /api/data/v9.2/MyApi(MyParameter=@alias)?@alias='longvalue' raccourcit le segment à seulement MyApi(MyParameter=@alias). En savoir plus sur l’utilisation d’alias de paramètres avec des fonctions d’API web.

Compatibilité de version

Cette version introduit des fonctionnalités que les versions précédentes ne prennent pas en charge. Les versions mineures suivantes peuvent fournir davantage de fonctionnalités que les versions mineures antérieures ne prennent pas en charge. Votre code écrit pour v9.0 continue de fonctionner dans les futures versions lorsque vous référencez v9.0 dans votre URL.

À mesure que de nouvelles fonctionnalités sont introduites, elles peuvent entrer en conflit avec les versions antérieures. Ces changements disruptifs sont nécessaires pour améliorer le service. La plupart du temps, les fonctionnalités restent les mêmes entre les versions, mais n'en soyez pas sûr que c'est toujours le cas.

Méthodes HTTP

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

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. L’API web retourne toute erreur dans la réponse en tant que JSON. Bien que votre code fonctionne même si cet en-tête n’est pas inclus, incluez-le comme meilleure pratique.

La version actuelle d’OData est 4.0, mais les futures versions peuvent introduire de nouvelles fonctionnalités. Pour vous assurer qu’il n’existe aucune ambiguïté concernant la version OData qui s’applique à votre code, incluez toujours une instruction explicite de la version OData actuelle et de la version maximale. Utilisez les en-têtes OData-Version et OData-MaxVersion définis sur la valeur 4.0.

Les requêtes qui étendent les propriétés de navigation à valeur de collection peuvent retourner des données mises en cache pour ces propriétés qui ne reflètent pas les 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, consultez Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests 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êtes Prefer

Utilisez l’en-tête Prefer avec les valeurs suivantes pour spécifier les préférences.

Demander des annotations

Vous pouvez demander différentes données d'annotation OData à être renvoyées avec les résultats à l'aide de l'en-tête de requête Prefer: odata.include-annotations. Vous pouvez choisir de retourner toutes les annotations ou de spécifier des annotations spécifiques. Le tableau suivant décrit les annotations prises en charge par l’API web Dataverse :

Pour demander des annotations spécifiques, incluez-les 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 suivant Prefer inclut uniquement les valeurs mises en forme et toutes les annotations de détails d’erreur supplémentaires :

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

Autres en-têtes

Lorsque vous exécutez des opérations par lots, vous devez appliquer plusieurs en-têtes différents dans la demande et pour chaque partie envoyée dans le corps de la requête. 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.

Analyse des erreurs relatives à la réponse

La réponse inclut des détails sur les erreurs au format JSON dans le 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 incluent plus de détails par le biais d’annotations. Lorsqu’une demande inclut l’en-tête Prefer: odata.include-annotations="*" , la réponse inclut toutes les annotations qui contiennent plus de détails sur les erreurs et une URL qui peut vous diriger vers des conseils spécifiques pour l’erreur.

Les développeurs écrivant des plug-ins peuvent définir certains de ces détails. Par exemple, supposons que vous disposez d’un plug-in qui génère une erreur à l’aide du constructeur InvalidPluginExecutionException(OperationStatus, Int32, String). Ce constructeur accepte une OperationStatus valeur, 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 vous enregistrez ce module sur le message de création d'une entité de compte et que la requête de création d’un compte inclut la odata.include-annotations="*" préférence, la requête et la réponse ressemblent à l’exemple suivant :

Demande :

POST https://yourorg.api.crm.dynamics.com/api/data/v9.2/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.

Si vous ne souhaitez pas recevoir toutes les annotations dans la réponse, vous pouvez spécifier les annotations que vous souhaitez retourner. Au lieu d’utiliser Prefer: odata.include-annotations="*", utilisez la valeur suivante pour recevoir uniquement des valeurs mises en forme pour les opérations qui récupèrent des données et le lien d’aide si une erreur se produit : 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 la collection ExecutionContextSharedVariables. Pour en savoir plus, consultez :

• Ajouter une variable partagée au contexte d’exécution du plug-in
• Variables partagées

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 ligne de table à l’aide de l’API web
Récupérer une ligne de table à l’aide de l’API web
Mettre à jour et supprimer des lignes de table à l’aide de l’API web
Associer et dissocier des lignes de tables à l’aide de l’API web
Utiliser des fonctions API Web
Utiliser des actions de l'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
Effectuez des opérations conditionnelles à l’aide de l’API web.