Sastavljanje HTTP zahtjeva i obrada pogreški za Web API portala

Interakcija s API-jem na webu uključuje sastavljanje HTTP zahtjeva s potrebnim zaglavljima i obradu HTTP odgovora, uključujući i pogreške.

Važno

  • Verzija vašeg portala mora biti 9.3.3.x ili novija da bi ova značajka radila.

Određivanje verzije URL-a API-ja na webu

Konstruirajte URL adresu za Web AP pomoću formata u sljedećoj tablici.

Dio Opis
Protokol https://
Osnovni URL <portal URL>
Put API-ja na webu _api
Resurs Naziv tablice koju želite koristiti

Na primjer, upotrijebite ovaj format prilikom pozivanja na slučaj:

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

Svi resursi web-API-ja slijedit će odgovarajuće dozvole tablice portala u kontekstu s web-ulogama.

HTTP metode

HTTP zahtjevi mogu koristiti različite vrste metoda. Međutim, web-API portala podržava samo metode u sljedećoj tablici:

Metoda Korištenje
Nabavite Yammer Koristi se prilikom dohvaćanja podataka iz tablica.
Post Koristi se pri stvaranju tablica i akcija pozivanja.
Zakrpa Koristite prilikom ažuriranja tablica ili obavljanja operacija upsert.
Izbriši Upotrebljava se prilikom brisanja tablica ili pojedinačnih svojstava tablica.
Put Upotrebljava se u ograničenim situacijama za ažuriranje pojedinačnih svojstava tablica.

Zaglavlja HTTP

Web API podržava samo JSON. Svako HTTP zaglavlje mora sadržavati sljedeće:

  • Vrijednost zaglavlja je Prihvati za application/json, čak i kada se ne očekuje odgovor.
  • Ako zahtjev uključuje JSON podatke u tijelu zahtjeva, morate uključiti zaglavlje Vrsta sadržaja s vrijednošću odapplication/json.

Trenutačna verzija protokola OData je 4.0, ali buduće verzije mogu uključivati nove mogućnosti. Koristite sljedeću sintaksu da biste bili sigurni da nema nejasnoća u vezi s verzijom OData koja će se ubuduće primjenjivati na vaš kôd:

Sintaksa

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

Primjer: funkcija Wrapper AJAX za CSRF token

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

Primjer: dohvaćanje podataka tablice

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

Primjer: stvorite podatke tablice

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

Primjer: ažurirajte podatke tablice

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

Primjer: izbrišite podatke tablice

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

Određivanje koda statusa

Svaki odgovor HTTP zahtjeva uključuje kôd statusa. Kodovi stanja koje su vratili portali Web API uključuju sljedeće:

Kôd Opis Tip
U redu 200 Ovaj se odgovor prikazuje kada operacija vrati podatke u tijelu odgovora. Uspjeh
Nema sadržaja 204 Ovaj se odgovor prikazuje kada operacija uspje, ali ne vrati podatke u tijelu odgovora. Uspjeh
Zabranjeno 403 Ovaj se odgovor prikazuje za sljedeće vrste pogrešaka:
  • AccessDenied
  • AttributePermissionIsMissing
  • TablePermissionWriteIsMissingDuringUpdate
  • TablePermissionCreateIsMissing
  • TablePermissionCreateIsMissing
  • TablePermissionAppendIsMissngDuringAssociationChange
  • TablePermissionAppendIsMissngDuringAssociationChange
Pogreška klijenta
Neovlašteno 401 Ovaj se odgovor prikazuje za sljedeće vrste pogrešaka:
  • MissingPortalRequestVerificationToken
  • MissingPortalSessionCookie
Pogreška klijenta
Korisni podaci preveliki 413 Ovaj se odgovor prikazuje kad je duljina zahtjeva prevelika. Pogreška klijenta
Zahtjev nije ispravan 400 Ovaj se odgovor prikazuje kad argument nije valjan.
InvalidAttribute
Pogreška klijenta
Nije pronađeno 404 Ovaj se odgovor očekuje kad resurs ne postoji.
Tablica još nije izložena za web-API.
Pogreška klijenta
Metoda nije dopuštena 405 Ova se pogreška pojavljuje za pogrešne kombinacije metoda i resursa. Na primjer, ne možete koristiti DELETE ili PATCH za skup tablica. To se može pojaviti za sljedeće vrste pogrešaka:
  • InvalidOperation
  • NotSupported
Pogreška klijenta
Nije implementirano 501 Ovaj se odgovor prikazuje kad se tražena operacija nije implementirana. Pogreška poslužitelja
Usluga nije dostupna 503 Ovaj se odgovor prikazuje kad usluga Web API nije dostupna. Pogreška poslužitelja

Raščlanjivanje pogrešaka iz odgovora

Razmotrite sljedeći primjer HTTP odgovora koji još uvijek uključuje unutarnju pogrešku:

{
  "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ôdovi pogreške

Kodovi pogrešaka prikazuju se u heksadecimalnom formatu za sve obrađene scenarije. U sljedećoj tablici navedeni su svi kodovi pogreške s pripadajućim nazivom i porukom.

Kod pogreške Naziv pogreške Poruka o pogrešci
900400FF NoAttributesForTableCreate Nema atributa za radnju Stvaranje tablice.
90040100 InvalidAttribute Nije moguće pronaći atribut {0} za tablicu {1}.
90040101 AttributePermissionIsMissing Atribut {0} u tablici {1} nije omogućen za Web API.
90040102 TablePermissionWriteIsMissingDuringUpdate Nemate dozvolu za ažuriranje {0} entiteta.
90040103 TablePermissionCreateIsMissing Nemate dozvolu za stvaranje {0} entiteta.
90040104 TablePermissionCreateIsMissing Nemate dozvolu za brisanje entiteta {0).
90040105 TablePermissionAppendIsMissngDuringAssociationChange Nemate dozvolu za pridruživanje ili razdvajanje tablice {0} s {1}.
90040106 TablePermissionAppendToIsMissingDuringAssociationChange Nemate dozvolu za pridruživanje ili razdvajanje tablice {1} u {0}.
90040107 HttpAntiForgeryException Token kolačića protiv krivotvorenja i token obrasca polja se ne podudaraju.
90040109 MissingPortalSessionCookie Nevaljani token sesije proslijeđen je u metodu izbacivanja.
9004010C ResourceDoesNotExists Resurs nije pronađen za segment „{0}”.
9004010D CDSError Došlo je do pogreške DCS-a.

Odgovor za neobrađene pogreške s HTTP kodom statusa 500 vraća pogrešku „Prilikom obrade zahtjeva došlo je do neočekivane pogreške.”

Pogledajte

Pregled Web API-ja za portale
Portali pišu, ažuriraju i brišu operacije pomoću web-API-ja
Portali čitaju operacije pomoću web-API-ja