Zostavte požiadavky HTTP a spracujte chyby pre webové rozhranie API portálov

Článok
02/14/2023

Poznámka

S účinnosťou od 12. októbra 2022 sa portály Power Apps nazývajú Power Pages. Ďalšie informácie: Služba Microsoft Power Pages je teraz všeobecne dostupná (blog)
Čoskoro vykonáme migráciu a zlúčenie dokumentácie k portálom Power Apps s dokumentáciou k službe Power Pages.

Interakcia s webovým rozhraním API zahŕňa zostavenie požiadaviek HTTP s požadovanými hlavičkami a spracovanie odpovedí HTTP vrátane akýchkoľvek chýb.

Dôležité

Aby táto funkcia fungovala, musí byť vaša verzia portálu 9.3.3.x alebo novšia.

URL a verzie webového rozhrania API

Zostavte adresu URL webového rozhrania API pomocou formátu v nasledujúcej tabuľke.

Časť	Description
Protokol	https://
Základná URL adresa	<portal URL>
Cesta webového rozhrania API	_api
Prostriedok	Logický názov tabuľky, ktorú chcete použiť

Tento formát použite napríklad pri postúpení prípadu:

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

Všetky zdroje webového rozhrania API sa budú riadiť príslušnými povoleniami portálovej tabuľky v kontexte s webovými rolami.

Metódy HTTP

Požiadavky HTTP môžu používať rôzne druhy metód. Webové rozhranie API portálov však podporuje iba metódy v nasledujúcej tabuľke:

Method	Využitie
Získať	Používa sa pri získavaní údajov z tabuliek.
Potom	Použite pri vytváraní záznamov.
Oprava	Použite pri aktualizácii tabuliek alebo pri operáciách upsert.
Delete	Používa sa pri odstraňovaní záznamov alebo jednotlivých hodnôt polí záznamov.
Put	Použite v obmedzených situáciách na aktualizáciu jednotlivých polí záznamov.

Hlavičky protokolu HTTP

Webové rozhranie API podporuje iba JSON. Každá hlavička HTTP musí obsahovať:

Hodnota hlavičky Súhlasiť application/json aj v prípade, ak sa neočakáva žiadny text odpovede.
Ak žiadosť obsahuje v tele žiadosti údaje JSON, musíte uviesť hlavičku Content-Type s hodnotou application/json.

Aktuálna verzia OData je 4.0, ale budúce verzie môžu umožňovať nové funkcie. Pomocou nasledujúcej syntaxe zaistíte, že o verzii OData, ktorá sa v budúcnosti použije na váš kód, nebudú nejasnosti.

Syntax

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

Príklad: Funkcia Wrapper AJAX pre token 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)

Príklad: Získanie údajov tabuľky

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

Príklad: Vytvorenie údajov tabuľky

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

Príklad: Aktualizácia údajov tabuľky

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

Príklad: Odstránenie údajov tabuľky

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

Identifikujte stavové kódy

Každá odpoveď na požiadavku HTTP obsahuje stavový kód. Stavové kódy vrátené webovým rozhraním API portálov zahŕňajú nasledujúce:

Kód	Description	Type
200 OK	Očakávajte túto odpoveď, keď vaša operácia vráti údaje v texte odpovede.	Úspech
204 No Content	Očakávajte túto odpoveď, keď vaša operácia bude úspešná, no nevráti údaje v texte odpovede.	Úspech
403 Zakázané	Očakávajte túto odpoveď v prípade nasledujúcich typov chýb: AccessDenied AttributePermissionIsMissing TablePermissionWriteIsMissingDuringUpdate TablePermissionCreateIsMissing TablePermissionDeleteIsMissing TablePermissionAppendIsMissngDuringAssociationChange TablePermissionAppendToIsMissingDuringAssociateChange	Chyba klienta
401 Neoprávnené	Očakávajte túto odpoveď v prípade nasledujúcich typov chýb: MissingPortalRequestVerificationToken MissingPortalSessionCookie	Chyba klienta
413 Payload Too Large	Očakávajte túto odpoveď, keď je dĺžka žiadosti príliš veľká.	Chyba klienta
400 BadRequest	Očakávajte túto odpoveď, keď je argument neplatný. InvalidAttribute	Chyba klienta
404 Not Found	Očakávajte túto odpoveď, keď zdroj neexistuje. Tabuľka nie je sprístupnená pre webové rozhranie API.	Chyba klienta
405 Method Not Allowed	Táto chyba sa vyskytuje pre nesprávne kombinácie metód a prostriedkov. Napríklad nemôžete použiť DELETE ani PATCH na súbor tabuliek. K tejto situácii môže dôjsť z dôvodu nasledujúcich typov chýb: InvalidOperation NotSupported	Chyba klienta
501 Not Implemented	Očakávajte túto odpoveď, keď nie je implementovaná požadovaná operácia.	Chyba servera
503 Služba je nedostupná	Očakávajte túto odpoveď, keď služba webového rozhrania API nie je k dispozícii.	Chyba servera

Analyzujte chyby z odpovede

Zoberme si nasledujúci príklad odpovede HTTP, ktorá stále obsahuje vnútornú chybu:

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

Kódy chýb

Kódy chýb sa zobrazujú v hexadecimálnom formáte pre všetky spracované scenáre. V nasledujúcej tabuľke je uvedený každý chybový kód s príslušným menom a správou.

Kód chyby	Chybový názov	Chybové hlásenie
900400FF	NoAttributesForTableCreate	Žiadne atribúty pre akciu Vytvoriť tabuľku.
90040100	InvalidAttribute	Nemožno nájsť atribút {0} pre tabuľku {1}.
90040101	AttributePermissionIsMissing	Atribút {0} v tabuľke {1} nie je povolený pre webové rozhranie API.
90040102	TablePermissionWriteIsMissingDuringUpdate	Nemáte povolenie na aktualizáciu entity {0}.
90040103	TablePermissionCreateIsMissing	Nemáte povolenie na vytvorenie entity {0}.
90040104	TablePermissionDeleteIsMissing	Nemáte povolenie na odstránenie entity {0).
90040105	TablePermissionAppendIsMissngDuringAssociationChange	Nemáte povolenie na priradenie ani zrušenie priradenia tabuľky {0} s {1}.
90040106	TablePermissionAppendToIsMissingDuringAssociationChange	Nemáte povolenie na priradenie ani zrušenie priradenia tabuľky {1} s {0}
90040107	HttpAntiForgeryException	Token súboru cookie a token poľa formulára proti falšovaniu sa nezhodujú.
90040109	MissingPortalSessionCookie	Do metódy hádzania bol odovzdaný neplatný token relácie.
9004010C	ResourceDoesNotExists	Pre segment {0} sa nenašiel zdroj.
9004010D	CDSError	Vyskytla sa chyba služby CDS.

Odpoveď na nespracované chyby pomocou stavového kódu HTTP 500 vráti chybu – „Pri spracovaní žiadosti sa vyskytla neočakávaná chyba”.

Pozrite si tiež

Prehľad webového rozhrania API portálov
Operácie zápisu, aktualizácie a odstránenia portálov pomocou webového rozhrania API
Operácie čítania portálov pomocou webového rozhrania API