Teilen über

OData zur Abfrage von Daten verwenden

Jede Abfrage beginnt mit einer Sammlung von Entitäten. Entitätssammlungen umfassen:

EntitySet Ressourcen

Um alle EntitySet in Ihrer Umgebung verfügbaren Ressourcen zu finden, senden Sie eine GET Anforderung an das Web-API Dienstdokument:

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

Trinkgeld

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

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 eine beliebige Sammlung von Entitäten abfragen, die eine navigationsbezogene Eigenschaft mit Listenwert für einen bestimmten Datensatz darstellt. Wenn Sie beispielsweise Daten aus dem Kontoentitätstyp abrufen möchten, bei dem ein bestimmter Benutzer " OwningUser" ist, verwenden Sie die user_accounts Sammlungswert-Navigationseigenschaft aus dem angegebenen Systembenutzerdatensatz .

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

Der Name der sammlungswertigen Navigationseigenschaft:

Daten abrufen

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

Dieses Beispiel zeigt außerdem:

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 zum Starten der Abfrage ausgewählt haben, verfeinern Sie die Abfrage, um die benötigten Daten abzurufen. 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.
Zeilen anordnen Geben Sie die Sortierreihenfolge der Zeilen an, die zurückgegeben werden sollen.
Zeilen filtern Geben Sie an, welche Datenzeilen zurückgegeben werden sollen.
Seitenergebnisse Geben Sie an, wie viele Datenzeilen mit jeder Anforderung zurückgegeben werden sollen.
Daten aggregieren So gruppieren und aggregieren Sie die zurückgegebenen Daten.
Anzahl der Zeilen zählen 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 abgerufenen Ressourcen eingeschlossen werden sollen. Tabellen verbinden
$orderby Fordern Sie Ressourcen in einer bestimmten Reihenfolge an. Zeilen anordnen
$filter Eine Sammlung von Ressourcen filtern. Zeilen filtern
$apply Daten gruppieren und aggregieren. Daten aggregieren
$top Geben Sie die Anzahl der Elemente in der abgefragten Auflistung an, die in das Ergebnis eingeschlossen werden soll. Anzahl der Zeilen begrenzen
$count Fordern Sie eine Zählung der übereinstimmenden Ressourcen an, die in die Antwort aufgenommen werden sollen. Anzahl der Zeilen zählen

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 der Alias keinen zugewiesenen Wert aufweist, ist er NULL.

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 nicht die folgenden OData-Abfrageoptionen: $skip, , $searchund $format.

Beschränkungen der URL-Länge

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 ausführen, indem Sie eine POST Anforderung verwenden, um die OData-Abfrageoptionen aus der URL und in den Textkörper der Anforderung zu verschieben, wobei der Grenzwert zweimal so lang ist. Durch Senden einer Anforderung innerhalb einer GET$batchAnforderung können Sie URLs mit einer Länge von bis zu 64 KB (65.536 Zeichen) verwenden. Erfahren Sie mehr über Batchvorgänge mithilfe der Web-API.

Anzahl der Zeilen begrenzen

Verwenden Sie die $top OData-Abfrageoption, um die Anzahl der zurückgegebenen Zeilen zu begrenzen. Ohne diesen Grenzwert gibt Dataverse bis zu 5.000 Standardtabellenzeilen und 500 elastische Tabellenzeilen zurück.

Geben Sie alternativ eine Anzahl von Datensätzen an, die mithilfe von Paging zurückgegeben werden sollen. Verwenden Sie $top nicht, wenn Sie Seiten mit Daten anfordern. Erfahren Sie, wie Sie seitenseitige Ergebnisse anfordern.

Einschränkungen

Es gibt einige Dinge, die Sie mithilfe von FetchXml ausführen können, die OData nicht unterstützt.

Community-Tools

Notiz

Microsoft unterstützt keine Tools, die von der Community erstellt wurden. Wenn Sie Fragen oder Probleme mit Communitytools haben, wenden Sie sich an den Herausgeber des Tools.

Der Dataverse REST Builder ist ein Open Source-Projekt , das eine Benutzeroberfläche bereitstellt, mit der Sie viele Dinge mithilfe der Dataverse-Web-API erledigen können, einschließlich der Erstellung von Abfragen.

Das XrmToolBoxFetchXMLBuilder ist ein kostenloses Tool zum Verfassen und Testen von FetchXml-Anforderungen, generiert aber auch Code für OData-Abfragen mithilfe derselben Designerumgebung.

Funktionen von OData Version 4.0

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

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

Notiz

OData Version 4.01 ist die neueste Version. Sie enthält Verbesserungen und weitere Features, 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, wie man Spalten auswählt.

Spalten auswählen

  • Last updated on