HTTP-Anforderungen erstellen und Fehler behandeln

Sie interagieren mit der 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.

Web-API-URL und Versionen

So finden Sie die Web-API-URL für Ihre Umgebung:

1. Melden Sie sich bei Power Apps an, und wählen Sie dann Ihre Umgebung in der oberen rechten Ecke aus.

2. Wählen Sie die Schaltfläche Einstellungen in der oberen rechten Ecke und wählen Sie dann Entwickler-Ressourcen.

   

   Von hier aus können Sie den Wert für den Web-API-Endpunkt kopieren. Weitere Informationen finden Sie unter Anzeigen von Entwicklerressourcen.

In der folgenden Tabelle werden die Teile der URL beschrieben:

Die URL, die Sie verwenden, setzt sich aus diesen Teilen zusammen:

Protokoll + Umgebungsname + Region + Basis-URL + Web-API-Pfad + Version + Ressource.

Abrufen der Web-API-URL aus dem Ermittlungsdienst

Jeder Mandant kann über mehrere Umgebungen verfügen. Der Ermittlungsdienst gibt Informationen zu den Umgebungen zurück, die im Mandanten vorhanden sind. Dieser Dienst gibt eine Liste von Datensätzen Instance zurück. Die Instance.ApiUrl Eigenschaft stellt dieBasis-URL derProtokollumgebungsumgebung + + + für die Umgebung bereit.

Maximale URL-Länge

Die maximale URL-Länge, die der Dienst akzeptiert, beträgt 32 KB (32.768 Zeichen). Diese Länge eignet sich für die meisten Arten von Anforderungen, mit Ausnahme bestimmter GET Vorgänge, die sehr lange Zeichenfolgenabfrageparameter erfordern, z. B. Abfragen, die FetchXml verwenden. Wenn Sie Anfragen innerhalb des Hauptteils einer $batch-Anforderung senden, können Sie Anforderungen mit URLs von bis zu 64 KB (65.536 Zeichen) senden. Erfahren Sie mehr über das Senden von FetchXML innerhalb einer $batch-Anforderung.

Maximale OData-Segmentlänge

Die maximale Länge eines einzelnen Abschnitts in einer OData-Anforderung beträgt 260 Zeichen. Wenn ein einzelnes Segment der OData-Anforderung mehr als 260 Zeichen lang ist, gibt die Anforderung zurück 400 Bad Request - Invalid URL. Das Segment ist der Teil "Ressource" der URL und enthält alle Zeichen, die zum Beschreiben des Endpunkts und aller Inlineparameter erforderlich sind.

Wenn die Anforderung beispielsweise api/data/v9.2/MyApi(MyParameter='longvalue') ist, dann ist MyApi(MyParameter='longvalue') das Segment, das 260 Zeichen nicht überschreiten kann. Verwenden Sie immer Parameteraliase mit OData-Funktionen. Wenn Sie beispielsweise Ihre Funktion wie /api/data/v9.2/MyApi(MyParameter=@alias)?@alias='longvalue' zusammenstellen, wird das Segment auf nur MyApi(MyParameter=@alias) gekürzt. Erfahren Sie mehr über die Verwendung von Parameteraliasen mit Web-API-Funktionen.

Versionskompatibilität

In dieser Version werden Funktionen eingeführt, die in früheren Versionen nicht unterstützt werden. Nachfolgende Nebenversionen bieten möglicherweise mehr Funktionen, die frühere Nebenversionen nicht unterstützen. Ihr für v9.0 geschriebener Code funktioniert weiterhin in zukünftigen Versionen, wenn Sie in Ihrer URL auf v9.0 verweisen.

Wenn neue Funktionen eingeführt werden, können sie mit früheren Versionen in Konflikt stehen. Diese wichtigen Änderungen sind erforderlich, um den Dienst zu verbessern. In den meisten Fällen bleiben die Funktionen zwischen Versionen gleich, aber nehmen Sie nicht an, dass sie es immer tun.

HTTP-Methoden

In der folgenden Tabelle sind die HTTP-Methoden aufgeführt, die Sie mit der Dataverse Web-API verwenden können.

HTTP-Kopfzeilen

Fügen Sie mindestens die folgenden Header in alle HTTP-Anforderungen ein.

Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
If-None-Match: null

Obwohl das OData-Protokoll sowohl das JSON- als auch ATOM-Format zulässt, unzerstützt die Web-API nur JSON. Jede Anfrage sollte den Accept-Kopfzeilenwert von application/json beinhalten, auch wenn keine Antwort erwartet wird. Die Web-API gibt einen Fehler in der Antwort als JSON zurück. Ihr Code sollte auch dann funktionieren, wenn dieser Header nicht enthalten ist, fügen Sie ihn als bewährte Methode hinzu.

Die aktuelle OData-Version ist 4.0, aber zukünftige Versionen können neue Funktionen einführen. Um sicherzustellen, dass es keine Mehrdeutigkeit über die OData-Version gibt, die für Ihren Code gilt, schließen Sie immer eine explizite Anweisung der aktuellen OData-Version und die maximale Version ein. Verwenden Sie beide OData-Version- und OData-MaxVersion-Header, die auf den Wert 4.0 festgelegt sind.

Abfragen, die Eigenschaften für die Sammlungswertnavigation erweitern, geben möglicherweise zwischengespeicherte Daten für diese Eigenschaften zurück, die keine kürzlich vorgenommenen Änderungen widerspiegeln. Fügen Sie den If-None-Match: null-Header im Anforderungstext ein, um die Browser-Caching der Web-API-Anforderung zu überschreiben. Weitere Informationen finden Sie unter Hypertext Transfer Protocol (HTTP/1.1): Bedingte Anforderungen 3.2: If-None-Match.

Jede Anfrage, die JSON-Daten im Anforderungstext enthält, muss einen Content-Type-Header mit einem Wert von application/json beinhalten.

Content-Type: application/json  

Verwenden Sie andere Header, um bestimmte Funktionen zu aktivieren.

Bevorzugte Header

Verwenden Sie die Prefer-Kopfzeile mit den folgenden Werten, um Einstellungen anzugeben.

Anmerkungen anfordern

Sie können verschiedene OData-Anmerkungsdaten anfordern, die mit den Ergebnissen zurückgegeben werden sollen, indem Sie den Prefer: odata.include-annotations Anforderungsheader verwenden. Sie können auswählen, ob alle Anmerkungen zurückgegeben oder bestimmte Anmerkungen angegeben werden sollen. Die folgende Tabelle beschreibt die Anmerkungen, die die Dataverse Web-API unterstützt:

Um bestimmte Anmerkungen anzufordern, fügen Sie sie als durch Trennzeichen getrennte Werte ein. Sie können auch das Zeichen „*“ als Platzhalter verwenden. Der folgende Prefer Anforderungsheader enthält beispielsweise nur die formatierten Werte und alle zusätzlichen Fehlerdetailanmerkungen:

Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue,Microsoft.PowerApps.CDS.ErrorDetails*"

Andere Überschriften

Wenn Sie Batchvorgänge ausführen, müssen Sie in der Anforderung viele verschiedene Kopfzeilen anwenden sowie für jeden Teil, in dem der Text gesendet wird. Weitere Informationen: Ausführen von Batchvorgängen mit der Web-API.

Ermitteln von Statuscodes

Ob eine HTTP-Anforderung erfolgreich war oder nicht, die Antwort enthält einen Statuscode. Die folgende Tabelle beschreibt die Statuscodes, die von der Microsoft Dataverse Web-API zurückgegeben werden.

Parsing-Fehler in der Antwort

Die Antwort enthält Details zu Fehlern als JSON im folgenden Format.

{  
 "error":{  
  "code": "<This code is not related to the http status code and is frequently empty>",  
  "message": "<A message describing the error>"  
 }  
}  

Mehr Details mit Fehlern angeben

Einige Fehler enthalten weitere Details durch Anmerkungen. Wenn eine Anforderung den Prefer: odata.include-annotations="*" Header enthält, enthält die Antwort alle Anmerkungen, die weitere Details zu Fehlern enthalten, und eine URL, die Sie möglicherweise an bestimmte Anleitungen für den Fehler weiterleiten kann.

Entwickler, die Plug-Ins schreiben, können einige dieser Details festlegen. Angenommen, Sie haben ein Plug-In, das einen Fehler auslöst, indem Sie den InvalidPluginExecutionException(OperationStatus, Int32, String) -Konstruktor verwenden. Dieser Konstruktor akzeptiert einen OperationStatus Wert, einen benutzerdefinierten Ganzzahlfehlercode und eine Fehlermeldung.

Eine einfaches Plug-In könnte so aussehen:

namespace MyNamespace
{
    public class MyClass : IPlugin
    {
        public void Execute(IServiceProvider serviceProvider)
        {

            // Obtain the tracing service
            ITracingService tracingService =
            (ITracingService)serviceProvider.GetService(typeof(ITracingService));

            tracingService.Trace("Entering MyClass plug-in.");

             try
            {
                throw new InvalidPluginExecutionException(OperationStatus.Canceled, 12345, "Example Error Message.");
            }
            catch (InvalidPluginExecutionException ex)
            {
                tracingService.Trace("StackTrace:");
                tracingService.Trace(ex.StackTrace);
                throw ex;
            }
        }
    }
}

Wenn Sie dieses Plug-In bei der Nachricht "Erstellen" einer Kontoentität registrieren und die Anforderung zum Erstellen eines Kontos die odata.include-annotations="*" Einstellung enthält, sieht die Anforderung und Antwort wie im folgenden Beispiel aus:

Anforderung:

POST https://yourorg.api.crm.dynamics.com/api/data/v9.2/accounts HTTP/1.1
Content-Type: application/json;
Prefer: odata.include-annotations="*"
{
    "name":"Example Account"
}

Antwort:

HTTP/1.1 400 Bad Request
Content-Type: application/json; odata.metadata=minimal
{
    "error": {
        "code": "0x80040265",
        "message": "Example Error Message.",
        "@Microsoft.PowerApps.CDS.ErrorDetails.OperationStatus": "1",
        "@Microsoft.PowerApps.CDS.ErrorDetails.SubErrorCode": "12345",
        "@Microsoft.PowerApps.CDS.HelpLink": "http://go.microsoft.com/fwlink/?LinkID=398563&error=Microsoft.Crm.CrmException%3a80040265&client=platform",
        "@Microsoft.PowerApps.CDS.TraceText": "\r\n[MyNamespace: MyNamespace.MyClass ]\r\n[52e2dbb9-85d3-ea11-a812-000d3a122b89: MyNamespace.MyClass : Create of account] \r\n\r\n Entering MyClass plug-in.\r\nStackTrace:\r\n   at MyNamespace.MyClass.Execute(IServiceProvider serviceProvider)\r\n\r\n"
        "@Microsoft.PowerApps.CDS.InnerError.Message": "Example Error Message."
    }
}

Die folgende Tabelle beschreibt die Anmerkungen in der Antwort.

Wenn Sie nicht alle Anmerkungen in der Antwort empfangen möchten, können Sie angeben, welche Anmerkungen zurückgegeben werden sollen. Verwenden Sie anstelle von Prefer: odata.include-annotations="*" folgenden Wert, um nur formatierte Werte für Vorgänge zu erhalten, die Daten abrufen, und verwenden Sie den Hilfelink, wenn ein Fehler auftritt: Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue,Microsoft.PowerApps.CDS.HelpLink".

Weitere Informationen: Anforderungsanmerkungen

Eine gemeinsame Variable aus der Web-API hinzufügen

Sie können einen Zeichenfolgenwert festlegen, der für Plug-Ins im ExecutionContext in der SharedVariables-Sammlung verfügbar ist. Weitere Informationen finden Sie unter:

• Eine gemeinsam genutzte Variable zum Plug-In-Ausführungskontext hinzufügen
• Freigegebene Variablen

Siehe auch

Vorgänge mit der Web-API ausführen
Datenabfrage mit Web-API
Erstellen einer Tabellenzeile mithilfe der Web-API
Abrufen einer Tabellenzeile über die Web-API
Aktualisieren und Löschen von Tabellenzeilen über die Web-API
Vorhandene Tabellenzeilen über die Web-API zuordnen und Zuordnung wieder aufheben
Nutzen von Web-API-Funktionen
Web-API-Aktionen verwenden
Ausführen von Batchbetrieben mithilfe der Web-API
Einen anderen Benutzer mit der Web-API übernehmen
Führen Sie bedingte Vorgänge mithilfe der Web-API aus.