Stel HTTP-verzoeken samen en verwerk fouten voor de web-API van portals

Artikel
15-02-2023

Notitie

Met ingang van 12 oktober 2022 wordt Power Apps-portals hernoemd tot Power Pages. Meer informatie: Microsoft Power Pages is nu algemeen beschikbaar (blog)
We zullen binnenkort de documentatie voor Power Apps-portals migreren en samenvoegen met Power Pages-documentatie.

Interactie met de web-API omvat het opstellen van HTTP-aanvragen met vereiste headers en het afhandelen van HTTP-reacties, inclusief eventuele fouten.

Belangrijk

Uw portalversie moet 9.3.3.x of hoger zijn om deze functie te laten werken.

URL voor web-API en versiebeheer

Construeer de web-API-URL met behulp van de indeling in de volgende tabel.

Onderdeel	Omschrijving
Protocol	https://
Basis-URL	<portal URL>
Pad van web-API	_api
Bron	Logische naam van de tabel die u wilt gebruiken

Gebruik deze indeling bijvoorbeeld bij het verwijzen naar een case:

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

Alle web-API-resources volgen de respectieve portaltabelmachtigingen in verband met webrollen.

HTTP-methoden

HTTP-aanvragen kunnen verschillende soorten methoden gebruiken. De web-API van portals ondersteunt echter alleen de methoden in de volgende tabel:

Method	Gebruik
Yammer ophalen	Gebruiken bij het ophalen van gegevens uit tabellen.
Post	Te gebruiken bij het maken van records.
Patch	Te gebruiken bij het bijwerken van tabellen of het uitvoeren van upsert-bewerkingen.
Delete	Te gebruiken bij het verwijderen van records of individuele veldwaarden van records.
Put	Te gebruiken in beperkte situaties om afzonderlijke velden van records bij te werken.

HTTP-kopteksten

De web-API ondersteunt alleen JSON. Elke HTTP-header moet het volgende bevatten:

Een koptekstwaarde Accepteren van application/json, zelfs als er geen antwoordtekst wordt verwacht.
Als de aanvraag JSON-gegevens in de aanvraagbody bevat, moet u een Content-Type-header met een waarde van application/json opnemen.

De huidige OData-versie is 4.0, maar toekomstige versies kunnen nieuwe mogelijkheden bieden. Gebruik de volgende syntaxis om ervoor te zorgen dat er geen onduidelijkheid bestaat over de OData-versie die in de toekomst op uw code wordt toegepast:

Syntaxis

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

Voorbeeld: Wrapper AJAX-functie voor het CSRF-token

    (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)

Voorbeeld: Tabelgegevens ophalen

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

Voorbeeld: tabelgegevens maken

    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"))
        }
    });

Voorbeeld: tabelgegevens bijwerken

        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);
        }
    });

Voorbeeld: tabelgegevens verwijderen

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

Statuscodes identificeren

Elke respons op een HTTP-aanvraag bevat een statuscode. Hierna volgen statuscodes die door de web-API voor portals worden geretourneerd:

Code	Description	Type
200 OK	U kunt deze respons verwachten als uw bewerking gegevens retourneert in de responstekst.	Succes
204 Geen inhoud	U kunt deze respons verwachten als uw bewerking is geslaagd, maar geen gegevens retourneert in de responstekst.	Succes
403 Verboden	U kunt deze respons verwachten voor de volgende fouttypen: AccessDenied AttributePermissionIsMissing TablePermissionWriteIsMissingDuringUpdate TablePermissionCreateIsMissing TablePermissionDeleteIsMissing TablePermissionAppendIsMissngDuringAssociationChange TablePermissionAppendToIsMissingDuringAssociateChange	Clientfout
401 Onbevoegd	U kunt deze respons verwachten voor de volgende fouttypen: MissingPortalRequestVerificationToken MissingPortalSessionCookie	Clientfout
413 Nettolading te groot	Verwacht deze respons als de aanvraaglengte te groot is.	Clientfout
400 Onjuiste aanvraag	Verwacht deze respons als een argument ongeldig is. InvalidAttribute	Clientfout
404 Niet gevonden	Verwacht deze respons als de resource niet bestaat. De tabel wordt niet weergegeven voor de web-API.	Clientfout
405 Methode niet toegestaan	Deze fout treedt op voor onjuiste combinaties van methode en resource. U kunt bijvoorbeeld niet DELETE of PATCH gebruiken voor een verzameling van tabellen. Deze situatie op optreden bij de volgende fouttypen: InvalidOperation NotSupported	Clientfout
501 Niet geïmplementeerd	Verwacht deze respons als een aangevraagde bewerking niet is geïmplementeerd.	Serverfout.
503 Service niet beschikbaar	Verwacht deze respons als de web-API-service niet beschikbaar is.	Serverfout.

Parseerfouten van de respons

Bekijk de volgende voorbeeld-HTTP-respons die nog steeds de interne fout bevat:

{
  "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.."
      }
    }
  }

Foutcodes

Foutcodes worden weergegeven in hexadecimale indeling voor alle behandelde scenario's. In de volgende tabel wordt elke foutcode met de bijbehorende naam en bericht weergegeven.

Foutcode	Foutnaam	Foutbericht
900400FF	NoAttributesForTableCreate	Geen kenmerken voor actie Tabel maken.
90040100	InvalidAttribute	Kenmerk {0} is niet gevonden voor tabel {1}.
90040101	AttributePermissionIsMissing	Kenmerk {0} in tabel {1} is niet ingeschakeld voor web-API.
90040102	TablePermissionWriteIsMissingDuringUpdate	U bent niet gemachtigd om entiteit {0} bij te werken.
90040103	TablePermissionCreateIsMissing	U bent niet gemachtigd entiteit {0} te maken.
90040104	TablePermissionDeleteIsMissing	U bent niet gemachtigd entiteit {0) te verwijderen.
90040105	TablePermissionAppendIsMissngDuringAssociationChange	U bent niet gemachtigd om tabel {0} te koppelen aan of los te koppelen van {1}.
90040106	TablePermissionAppendToIsMissingDuringAssociationChange	U bent niet gemachtigd om tabel {1} te koppelen aan of los te koppelen van {0}
90040107	HttpAntiForgeryException	Het cookietoken tegen vervalsing en het formulierveldtoken komen niet overeen.
90040109	MissingPortalSessionCookie	Er is een ongeldig sessietoken doorgegeven aan de uitvoeringsmethode.
9004010C	ResourceDoesNotExists	Resource niet gevonden voor segment '{0}'.
9004010D	CDSError	CDS-fout opgetreden.

Respons voor niet-verwerkte fouten met HTTP-statuscode 500 retourneert de fout 'Er is een onverwachte fout opgetreden bij het verwerken van de aanvraag'.

Zie ook

Overzicht van Web-API voor portals
Bewerkingen voor schrijven, bewerken en verwijderen van portals met de web-API
Portals-leesbewerkingen met behulp van de web API