Teilen über

Datenabfrage mit Web-API

  • Artikel

 

Veröffentlicht: Januar 2017

Gilt für: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Wenn Sie Daten für einen Entitätssatz abrufen möchten, verwenden Sie eine GET-Anforderung. Wenn Sie Daten abrufen, können Sie Abfrageoptionen anwenden, um Kriterien für die gewünschten Daten und für die Entitätseigenschaften, die zurückgegeben werden sollen, festzulegen.

In diesem Thema

Grundlegendes Abfragebeispiel

Beschränkungen der Zahl der zurückgegebenen Entitäten

Geben Sie die Anzahl der in einer Seite zurückzugebenden Entitäten an

Verwenden von Systemabfrageoptionen

Anforderungsspezifische Eigenschaften

Ergebnisse filtern

Reihenfolge von Ergebnissen

Verwendung von Parameteraliasen mit Systemabfrageoptionen

Ergebnisse eingrenzen

Abrufen einer Anzahl von Entitäten

Formatierte Werte einschließen

Abrufen von Daten zu Sucheigenschaften

Filterung von Datensätzen auf Grundlage einer einzelbewerteten Navigationseigenschaft

Abrufen verwandter Entitäten durch Erweitern der Navigationseigenschaften

Grundlegendes Abfragebeispiel

Dieses Beispiel fragt den accounts-Entitätssatz ab und verwendet die Systemabfrageoptionen $select und $top, um die name-Eigenschaft für ersten drei Firmen zurückzugeben:

  • Anforderung

    GET cc_WebAPI_ServiceURI/accounts?$select=name&$top=3 HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

  • Response

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

{
 "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts(name)",
 "value": [
  {
   "@odata.etag": "W/\"501097\"",
   "name": "Fourth Coffee (sample)",
   "accountid": "89390c24-9c72-e511-80d4-00155d2a68d1"
  },
  {
   "@odata.etag": "W/\"501098\"",
   "name": "Litware, Inc. (sample)",
   "accountid": "8b390c24-9c72-e511-80d4-00155d2a68d1"
  },
  {
   "@odata.etag": "W/\"501099\"",
   "name": "Adventure Works (sample)",
   "accountid": "8d390c24-9c72-e511-80d4-00155d2a68d1"
  }
 ]
}

Beschränkungen der Zahl der zurückgegebenen Entitäten

Sofern Sie keine kleinere Seitengröße angeben, wird ein Maximum von 5000 Entitäten pro Anforderung zurückgegeben. Falls mehrere Entitäten vorhanden sind, die mit den Abfragenfilterkriterien übereinstimmen, wird eine @odata.nextLink-Eigenschaft mit den Ergebnissen zurückgegeben. Verwenden Sie den Wert der @odata.nextLink-Eigenschaft mit einer neuen GET-Anforderung, um die nächste Datenseite zurückzugeben.

Hinweis

Abfragen für Modellentitäten werden nicht begrenzt oder in einer Seite ausgegeben.Weitere Informationen:Metadaten mit Web-API abfragen

Geben Sie die Anzahl der in einer Seite zurückzugebenden Entitäten an

Verwenden Sie den odata.maxpagesize-Einstellungswert, um die Anzahl der Entitäten, die in der Antwort zurückgegeben werden, anzufordern.

Hinweis

Sie können keinen odata.maxpagesize-Einstellungswert verwenden, der größer als 5000 ist.

Das folgende Bespiel fragt den accounts -Entitätssatz ab und gibt die name-Eigenschaft für die ersten drei Firmen zurück.

  • Anforderung

    GET cc_WebAPI_ServiceURI/accounts?$select=name HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=3

  • Antwort

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 402
Preference-Applied: odata.maxpagesize=3

{
  "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts(name)",
  "value": [
    {
      "@odata.etag": "W/\"437194\"",
      "name": "Fourth Coffee (sample)",
      "accountid": "7d51925c-cde2-e411-80db-00155d2a68cb"
    },
    {
      "@odata.etag": "W/\"437195\"",
      "name": "Litware, Inc. (sample)",
      "accountid": "7f51925c-cde2-e411-80db-00155d2a68cb"
    },
    {
      "@odata.etag": "W/\"468026\"",
      "name": "Adventure Works (sample)",
      "accountid": "8151925c-cde2-e411-80db-00155d2a68cb"
    }
  ],
  "@odata.nextLink": "cc_WebAPI_ServiceURI/accounts?$select=name&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b8151925C-CDE2-E411-80DB-00155D2A68CB%257d%2522%2520first%253d%2522%257b7D51925C-CDE2-E411-80DB-00155D2A68CB%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20/%3E"
}

Verwenden Sie den Wert der @odata.nextLink-Eigenschaft, um die nächste Datensatzgruppe anzufordern. Sie sollten keine zusätzlichen Systemabfrageoptionen für den Wert ändern oder anfügen. Für jede nachfolgende Anforderung weiterer Seiten sollten Sie denselben odata.maxpagesize-Einstellungswert verwenden, der sich in der ursprünglichen Anforderung verwendet wurde. Zwischenspeichern Sie auch die zurückgegebenen Ergebnisse oder den Wert der @odata.nextLink-Eigenschaft, sodass Sie zu zuvor abgerufenen Seiten zurückkehren können.

Hinweis

Der Wert der @odata.nextLink-Eigenschaft ist URI-codiert. Falls Sie den Wert vor dem Senden URI-codieren, verursachen die XML-Cookieinformationen in der URL einen Fehler.

Verwenden von Systemabfrageoptionen

Jede der Systemabfrageoptionen, die Sie zur URL für den Entitätssatz anfügen, wird mithilfe der Syntax für Abfragezeichenfolgen hinzugefügt. Die erste wird nach [?] angefügt und die nachfolgenden Abfrageoptionen werden mithilfe von [&] getrennt. Alle Abfrageoptionen unterscheiden zwischen Groß-/Kleinschreibung, wie im folgenden Beispiel angezeigt.

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue&$top=3&$filter=revenue gt 100000

Anforderungsspezifische Eigenschaften

Verwenden Sie die $select-Systemabfrageoption, um die zurückgegebenen Eigenschaften zu begrenzen, wie im folgenden Beispiel angezeigt.

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue

Wichtig

Dies ist eine bewährte Methode für die Leistung. Wenn Eigenschaften nicht mithilfe von $selectangegeben wurden, werden alle Eigenschaften zurückgegeben.

Wenn Sie bestimmte Eigenschaftstypen anfordern, können Sie erwarten, dass zusätzliche Schreibschutzeigenschaften automatisch zurückgegeben werden.

Wenn Sie einen Geldwert anfordern, wird die _transactioncurrencyid_value-Sucheigenschaft zurückgegeben. Diese Eigenschaft enthält nur den GUID-Wert der Transaktionswährung, daher könnten Sie diesen Wert verwenden, um Informationen über die Währung mithilfe von transactioncurrency EntityType abzurufen. Alternativ können Sie durch das Anfordern von Anmerkungen zusätzliche Daten in derselben Anforerung abrufen.Weitere Informationen:Abrufen von Daten zu Sucheigenschaften

Wenn Sie eine Eigenschaft anfordern, die Teil eines zusammengesetzten Attributs für eine Adresse ist, erhalten Sie auch die zusammengesetzte Eigenschaft. Wenn beispielsweise Ihre Abfrage die address1_line1-Eigenschaft für einen Kontakt anfordert, wird die address1_composite-Eigenschaft ebenfalls zurückgegeben.Weitere Informationen:Zusammengesetzte Attribute.

Ergebnisse filtern

Verwenden Sie die $filter-Systemabfrageoption, um Kriterien für Entitäten festzulegen, die zurückgegeben werden sollen.

Standardfilteroperatoren

Die Web-API unterstützt die OData-Standardfilteroperatoren, die in der folgenden Tabelle aufgelistet werden.

Operator

Beschreibung

Beispiel

Vergleichsoperatoren

eq

Gleich

$filter=revenue eq 100000

ne

Ungleich

$filter=revenue ne 100000

gt

Größer als

$filter=revenue gt 100000

ge

Größer als oder gleich

$filter=revenue ge 100000

lt

Kleiner als

$filter=revenue lt 100000

le

Kleiner oder gleich

$filter=revenue le 100000

Logische Operatoren

and

Logisch und

$filter=revenue lt 100000 and revenue gt 2000

or

Logisch oder

$filter=contains(name,'(sample)') or contains(name,'test')

not

Logische Negation

$filter=not contains(name,'sample')

Gruppieren von Operatoren

( )

Rangfolgengruppierung

(contains(name,'sample') or contains(name,'test')) and revenue gt 5000

Hinweis

Dies ist eine Teilmenge von 11.2.5.1.1 Integrierte Filter-Vorgänge. Arithmetische Operatoren und der Vergleich hat Operator werden von der Web-API nicht unterstützt.

Standardabfragenfunktionen

Die Web-Api unterstützt diese standardmäßigen OData-Zeichenfolgenabfragefunktionen.

Funktion

Beispiel

contains

$filter=contains(name,'(sample)')

endswith

$filter=endswith(name,'Inc.')

startswith

$filter=startswith(name,'a')

Hinweis

Dies ist eine Teilmenge von 11.2.5.1.2 Integrierte Abfragefunktionen.Date, Math, Type, Geo und andere String-Funktionen werden nicht in der Web-API unterstützt.

Microsoft Dynamics 365Web API Abfragefunktionen

Microsoft Dynamics 365 enthält einige spezielle Funktionen, die Parameter akzeptieren, Boolesche Werte zurückgeben und als Filterkriterium in einer Abfrage verwendet werden können. Eine Liste dieser Funktionen finden Sie unter Web API Query Function Reference. Im Folgenden finden Sie ein Beispiel für die Suche von Between Function nach Firmen mit einer Mitarbeiterzahl zwischen 5 und 2000.

GET cc_WebAPI_ServiceURI/accounts?$select=name,numberofemployees&$filter=Microsoft.Dynamics.CRM.Between(PropertyName='numberofemployees',PropertyValues=["5","2000"])

Weitere Informationen:Verfassen Sie Sie eine Abfrage mit Funktionen.

Reihenfolge von Ergebnissen

Geben Sie die Reihenfolge an, in der Elemente unter Verwendung Systemabfrageoption $orderby zurückgegeben werden. Verwenden Sie das asc- oder desc-Suffix, um eine jeweils aufsteigende oder absteigende Reihenfolge anzugeben. Die Standardeinstellung ist aufsteigend, wenn das Suffix nicht angewendet wird. Das folgende Beispiel zeigt das Abrufen der Namens- und Umsatzeigenschaften von Firmen, sortiert nach aufsteigendem Umsatz und absteigendem Namen.

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue,&$orderby=revenue asc,name desc&$filter=revenue ne null

Verwendung von Parameteraliasen mit Systemabfrageoptionen

Sie können Parameteraliase für $filter- und $orderby-Systemabfrageoptionen verwenden. Parameteraliase erlauben die mehrmalige Verwendung des gleichen Werts in einer Anforderung. Wenn dem Alias kein Wert zugeordnet wurde, wird angenommen, dass er NULL ist.

Ohne Parameteralias

 
GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue,&$orderby=revenue asc,name desc&$filter=revenue ne null

Mit Parameteralias

 
GET cc_WebAPI_ServiceURI/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.Weitere Informationen:Nutzen von Web-API-Funktionen

Ergebnisse eingrenzen

Sie können die Anzahl der zurückgegebenen Ergebnisse einschränken, indem Sie die Systemabfrageoption $top, verwenden. Im folgenden Beispiel werden nur die ersten drei Firmenentitäten zurückgegeben.

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue&$top=3

Hinweis

Durch Einschränken der Ergebnisse mit $top wird die Anwendung der odata.maxpagesize-Einstellung verhindert. Sie können die odata.maxpagesize-Einstellung oder $top verwenden, aber nicht beide gleichzeitig. Weitere Informationen zu odata.maxpagesize finden Sie unter Geben Sie die Anzahl der in einer Seite zurückzugebenden Entitäten an.

Sie sollten außerdem nicht $top mit $count verwenden.

Abrufen einer Anzahl von Entitäten

Verwenden Sie die Systemabfrageoption $count mit dem Wert true, um eine Anzahl von Entitäten einzuschließen, die die Filterkriterien bis 5000 entsprechen.

Hinweis

Der Zählwert steht nicht für die Gesamtanzahl von Entitäten im System. Er ist durch die maximale Anzahl von Entitäten begrenzt, die zurückgegeben werden können.Weitere Informationen:Beschränkungen der Zahl der zurückgegebenen Entitäten

Die @odata.count-Antworteigenschaft enthält die Anzahl der Entitäten, die den Filterkriterien entsprechen, ungeachtet einer odata.maxpagesize-Einstellungsbeschränkung.

Hinweis

Sie sollten nicht $top mit $count verwenden.

Das folgende Beispiel zeigt, dass zehn Firmen vorhanden sind, die den Kriterien übereinstimmen, wo der Name „Beispiel” enthält, aber nur die ersten drei Firmen zurückgegeben werden.

  • Anforderung

    GET cc_WebAPI_ServiceURI/accounts?$select=name&$filter=contains(name,'sample')&$count=true HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=3

  • Antwort

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

{
  "@odata.context":"cc_WebAPI_ServiceURI/$metadata#accounts(name)",
"@odata.count":10,
"value":[
    {
      "@odata.etag":"W/\"502482\"","name":"Fourth Coffee (sample)","accountid":"655eaf89-f083-e511-80d3-00155d2a68d3"
    },{
      "@odata.etag":"W/\"502483\"","name":"Litware, Inc. (sample)","accountid":"675eaf89-f083-e511-80d3-00155d2a68d3"
    },{
      "@odata.etag":"W/\"502484\"","name":"Adventure Works (sample)","accountid":"695eaf89-f083-e511-80d3-00155d2a68d3"
    }
  ],"@odata.nextLink":"cc_WebAPI_ServiceURI/accounts?$select=name&$filter=contains(name,'sample')&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b695EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520first%253d%2522%257b655EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Wenn Sie keine Daten bis auf die Anzahl zurückgeben möchten, können Sie $count auf eine beliebige Sammlung anwenden, um nur den Wert abzurufen.

  • Anforderung

    GET cc_WebAPI_ServiceURI/accounts/$count HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

  • Antwort

    HTTP/1.1 200 OK
Content-Type: text/plain
OData-Version: 4.0

10

Formatierte Werte einschließen

Wenn Sie mit den Ergebnissen formatierte Werte für Eigenschaften abrufen möchten, verwenden Sie die Einstellung odata.include-annotations mit dem Wert OData.Community.Display.V1.FormattedValue. Die Antwort schließt diese Werte mit Eigenschaften ein, die mit der nächsten Namenskonvention übereinstimmen:

<propertyname>@OData.Community.Display.V1.FormattedValue

Das folgende Bespiel fragt den Firmenentitätssatz ab und gibt den ersten Datensatz zurück, einschließlich Eigenschaften, die formatierte Werte unterstützen.

  • Anforderung

    GET cc_WebAPI_ServiceURI/accounts?$select=name,donotpostalmail,accountratingcode,numberofemployees,revenue&$top=1 HTTP/1.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": "cc_WebAPI_ServiceURI/$metadata#accounts(name,donotpostalmail,accountratingcode,numberofemployees,revenue)",
 "value": [
 {
  "@odata.etag": "W/"502170"",
  "name": "Fourth Coffee (sample)",
  "donotpostalmail@OData.Community.Display.V1.FormattedValue": "Allow",
  "donotpostalmail": false,
  "accountratingcode@OData.Community.Display.V1.FormattedValue": "Default Value",
  "accountratingcode": 1,
  "numberofemployees@OData.Community.Display.V1.FormattedValue": "9,500",
  "numberofemployees": 9500,
  "revenue@OData.Community.Display.V1.FormattedValue": "$100,000.00",
  "revenue": 100000,
  "accountid": "89390c24-9c72-e511-80d4-00155d2a68d1",
  "transactioncurrencyid_value": "50b6dd7b-f16d-e511-80d0-00155db07cb1" } ]
}

Abrufen von Daten zu Sucheigenschaften

Wenn die Abfrage Sucheigenschaften enthält, können Sie Anmerkungen anfordern, die zusätzliche Informationen zu den Daten dieser Eigenschaften bieten. Meistens können die gleichen Daten mit Kenntnissen der einzelbewerteten Navigationseigenschaften und der Daten, die in den verknüpften Entitäten enthalten sind, abgeleitet werden. Wenn die Eigenschaft jedoch ein Suchattribut darstellt, das auf mehr als einen Entitätstyp verweisen kann, können Ihnen diese Informationen mitteilen, auf welchen Entitätstyp die Sucheigenschaft verweist.Weitere Informationen:d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_lookupProperties

Es gibt zwei zusätzliche Anmerkungstypen für diese Eigenschaften.

Annotation

Beschreibung

Microsoft.Dynamics.CRM.associatednavigationproperty

Der Name der einzelbewerteten Navigationseigenschaft, der den Verweis auf die Entität einschließt.

Microsoft.Dynamics.CRM.lookuplogicalname

Der logische Name der Entität, auf die die Suche verweist.

Diese Eigenschaften können auch formatierte Werte enthalten, wie in Formatierte Werte einschließen beschrieben. Genau wie formatierte Werte können Sie die anderen Anmerkungen mithilfe der odata.include-annotations-Einstellung zurückgeben, die auf den bestimmten gewünschten Anmerkungstyp festgelegt ist, oder Sie können den Wert auf "*" festlegen und alle drei zurückgeben. Das folgende Beispiel zeigt die Anforderung und Antwort zum Abrufen von Informationen über die _customerid_value-Sucheigenschaft der incident-Entität mit eingeschlossenen Anmerkungen.

  • Anforderung

    GET cc_WebAPI_ServiceURI/incidents(39dd0b31-ed8b-e511-80d2-00155d2a68d4)?$select=title,customerid_value&$expand=customerid_contact($select=fullname) HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.include-annotations="*"

  • Antwort

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

{
   "@odata.context":"cc_WebAPI_ServiceURI/$metadata#incidents(title,_customerid_value,customerid_contact(fullname))/$entity",
   "@odata.etag":"W/\"504696\"",
   "_customerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty":"customerid_contact",
   "_customerid_value@Microsoft.Dynamics.CRM.lookuplogicalname":"contact",
   "_customerid_value@OData.Community.Display.V1.FormattedValue":"Susanna Stubberod (sample)",
   "_customerid_value":"7ddd0b31-ed8b-e511-80d2-00155d2a68d4",
   "incidentid":"39dd0b31-ed8b-e511-80d2-00155d2a68d4",
   "customerid_contact":{
      "@odata.etag":"W/\"503587\"",
      "fullname":"Susanna Stubberod (sample)",
      "contactid":"7ddd0b31-ed8b-e511-80d2-00155d2a68d4"
   }
}

Filterung von Datensätzen auf Grundlage einer einzelbewerteten Navigationseigenschaft

Navigationseigenschaften ermöglichen den Zugriff auf Daten zur aktuellen Entität.Einzelwertige Navigationseigenschaften entsprechen Suchattributen, die viel-zu-ein-Beziehungen unterstützen und eine Referenz auf eine andere Entität einstellen dürfen.Weitere Informationen:d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_navprops

Sie können Ihre Entitätssatzdatensätze auf Grundlage einwertiger Navigationseigenschaftswerte filtern. Zum Beispiel können Sie untergeordnete Firmen für die angegebene Firma abrufen. Sie können nur den primären Attributswert der Entität verwenden, die von einer eintwertigen navigationseigenschaft verweisen wurde, um Datensätze zu filtern. Beispiel:

  • Abrufen aller passenden Firmen für eine angegebene Kontaktkennung

    • Anforderung

      GET cc_WebAPI_ServiceURI/accounts?$select=name&$filter=primarycontactid/contactid%20eq%20a0dbf27c-8efb-e511-80d2-00155db07c77 HTTP/1.1
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":"cc_WebAPI_ServiceURI/$metadata#accounts(name)",
     "value":[
    {
      "@odata.etag":"W/\"513479\"",
      "name":"Adventure Works (sample)",
      "accountid":"3adbf27c-8efb-e511-80d2-00155db07c77"
    },{
      "@odata.etag":"W/\"514057\"",
      "name":"Blue Yonder Airlines (sample)",
      "accountid":"3edbf27c-8efb-e511-80d2-00155db07c77"
    }
  ]
}

  • Rufen Sie untergeordnete Konten für die angegebene Konto-ID ab.

    • Anforderung

      GET cc_WebAPI_ServiceURI/accounts?$select=name&$filter=parentaccountid/accountid%20eq%203adbf27c-8efb-e511-80d2-00155db07c77
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":"cc_WebAPI_ServiceURI/$metadata#accounts(name)",
    "value":[
    {
      "@odata.etag":"W/\"514058\"",
      "name":"Sample Child Account 1",
      "accountid":"915e89f5-29fc-e511-80d2-00155db07c77"
    },{
      "@odata.etag":"W/\"514061\"",
      "name":"Sample Child Account 2",
      "accountid":"03312500-2afc-e511-80d2-00155db07c77"
    }
  ]
}

Abrufen verwandter Entitäten durch Erweitern der Navigationseigenschaften

Verwenden Sie die $expand-Systemabfrageoption in den Navigationseigenschaften, um zu steuern, welche Daten von den verbundenen Entitäten zurückgegeben werden. Es gibt zwei Typen von Navigationseigenschaften:

  • Einzelwertige Navigationseigenschaften entsprechen Suchattributen, die viel-zu-ein-Beziehungen unterstützen und eine Referenz auf eine andere Entität einstellen dürfen.

  • Sammlungswertige Navigationseigenschaften entsprechen ein-zu-vielen oder viel-zu-vielen Verhältnissen.

Wenn Sie nur den Namen der Navigationseigenschaft einschließen, rufen Sie alle Eigenschaften für in Verbindung stehende Datensätze ab. Sie können die Eigenschaften begrenzen, die für in Verbindung stehende Aufzeichnungen unter Verwendung der Systemabfrageoption $select in Klammern nach dem Namen der Navigationseigenschaft zurückgegeben werden. Verwenden Sie dieses für einzelwertige und sammlungswertige Navigationseigenschaften.

Hinweis

Informationen zum Abrufen verbundener Entitäten für eine Entitätsinstanz finden Sie unter Abrufen verwandter Entitäten für eine Entität durch Erweitern der Navigationseigenschaften.

  • Rufen Sie verbundene Entitäten ab, indem Sie einzelwertige Navigationseigenschaften erweitern: Das folgende Beispiel zeigt, wie Sie den Kontakt für alle Firmendatensätze abrufen. Für die in Verbindung stehenden Kontaktdatensätze rufen wir nur die Kontaktkennung und den vollen Namen ab.

    • Anforderung

      GET cc_WebAPI_ServiceURI/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname) HTTP/1.1
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":"cc_WebAPI_ServiceURI/$metadata#accounts(name,primarycontactid,primarycontactid(contactid,fullname))","value":[
    {
      "@odata.etag":"W/\"513475\"","name":"Fourth Coffee (sample)","accountid":"36dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"9cdbf27c-8efb-e511-80d2-00155db07c77","fullname":"Yvonne McKay (sample)"
      }
    },{
      "@odata.etag":"W/\"513477\"","name":"Litware, Inc. (sample)","accountid":"38dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"9edbf27c-8efb-e511-80d2-00155db07c77","fullname":"Susanna Stubberod (sample)"
      }
    },{
      "@odata.etag":"W/\"513479\"","name":"Adventure Works (sample)","accountid":"3adbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a0dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Nancy Anderson (sample)"
      }
    },{
      "@odata.etag":"W/\"513481\"","name":"Fabrikam, Inc. (sample)","accountid":"3cdbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a2dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Maria Campbell (sample)"
      }
    },{
      "@odata.etag":"W/\"514057\"","name":"Blue Yonder Airlines (sample)","accountid":"3edbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a0dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Nancy Anderson (sample)"
      }
    },{
      "@odata.etag":"W/\"513485\"","name":"City Power & Light (sample)","accountid":"40dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a6dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Scott Konersmann (sample)"
      }
    },{
      "@odata.etag":"W/\"513487\"","name":"Contoso Pharmaceuticals (sample)","accountid":"42dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a8dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Robert Lyon (sample)"
      }
    },{
      "@odata.etag":"W/\"513489\"","name":"Alpine Ski House (sample)","accountid":"44dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"aadbf27c-8efb-e511-80d2-00155db07c77","fullname":"Paul Cannon (sample)"
      }
    },{
      "@odata.etag":"W/\"513491\"","name":"A. Datum Corporation (sample)","accountid":"46dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"acdbf27c-8efb-e511-80d2-00155db07c77","fullname":"Rene Valdes (sample)"
      }
    },{
      "@odata.etag":"W/\"513493\"","name":"Coho Winery (sample)","accountid":"48dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"aedbf27c-8efb-e511-80d2-00155db07c77","fullname":"Jim Glynn (sample)"
      }
    }
  ]
}

    Anstatt, die verbundenen Entitäten für Entitätensätze abzurufen, können Sie auch Verweise (Verbindungen) auf die verbundenen Entitäten zurückgeben, indem Sie die einwertige Navigationseigenschaft mit der Option $ref erweitern. Im folgenden Beispiel werden Links zum Kontaktdatensatz für alle Firmen zurückgegeben.

    • Anforderung

      GET cc_WebAPI_ServiceURI/accounts?$select=name&$expand=primarycontactid/$ref HTTP/1.1
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":"cc_WebAPI_ServiceURI/$metadata#accounts(name,primarycontactid)","value":[
    {
      "@odata.etag":"W/\"513475\"","name":"Fourth Coffee (sample)","_primarycontactid_value":"9cdbf27c-8efb-e511-80d2-00155db07c77","accountid":"36dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(9cdbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513477\"","name":"Litware, Inc. (sample)","_primarycontactid_value":"9edbf27c-8efb-e511-80d2-00155db07c77","accountid":"38dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(9edbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513479\"","name":"Adventure Works (sample)","_primarycontactid_value":"a0dbf27c-8efb-e511-80d2-00155db07c77","accountid":"3adbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a0dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513481\"","name":"Fabrikam, Inc. (sample)","_primarycontactid_value":"a2dbf27c-8efb-e511-80d2-00155db07c77","accountid":"3cdbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a2dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"514057\"","name":"Blue Yonder Airlines (sample)","_primarycontactid_value":"a0dbf27c-8efb-e511-80d2-00155db07c77","accountid":"3edbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a0dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513485\"","name":"City Power & Light (sample)","_primarycontactid_value":"a6dbf27c-8efb-e511-80d2-00155db07c77","accountid":"40dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a6dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513487\"","name":"Contoso Pharmaceuticals (sample)","_primarycontactid_value":"a8dbf27c-8efb-e511-80d2-00155db07c77","accountid":"42dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a8dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513489\"","name":"Alpine Ski House (sample)","_primarycontactid_value":"aadbf27c-8efb-e511-80d2-00155db07c77","accountid":"44dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(aadbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513491\"","name":"A. Datum Corporation (sample)","_primarycontactid_value":"acdbf27c-8efb-e511-80d2-00155db07c77","accountid":"46dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(acdbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513493\"","name":"Coho Winery (sample)","_primarycontactid_value":"aedbf27c-8efb-e511-80d2-00155db07c77","accountid":"48dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(aedbf27c-8efb-e511-80d2-00155db07c77)"
      }
    }
  ]
}

    • Rufen Sie verbundene Entitäten ab, indem Sie sammlungswertige Navigationseigenschaften erweitern: Wenn Sie auf sammlungswertige Navigationsparameter erweitern, um verbundene Entitäten für Entitätssätze abzurufen, wird eine @odata.nextLink-Eigenschaft für die verbundenen Eintäten zurückgegeben. Sie sollten den Wert der @odata.nextLink-Eigenschaft mit einer neuen GET-Anforderung nutzen, um die benötigten Daten zurückzugeben.

      Im folgenden Beispiel werden die Aufgaben zurückgegeben, die den Ersten 5 Firmendatensätzen zugewiesen werden.

      • Anforderung

        GET cc_WebAPI_ServiceURI/accounts?$top=5&$select=name&$expand=Account_Tasks($select%20=%20subject,%20scheduledstart) HTTP/1.1
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":"cc_WebAPI_ServiceURI/$metadata#accounts(name,Account_Tasks,Account_Tasks(subject,scheduledstart))","value":[
    {
      "@odata.etag":"W/\"513475\"","name":"Fourth Coffee (sample)","accountid":"36dbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(36dbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"513477\"","name":"Litware, Inc. (sample)","accountid":"38dbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(38dbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"514074\"","name":"Adventure Works (sample)","accountid":"3adbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(3adbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"513481\"","name":"Fabrikam, Inc. (sample)","accountid":"3cdbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(3cdbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"514057\"","name":"Blue Yonder Airlines (sample)","accountid":"3edbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(3edbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    }
  ]
}

  • Rufen Sie verbundene Entitäten durch Erweitern von einzelwertigen und sammlungswertigen Navigationseigenschaften ab: Das folgende Beispiel zeigt, wie Sie verbundene Entitäten für Entitätssätze unter Verwendung der einzel- und sammlungswertigen Navigationseigenschaften erweitern können. Wie zuvor erklärt, gibt die Erweiterung auf sammlungswertige Navigationseigenschaften, um verbundene Entitäten für Entitätssätze zurückzugeben eine @odata.nextLink-Eigenschaft für die verbundenen Entitäten zurück. Sie sollten den Wert der @odata.nextLink-Eigenschaft mit einer neuen GET-Anforderung nutzen, um die benötigten Daten zurückzugeben.

    In diesem Beispiel rufen wir den Kontakt und die Aufgaben ab, die den ersten 3 Firmen zugewiesen werden.

    • Anforderung

      GET cc_WebAPI_ServiceURI/accounts?$top=3&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)  HTTP/1.1
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":"cc_WebAPI_ServiceURI/$metadata#accounts(name,primarycontactid,Account_Tasks,primarycontactid(contactid,fullname),Account_Tasks(subject,scheduledstart))","value":[
    {
      "@odata.etag":"W/\"550614\"",
          "name":"Fourth Coffee (sample)",
          "accountid":"5b9648c3-68f7-e511-80d3-00155db53318",
          "primarycontactid":{
              "contactid":"c19648c3-68f7-e511-80d3-00155db53318",
              "fullname":"Yvonne McKay (sample)"
      },
      "Account_Tasks":[

       ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(5b9648c3-68f7-e511-80d3-00155db53318)/Account_Tasks?$select=subject,scheduledstart"
    },{
      "@odata.etag":"W/\"550615\"",
          "name":"Litware, Inc. (sample)",
          "accountid":"5d9648c3-68f7-e511-80d3-00155db53318",
          "primarycontactid":{
              "contactid":"c39648c3-68f7-e511-80d3-00155db53318",
              "fullname":"Susanna Stubberod (sample)"
      },"Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(5d9648c3-68f7-e511-80d3-00155db53318)/Account_Tasks?$select=subject,scheduledstart"
    },{
      "@odata.etag":"W/\"550616\"",
      "name":"Adventure Works (sample)",
      "accountid":"5f9648c3-68f7-e511-80d3-00155db53318",
      "primarycontactid":{
        "contactid":"c59648c3-68f7-e511-80d3-00155db53318",
        "fullname":"Nancy Anderson (sample)"
      },"Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(5f9648c3-68f7-e511-80d3-00155db53318)/Account_Tasks?$select=subject,scheduledstart"
    }
  ]
}

Siehe auch

Web API-Abfragedatenbeispiel (C#)
Web API-Abfragedatenbeispiele (clientseitiges JavaScript)
Vorgänge mithilfe der Web-API ausführen
HTTP-Anforderungen verfassen und Fehler beheben
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