Freigeben über

OData zur Abfrage von Daten verwenden

  • Artikel

Jede Abfrage beginnt mit einer Sammlung von Entitäten. Entitätssammlungen können sein:

EntitySet Ressourcen

Um alle EntitySet in Ihrem Umgebung verfügbaren Ressourcen zu finden, senden Sie eine GET Anfrage an das Web-API- Servicedokument:

Anforderung:

GET [Organization URI]/api/data/v9.2/
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Antwort:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata",
    "value": [
        {
            "name": "aadusers",
            "kind": "EntitySet",
            "url": "aadusers"
        },
        {
            "name": "accountleadscollection",
            "kind": "EntitySet",
            "url": "accountleadscollection"
        },
        {
            "name": "accounts",
            "kind": "EntitySet",
            "url": "accounts"
        },
      ... <Truncated for brevity>
   [
}

Tipp

Diese Werte sind in der Regel der Pluralname der Tabelle, aber sie können auch anders lauten. Verwenden Sie die Ergebnisse dieser Anfrage, um zu bestätigen, dass Sie den richtigen EntitySet Ressourcennamen verwenden.

Beginnen Sie beispielsweise mit der accounts EntitySet-Ressource, um Daten vom Konto-Entitätstyp abzurufen.

GET [Organization URI]/api/data/v9.2/accounts

Gefilterte Sammlungen

Sie können jede Sammlung von Entitäten abfragen, die durch eine Navigationseigenschaft mit Sammlungswert eines angegebenen Datensatzes dargestellt werden. Wenn Sie beispielsweise Daten vom Kontoentitätstyp abrufen möchten, bei dem ein bestimmter Benutzer der Besitzer ist, können Sie die user_accounts sammlungswertige Navigationseigenschaft aus dem angegebenen Systembenutzer Datensatz verwenden.

GET [Organization URI]/api/data/v9.2/systemusers(<systemuserid value>)/user_accounts?$select=name

Um den Namen der Navigationseigenschaft mit dem Wert einer Sammlung zu finden:

Daten abrufen

Um Daten aus einer Sammlung abzurufen, senden Sie eine GET Anfrage an die Sammlungsressource. Das folgende Beispiel zeigt das Abrufen von Daten vom Konto-Entitätstyp.

Dieses Beispiel zeigt auch:

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,statecode,statuscode&$orderby=name&$top=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Antwort:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

{
   "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,statecode,statuscode)",
   "value": [
      {
         "@odata.etag": "W/\"112430907\"",
         "name": "A. Datum Corporation (sample)",
         "statecode@OData.Community.Display.V1.FormattedValue": "Active",
         "statecode": 0,
         "statuscode@OData.Community.Display.V1.FormattedValue": "Active",
         "statuscode": 1,
         "accountid": "4b757ff7-9c85-ee11-8179-000d3a9933c9"
      }
   ]
}

Abfrage verfeinern

Nachdem Sie die Tabelle ausgewählt haben, mit der Ihre Abfrage beginnen soll, verfeinern Sie die Abfrage, um die benötigten Daten zu erhalten. In den folgenden Artikeln wird erläutert, wie Sie Ihre Abfrage vervollständigen.

Artikel Aufgabe
Spalten auswählen Geben Sie an, welche Datenspalten zurückgegeben werden sollen.
Tabellen verbinden Geben Sie an, welche zugehörigen Tabellen in den Ergebnissen zurückgegeben werden sollen.
Bestellzeilen Geben Sie die Sortierreihenfolge der Zeilen an, die zurückgegeben werden sollen.
Filterzeilen Geben Sie an, welche Datenzeilen zurückgegeben werden sollen.
Seitenergebnisse Geben Sie an, wie viele Datenzeilen mit jeder Anforderung zurückgegeben werden sollen.
Aggregatdaten So gruppieren und aggregieren Sie die zurückgegebenen Daten.
Anzahl der Zeilen So ermitteln Sie die Anzahl der zurückgegebenen Zeilen.
Leistungsoptimierungen So optimieren Sie die Leistung

OData-Abfrageobtionen

Verwenden Sie diese Optionen, um die von einer Sammlung zurückgegebenen Ergebnisse zu ändern. Die folgende Tabelle beschreibt die OData Abfrageoptionen, die die Dataverse Web-API unterstützt.

Option Verwendet um Weitere Informationen
$select Fordern Sie einen bestimmten Satz von Eigenschaften für jede Entität oder jeden komplexen Typ an. Spalten auswählen
$expand Geben Sie die zugehörigen Ressourcen an, die in Übereinstimmung mit den abgerufenen Ressourcen eingeschlossen werden sollen. Tabellen verbinden
$orderby Fordern Sie Ressourcen in einer bestimmten Reihenfolge an. Bestellzeilen
$filter Eine Sammlung von Ressourcen filtern. Filterzeilen
$apply Daten gruppieren und aggregieren. Aggregatdaten
$top Die Anzahl der Elemente in der abgefragten Sammlung, die in das Ergebnis einbezogen werden sollen definieren. Begrenzen Sie die Anzahl der Zeilen
$count Fordern Sie eine Anzahl der übereinstimmenden Ressourcen an, die in den Ressourcen in der Antwort enthalten sind. Anzahl der Zeilen

Um mehrere Optionen anzuwenden, trennen Sie die Abfrageoptionen durch ein Fragezeichen (?) vom Ressourcenpfad. Trennen Sie die einzelnen Optionen nach der ersten durch ein Et-Zeichen (&). Bei Optionsnamen wird zwischen Groß- und Kleinschreibung unterschieden.

Verwendung von Parameteraliasen mit Systemabfrageoptionen

Sie können Parameteraliase für $filter- und $orderby-Systemabfrageoptionen verwenden, aber derzeit nicht innerhalb der $expand-Option. Parameter-Aliase lassen es zu, dass Sie denselben Wert mehrfach in einer Anfrage verwenden. Wenn dem Alias kein Wert zugeordnet wurde, wird angenommen, dass er NULL ist.

Ohne Parameteraliase:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
&$orderby=revenue asc,name desc
&$filter=revenue ne null

Mit Parameteraliassen:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
&$orderby=@p1 asc,@p2 desc
&$filter=@p1 ne @p3&@p1=revenue&@p2=name

Sie können auch Parameteraliase verwenden, wenn Sie Funktionen verwenden. Erfahren Sie, wie Sie Web-API-Funktionen verwenden

Nicht unterstützte OData-Abfrageoptionen

Die Dataverse Web-API unterstützt die folgenden OData-Abfrageoptionen nicht: $skip,$search,$format.

URL-Längenbeschränkungen

Die Länge einer URL in einer GET Anfrage ist auf 32 KB (32.768 Zeichen) begrenzt. Das Einbinden vieler komplexer OData-Abfrageoptionen als Parameter in die URL kann das Limit erreichen. Sie können einen $batch Vorgang mithilfe einer POST Anfrage ausführen, um die OData-Abfrageoptionen aus der URL in den Textkörper der Anfrage zu verschieben, wo das Limit doppelt so lang ist. Das Senden einer GET-Anfrage innerhalb eines $batch lässt URLs mit einer Länge von bis zu 64 KB (65.536 Zeichen) zu. Erfahren Sie mehr über Batchvorgänge mit der Web-API.

Beschränken der Anzahl von Zeilen

Um die Anzahl der zurückgegebenen Zeilen zu begrenzen, verwenden Sie die $top OData-Abfrageoption. Ohne diese Begrenzung Dataverse werden bis zu 5.000 Zeilen zurückgegeben.

Alternativ können Sie mithilfe von Auslagerung eine Anzahl von Datensätzen angeben, die zurückgegeben werden sollen. Verwenden Sie $top nicht, wenn Sie Datenseiten anfordern. Erfahren Sie, wie Sie ausgelagerte Ergebnisse anfordern

Einschränkungen

Es gibt einige Dinge, die Sie mit FetchXml tun können, die von OData nicht unterstützt werden.

Community-Tools

Hinweis

Von der Community erstellte Tools werden von Microsoft nicht unterstützt. Wenn Sie Fragen oder Probleme mit Community-Tools haben, wenden Sie sich an den Herausgeber des Tools.

Der Dataverse REST Builder ist ein Open-Source-Projekt, das eine Benutzeroberfläche bereitstellt, die Sie bei der Verwendung der Dataverse Web-API bei vielen Aufgaben unterstützt, einschließlich der Erstellung von Abfragen.

Die XrmToolBox FetchXMLBuilder ist ein kostenloses Tool zum Erstellen und Testen von FetchXml-Anfragen, generiert aber auch Code für OData-Abfragen mit derselben Designer-Erfahrung.

Funktionen von OData Version 4.0

Die Dataverse Web-API ist ein OData-Dienst der Version 4.0. In den folgenden Abschnitten der OData 4.0-Spezifikation wird das Abrufen von Daten beschrieben:

Dieser Artikel und die anderen Artikel in diesem Abschnitt beschreiben die Teile der 4.0 OData-Spezifikation, die von der Dataverse Web-API implementiert werden, und wie Sie diese zum Abrufen von Geschäftsdaten verwenden können Dataverse.

Hinweis

Die OData-Version 4.01 ist die neuste Version. Es enthält Verbesserungen und zusätzliche Funktionen, die in Version 4.0 nicht verfügbar sind und daher derzeit nicht in der Dataverse Web-API verfügbar sind.

Nächste Schritte,

Lernen Sie, wie man Spalten auswählt.

Spalten auswählen

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).