Skapa HTTP-förfrågningar och hantera fel för portalwebb-API

Artikel
03/16/2023

Att samverka med webb-API inkluderar att HTTP-begäran skapas med obligatoriska rubriker och hantering av HTTP-svar, inklusive eventuella fel.

Viktigt!

Portalversionen måste vara 9.3.3.x eller senare för att den här funktionen ska fungera.

URL och version för webb-API

Konstruera webb-API-adressen med hjälp av formatet i följande tabell.

Delvis	Description
Protokoll	https://
Bas-URL	<portal URL>
Sökväg till Webb-API	_api
Resurs	Logiskt namn på tabellen du vill använda

Använd t.ex. följande format när du refererar ett ärende:

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

Alla webb-API-resurser följer respektive tabellbehörighet i kontexten med webbroller.

HTTP-metoder

HTTP-begäran kan använda olika typer av metoder. Webb-API för portaler stöder dock endast metoderna i följande tabell:

Metod	Användning
Hämta	Används när data hämtas från tabeller.
Publicera	Används när poster skapas.
Korrigering	Används när du uppdaterar tabeller eller gör upsert-åtgärder.
Delete	Används när du tar bort poster eller enskilda fältvärden för poster.
Put	Används i begränsade situationer för att uppdatera enskilda postfält.

HTTP-rubriker

Webb-API:t stöder endast JSON. Varje HTTP-rubrik måste innehålla:

Rubrikvärdet Acceptera förprogram/json, även när ingen svarstext förväntas.
Om förfrågan innehåller JSON-data i begärandetexten måste du ha med rubriken Innehållstyp med värdetapplication/json.

Den aktuella OData-versionen är 4.0, men framtida versioner kan tillåta nya funktioner. Använd följande syntax för att säkerställa att OData-versionen inte är tvetydig och att den kommer att användas för din kod i framtiden:

Syntax

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

Exempel: funktionen wrapper AJAX för 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)

Exempel: Hämta tabelldata

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

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

Exempel: Uppdatera 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);
		}
	});

Exempel: Ta bort tabelldata

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

Identifiera statuskoder

Varje svar på en HTTP-begäran omfattar en statuskod. Statuskoder som returneras av portals webb-API omfattar följande:

Kod	Description	Type
200 OK	Förvänta dig det här svaret om din åtgärd ska returnera data i svarstexten.	Genomfört
204 inget innehåll	Förvänta dig det här svaret om din åtgärd lyckas men inte returnerar data i svarstexten.	Genomfört
403 Förbjuden	Detta svar förväntas för följande typer av fel: AccessDenied AttributePermissionIsMissing TablePermissionWriteIsMissingDuringUpdate TablePermissionCreateIsMissing TablePermissionDeleteIsMissing TablePermissionAppendIsMissngDuringAssociationChange TablePermissionAppendToIsMissingDuringAssociateChange	Klientfel
401 Ej auktoriserad	Detta svar förväntas för följande typer av fel: MissingPortalRequestVerificationToken MissingPortalSessionCookie	Klientfel
413 nyttolast är för stor	Förvänta dig det här svaret när längden på begäran är för stor.	Klientfel
400 BadRequest	Förvänta dig svaret när ett argument är ogiltigt. InvalidAttribute	Klientfel
404 kunde inte hittas	Det här svaret förväntas när resursen inte finns. Tabellen visas inte för webb-API.	Klientfel
405 metoden är inte tillåten	Det här felet uppstår för felaktiga metod- och resurskombinationer. Du kan till exempel inte använda DELETE eller PATCH på en samling med tabeller. Denna situation kan ske för följande typer av fel: InvalidOperation NotSupported	Klientfel
501 ej implementerat	Det här svaret förväntas när en begärd åtgärd inte implementeras.	Serverfel
503 Tjänsten är inte tillgänglig	Förvänta dig svaret när webb-API-tjänsten inte är tillgänglig.	Serverfel

Parsningsfel från svaret

Tänk på följande exempel-HTTP på svar som fortfarande innehåller det interna felet:

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

Felkoder

Felkoder visas i hexadecimalt format för alla hanterade scenarier. I följande tabell visas varje felkod med respektive namn och meddelande.

Felkod	Felnamn	Felmeddelande
900400FF	NoAttributesForTableCreate	Det finns inga attribut för åtgärden Skapa tabell.
90040100	InvalidAttribute	Attributet {0} kan inte hittas för tabellen {1}.
90040101	AttributePermissionIsMissing	Attributet {0} i tabellen {1} är inte aktiverat för webb-API:et.
90040102	TablePermissionWriteIsMissingDuringUpdate	Du har inte behörighet att uppdatera entiteten {0}.
90040103	TablePermissionCreateIsMissing	Du har inte behörighet att skapa entiteten {0}.
90040104	TablePermissionDeleteIsMissing	Du har inte behörighet att ta bort entiteten {0).
90040105	TablePermissionAppendIsMissngDuringAssociationChange	Du har inte behörighet att associera eller ta bort associationen till tabellen {0} med {1}.
90040106	TablePermissionAppendToIsMissingDuringAssociationChange	Du har inte behörighet att associera eller ta bort associationen till tabellen {1} till {0}.
90040107	HttpAntiForgeryException	Cookie-token för antiförfalskning för formulärfältets token överensstämmer inte.
90040109	MissingPortalSessionCookie	En ogiltig sessionstoken angavs i utlösningsmetoden.
9004010C	ResourceDoesNotExists	Det gick inte att hitta resursen för segmentet "{0}".
9004010D	CDSError	Ett CDS-fel inträffade.

Svar på ohanterade fel med HTTP-statuskod 500 kommer att returnera felet "Ett oväntat fel inträffade när förfrågan bearbetades".

Dela via