Partage via

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

  • Article

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

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é).