Kurti portalų žiniatinklio API HTTP užklausas ir apdoroti klaidas

2023-02-13

Pastaba

Nuo 2022 m. spalio 12 d. „Power Apps“ portalai tampa „Power Pages“. Daugiau informacijos: „Microsoft Power Pages“ dabar yra visuotinai prieinama (tinklaraštis)
Greitai perkelsime ir suliesime „Power Apps“ portalų dokumentaciją su „Power Pages“ dokumentacija.

Į sąveiką su žiniatinkliu API įtraukiamos HTTP užklausų su reikiamomis antraštėmis kūrimas ir HTTP atsakų apdorojimas, įskaitant klaidas.

Svarbu

Kad veiktų ši funkcija, jūsų portalo versija turi būti 9.3.3.x arba naujesnė.

Žiniatinklio API URL ir versijos kūrimas

Sukurti žiniatinklio API URL naudojant formatą pateiktą tolesnėje lentelėje.

Dalis	Aprašą
Protokolas	https://
Pagrindinis URL	<portal URL>
Žiniatinklio API kelias	_api
Išteklius	Loginis norimos naudoti lentelės pavadinimas

Pavyzdžiui, naudokite šį formatą, kai nurodote į atvejį:

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

Visi žiniatinklio API ištekliai bus naudojami pagal atitinkamas portalo lentelės teises, atsižvelgiant į žiniatinklio vaidmenis.

HTTP metodai

HTTP užklausos gali naudoti skirtingų tipų metodus. Tačiau portalų žiniatinklio API palaiko tik metodus, pateiktus tolesnėje lentelėje:

Būdas	Naudojimas
Gauti „Yammer“	Naudokite nuskaitydami duomenis iš lentelių.
Post	Naudokite kurdami įrašus.
Pataisa	Naudokite lentelių naujinimui ar „upsert” operacijų atlikimui.
Delete	Naudokite naikindami įrašus arba atskiras įrašų laukų reikšmes.
Įdėti	Naudokite tam tikrose situacijose, kad atnaujintumėte atskirus įrašų laukus.

HTTP antraštės

Žiniatinklio API palaiko tik JSON. Į kiekvieną HTTP antraštę turi būti įtraukta:

Priimti antraštės vertė taikymas/json, net jei nesitikima jokio atsako pagrindinio teksto.
Jei užklausos pagrindiniame tekste yra JSON duomenų, turite įtraukti Turinio tipo antraštę su reikšme application/json.

Dabartinė „OData“ versija yra 4.0, bet ateities versijos gali leisti naujas funkcijas. Naudokite pateiktą sintaksę tam, kad užtikrintumėte, jog nėra jokio dviprasmiškumo dėl „OData“ versijos, kuri bus taikoma jūsų kodui ateityje:

Sintaksė

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

Pavyzdys: Vyniotuvo AJAX funkcija CSRF atpažinimo ženklui

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

Pavyzdys: lentelės duomenų nuskaitymas

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

Pavyzdys: Lentelės duomenų kūrimas

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

Pavyzdys: Lentelės duomenų naujinimas

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

Pavyzdys: Lentelės duomenų naikinimas

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

Būsenos kodų identifikavimas

Kiekviename HTTP užklausos atsakyme yra būsenos kodas. Būsenos kodai, grąžinti portalų žiniatinklio API:

Kodas	Aprašą	Tipas
200 GERAI	Tikėkitės šio atsako, kai Jūsų operacija grąžins duomenis atsako pagrindiniame tekste.	Sėkmingai
204 Turinio nėra	Tikėkitės šio atsako, kai Jūsų operacija sėkminga, tačiau negrąžina duomenų atsako pagrindiniame tekste.	Sėkmingai
403 draudžiama	Tikėkitės šio atsako į šiuos klaidų tipus: AccessDenied AttributePermissionIsMissing „TablePermissionWriteIsMissingDuringUpdate” „TablePermissionCreateIsMissing” „TablePermissionDeleteIsMissing” „TablePermissionAppendIsMissngDuringAssociationChange” „TablePermissionAppendToIsMissingDuringAssociateChange”	Kliento klaida
401 neautorizuota	Tikėkitės šio atsako į šiuos klaidų tipus: MissingPortalRequestVerificationToken MissingPortalSessionCookie	Kliento klaida
413 Paketo turinys per didelis	Tikėtis šio atsako, kai užklausos trukmė yra per didelė.	Kliento klaida
400 BlogaUžklausa	Tikėkitės šio atsako, kai argumentas neleistinas. InvalidAttribute	Kliento klaida
404 Nerasta	Tikėkitės šio atsako, kai ištekliai neegzistuoja. Lentelė nėra pateikiama žiniatinklio API.	Kliento klaida
405 Metodas neleidžiamas	Ši klaida įvyksta dėl neteisingo metodo ir išteklių derinių. Pavyzdžiui, negalite naudoti NAIKINTI arba PATAISYTI lentelių rinkiniui. Ši situacija gali nutikti šiems klaidų tipams: InvalidOperation NotSupported	Kliento klaida
501 Neįdiegta	Tikėtis šio atsako, kai tam tikra užklausta operacija neįdiegta.	Serverio klaida
503 paslauga nepasiekiama	Tikėkitės šio atsako, kai žiniatinklio API paslaugos yra neprieinamos.	Serverio klaida

Klaidų analizavimas iš atsako

Apgalvokite tolesnį HTTP atsako pavyzdį, kuris vis dar turi vidinę klaidą:

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

Klaidų kodai

Visų apdorojamų scenarijų klaidų kodai rodomi šešioliktainiu formatu. Tolesnė lentelė pateikia visų klaidų kodus su jų pavadinimais ir pranešimais.

Klaidos kodas	Klaidos pavadinimas	Klaidos pranešimas
900400FF	„NoAttributesForTableCreate”	Lentelės kūrimo veiksmo atributų nėra.
90040100	InvalidAttribute	Nepavyko rasti lentelės {1} atributo {0}.
90040101	AttributePermissionIsMissing	Atributas {0} lentelėje {1} neįjungtas žiniatinklio API.
90040102	„TablePermissionWriteIsMissingDuringUpdate”	Neturite leidimo naujinti {0} objekto.
90040103	„TablePermissionCreateIsMissing”	Neturite leidimo kurti {0} objekto.
90040104	„TablePermissionDeleteIsMissing”	Neturite leidimo naikinti {0) objekto.
90040105	„TablePermissionAppendIsMissngDuringAssociationChange”	Jūs neturite teisės susieti arba atsieti lentelės {0} su {1}.
90040106	„TablePermissionAppendToIsMissingDuringAssociationChange”	Jūs neturite teisės susieti arba atsieti lentelės {1} su {0}
90040107	HttpAntiForgeryException	Apsaugos nuo klastojimo slapuko atpažinimo ženklas ir formos lauko atpažinimo ženklas nesutampa.
90040109	MissingPortalSessionCookie	Neleistinas seanso atpažinimo ženklas buvo perduotas į metimo metodą.
9004010C	ResourceDoesNotExists	Nepavyko rasti '{0}' segmento išteklių.
9004010D	CDSError	Įvyko CDS klaida.

Nesutvarkytų klaidų su HTTP būsenos kodu 500 atsakas grąžins klaidą „Apdorojant užklausą įvyko netikėta klaida“.

Taip pat žr.

Portalų žiniatinklio API apžvalga
Portalų rašymo, naujinimo ir naikinimo operacijos su žiniatinklio API
Portalų skaitymo operacijos naudojant žiniatinklio API