HTTP-Anforderungen verfassen und Fehler beheben

Veröffentlicht: Januar 2017

Gilt für: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Sie interagieren mit dem Web API, indem Sie HTTP-Anforderungen erstellen und senden. Sie müssen wissen, wie die entsprechenden HTTP-Kopfzeilen festgelegt werden und auf mögliche Fehler in der Antwort reagieren.

In diesem Thema

Web-API-URL und Versionen

HTTP-Methoden

HTTP-Kopfzeilen

Ermitteln von Statuscodes

Analysefehler von der Antwort

Web-API-URL und Versionen

Um auf das Web-API zuzugreifen müssen Sie eine URL mithilfe von Komponenten der folgenden Tabelle verfassen.

Die URL, die Sie verwenden, wird mit diesen Teilen zusammengesetzt: Protokoll + Basis-URL + Web-API-Pfad + Version + Ressource.

Versionskompatibilität

In dieser Version haben wir einige Zusatzänderungen mit jedem Update oder Service Pack angewendet. Wenn die Updates übernommen werden, werden dieselben Funktionen den folgenden Nebenversionen hinzugefügt. Wenn Sie also Version 8.2 verwenden können, dann haben Version 8.1 und 8,0 dieselben Features. Dies ist möglich, da alle Änderungen additiv bzw. Programmfehlerbehebungen waren, welche die Elemente betreffen, die in Microsoft Dynamics 365-Web-API-Einschränkungen aufgeführt sind. Es wurden keine grundlegenden Änderungen eingeführt.

HTTP-Methoden

HTTP-Anforderungen können zahlreiche verschiedene Methoden anwenden. Wenn Sie die Internet-API verwenden, werden Sie nur die in der folgenden Tabelle aufgeführten Methoden anwenden.

HTTP-Kopfzeilen

Obwohl das OData-Protokoll sowohl das Format JSON als auch ATOM zulässt, unzerstützt die Web API nur JSON. Deshalb können folgende Kopfzeilen angewandt werden.

Jede Anfrage sollte den Accept-Kopfzeilenwert von application/json beinhalten, auch wenn keine Antwort erwartet wird. Jeder Fehler, der in der Antwort zurückgegeben wurde, wird zurückgegeben als JSON. Auch wenn Ihr Code verwendet werden kann, wenn die Kopfzeile nicht enthalten ist, sollten Sie sie im Rahmen der bewährten Methoden einschließen.

Die aktuelle OData-Version ist 4.0, aber zukünftige Versionen werden die Möglichkeit bieten neue Funktionen zu verwenden. Um sicherzustellen dass es keine Verwechselung der OData-Version für den Code gibt, sollten Sie immer eine die aktuellen OData-Version sowie die neustmögliche Version für den Code angeben. Verwenden Sie OData-Version und OData-MaxVersion Kopfzeilen, um einen Wert auf 4.0 zu setzen.

Alle HTTP-Kopfzeilen sollten folgende mindestens folgende Kopfzeilen enthalten.

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

Jede Anfrage, die JSON-Daten im Anforderungstext enthält, muss eine Content-Type-Kopfzeile mit einem Wert für application/json beinhalten.

Content-Type: application/json

Sie können zusätzliche Kopfzeilen verwenden, um bestimmte Möglichkeiten zu aktivieren.

• Um Daten für Erstellen- (POST) oder Aktualisieren-Vorgänge (PATCH) für Entitäten zurückzugeben, nutzen Sie die return=representation-Einstellung. Wenn diese Einstellung auf eine POST-Anfrage angewendet wurde, hat eine erfolgreiche Antwort den Status 201 (Created). Eine PATCH-Anfrage hat eine erfolgreiche Antwort den Status 200 (OK). Ohne diese angewendete Einstellung haben beide Vorgänge Status 204 (No Content), um anzuzeigen, dass standardmäßig keine Daten im Textteil der Antwort zurückgegeben werden.

  Hinweis

  Diese Funktion wurde mit Update für Dynamics 365 (online und lokal), Dezember 2016 hinzugefügt.

• Zum über eine Abfrage formatierte Werte zurückzugeben, beziehen Sie die odata.include-annotations-Einstellung mit dem Wert Microsoft.Dynamics.CRM.formattedvalue über die Kopfzeile ein.Weitere Informationen:Formatierte Werte einschließen

• Sie können die Prefer-Kopfzeile mit der odata.maxpagesize-Option auch dazu verwenden, anzugeben, wie viele Seiten Sie zurückgeben möchten.Weitere Informationen:Geben Sie die Anzahl der in einer Seite zurückzugebenden Entitäten an

• Um den Kontaxt eines andern Benutzers zu nutzen wenn der Aufrufer die entsprechenden Berechtigungen hat, fügen Sie die MSCRMCallerID-Kopfzeile mit dem systemuserid-Wert des Benutzers hinzu.Weitere Informationen:Annehmen eines anderen Benutzerkontos mit Web API.

• Um die optimistische Parallelität anzuwenden, können Sie die If-Match-Header mit einem Wert Etag anwenden.Weitere Informationen:Optimistische Parallelität anwenden.

• Um die Duplikaterkennung für eine POST-Anforderung zu aktivieren, können Sie den MSCRM.SuppressDuplicateDetection: false-Header verwenden.Weitere Informationen:244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection

• Um zu steuern, ob ein Upsert-Vorgang tatsächlich eine Entität erstellt oder aktualisiert, können Sie die Kopfzeilen If-Match and If-None-Match verwenden.Weitere Informationen:Upsert einer Entität.

• Wenn Sie Batchbetriebe ausführen, müssen Sie in der Anforderung verschiedene Kopfzeilen anwenden sowie für jeden Teil, in dem der Text gesendet wird.Weitere Informationen:Ausführen von Batchbetrieben mithilfe der Web-API.

Ermitteln von Statuscodes

Egal, ob eine HTTP-Anforderung erfolgreich ist oder fehlschlägt, die Antwort umfasst einen Statuscode. Die Statuscodes, die durch Microsoft Dynamics 365 Web API zurückgegeben werden umfassen Folgendes.

Analysefehler von der Antwort

Details zu Fehlern sind als JSON in der Antwort enthalten. Fehler werden in diesem Format angezeigt.

 { "error":{ "code": "
         <This code is not related to the http status code and is frequently empty>", "message": "
         <A message describing the error>", "innererror": { "message": "
         <A message describing the error, this is frequently the same as the outer message>", "type": "Microsoft.Crm.CrmHttpException", "stacktrace": "
         <Details from the server about where the error occurred>" } } }

Siehe auch

Vorgänge mithilfe der Web-API ausführen
Datenabfrage mit Web-API
Erstellen einer Entität mithilfe des Web-API
Abrufen einer Entität mithilfe des Web-API
Entitäten aktualisieren und löschen mithilfe der Web API
Entitäten zuordnen und Zuordnungen aufheben mithilfe der Web API
Nutzen von Web-API-Funktionen
Nutzen von Web-API-Aktionen
Ausführen von Batchbetrieben mithilfe der Web-API
Annehmen eines anderen Benutzerkontos mit Web API
Bedingte Vorgänge mithilfe der Web-API ausführen

Microsoft Dynamics 365

© 2017 Microsoft. Alle Rechte vorbehalten. Copyright