Freigeben über

HTTP-Anforderungen verfassen und Fehler beheben

  • Artikel

 

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.

Element

Beschreibung

Protokoll

Das entsprechende Protokoll, entweder https:// oder http://.

Basis-URL

Dies ist die URL, die Sie üblicherweise verwenden, um die Webanwendung zu öffnen.

  • Für Microsoft Dynamics 365 (online) verwenden Sie <tenant name>.crm.dynamics.com.

  • Für Bereitstellung mit Internetzugriff (IFD): Verwenden Sie die entsprechende URL für die Instanz. Dies ist: <organization name>.<domain name>.

  • Für Dynamics 365 (lokal): verwenden Sie <server name>/<organization name>

Web-API-Pfad

Der Pfad zur Web-API ist /api/data/.

Version

Die Version wird auf folgende Weise ausgedrückt: v[Major_version].[Minor_version][PatchVersion]/. Gültige Versionen für diese Version sind:

  • v8.0/ Für Microsoft Dynamics CRM Online 2016-Update 0.1 und Microsoft Dynamics CRM 2016-Update 0.1

  • v8.1/ Für Microsoft Dynamics CRM Online 2016-Update 1 und Microsoft Dynamics CRM 2016 Service Pack 1

  • v8.2/ für Update für Dynamics 365 (online und lokal), Dezember 2016

Der bestimmte Wert, den Sie verwenden, ist bei dieser Version nicht wichtig, wenn Sie die entsprechenden Updates oder Service Packs angewendet haben. Weitere Informationen: Versionskompatibilität

Ressource

Der Name der Entität, Funktion oder Aktionen, die Sie verwenden möchten.

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.

Hinweis

Mit der folgenden Hauptversion (v9) werden Funktionen eingeführt, die nur für diese Version zur Verfügung stehen. Nachfolgende Nebenversionen bieten ggf. weitere Funktionen, die nicht auf die früheren Nebenversionen zurückübertragen werden. Ihr Code, der für v8.x geschrieben ist, funktioniert weiterhin in v9.x, wenn Sie in der URL, die Sie verwenden, auf v8.2 verweisen.

Für die v8.x-Version verwenden Sie die aktuellste Version, die Sie haben und von der Sie wissen, dass Updates und Service Packs in dieser Hauptversion keine wichtigen Änderungen enthalten. Dies wird jedoch in zukünftigen Versionen anders sein, in denen Sie mehr Aufmerksamkeit auf die Version des Services lenken müssen, auf den Sie sich beziehen.

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.

Methode

Verwendung

GET

Wird verwendet, wenn Daten inkl. aufrufender Funktionen abgerufen werden. Der erwartete Statuscode für einen erfolgreiches Abrufen ist 200 OK.

POST

Wird verwendet wenn Entitäten erstellt oder Aktionen aufgerufen werden.

PATCH

Wird verwendet, wenn Entitäten aktualisiert werden oder Upsert Vorgänge ausgeführt werden.

DELETE

Wir verwendet, wenn Entitäten oder Einzelpersoneneigenschaften gelöscht werden.

PUT

Verwendung in bestimmten Fällen zur Aktualisierung einzelner Eigenschaften von Entitäten. Diese Methode wird nicht empfohlen, wenn die meisten Entitäten aktualisiert werden. Verwenden Sie diese Option, wenn Sie Entitäten vorbildliche aktualisieren.

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.

Code

Beschreibung

Typ

200 OK

Dies annehmen, wenn durch den Vorgang Daten im Antworttext zurückgegeben werden.

Erfolgreich

201 Created

Erwarten Sie dies, wenn Ihr Entitäts-POST Vorgang erfolgreich ist und Sie die return-representation Einstellung in der Anfrage angegeben haben.

Hinweis

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

Erfolgreich

204 No Content

Dies annehmen, wenn der Vorgang erfolgreich durchgeführt wird, jedoch keine Daten im Antworttext zurückgegeben werden.

Erfolgreich

304 Not Modified

Dies beim Testen, ob eine Entität seit dem letzten Abruf geändert wurde, annehmen.Weitere Informationen:Bedingte Abrufe

Umleitung

403 Forbidden

Folgendes für die folgenden Fehlertypen annehmen:

  • AccessDenied

  • AttributePermissionReadIsMissing

  • AttributePermissionUpdateIsMissingDuringUpdate

  • AttributePrivilegeCreateIsMissing

  • CannotActOnBehalfOfAnotherUser

  • CannotAddOrActonBehalfAnotherUserPrivilege

  • CrmSecurityError

  • InvalidAccessRights

  • PrincipalPrivilegeDenied

  • PrivilegeCreateIsDisabledForOrganization

  • PrivilegeDenied

  • unManagedinvalidprincipal

  • unManagedinvalidprivilegeedepth

Client-Fehler

401 Unauthorized

Folgendes für die folgenden Fehlertypen annehmen:

  • BadAuthTicket

  • ExpiredAuthTicket

  • InsufficientAuthTicket

  • InvalidAuthTicket

  • InvalidUserAuth

  • MissingCrmAuthenticationToken

  • MissingCrmAuthenticationTokenOrganizationName

  • RequestIsNotAuthenticated

  • TamperedAuthTicket

  • UnauthorizedAccess

  • UnManagedInvalidSecurityPrincipal

Client-Fehler

413 Payload Too Large

Dies annehmen, wenn die Anforderung zu lang ist.

Client-Fehler

400 BadRequest

Dies annehmen, wenn ein Argument ungültig ist.

Client-Fehler

404 Not Found

Dies annehmen, wenn die Ressource nicht vorhanden ist.

Client-Fehler

405 Method Not Allowed

Dieser Fehler tritt für falsche Methoden und Ressourcenkombinationen auf. Beispielsweise können Sie weder DELETE noch PATCH bei einer Sammlung von Entitäten verwenden.

Folgendes für die folgenden Fehlertypen annehmen:

  • CannotDeleteDueToAssociation

  • InvalidOperation

  • NotSupported

Client-Fehler

412 Precondition Failed

Folgendes für die folgenden Fehlertypen annehmen:

  • ConcurrencyVersionMismatch

  • DuplicateRecord

Client-Fehler

500 Internal Server Error

Erwarten Sie dies, wenn eine POST-Anforderung zum Erstellen einer Entität die Duplikaterkennung aktiviert und die zu erstellende Entität ein Duplikat wäre.Weitere Informationen:244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection

Serverfehler

501 Not Implemented

Dies annehmen, wenn ein angeforderter Vorgang nicht implementiert wird.

Serverfehler

503 Service Unavailable

Dies annehmen, wenn der Web-API-Service nicht verfügbar ist.

Serverfehler

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