Del via

Skrive HTTP-forespørsler og behandle feil for portalenes web-API

  • Artikkel

Samhandling med Web-API-en omfatter å skrive HTTP-forespørsler med nødvendige hoder og håndtering av HTTP-svar, inkludert eventuelle feil.

Viktig

  • Portalversjonen må være 9.3.3.x eller senere for at denne funksjonen skal fungere.

URL-adresse til Web API og versjonskontroll

Konstruere URL-adressen for Web-API-en ved hjelp av formatet i tabellen nedenfor.

Del Bekrivelse
Protokoll https://
Primær nettadresse <URL-adressen til portalen>
Web API-bane _api
Ressurs Logisk navn på tabellen du vil bruke

Bruk for eksempel dette formatet når du refererer til en sak:

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

Alle web-API-ressurser følger de respektive tabelltillatelsene i sammenheng med webroller.

HTTP-metoder

HTTP-forespørsler kan bruke ulike typer metoder. Portal-Web-API-en støtter imidlertid bare metodene i tabellen nedenfor:

Metode Bruk
Hent Brukes ved henting av data fra tabeller.
Post Bruk ved oppretting av oppføringer.
Oppdatering Brukes når tabeller oppdateres eller utføres i upsert-operasjoner.
Delete Brukes ved sletting av oppføringer eller individuelle feltverdier for oppføringer.
Put Bruk i begrensede situasjoner for å oppdatere individuelle oppføringsfelt.

HTTP-topptekster

Web-API-en støtter bare JSON. Hver HTTP-overskrift må inneholde følgende:

  • En Godta-overskriftsverdi for application/json, selv når ingen svartekst forventes.
  • Hvis forespørselen inkluderer JSON-data i brødteksten for forespørselen, må du inkludere et Content-Type-hode med verdienapplication/json.

Den gjeldende OData-versjonen er 4.0, men fremtidige versjoner kan tillates for nye funksjoner. Bruk følgende syntaks for å sikre at det ikke er tvetydighet om OData-versjonen som skal brukes på koden i fremtiden:

Syntaks

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

Eksempel: Wrapper AJAX-funksjon for CSRF-tokenet

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

Eksempel: Hente tabelldata

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

Eksempel: Opprette tabelldata

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

Eksempel: Oppdatere tabelldata

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

Eksempel: Slette tabelldata

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

Identifisere statuskoder

Hvert svar på HTTP-forespørselen inkluderer en statuskode. Statuskoder som returneres av nett-API for portaler, omfatter følgende:

Kode Description Type
200 OK Forvent dette svaret når operasjonen vil returnere data i svarteksten. Lyktes
204 Uten innhold Forvent dette svaret når operasjonen lykkes, men ikke returnerer data i svarteksten. Lyktes
403 Ikke tillatt Forvent dette svaret for følgende typer feil:
  • AccessDenied
  • AttributePermissionIsMissing
  • TablePermissionWriteIsMissingDuringUpdate
  • TablePermissionCreateIsMissing
  • TablePermissionDeleteIsMissing
  • TablePermissionAppendIsMissngDuringAssociationChange
  • TablePermissionAppendToIsMissingDuringAssociateChange
 Klientfeil
401 Uautorisert Forvent dette svaret for følgende typer feil:
  • MissingPortalRequestVerificationToken
  • MissingPortalSessionCookie
 Klientfeil
413 Nyttelast er for stor Forvent dette svaret når forespørselslengden er for stor. Klientfeil
400 BadRequest Forvent dette svaret når et argument er ugyldig.
InvalidAttribute		 Klientfeil
404 Ikke funnet Forvent dette svaret når ressursen ikke finnes.
Tabellen vises ikke for web-API-en.		 Klientfeil
405 Metode ikke tillatt Denne feilen oppstår for feil metode- og ressurskombinasjoner. Du kan for eksempel ikke bruke DELETE eller PATCH på en tabellsamling. Denne situasjonen kan skje for følgende typer feil:
  • InvalidOperation
  • NotSupported
 Klientfeil
501 Ikke implementert Forvent dette svaret når en forespurt operasjon ikke er implementert. Serverfeil
503 Tjenesten er utilgjengelig Forvent dette svaret når Web-API-tjenesten ikke er tilgjengelig. Serverfeil

Analysere feil fra svaret

Vurder følgende HTTP-eksempelsvar som fremdeles inneholder den indre feilen:

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

Feilkoder

Feilkoder vises i heksadesimal format for alle behandlede scenarier. Følgende tabell viser hver feilkode med det respektive navnet og den tilhørende meldingen.

Feilkode Navn på feil Feilmelding
900400FF NoAttributesForTableCreate Ingen attributter for handlingen Opprett tabell.
90040100 InvalidAttribute Attributtet {0} ble ikke funnet for tabellen {1}.
90040101 AttributePermissionIsMissing Attributtet {0} i tabellen {1} er ikke aktivert for Web-API.
90040102 TablePermissionWriteIsMissingDuringUpdate Du har ikke tillatelse til å oppdatere en {0}-enhet.
90040103 TablePermissionCreateIsMissing Du har ikke tillatelse til å opprette en {0}-enhet.
90040104 TablePermissionDeleteIsMissing Du har ikke tillatelse til å slette {0)-enhet.
90040105 TablePermissionAppendIsMissngDuringAssociationChange Du har ikke tillatelse til å knytte tabellen til eller oppheve tilknytningen av tabellen {0} med {1}.
90040106 TablePermissionAppendToIsMissingDuringAssociationChange Du har ikke tillatelse til å knytte tabellen til eller oppheve tilknytningen av tabellen {1} til {0}
90040107 HttpAntiForgeryException Tokenet for informasjonskapselen for å motvirke forfalskning og token for skjemafelt samsvarer ikke.
90040109 MissingPortalSessionCookie Et ugyldig øktstoken ble sendt til den utløsende metoden.
9004010C ResourceDoesNotExists Finner ikke ressurs for segmentet {0}.
9004010D CDSError Det oppstod en CDS-feil.

Svar for ubehandlede feil ved hjelp av HTTP-statuskode 500, returnerer feilen – Det oppstod en uventet feil under behandling av forespørselen.

Se også