Povratne informacije

Sestava zahtev HTTP in obdelava napak za spletni API portalov

  • Članek
  • 2 min za branje

Interakcija s spletnim API-jem vključuje sestavljanje zahtev HTTP z obveznimi glavami in obravnavanje odgovorov HTTP, vključno z morebitnimi napakami.

Pomembno

  • Za delovanje te funkcije morate imeti portal različice 9.3.3.x ali novejše.

URL spletnega API-ja in shranjevanje različic

Sestavite URL spletnega API-ja z uporabo oblike v naslednji tabeli.

Del Opis
Protokol https://
Osnovni URL <portal URL>
Pot spletnega API-ja _api
Vir Ime tabele, ki jo želite uporabiti

To obliko zapisa na primer uporabite pri sklicevanju na primer:

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

Vsi viri spletnega API-ja bodo sledili ustreznim dovoljenja za tabelo portala v kontekstu spletnih vlog.

Načini HTTP

Zahteve HTTP lahko uporabljajo različne načine. Vendar spletni API portalov podpira samo metode v naslednji tabeli:

Metoda Uporaba
Ustvari račun v storitvi Yammer Uporabite pri pridobivanju podatkov iz tabel.
Pošlji Uporabite pri ustvarjanju tabel in klicanju dejanj.
Patch Uporabite pri posodabljanju tabel ali izvajanju postopkov upsert.
Delete Uporabite pri brisanju tabel ali posameznih lastnosti tabel.
Put Uporabite v omejenih situacijah za posodabljanje posameznih lastnosti tabel.

Glave HTTP

Spletni API podpira samo JSON. Vsaka HTTP glava mora vsebovati:

  • Glava Sprejmi vrednosti application/json, tudi kadar je pričakovati telo brez odziva.
  • Če zahteva vključuje podatke JSON v telesu zahteve, morate vključiti glavo Vrsta vsebine z vrednostjoapplication/json.

Trenutna različica vira OData je 4.0, vendar bodo prihodnje različice morda omogočale nove zmogljivosti. Uporabite naslednjo sintakso, da zagotovite, da ni dvoumnosti glede različice OData, ki bo uporabljena za vašo kodo v prihodnosti:

Sintaksa

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

Primer: Funkcija Wrapper AJAX za žeton 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)

Primer: Pridobite podatke tabele

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

Primer: ustvarjanje podatkov tabel

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

Primer: posodabljanje podatkov tabel

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

Primer: brisanje podatkov tabel

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

Prepoznavanje kod stanja

Vsak odgovor na zahtevo HTTP vključuje kodo stanja. Kode stanja, ki jih vrne spletni API portalov, vključujejo naslednje:

Koda Description Vnesi
200 V redu Pričakujte ta odgovor, ko postopek vrne podatke v telesu odziva. Uspeh
204 Ni vsebine Pričakujte ta odgovor, ko postopek uspe, vendar ne vrne podatkov v telesu odziva. Uspeh
403 – Prepovedano Pričakujte ta odgovor za naslednje vrste napak:
  • AccessDenied
  • AttributePermissionIsMissing
  • TablePermissionWriteIsMissingDuringUpdate
  • TablePermissionCreateIsMissing
  • TablePermissionDeleteIsMissing
  • TablePermissionAppendIsMissngDuringAssociationChange
  • TablePermissionAppendToIsMissingDuringAssociateChange
 Napaka odjemalca
401 – Nedovoljeno Pričakujte ta odgovor za naslednje vrste napak:
  • MissingPortalRequestVerificationToken
  • MissingPortalSessionCookie
 Napaka odjemalca
413 Prevelik obseg Ta odgovor pričakujte, ko je dolžina zahteve prevelika. Napaka odjemalca
400 Napačna zahteva Pričakujte ta odgovor, če argument ni veljaven.
InvalidAttribute		 Napaka odjemalca
404 Ni mogoče najti Pričakujte ta odgovor, ko vir ne obstaja.
Tabela ni izpostavljena za spletni API.		 Napaka odjemalca
405 Način ni dovoljen Ta napaka se pojavi pri napačnih kombinacijah metod in virov. Tako na primer za zbirko tabel ne morete uporabiti funkcije DELETE ali PATCH. Do te situacije lahko pride za naslednje vrste napak:
  • InvalidOperation
  • NotSupported
 Napaka odjemalca
501 Ni uporabljeno Pričakujte ta odgovor, ko zahtevano dejanje ni izvedeno. Napaka strežnika
503 – Storitev ni na voljo. Pričakujte ta odgovor, ko storitev spletnega API-ja ni na voljo. Napaka strežnika

Napake razčlenitve iz odgovora

Razmislite o naslednjem primeru odgovora HTTP, ki še vedno vključuje notranjo napako:

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

Kode napak

Kode napak so prikazane v šestnajstiški obliki za vse obdelane scenarije. V naslednji tabeli so navedene vse kode napak s pripadajočim imenom in sporočilom.

Koda napake Ime napake Sporočilo o napaki
900400FF NoAttributesForTableCreate Ni atributov za dejanje Ustvari tabelo.
90040100 InvalidAttribute Atributa {0} ni mogoče najti za tabelo {1}.
90040101 AttributePermissionIsMissing Atribut {0} v tabeli {1} ni omogočen za spletni API.
90040102 TablePermissionWriteIsMissingDuringUpdate Nimate dovoljenja za posodobitev entitete {0}.
90040103 TablePermissionCreateIsMissing Nimate dovoljenja za ustvarjanje entitete {0}.
90040104 TablePermissionDeleteIsMissing Nimate dovoljenja za izbris entitete {0).
90040105 TablePermissionAppendIsMissngDuringAssociationChange Nimate dovoljenja za pridružitev tabele {0} na {1} ali preklic pridružitve.
90040106 TablePermissionAppendToIsMissingDuringAssociationChange Nimate dovoljenja za pridružitev tabele {1} na {0} ali preklic pridružitve
90040107 HttpAntiForgeryException Žeton piškotkov proti ponarejanju in žeton polja obrazca se ne ujemata.
90040109 MissingPortalSessionCookie Neveljaven žeton seje je bil poslan v načinu vrnitve.
9004010C ResourceDoesNotExists Vira za segment »{0}« ni mogoče najti.
9004010D CDSError Prišlo je do napake CDS.

Odgovor na neobdelane napake s kodo stanja HTTP 500 bo vrnil napako »Med obdelavo zahteve je prišlo do nepričakovane napake«.

Glejte tudi

Pregled spletnega API-ja za portale
Portali pišejo, posodabljajo in brišejo operacije z uporabo spletnega API-ja
Portali berejo operacije s spletnim API-jem

Opomba

Ali nam lahko poveste, kateri je vaš prednostni jezik za dokumentacijo? Izpolnite kratko anketo. (upoštevajte, da je v angleščini)

Z anketo boste porabili približno sedem minut. Ne zbiramo nobenih osebnih podatkov (izjava o zasebnosti).