Auswählen-Spalten mit OData

Artikel
08/05/2024

Wichtig

Wenn Sie Daten abfragen, ist es wichtig, die Menge der zurückgegebenen Daten zu begrenzen, um die Leistung zu optimieren. Nur die Spalten mit den erforderlichen Daten auswählen.

Verwenden Sie die $select Abfrageoption , um auszuwählen, welche Spalten mit Ihrer Abfrage zurückgegeben werden sollen. In OData wird jede Spalte als Eigenschaft dargestellt. Wenn Sie keine $select Abfrageoption einfügen, werden alle Eigenschaften zurückgegeben.

Das folgende Beispiel fordert die name und revenue Eigenschaften aus der ersten Zeile der accounts EntitySet-Ressource an:

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue&$top=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": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,revenue)",
    "value": [
        {
            "@odata.etag": "W/\"81052965\"",
            "name": "Litware, Inc. (sample)",
            "revenue": 20000.0000,
            "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1",
            "accountid": "4624eff7-53d3-ed11-a7c7-000d3a993550"
        }
    ]
}

Die Primärschlüsseleigenschaft wird immer zurückgegeben, sodass Sie sie nicht in Ihre $select aufnehmen müssen. In diesem Beispiel ist accountid der Primärschlüssel.

In Antwort können auch andere Eigenschaftswerte enthalten sein. In diesem Fall wird die _transactioncurrencyid_value Nachschlageeigenschaft für die zugehörige Währungstabelle (TransactionCurrency)/Entitätsreferenz eingeschlossen, da revenue es sich um eine Währungseigenschaft handelt.

Welche Eigenschaften sind verfügbar?

Alle verfügbaren Eigenschaften für eine Entität finden Sie im $metadata-Dienstdokument. Weitere Informationen: Web-API-Eigenschaften

Die Typen der Entitäten, die in Dataverse enthalten sind, werden in Web API Entity Type Reference beschrieben.

Tipp

Der einfachste Weg, schnell herauszufinden, welche Eigenschaften verfügbar sind, besteht darin, eine Anfrage mit der $top Abfrageoption mit dem Wert 1 zu senden, ohne $select zu verwenden.

Formatierte Werte

Formatierte Werte sind auf dem Server generierte Zeichenfolgenwerte, die Sie in Ihrer Anwendung verwenden können. Formatierte Werte schließen ein:

Die lokalisierten Bezeichnungen für die Spalten „Auswahl“, „Auswahl“, „Ja/Nein“, „Status“ und „Statusgrund“
Der primäre Namenswert für Such- und Eigentümereigenschaften
Währungswerte mit Währungssymbolen
Formatierte Datumswerte in der Zeitzone des Benutzers

Um formatierte Werte in Ihre Ergebnisse einzuschließen, verwenden Sie den Prefer-Anforderungsheader , um die odata.include-annotations-Präferenz zu senden.

Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Formatierte Werte sind eine von mehreren Anmerkungen, die Sie anfordern können. Verwenden Sie Prefer: odata.include-annotations="*", um alle Anmerkungen einzuschließen. Weitere Informationen: Anmerkungen anfordern

Der formatierte Wert wird mit dem Datensatz mit einer Anmerkung zurückgegeben, die dieser Konvention folgt:

<property name>@OData.Community.Display.V1.FormattedValue

Zum Beispiel:

Anforderung:

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

Die folgende Tabelle beschreibt die Werte und formatierten Werte, die für die angeforderten Eigenschaften zurückgegeben werden.

Eigenschaften	Wert	Formatierter Wert
`name`	`Litware, Inc. (sample)`	Nein
`revenue`	`20000.0000`	`$20,000.00`
`_primarycontactid_value`	`70bf4d48-34cb-ed11-b596-0022481d68cd`	`Susanna Stubberod (sample)`
`customertypecode`	`1`	`Competitor`
`modifiedon`	`2023-04-07T21:59:01Z`	`4/7/2023 2:59 PM`
`_transactioncurrencyid_value`	`228f42f8-e646-e111-8eb7-78e7d162ced1`	`US Dollar`
`accountid`	`78914942-34cb-ed11-b596-0022481d68cd`	Nein

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,revenue)",
    "value": [
{
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "revenue@OData.Community.Display.V1.FormattedValue": "$20,000.00",
            "revenue": 20000.0000,
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "customertypecode@OData.Community.Display.V1.FormattedValue": "Competitor",
            "customertypecode": 1,
            "modifiedon@OData.Community.Display.V1.FormattedValue": "4/7/2023 2:59 PM",
            "modifiedon": "2023-04-07T21:59:01Z",
            "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar",
            "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}

Suche Eigenschaftsdaten

Wenn eine Nachschlageeigenschaft eine Beziehung mit mehreren Tabellen oder eine polymorphe Beziehung darstellt, müssen Sie bestimmte Anmerkungen anfordern, um zu bestimmen, welche Tabelle die zugehörigen Daten enthält.

Beispielsweise enthalten viele Tabellen Datensätze, die Benutzer oder Teams besitzen können. Eigentumsdaten werden in einer Suchfeld-Spalte mit dem Namen ownerid gespeichert. Diese Spalte ist eine einwertige Navigationseigenschaft in OData. Sie könnten $expand verwenden, um einen Join zu erstellen, um diesen Wert zu erhalten, aber Sie können $select nicht verwenden. Sie können jedoch $select verwenden, um die entsprechende _ownerid_value Nachschlageeigenschaft abzurufen.

Wenn Sie die Suchfeld-Eigenschaft _ownerid_value mit Ihrer $select einschließen, wird ein GUID-Wert zurückgegeben. Dieser Wert sagt Ihnen nicht, ob der Eigentümer des Datensatzes ein Benutzer oder ein Team ist. Sie müssen Anmerkungen anfordern, um diese Daten zu erhalten.

Um diese Anmerkungen in Ihre Ergebnisse einzuschließen, verwenden Sie den Anforderungsheader „Prefer“ , um die Präferenz „odata.include-annotations“ mit diesen Einstellungen zu senden:

Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

Tipp

Oder Sie können Prefer: odata.include-annotations="*" verwenden, um alle Anmerkungen einzuschließen. Weitere Informationen: Anmerkungen anfordern

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts?$select=name,_ownerid_value&$top=2
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

Die folgende Antwort gibt zwei verschiedene Kontodatensätze zurück. Das _ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname Anmerkungen sagt Ihnen, dass a team das erste besitzt und a systemuser das zweite besitzt.

Antwort:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0
Preference-Applied: odata.include-annotations="Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,_ownerid_value)",
    "value": [
        {
            "@odata.etag": "W/\"81550512\"",
            "name": "Adventure Works (sample)",
            "_ownerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "ownerid",
            "_ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "team",
            "_ownerid_value": "39e0dbe4-131b-e111-ba7e-78e7d1620f5e",
            "accountid": "1adef0b8-54d3-ed11-a7c7-000d3a993550"
        },
        {
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "_ownerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "ownerid",
            "_ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "systemuser",
            "_ownerid_value": "4026be43-6b69-e111-8f65-78e7d1620f5e",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}

<lookup property name>@Microsoft.Dynamics.CRM.lookuplogicalname ist der logische Name der Bezugstabelle.
<lookup property name>@Microsoft.Dynamics.CRM.associatednavigationproperty ist der Name der entsprechenden einwertigen Navigationseigenschaft. Sie können $expand mit diesem Wert in einer anderen Anfrage verwenden, um weitere Daten aus dem verknüpften Datensatz abzurufen.

Spaltenaliasse

Für die Web-API verwenden Sie fetchxml, um benutzerdefinierte Aliase für Spalten anzugeben.

Derzeit gibt es keine Möglichkeit, Spaltenaliase mithilfe der Dataverse Web-API unter Verwendung von OData anzugeben. OData 4.0 enthält nicht die in OData 4.01 eingeführte Systemabfrageoption $compute , die zum Bereitstellen dieser Funktion erforderlich ist.

Nächste Schritte,

Informationen zum Verknüpfen von Tabellen.

Tabellen verbinden

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).

Teilen über

Auswählen-Spalten mit OData

Welche Eigenschaften sind verfügbar?

Formatierte Werte

Suche Eigenschaftsdaten

Spaltenaliasse

Nächste Schritte,

Zusätzliche Ressourcen