HTTP-kérelmek megírása és a portálok webes API-ját érintő hibák kezelése

2023-02-13

Megjegyzés

október 12-től a Power Apps-portálok a Power Pages nevet kapják. További információ: A Microsoft Power Pages már általánosan elérhető (blog)
A Power Apps-portál dokumentációját hamarosan áttelepítjük és egyesítjük a Power Pages dokumentációjával.

A webes API-val folytatott kommunikáció magában foglalja a szükséges fejlécekkel rendelkező HTTP-kérések létrehozását és a HTTP-válaszok kezelését, beleértve az esetleges hibákat is.

Fontos

A portálverziónak 9.3.3.x-nek vagy újabbnak kell lennie, hogy ez a funkció működjön.

webes API URL-címe és verziószámozás

A webes API URL-jének összeállítása az alábbi táblázat formátumának használatával.

Rész	Description
Protokoll	https://
Alap URL	<portal URL>
Webes API elérési útja	_api
Erőforrás	A használni kívánt tábla logikai neve

Ezt a formátumot például akkor használja, ha egy esetre hivatkozik:

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

Minden webes API-erőforrások a megfelelő portál táblaengedélyeket követi a webes szerepkörök környezetében.

HTTP-módszerek

A HTTP-kérések többféle típusú módszert is használhatnak. A portálok webes API azonban csak a következő táblában szereplő metódusokat támogatja:

Method	Felhasználás
Get	Használja, amikor adatokat kér le a táblákból.
Post	Használja rekordok létrehozásakor.
Javítás	Táblafrissítéskor vagy upsert-műveletek végrehajtásához használható.
Delete	Akkor használja, ha rekordokat vagy rekordok egyes mezőértékeit törli.
Put	Korlátozott helyzetekben használhatja az egyes rekordmezők frissítését.

HTTP-fejlécek

A webes API csak a JSON-t támogatja. Minden HTTP-fejlécnek tartalmaznia kell a következőket:

Akkor is az application/json Efogadás fejlécérték, ha nincs várt választörzs.
Ha a kérelem JSON-adatot tartalmaz a kérelem törzsében, akkor tartalmaznia kell egy Content-Type fejlécet, amelynek értéke application/json.

A jelenlegi OData verzió a 4.0-s, de a későbbi verziók új funkciókat is engedélyezhetnek majd. A következő szintaxis használatával biztosíthatja, hogy a jövőben ne legyen félreérthető a kódra alkalmazott OData-verzió:

Szintaxis

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

Példa: a burkoló AJAX-függvénye a CSRF-kódhoz

    (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élda: Táblaadatok lekérése

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

Példa: Táblaadatok létrehozása

    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élda: Táblaadatok frissítése

        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élda: Táblaadatok törlése

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

Állapotkódok azonosítása

A HTTP-kérelmekre adott válaszok egy állapotkódot tartalmaznak. A portálok webes API által visszaadott állapotkódok a következőket tartalmazzák:

Kód	Description	Type
200 OK	Ez a válasz akkor várható, ha a művelet a válasz törzsében adatot ad vissza.	Sikeres végrehajtás
204 Nincs tartalom	Ez a válasz akkor várható, ha a művelet sikeres, de a válasz törzsében nem adatot ad vissza.	Sikeres végrehajtás
403 Tiltott	A válasz a következő típusú hibák esetében várható: AccessDenied AttributePermissionIsMissing TablePermissionWriteIsMissingDuringUpdate TablePermissionCreateIsMissing TablePermissionDeleteIsMissing TablePermissionAppendIsMissngDuringAssociationChange TablePermissionAppendToIsMissingDuringAssociateChange	Ügyfélhiba
401 Nem engedélyezett	A válasz a következő típusú hibák esetében várható: MissingPortalRequestVerificationToken MissingPortalSessionCookie	Ügyfélhiba
413 A hasznos adat túl nagy	Ez a válasz akkor várható, ha a kérelem hossza túl nagy.	Ügyfélhiba
400 BadRequest	A válasz akkor várható, ha egy argumentum érvénytelen. InvalidAttribute	Ügyfélhiba
404 Nem található	Ez a válasz akkor várható, amikor az erőforrás nem létezik. A tábla nem látható a webes API-ban.	Ügyfélhiba
405 Nem engedélyezett módszer	Ez a hiba helytelen módszer- és erőforrás-kombinációk esetén fordul elő. Nem használhatja például a DELETE vagy a PATCH összetevőt a táblák egy gyűjteményén. Ez a helyzet a következő típusú hibák esetén fordulhat elő: InvalidOperation NotSupported	Ügyfélhiba
501 Nincs megvalósítva	Ez a válasz akkor várható, ha néhány kért művelet nincs implementálva.	Kiszolgálóhiba
503 A szolgáltatás nem érhető el	Ez a válasz akkor várható, ha a webes API-szolgáltatás nem érhető el.	Kiszolgálóhiba

Hibák elemzése a válaszból

Nézze meg a következő példában szereplő HTTP-választ, amely még mindig tartalmazza a belső hibát:

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

Hibakódok

A hibakódok hexadecimális formátumban jelennek meg az összes kezelt eset esetében. A következő táblázatban az egyes hibakódok és kódok neve és üzenete látható.

Hibakód	Hiba neve	Hibaüzenet
900400FF	NoAttributesForTableCreate	Nincsenek attribútumok a Tábla létrehozása művelethez.
90040100	InvalidAttribute	Nem található a(z) {0} attribútum a(z) {1} tábla esetében.
90040101	AttributePermissionIsMissing	A(z) {1} tábla {0} attribútuma nem engedélyezett Web API esetén.
90040102	TablePermissionWriteIsMissingDuringUpdate	Nincs jogosultsága a(z) {0} entitás frissítésére.
90040103	TablePermissionCreateIsMissing	Nincs jogosultsága a(z) {0} entitás létrehozására.
90040104	TablePermissionDeleteIsMissing	Nincs jogosultsága a(z) {0) entitás törlésére.
90040105	TablePermissionAppendIsMissngDuringAssociationChange	Nincs jogosultsága a(z) {0} tábla és a(z) {1} társításához vagy a társítás megszüntetéséhez.
90040106	TablePermissionAppendToIsMissingDuringAssociationChange	Nincs jogosultsága a(z) {1} tábla és a(z) {0} társításához vagy a társítás megszüntetéséhez
90040107	HttpAntiForgeryException	A hamisítás elleni cookie tokenje és az űrlapmező tokenje nem egyezik.
90040109	MissingPortalSessionCookie	Érvénytelen munkamenet-token lett átadva az eldobási módszernek.
9004010C	ResourceDoesNotExists	Nincs erőforrás a(z) „{0}” szegmens esetében.
9004010D	CDSError	CDS-hiba történt.

A nem kezelt hibákra vonatkozó válasz a 500 HTTP-állapotkóddal visszaadja a hibát: „A kérés feldolgozása közben nem várt hiba történt”.

Kapcsolódó információk

A Portálok webes API áttekintése
Portálműveletek írása, frissítése és törlése a webes API használatával
A webes API-t használó olvasási portálműveletek