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

  • Artikel

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.

Siehe auch