Skrive HTTP-forespørsler og behandle feil for portalenes web-API

Artikkel
02/15/2023

Obs!

Fra og med 12. oktober 2022 er Power Apps-portaler Power Pages. Mer informasjon: Microsoft Power Pages er nå tilgjengelig (blogg)
Vi overfører og slår snart sammen Power Apps-portaldokumentasjonen med Power Pages-dokumentasjonen.

Samhandling med Web-API-en omfatter å skrive HTTP-forespørsler med nødvendige hoder og håndtering av HTTP-svar, inkludert eventuelle feil.

Viktig

Portalversjonen må være 9.3.3.x eller senere for at denne funksjonen skal fungere.

URL-adresse til Web API og versjonskontroll

Konstruere URL-adressen for Web-API-en ved hjelp av formatet i tabellen nedenfor.

Del	Bekrivelse
Protokoll	https://
Primær nettadresse	<portal URL>
Web API-bane	_api
Ressurs	Logisk navn på tabellen du vil bruke

Bruk for eksempel dette formatet når du refererer til en sak:

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

Alle web-API-ressurser følger de respektive portaltabelltillatelsene i sammenheng med webroller.

HTTP-metoder

HTTP-forespørsler kan bruke ulike typer metoder. Portal-Web-API-en støtter imidlertid bare metodene i tabellen nedenfor:

Method	Bruk
Hent	Brukes ved henting av data fra tabeller.
Post	Bruk ved oppretting av oppføringer.
Oppdatering	Brukes når tabeller oppdateres eller utføres i upsert-operasjoner.
Delete	Brukes ved sletting av oppføringer eller individuelle feltverdier for oppføringer.
Put	Bruk i begrensede situasjoner for å oppdatere individuelle oppføringsfelt.

HTTP-topptekster

Web-API-en støtter bare JSON. Hver HTTP-overskrift må inneholde følgende:

En Godta-overskriftsverdi for application/json, selv når ingen svartekst forventes.
Hvis forespørselen inkluderer JSON-data i brødteksten for forespørselen, må du inkludere et Content-Type-hode med verdien application/json.

Den gjeldende OData-versjonen er 4.0, men fremtidige versjoner kan tillates for nye funksjoner. Bruk følgende syntaks for å sikre at det ikke er tvetydighet om OData-versjonen som skal brukes på koden i fremtiden:

Syntaks

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

Eksempel: Wrapper AJAX-funksjon for CSRF-tokenet

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

Eksempel: Hente tabelldata

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

Eksempel: Opprette tabelldata

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

Eksempel: Oppdatere tabelldata

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

Eksempel: Slette tabelldata

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

Identifisere statuskoder

Hvert svar på HTTP-forespørselen inkluderer en statuskode. Statuskoder som returneres av nett-API for portaler, omfatter følgende:

Kode	Description	Type
200 OK	Forvent dette svaret når operasjonen vil returnere data i svarteksten.	Lyktes
204 Uten innhold	Forvent dette svaret når operasjonen lykkes, men ikke returnerer data i svarteksten.	Lyktes
403 Ikke tillatt	Forvent dette svaret for følgende typer feil: AccessDenied AttributePermissionIsMissing TablePermissionWriteIsMissingDuringUpdate TablePermissionCreateIsMissing TablePermissionDeleteIsMissing TablePermissionAppendIsMissngDuringAssociationChange TablePermissionAppendToIsMissingDuringAssociateChange	Klientfeil
401 Uautorisert	Forvent dette svaret for følgende typer feil: MissingPortalRequestVerificationToken MissingPortalSessionCookie	Klientfeil
413 Nyttelast er for stor	Forvent dette svaret når forespørselslengden er for stor.	Klientfeil
400 BadRequest	Forvent dette svaret når et argument er ugyldig. InvalidAttribute	Klientfeil
404 Ikke funnet	Forvent dette svaret når ressursen ikke finnes. Tabellen vises ikke for web-API-en.	Klientfeil
405 Metode ikke tillatt	Denne feilen oppstår for feil metode- og ressurskombinasjoner. Du kan for eksempel ikke bruke DELETE eller PATCH på en tabellsamling. Denne situasjonen kan skje for følgende typer feil: InvalidOperation NotSupported	Klientfeil
501 Ikke implementert	Forvent dette svaret når en forespurt operasjon ikke er implementert.	Serverfeil
503 Tjenesten er utilgjengelig	Forvent dette svaret når Web-API-tjenesten ikke er tilgjengelig.	Serverfeil

Analysere feil fra svaret

Vurder følgende HTTP-eksempelsvar som fremdeles inneholder den indre feilen:

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

Feilkoder

Feilkoder vises i heksadesimal format for alle behandlede scenarier. Følgende tabell viser hver feilkode med det respektive navnet og den tilhørende meldingen.

Feilkode	Navn på feil	Feilmelding
900400FF	NoAttributesForTableCreate	Ingen attributter for handlingen Opprett tabell.
90040100	InvalidAttribute	Attributtet {0} ble ikke funnet for tabellen {1}.
90040101	AttributePermissionIsMissing	Attributtet {0} i tabellen {1} er ikke aktivert for Web-API.
90040102	TablePermissionWriteIsMissingDuringUpdate	Du har ikke tillatelse til å oppdatere en {0}-enhet.
90040103	TablePermissionCreateIsMissing	Du har ikke tillatelse til å opprette en {0}-enhet.
90040104	TablePermissionDeleteIsMissing	Du har ikke tillatelse til å slette {0)-enhet.
90040105	TablePermissionAppendIsMissngDuringAssociationChange	Du har ikke tillatelse til å knytte tabellen til eller oppheve tilknytningen av tabellen {0} med {1}.
90040106	TablePermissionAppendToIsMissingDuringAssociationChange	Du har ikke tillatelse til å knytte tabellen til eller oppheve tilknytningen av tabellen {1} til {0}
90040107	HttpAntiForgeryException	Tokenet for informasjonskapselen for å motvirke forfalskning og token for skjemafelt samsvarer ikke.
90040109	MissingPortalSessionCookie	Et ugyldig øktstoken ble sendt til den utløsende metoden.
9004010C	ResourceDoesNotExists	Finner ikke ressurs for segmentet {0}.
9004010D	CDSError	Det oppstod en CDS-feil.

Svar for ubehandlede feil ved hjelp av HTTP-statuskode 500, returnerer feilen – Det oppstod en uventet feil under behandling av forespørselen.

Se også

Oversikt over nett-API for portaler
Portaler skriver, oppdatere og sletter operasjoner ved hjelp av Web-API
Leseoperasjoner for portaler ved hjelp av web-API