HTTP-taotluste koostamine ja portaalide veebi API tõrgete lahendamine

Artikkel
03/14/2023

Märkus

Alates 12. oktoobrist 2022 on Power Appsi portaalid Power Pages. Lisateave: Microsoft Power Pages on nüüd üldiselt saadaval (ajaveebipostitus)
Peagi migreerime ja ühendame Power Appsi portaalide dokumentatsiooni Power Pagesi dokumentatsiooniga.

Veebi-API-ga suhtlemine hõlmab HTTP-päringute koostamist vajalike päistega ning HTTP-vastuste, sealhulgas tõrked, käsitlemist.

Oluline

Teie portaali versioon peab olema 9.3.3.x või uuem, et see funktsioon töötaks.

Veebi-API URL ja versioonid

Veebi-API URL-i koostamiseks kasutage järgmises tabelis olevat vormingut.

Osa	Kirjeldus
Protokoll	https://
Baas-URL	<portal URL>
Veebi-API tee	_api
Ressurss	Kasutatava tabeli loogiline nimi

Näiteks kasutage juhtumile viitamisel seda vormingut.

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

Kõik veebiliidese ressursid järgivad veebirollide kontekstis vastavaid portaalitabeli õigusi.

HTTP-meetodid

HTTP-päringute puhul saab kasutada eri meetodeid. Kuid portaalide veebi-API toetab ainult järgmises tabelis esitatud meetodeid.

Meetod	Kasutus
Hangi	Kasutage andmete toomisel tabelitest.
Post	Kasutage kirjete loomisel.
Patch	Kasutage tabelite värskendamisel või ülespoole suunatud toimingute tegemisel.
Kustutusklahv (Delete)	Kasutage kirjete või kirjete üksikute väljaväärtuste kustutamisel.
Put	Kasutage piiratud olukordades kirjete üksikute väljade värskendamiseks.

HTTP-päised

Veebi-API toetab ainult JSON-i. Iga HTTP-päis peab sisaldama järgmist.

Päise Aktsepteeri väärtus Application/JSON, isegi juhul, kui vastuse sõnumit ei eeldata.
Kui päring sisaldab päringukehas JSON-i andmeid, peate lisama päise Content-Type, mille väärtus on application/json.

Praegune OData versioon on 4,0, kuid tulevased versioonid võivad lubada uusi võimalusi. Kasutage järgmist süntaksit tagamiseks, et OData versioonis, mis rakendub edaspidi teie koodile, ei oleks ebaselgust.

Süntaks

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

Näide: ümbrise AJAX funktsioon CSRF turbelubade jaoks

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

Näide: tabeli andmete toomine

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

Näide: tabeli andmete loomine

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

Näide: tabeli andmete värskendamine

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

Näide: tabeli andmete kustutamine

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

Olekukoodide tuvastamine

Iga HTTP-päringu vastus sisaldab olekukoodi. Portaalide veebi-API tagastatud olekukoodid on järgmised.

Kood	Kirjeldus	Tüüp
200 OK	See vastus tagastatakse, kui teie toiming tagastab vastusekehas andmeid.	Õnnestus
204 sisu pole	See vastus tagastatakse, kui teie toiming õnnestub, aga ei tagasta vastusekehas andmeid.	Õnnestus
403 keelatud	See vastus tagastatakse järgmist tüüpi tõrgete puhul. AccessDenied AttributePermissionIsMissing TablePermissionWriteIsMissingDuringUpdate TablePermissionCreateIsMissing TablePermissionDeleteIsMissing TablePermissionAppendIsMissngDuringAssociationChange TablePermissionAppendToIsMissingDuringAssociateChange	Klienditõrge
401 volitamata	See vastus tagastatakse järgmist tüüpi tõrgete puhul. MissingPortalRequestVerificationToken MissingPortalSessionCookie	Klienditõrge
413 last on liiga suur	See vastus tagastatakse, kui päring on liiga suur.	Klienditõrge
400 vigane päring	See vastus tagastatakse, kui argument ei sobi. InvalidAttribute	Klienditõrge
404 ei leitud	Oodake seda vastust, kui ressurssi pole olemas. Tabel pole veebiliidese jaoks eksponeeritud.	Klienditõrge
405 meetod pole lubatud	See tõrge ilmneb vale meetodi ja ressursi kombinatsioonide puhul. Näiteks ei saa te tabelite kogumis kasutada DELETE ega PATCH. See võib juhtuda järgmist tüüpi tõrgete puhul. InvalidOperation NotSupported	Klienditõrge
501 pole kasutusele võetud	See vastus tagastatakse, kui mõnda taotletud toimingut pole rakendatud.	Serveri tõrge
503 teenus pole saadaval	Seda vastust oodake, kui veebi-API teenus pole saadaval.	Serveri tõrge

Vigade sõelumine vastusest

Kaaluge järgmist HTTP vastust, mis endiselt sisaldab sisemist tõrget.

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

Tõrkekoodid

Tõrkekoodid kuvatakse kõigi käsitletud stsenaariumide puhul kuueteistkümnendvormingus. Järgmises tabelis on toodud kõik tõrkekoodid koos vastava nime ja teatega.

Tõrkekood	Tõrke nimi	Tõrketeade
900400FF	NoAttributesForTableCreate	Tabeli loomise toimingu atribuute ei ole.
90040100	InvalidAttribute	Tabeli {1} atribuuti {0} ei leidu.
90040101	AttributePermissionIsMissing	Tabeli {1} atribuut {0} pole veebi-API jaoks lubatud.
90040102	TablePermissionWriteIsMissingDuringUpdate	Teil pole olemi {0} värskendamiseks õigusi.
90040103	TablePermissionCreateIsMissing	Teil pole olemi {0} loomiseks õigusi.
90040104	TablePermissionDeleteIsMissing	Teil pole olemi {0) kustutamiseks õigusi.
90040105	TablePermissionAppendIsMissngDuringAssociationChange	Teil pole luba tabeli {0} seostamiseks või lahtiühendamiseks teenusega {1}.
90040106	TablePermissionAppendToIsMissingDuringAssociationChange	Teil pole luba tabeli {1} seostamiseks või lahtiühendamiseks teenusesse {0}.
90040107	HttpAntiForgeryException	Pettusevastase küpsise luba ja vormi välja luba ei ühti.
90040109	MissingPortalSessionCookie	Tagastamismeetodisse edastati sobimatu seansi identifikaator.
9004010C	ResourceDoesNotExists	Segmendi '{0}' jaoks ei leitud ressurssi.
9004010D	CDSError	Ilmnes CDS-i tõrge.

Käsitlemata tõrgete HTTP-olekukoodiga 500 vastus tagastab tõrke "päringu töötlemisel ilmnes ootamatu tõrge".

Vt ka

Portaalide veebi API ülevaade
Portaalide kirjutamis-, värskendamis- ja kustutamistoimingu veebi-API-d kasutades
Portaalide lugemistoimingud, mis kasutavad veebi-API-d