Rédiger des requêtes HTTP et gérer les erreurs pour l’API Web des portails

Article
03/15/2023

Notes

À compter du 12 octobre 2022, le portail Power Apps devient Power Pages. Plus d’informations : Microsoft Power Pages est maintenant généralement disponible (blog)
Nous allons bientôt migrer et fusionner la documentation des portails Power Apps avec la documentation de Power Pages.

L’interaction avec l’API Web comprend la composition de requêtes HTTP avec les en-têtes requis et la gestion des réponses HTTP, y compris les erreurs.

Important

La version de votre portail doit être 9.3.3.x ou ultérieure pour que cette fonctionnalité soit opérationnelle.

URL et versions d’API Web

Construisez l’URL de l’API web en utilisant le format du tableau suivant.

Partie	Description
Protocole	https://
URL de base	<portal URL>
Chemin d’accès de l’API Web	_api
Ressource	Nom logique de la table à utiliser

Par exemple, utilisez ce format lorsque vous référez un cas :

https://contoso.powerappsportals.com/_api/case

Toutes les ressources de l’API Web suivront les autorisations de table de portail dans le contexte des rôles Web.

Méthodes HTTP

Les requêtes HTTP peuvent utiliser différents types de méthodes. Cependant, l’API web des portails ne prend en charge que les méthodes du tableau suivant :

Method	Utilisation
Obtenir	À utiliser lors de la récupération de données à partir de tables.
Après	À utiliser lors de la création d’enregistrements.
Correctif logiciel	À utiliser lors de la mise à jour de tables ou l’exécution d’opérations de type upsert.
Delete	À utiliser lors de la suppression d’enregistrements ou de valeurs de champ individuelles d’enregistrements.
Put	À utiliser dans des situations limitées pour mettre à jour des champs d’enregistrements individuels.

En-têtes HTTP

L’API web prend uniquement en charge JSON. Chaque en-tête HTTP doit inclure :

Une valeur d’en-tête Accept de application/json, même lorsqu’aucun corps de réponse n’est prévu.
Si le corps de la demande inclut des données JSON, vous devez inclure un en-tête Content-Type contenant une valeur application/json.

La version OData actuelle est la 4.0, mais les futures versions pourraient autoriser de nouvelles fonctionnalités. Utilisez la syntaxe suivante pour vous assurer qu’il n’y a aucune ambiguïté sur la version OData qui sera appliquée à votre code à l’avenir :

Syntaxe

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

Exemple : fonction Wrapper AJAX pour le jeton CSRF

    (function(webapi, $){
        function safeAjax(ajaxOptions) {
            var deferredAjax = $.Deferred();
    
            shell.getTokenDeferred().done(function (token) {
                // add headers for ajax
                if (!ajaxOptions.headers) {
                    $.extend(ajaxOptions, {
                        headers: {
                            "__RequestVerificationToken": token
                        }
                    }); 
                } else {
                    ajaxOptions.headers["__RequestVerificationToken"] = token;
                }
                $.ajax(ajaxOptions)
                    .done(function(data, textStatus, jqXHR) {
                        validateLoginSession(data, textStatus, jqXHR, deferredAjax.resolve);
                    }).fail(deferredAjax.reject); //ajax
            }).fail(function () {
                deferredAjax.rejectWith(this, arguments); // on token failure, pass the token ajax and args
            });
    
            return deferredAjax.promise();  
        }
        webapi.safeAjax = safeAjax;
})(window.webapi = window.webapi || {}, jQuery)

Exemple : récupérer les données d’un tableau

    webapi.safeAjax({
                type: "GET",
                url: "/_api/contacts?$select=firstname,lastname",
                contentType: "application/json",
                success: function (res) {
                        console.log(res);
                }
    });

Exemple : Créer des données de table

    webapi.safeAjax({
        type: "POST",
        url: "/_api/accounts",
        contentType: "application/json",
        data: JSON.stringify({
            "name": "Sample Account"
        }),
        success: function (res, status, xhr) {
            console.log("entityID: "+ xhr.getResponseHeader("entityid"))
        }
    });

Exemple : mettre à jour des données de table

        webapi.safeAjax({
        type: "PATCH",
        url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
        contentType: "application/json",
        data: JSON.stringify({
            "name": "Sample Account - Updated"
        }),
        success: function (res) {
            console.log(res);
        }
    });

Exemple : Supprimer des données de table

        webapi.safeAjax({
        type: "DELETE",
        url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
        contentType: "application/json",
        success: function (res) {
            console.log(res);
        }
    });

Identifier les codes de statut

Chaque réponse de requête HTTP comprend un code de statut. Les codes de statut sont renvoyés par l’API Web des portails 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
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
403 Interdit	Est généré pour les types d’erreurs suivants : AccessDenied AttributePermissionIsMissing TablePermissionWriteIsMissingDuringUpdate TablePermissionCreateIsMissing TablePermissionDeleteIsMissing TablePermissionAppendIsMissngDuringAssociationChange TablePermissionAppendToIsMissingDuringAssociateChange	Erreur du client
401 Non autorisé	Est généré pour les types d’erreurs suivants : MissingPortalRequestVerificationToken MissingPortalSessionCookie	Erreur du client
413 Payload Too Large	Générée lorsque la longueur de la demande est trop grande.	Erreur du client
400 BadRequest	Générée lorsqu’un argument n’est pas valide. InvalidAttribute	Erreur du client
404 Not Found	Réponse générée lorsque la ressource n’existe pas. La table n’est pas exposée pour l’API Web.	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 de tables. Cette situation est générée pour les types d’erreurs suivants : InvalidOperation NotSupported	Erreur du client
501 Not Implemented	Générée lorsqu’une opération demandée n’est pas implémentée.	Erreur de serveur
503 Service indisponible	Réponse générée lorsque le service API web n’est pas disponible.	Erreur de serveur

Analyse des erreurs relatives à la réponse

Considérez l’exemple de réponse HTTP suivant qui inclut toujours l’erreur interne :

{
  "error":{
    "code": "This code is not related to the http status code and is frequently empty",
    "message": "A message describing the error",
    "cdscode": "Dataverse error code",
    "innererror": {
        "code": "800xxxx",
        "message": "A message describing the error. This is frequently the same as the outer message.."
      }
    }
  }

Codes d’erreur

Les codes d’erreur sont affichés au format hexadécimal pour tous les scénarios traités. Le tableau suivant répertorie chaque code d’erreur avec son nom et son message respectifs.

Code de l’erreur	Nom de l’erreur	Message d’erreur
900400FF	NoAttributesForTableCreate	Aucun attribut pour l’action Créer une table.
90040100	InvalidAttribute	L’attribut {0} est introuvable pour la table {1}.
90040101	AttributePermissionIsMissing	L’attribut {0} de la table {1} n’est pas activé pour l’API Web.
90040102	TablePermissionWriteIsMissingDuringUpdate	Vous n’êtes pas autorisé à mettre à jour l’entité {0}.
90040103	TablePermissionCreateIsMissing	Vous n’êtes pas autorisé à créer une entité {0}.
90040104	TablePermissionDeleteIsMissing	Vous n’êtes pas autorisé à supprimer l’entité {0).
90040105	TablePermissionAppendIsMissngDuringAssociationChange	Vous n’êtes pas autorisé à associer ou dissocier la table {0} avec {1}.
90040106	TablePermissionAppendToIsMissingDuringAssociationChange	Vous n’êtes pas autorisé à associer ou dissocier la table {1} avec {0}
90040107	HttpAntiForgeryException	Le jeton de cookie anti-falsification et le jeton de champ de formulaire ne correspondent pas.
90040109	MissingPortalSessionCookie	Un jeton de session non valide a été transmis dans la méthode de renvoi.
9004010C	ResourceDoesNotExists	Ressource introuvable pour le segment {0}.
9004010D	CDSError	Une erreur CDS s’est produite.

La réponse aux erreurs non traitées avec le code d’état HTTP 500 renvoie l’erreur suivante : « Une erreur inattendue s’est produite lors du traitement de la demande ».

Voir aussi

Vue d’ensemble des portails Web API
Opérations d’écriture, de mise à jour et de suppression à l’aide de l’API Web
Les portails lisent les opérations à l’aide de l’API Web