HTTP-pyyntöjen laatiminen ja virheiden käsitteleminen portaalien verkko-ohjelmointirajapinnassa

Artikkeli
03/16/2023

Verkko-ohjelmointirajapinnan käyttäminen sisältää vaaditut ylätunnisteet sisältävien HTTP-pyyntöjen laatimisen ja HTTP-vastausten, myös mahdollisten virheiden, käsittelemisen.

Tärkeä

Portaalin version on oltava 9.3.3.x tai uudempi versio, jotta toiminto toimii oikein.

Verkko-ohjelmointirajapinnan URL-osoite ja versionhallinta

Laadi verkko-ohjelmointirajapinnan URL-osoite käyttämällä seuraavassa taulukossa olevaa muotoa.

Osittain	Description
Protokolla	https://
URL-perusosoite	<portaalin URL-osoite>
Verkko-ohjelmointirajapinnan polku	_api
Resurssi	Käytettävän taulukon looginen nimi

Käytä esimerkiksi seuraavaa muotoa palvelupyyntöön viitatessa:

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

Kaikki verkko-ohjelmointirajapintaresurssit noudattavat soveltuvia taulukko-oikeuksia verkkoroolien yhteydessä.

HTTP-menetelmät

HTTP-pyynnöt voivat käyttää erilaisia menetelmiä. Portaalien verkko-ohjelmointirajapinta tukee vain seuraavassa taulukossa olevia menetelmiä:

Metodi	Käyttö
Get	Käytä noudettaessa tietoja taulukoista.
Julkaise	Käytetään tietueita luotaessa.
Ohjelmakorjaus	Käytetään taulukoita päivitettäessä tai upsert-toimintoja tehtäessä.
Delete	Käytetään poistettaessa tietueita tai tietueiden yksittäisten kenttien arvoja.
Put	Käytetään rajoitetuissa tilanteissa tietueiden yksittäisten kenttien päivittämiseen.

HTTP-otsikot

Verkko-ohjelmointirajapinta tukee vain JSON-muotoa. Jokaisessa HTTP-ylätunnisteessa on oltava seuraavat:

Hyväksy-ylätunnisteen application/json-arvo, vaikka vastaustekstiä ei odoteta.
Jos pyyntö sisältää JSON-tietoja pyyntötekstissä, myös Sisältötyyppi-ylätunnista, jonka arvo on application/json, on sisällytettävä.

Nykyinen OData-versio on 4,0, mutta tulevat versiot voivat sallia uusia toimintoja. Seuraavan syntaksin avulla voit varmistaa, että koodiin tulevaisuudessa sovellettavassa OData-versiossa ei ole epäselvyyttä:

Syntaksi

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

Esimerkki: CSRF-tunnuksen paketoijan AJAX-funktio

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

Esimerkki: Nouda taulukon tiedot

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

Esimerkki: taulukon tietojen luominen

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

Esimerkki: taulukon tietojen päivittäminen

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

Esimerkki: taulukon tietojen poistaminen

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

Tilakoodien määrittäminen

Jokaisessa HTTP-pyynnön vastauksessa on tilakoodi. Seuraavat ovat portaalien verkko-ohjelmointirajapinnan palauttamia tilakoodeja:

Koodi	Description	Type
200 OK	Odota tätä vastausta, kun toiminto palauttaa tietoja vastaustekstissä.	Onnistui
204 Ei sisältöä	Odota tätä vastausta, kun toiminto onnistuu mutta ei palauta tietoja vastaustekstissä.	Onnistui
403 Käyttö estetty	Odota tätä vastausta seuraavissa virhetyypeissä: AccessDenied AttributePermissionIsMissing TablePermissionWriteIsMissingDuringUpdate TablePermissionCreateIsMissing TablePermissionDeleteIsMissing TablePermissionAppendIsMissngDuringAssociationChange TablePermissionAppendToIsMissingDuringAssociateChange	Asiakasvirhe
401 Ei sallittu	Odota tätä vastausta seuraavissa virhetyypeissä: MissingPortalRequestVerificationToken MissingPortalSessionCookie	Asiakasvirhe
413 Tietojen koko on liian suuri	Odota tätä vastaus, kun pyyntö on liian pitkä.	Asiakasvirhe
400 BadRequest	Odota tätä vastausta, kun argumentti on virheellinen. InvalidAttribute	Asiakasvirhe
404 Ei löytynyt	Odota tätä vastausta, kun resurssia ei ole. Taulukko ei ole näkyvissä verkko-ohjelmointirajapinnassa.	Asiakasvirhe
405 Menetelmä ei sallita	Tämä virhe esiintyy, kun menetelmä- ja resurssiyhdistelmä on virheellinen. Esimerkiksi DELETE- tai PATCH-komentoa ei voi käyttää taulukkokokoelmassa. Tämä tilanne voi esiintyä seuraavissa virhetyypeissä: InvalidOperation NotSupported	Asiakasvirhe
501 Ei toteutettu	Odota tätä vastausta, kun jotain pyydettyä toimintoa ei voi toteuttaa.	Palvelinvirhe
503 Palvelu ei ole käytettävissä	Odota tätä vastausta, kun verkko-ohjelmointirajapintapalvelu ei ole käytettävissä.	Palvelinvirhe

Virheiden jäsentäminen vastauksesta

Pohdi seuraavia HTTP-esimerkkivastauksia, joissa on edelleen sisäinen virhe:

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

Virhekoodit

Virhekoodit näkyvät heksadesimaalimuodossa kaikissa käsitellyissä skenaarioissa. Seuraavassa taulukossa on luettelo jokaisesta virhekoodista sekä sen nimestä ja siihen liittyvästä sanomasta.

Virhekoodi	Virheen nimi	Virhesanoma
900400FF	NoAttributesForTableCreate	Ei määritteitä Luo taulukko -toiminnolle.
90040100	InvalidAttribute	Määritettä {0} ei löytynyt taulukolle {1}.
90040101	AttributePermissionIsMissing	Taulukon {1} määrite {0} ei ole käytössä www-ohjelmointirajapinnassa.
90040102	TablePermissionWriteIsMissingDuringUpdate	Sinulla ei ole entiteetin {0} päivitysoikeutta.
90040103	TablePermissionCreateIsMissing	Sinulla ei ole entiteetin {0} luontioikeutta.
90040104	TablePermissionDeleteIsMissing	Sinulla ei ole entiteetin {0) poisto-oikeutta.
90040105	TablePermissionAppendIsMissngDuringAssociationChange	Oikeutta taulukon {0} liittämiseen kohteeseen {1} tai liitoksen poistamiseen ei ole.
90040106	TablePermissionAppendToIsMissingDuringAssociationChange	Oikeutta taulukon {1} liittämiseen kohteeseen {0} tai liitoksen poistamiseen ei ole.
90040107	HttpAntiForgeryException	Väärennyksen estävä evästetunnus ja lomakekentän tunnus eivät vastaa toisiaan.
90040109	MissingPortalSessionCookie	Virheellinen istuntotunnus välitettiin palautusmenetelmään.
9004010C	ResourceDoesNotExists	Segmentille {0} ei löydy resurssia.
9004010D	CDSError	Tapahtui CDS-virhe.

Käsittelemättömien virheiden, joissa on HTTP-tilakoodi 500, vastaus palauttaa virheen Odottamaton virhe pyyntöä käsiteltäessä.

Jaa