HTTP-Anforderungen verfassen und Fehler für die Web API-Portale behandeln

Artikel
03/16/2023

Die Interaktion mit der Web-API umfasst das Erstellen von HTTP-Anforderungen mit den erforderlichen Headern und das Behandeln von HTTP-Antworten, einschließlich etwaiger Fehler.

Wichtig

Ihre Portalversion muss 9.3.3.x oder höher sein, damit diese Funktion funktioniert.

Web-API-URL und Versionsverwaltung

Erstellen Sie die Web-API-URL mithilfe des Formats in der folgenden Tabelle.

Komponente	Beschreibung
Protokoll	https://
Basis-URL	<Portal-URL>
Web-API-Pfad	_api
Ressource	Logischer Name der Tabelle, die Sie verwenden möchten

Verwenden Sie dieses Format beispielsweise, wenn Sie auf einen Fall verweisen:

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

Alle Web-API-Ressourcen folgen den jeweiligen Tabellenberechtigungen im Zusammenhang mit den Webrollen.

HTTP-Methoden

HTTP-Anforderungen können verschiedene Arten von Methoden verwenden. Die Portale-Web-API unterstützt jedoch nur die in der folgenden Tabelle aufgeführten Methoden:

Methode	Verbrauch
Abrufen	Verwendung beim Abrufen von Daten aus Tabellen.
Posten	Wird beim Erstellen von Datensätzen verwendet.
Patch	Wird verwendet, wenn Tabellen aktualisiert werden oder Upsert-Vorgänge ausgeführt werden.
Delete	Wird beim Löschen von Datensätzen oder einzelnen Feldwerten von Datensätzen verwendet.
Put	Wird in bestimmten Fällen zur Aktualisierung einzelner Datensatzfelder verwendet.

HTTP-Kopfzeilen

Die Web-API unterstützt nur JSON. Jeder HTTP-Header muss Folgendes enthalten:

Ein Akzeptieren-Kopfzeilenwert von Anwendung/JSON, auch wenn kein Antworttext erwartet wird.
Wenn die Anforderung JSON-Daten im Anforderungstext enthält, muss ein Content-Type-Header mit dem Wert application/json enthalten sein.

Die aktuelle OData-Version ist 4.0, aber zukünftige Versionen bieten eventuell die Möglichkeit, neue Funktionen zu verwenden. Verwenden Sie die folgende Syntax, um sicherzustellen, dass es keine Unklarheiten über die OData-Version gibt, die in Zukunft auf Ihren Code angewendet wird:

Syntax

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

Beispiel: Wrapper-AJAX-Funktion für das 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)

Beispiel: Tabellendaten abrufen

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

Beispiel: Tabellendaten erstellen

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

Beispiel: Tabellendaten aktualisieren

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

Beispiel: Tabellendaten löschen

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

Ermitteln von Statuscodes

Jede HTTP-Anforderungsantwort enthält einen Statuscode. Zu den von der Portale-Web-API zurückgegebenen Statuscodes gehören die folgenden:

Code	Beschreibung	Typ
200 OK	Nehmen Sie diese Antwort an, wenn durch den Vorgang Daten im Antworttext zurückgegeben werden.	Erfolg
204 Kein Inhalt	Nehmen Sie diese Antwort an, wenn der Vorgang erfolgreich durchgeführt wird, jedoch keine Daten im Antworttext zurückgegeben werden.	Erfolg
403 – verboten	Nehmen Sie diese Antwort für die folgenden Fehlertypen an: AccessDenied AttributePermissionIsMissing TablePermissionWriteIsMissingDuringUpdate TablePermissionCreateIsMissing TablePermissionDeleteIsMissing TablePermissionAppendIsMissngDuringAssociationChange TablePermissionAppendToIsMissingDuringAssociateChange	Client-Fehler
401 – nicht autorisiert	Nehmen Sie diese Antwort für die folgenden Fehlertypen an: MissingPortalRequestVerificationToken MissingPortalSessionCookie	Client-Fehler
413 Nutzlast zu groß	Nehmen Sie die Antwort an, wenn die Anforderung zu lang ist.	Client-Fehler
400 BadRequest	Nehmen Sie diese Antwort an, wenn ein Argument ungültig ist. InvalidAttribute	Client-Fehler
404 Seite nicht gefunden	Nehmen Sie diese Antwort an, wenn die Ressource nicht vorhanden ist. Die Tabelle ist nicht für die Web-API verfügbar.	Client-Fehler
405 Methode nicht erlaubt	Dieser Fehler tritt für falsche Methoden und Ressourcenkombinationen auf. Beispielsweise können Sie weder DELETE noch PATCH bei einer Sammlung von Tabellen verwenden. Diese Situation kann bei folgenden Fehlertypen auftreten: InvalidOperation NotSupported	Client-Fehler
501 Nicht implementiert	Nehmen Sie diese Antwort an, wenn ein angeforderter Vorgang nicht implementiert wird.	Serverfehler
503 – Dienst ist nicht verfügbar	Nehmen Sie diese Antwort an, wenn der Web-API-Service nicht verfügbar ist.	Serverfehler

Analysefehler von der Antwort

Betrachten Sie die folgende Beispiel-HTTP-Antwort, die noch den inneren Fehler enthält:

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

Fehlercodes

Fehlercodes werden für alle behandelten Szenarien im Hexadezimalformat angezeigt. In der folgenden Tabelle sind alle Fehlercodes mit ihren jeweiligen Namen und Meldungen aufgeführt.

Fehlercode	Fehlername	Fehlermeldung
900400FF	NoAttributesForTableCreate	Keine Attribute zur Aktion „Tabelle erstellen“.
90040100	InvalidAttribute	Die Attribut {0} wurde in der Tabelle {1} nicht gefunden.
90040101	AttributePermissionIsMissing	Das Attribut {0} in der Tabelle {1} ist für die Web-API nicht aktiviert.
90040102	TablePermissionWriteIsMissingDuringUpdate	Sie besitzen keine Berechtigung zum Aktualisieren der Entität {0}.
90040103	TablePermissionCreateIsMissing	Sie besitzen keine Berechtigung zum Erstellen der Entität {0}.
90040104	TablePermissionDeleteIsMissing	Sie besitzen keine Berechtigung zum Löschen der Entität {0).
90040105	TablePermissionAppendIsMissngDuringAssociationChange	Sie sind nicht berechtigt, die Tabelle {0} {1} zuzuordnen oder die Zuordnung aufzuheben.
90040106	TablePermissionAppendToIsMissingDuringAssociationChange	Sie sind nicht berechtigt, die Tabelle {1} {0} zuzuordnen oder die Zuordnung aufzuheben.
90040107	HttpAntiForgeryException	Das Anti-Fälschungs-Cookie-Token und das Formularfeld-Token stimmen nicht überein.
90040109	MissingPortalSessionCookie	Ein ungültiges Sitzungstoken wurde an die auslösende Methode übergeben.
9004010C	ResourceDoesNotExists	Die Ressource wurde für das Segment ‚{0}‘ nicht gefunden.
9004010D	CDSError	CDS-Fehler

Die Antwort auf nicht behandelte Fehler mit dem HTTP-Statuscode 500 gibt den Fehler „Bei der Verarbeitung der Anforderung ist ein unerwarteter Fehler aufgetreten“ zurück.

Freigeben über