OData zur Abfrage von Daten verwenden

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

• EntitySet-Ressourcen: Eine der Web-API-EntitySet-Sammlungen.
• Gefilterte Sammlungen: Eine Reihe von Entitäten, die von einer sammlungsbewerteten Navigationseigenschaft für einen bestimmten Datensatz zurückgegeben werden.
• Eine erweiterte sammlungswertige Navigationseigenschaft.
• Eine von einer Funktion zurückgegebene Sammlung.

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>
   [
}

Beginnen Sie beispielsweise mit der accounts EntitySet-Ressource, um Daten aus dem Kontoentitä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 z. B. Daten aus dem Kontoentitätstyp abrufen möchten, bei dem ein bestimmter Benutzender der OwningUser ist, können Sie die sammlungswertige Navigationseigenschaft user_accounts aus dem angegebenen systemuser-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:

• Für alle Dataverse-Tabellen und -Beziehungen können Sie den Web API Entity Type Reference überprüfen
• Für angepasste Tabellen oder Beziehungen suchen Sie nach den Navigationseigenschaften mit Sammlungswerten innerhalb des $Metadaten Service Dokuments.

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 Kontoentitätstyp.

Dieses Beispiel zeigt auch:

• Das Begrenzen der zurückgegebenen Spalten mit $select Weitere Informationen zur Auswahl von Spalten
• Das Sortieren der Ergebnisse mithilfe von $orderby. Erfahren Sie mehr über das Sortieren von Spalten
• Das Begrenzen der zurückgegebenen Reihen mit $top. Erfahren Sie mehr über das Beschränken der Anzahl von Zeilen
• Anzeige formatierter Werte mithilfe des Anforderungsheaders: Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue". Erfahren Sie mehr über formatierte Werte

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.

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.

Wenn Sie mehrere Optionen anwenden möchten, trennen Sie die Abfrageoptionen mit einem Fragezeichen (?) vom Ressourcenpfad. Trennen Sie jede Option nach der ersten mit einem kaufmännischen Und-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 mehr über die Verwendung von Web-API-Funktionen

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änger einer URL in einer GET-Anforderung wird auf 32 KB (32.768 Zeichen) begrenzt. Die Einbeziehung vieler komplexer OData-Abfrageoptionen als Parameter in die URL kann dazu führen, dass der Grenzwert erreicht wird. Sie können einen $batch-Vorgang mit einer POST-Anforderung als eine Methode zum Verschieben von OData-Abfrageoptionen aus der URL und in den Anforderungstext verwenden. Dort ist der Grenzwert doppelt so hoch. 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 mithilfe 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 diesen Grenzwert gibt Dataverse bis zu 5.000 Zeilen zurück.

Alternativ können Sie mithilfe von Auslagerung eine Anzahl von Datensätzen angeben, die zurückgegeben werden sollen. Verwenden Sie $top nicht, wenn Sie Seiten mit Daten 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.

• Sie können Tabellen nicht völlig ohne Beziehung verknüpfen. OData erlaubt nur die Verwendung der Abfrageoption $expand zum Verknüpfen von Tabellen mithilfe von Navigationseigenschaften, die Teil von Beziehungen im Datenmodell sind.

• Sie können keine verschachtelten $expand mit N:N-Beziehung verwenden.

• Unter Aggregationsbeschränkungen werden die folgenden Beschränkungen für Aggregationen mit OData aufgeführt:

  • Eindeutige Zahlen mit CountColumn erhalten
  • Zeitzone beim Gruppieren nach Datum
  • Zeilenaggregat
  • Limit pro Abfrage

• Tabellenübergreifende Spaltenvergleiche durchführen. OData unterstützt das Filtern von Spaltenwerten in derselben Zeile, diese müssen sich jedoch in derselben Tabelle befinden.

• Sie brauchen die Standardsortierreihenfolge für Auswahlspalten nicht zu überschreiben. Das Standardverhalten beim Sortieren von Auswahlspalten besteht darin, die ganzzahligen Werte anstelle des lokalisierten Beschriftungswerts zu verwenden.

• Sie können die Leistungsoptimierung „Late Materialize“-Abfrage nicht verwenden.

Community-Tools

Der Dataverse REST-Generator ist ein Open-Source-Projekt, das eine Benutzeroberfläche bereitstellt, mit der Sie viele Dinge mit der Dataverse-Web-API tun können, wie zum Beispiel Abfragen verfassen.

Die XrmToolBoxFetchXMLBuilder ist ein kostenloses Tool zum Erstellen und Testen von FetchXml-Anforderungen, generiert aber auch Code für -Abfragen mit derselben Designererfahrung.

Funktionen von OData Version 4.0

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

• OData-Version 4.0. Teil 1: Protokoll plus Errata 03 11.2 Daten anfordern
• OData-Version 4.0. Teil 2: URL-Konventionen plus Errata 03 5 Abfrageoptionen

In diesem und in den anderen Artikeln dieses Abschnitts werden die Teile der OData-Spezifikation 4.0 beschrieben, die von der Dataverse-Web-API implementiert werden. Darüber hinaus wird beschrieben, wie Sie sie zum Abrufen von Geschäftsdaten aus Dataverse verwenden können.

Nächste Schritte,

Lernen Sie, wie man Spalten auswählt.