Vytvořte požadavky HTTP a zpracujte chyby pro webové rozhraní API portálů

Článek
02/15/2023

Poznámka

S účinností od 12. října 2022 jsou portály Power Apps Power Pages. Další informace: Služba Microsoft Power Pages je nyní obecně dostupná (blog)
Zanedlouho migrujeme a sloučíme dokumentaci k portálům Power Apps s dokumentací k Power Pages.

Interakce s webovým rozhraním API zahrnuje vytváření požadavků HTTP s požadovanými záhlavími a zpracovávání odpovědí HTTP, včetně veškerých chyb.

Důležité

Aby tato funkce fungovala, musí být vaše verze portálu 9.3.3.x nebo novější.

Adresa URL webového rozhraní API a správa verzí

Vytvořte adresu URL webového rozhraní API pomocí formátu v následující tabulce.

Část	Description
Protokol	https://
Základní adresa URL	<portal URL>
Cesta webového rozhraní API	_api
Resource	Logický název tabulky, kterou chcete použít

Například použijte tento formát, když odkazujete na případ:

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

Všechny prostředky webového rozhraní API se budou řídit příslušnými oprávněními tabulky portálu v kontextu s webovými rolemi.

Metody HTTP

Požadavky HTTP mohou používat různé druhy metod. Webová rozhraní API portálů však podporuji pouze metody v následující tabulce:

Method	Využití
Získat	Použijte při načítání dat z tabulek.
Zveřejnit	Použijte při vytváření záznamů.
Oprava	Použijte při aktualizaci tabulek nebo při operacích upsert.
Odstranění	Použijte při odstraňování záznamů nebo jednotlivých hodnot polí záznamů.
Put	Použijte v omezených situacích k aktualizaci jednotlivých polí záznamů.

Záhlaví HTTP

Webové rozhraní API podporuje pouze JSON. Každé záhlaví HTTP musí obsahovat:

Hodnota záhlaví Přijmout application/json, i když se neočekává žádné tělo odpovědi.
Pokud text požadavku obsahuje data JSON, musíte zahrnout záhlaví Content-Type s hodnotou application/json.

Aktuální verze OData je 4.0, ale budoucí verze mohou umožňovat nové funkce. Použijte následující syntaxi, abyste zajistili, že nebudou žádné nejasnosti ohledně verze OData, která bude v budoucnu použita na váš kód:

Syntaxe

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

Příklad: Obálková funkce AJAX pro 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)

Příklad: Načtení dat tabulky

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

Příklad: Vytvoření dat tabulky

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

Příklad: Aktualizace dat tabulky

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

Příklad: Odstranění dat tabulky

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

Vysvětlení stavových kódů

Každá odpověď na požadavek HTTP obsahuje stavový kód. Stavové kódy vrácené webovým rozhraním API portálů zahrnují následující:

Kód	Description	Type
200 OK	Očekávejte tuto odpověď, když vaše operace vrátí data v textu odpovědi.	Úspěch
204 Chybí obsah	Očekávejte tuto odpověď, když vaše operace uspěje, ale nevrátí data v textu odpovědi.	Úspěch
403 Zakázáno	Očekávejte tuto odpověď u následujících typů chyb: AccessDenied AttributePermissionIsMissing TablePermissionWriteIsMissingDuringUpdate TablePermissionCreateIsMissing TablePermissionDeleteIsMissing TablePermissionAppendIsMissngDuringAssociationChange TablePermissionAppendToIsMissingDuringAssociateChange	Chyba klienta
401 Neautorizováno	Očekávejte tuto odpověď u následujících typů chyb: MissingPortalRequestVerificationToken MissingPortalSessionCookie	Chyba klienta
413 Příliš velká datová část	Tuto odpověď očekávejte, pokud je délka požadavku příliš velká.	Chyba klienta
400 Nepsrávný požadavek	Pokud je argument neplatný, očekávejte tuto odpověď. InvalidAttribute	Chyba klienta
404 Nenalezeno	Pokud zdroj neexistuje, očekávejte tuto odpověď. Tabulka není vystavena pro webové rozhraní API.	Chyba klienta
405 Nepovolená metoda	K této chybě dochází při nesprávné kombinaci metod a prostředků. Například nemůžete použít DELETE nebo PATCH na kolekci tabulek. Tato situace může nastat u následujících typů chyb: InvalidOperation NotSupported	Chyba klienta
501 Není implementováno	Tuto odpověď očekávejte, pokud není implementována požadovaná operace.	Chyba serveru
503 Nedostupná služba	Tuto odpověď očekávejte, když služba webového rozhraní API není k dispozici.	Chyba serveru

Analýza chyb z odpovědi

Zvažte následující příklad odpovědi HTTP, která stále obsahuje vnitřní 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 chyb

Kódy chyb jsou zobrazeny v hexadecimálním formátu pro všechny zpracované scénáře. V následující tabulce je uveden každý chybový kód s příslušným názvem a zprávou.

Kód chyby	Název chyby	Chybová zpráva
900400FF	NoAttributesForTableCreate	Žádné atributy pro akci Vytvořit tabulku
90040100	InvalidAttribute	Atribut {0} tabulky {1} nelze najít.
90040101	AttributePermissionIsMissing	Atribut {0} v tabulce {1} nemá povolené webové rozhraní API.
90040102	TablePermissionWriteIsMissingDuringUpdate	Nemáte oprávnění k aktualizaci entity {0}.
90040103	TablePermissionCreateIsMissing	Nemáte oprávnění k vytvoření entity {0}.
90040104	TablePermissionDeleteIsMissing	Nemáte oprávnění k odstranění entity {0).
90040105	TablePermissionAppendIsMissngDuringAssociationChange	Nemáte oprávnění k přidružení nebo zrušení přidružení tabulky {0} s {1}.
90040106	TablePermissionAppendToIsMissingDuringAssociationChange	Nemáte oprávnění k přidružení nebo zrušení přidružení tabulky {1} k {0}.
90040107	HttpAntiForgeryException	Token souboru cookie proti padělání a token pole formuláře se neshodují.
90040109	MissingPortalSessionCookie	Do metody, která vyvolala chybu, byl předán neplatný token relace.
9004010C	ResourceDoesNotExists	Pro segment {0} nebyl nalezen zdroj.
9004010D	CDSError	Došlo k chybě CDS.

Odpověď na neošetřené chyby se stavovým kódem HTTP 500 vrátí chybu „Při zpracování požadavku došlo k neočekávané chybě“.

Viz také

Přehled webového rozhraní API portálů
Operace portálu pro zápis, aktualizaci a odstranění entit pomocí webového rozhraní API
Operace čtení pomocí webového rozhraní API portálů