Abrufen einer Tabellenzeile über die Web-API

  • Artikel

Verwenden Sie eine GET-Anfrage, um Daten für eine als Ressource angegebenen Datensatz mit einem eindeutigen Bezeichner abzurufen. Beim Abrufen einer Tabellenzeile (Entitätsdatensatz) können Sie auch bestimmte Eigenschaften abfragen und die Navigationseigenschaften erweitern, um Eigenschaften von verknüpften Datensätzen in verschiedenen Tabellen zurückzugeben.

Hinweis

Informationen zum Abrufen von Tabellendefinitionen finden Sie unter Abfragen von Tabellendefinitionen mit der Web-API.

Grundlegendes Abrufen

Das folgende Beispiel gibt Daten für einen Datensatz der Entität „Konto“ zurück, dessen Primärschlüsselwert gleich 00000000-0000-0000-0000-000000000001 ist:

GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)

In diesem Beispiel werden alle Eigenschaften des Datensatzes eines Kontos zurückgegeben, was nicht gerade zu den besten Leistungsmerkmalen gehört. Sie sollten immer die Systemabfrageoption $select verwenden, um die zurückgegebenen Eigenschaften beim Abrufen von Daten einzuschränken. Dies ist besonders wichtig, wenn Sie mehrere Datenzeilen abrufen. Mehr Informationen: Datenabfrage über die Web-API.

Spezifische Eigenschaften abrufen

Um die Eigenschaften einzuschränken, die zurückgegeben werden, wenn Sie Daten mit einer GET-Anfrage abrufen, verwenden Sie die Systemabfrageoption $select mit einer kommagetrennten Liste von Eigenschaftsnamen. Eine wichtige Best Practice für die Leistung ist, nur die Eigenschaften anzufordern, die Sie benötigen. Wenn Sie keine Eigenschaften angeben, die zurückgegeben werden sollen, werden alle Eigenschaften zurückgegeben.

Das folgende Beispiel ruft die Eigenschaften name und revenue für die Entität „Konto“ mit dem Primärschlüsselwert 00000000-0000-0000-0000-000000000001 ab:

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)?$select=name,revenue HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
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)/$entity",  
"@odata.etag": "W/\"502186\"",  
"name": "A. Datum Corporation (sample)",  
"revenue": 10000,  
"accountid": "00000000-0000-0000-0000-000000000001",  
"_transactioncurrencyid_value":"b2a6b689-9a39-e611-80d2-00155db44581"  
}

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

Wenn Sie einen Geld-Wert anfordern, wird das _transactioncurrencyid_value Suchfeld zurückgegeben. Diese Eigenschaft enthält nur den GUID-Wert der Transaktionswährung, sodass Sie damit Informationen über die Währung mit Hilfe des Transactioncurrency EntityType abrufen können. Alternativ können Sie mehr Daten in der gleichen Anfrage erhalten, indem Sie Anmerkungen anfordern.

Wenn Sie eine Eigenschaft anfordern, die Teil eines zusammengesetzten Attributs für eine Adresse ist, erhalten Sie auch die zusammengesetzte Eigenschaft. Wenn Ihre Abfrage zum Beispiel die Eigenschaft address1_line1 für einen Kontakt anfordert, wird auch die Eigenschaft address1_composite zurückgegeben.

Datensatz unter Verwendung eines alternativen Schlüssels abrufen

Wenn für eine Entität ein alternativer Schlüssel definiert wurde, können Sie diesen anstelle des eindeutigen Bezeichners verwenden, um die Entität abzurufen, zu aktualisieren oder zu löschen. Standardmäßig sind keine alternativen Schlüssel für Entitäten konfiguriert. Alternative Schlüssel sind nur verfügbar, wenn Ihr Unternehmen oder eine Lösung sie hinzufügt.

Alternative Schlüsselwerte mit den folgenden Zeichen /, <, >, *, %, &, :, \\, ?, + werden derzeit nicht unterstützt.

Wenn die Contact Entität beispielsweise eine alternative Schlüsseldefinition hat, die sowohl die Eigenschaften firstname als auch emailaddress1 enthält, können Sie den Kontakt mit einer Abfrage abrufen, die Daten für diese Schlüssel enthält:

GET [Organization URI]/api/data/v9.2/contacts(firstname='Joe',emailaddress1='abc@example.com')

Wenn die Definition des alternativen Schlüssels ein Feld vom Typ Suchfeld enthält (z.B. die Eigenschaft primarycontactid für die Entität account), können Sie die account mithilfe der Lookup-Eigenschaften abrufen, wie im folgenden Beispiel:

GET [Organization URI]/api/data/v9.2/accounts(_primarycontactid_value=00000000-0000-0000-0000-000000000001)

Dokumente in Speicherpartitionen abrufen

Wenn Sie einen Datensatz in einer elastischen Tabelle abrufen, der in einer Partition gespeichert ist, stellen Sie sicher, dass Sie den Partitionsschlüssel angeben.

Rufen Sie einen einzelnen Eigenschaftswert ab

Wenn Sie nur den Wert einer einzelnen Eigenschaft abrufen müssen, können Sie den Namen der Eigenschaft an den URI der Entität anhängen. Es ist eine Best Practice für die Leistung, die zurückgegebene Datenmenge zu reduzieren.

Das folgende Beispiel gibt nur den Wert der Eigenschaft name für eine Entität account zurück:

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/name 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":"[Organization URI]/api/data/v9.2/$metadata#accounts(00000000-0000-0000-0000-000000000001)/name",
"value":"Adventure Works (sample)"
}

Den Rohwert einer Eigenschaft abrufen

Um den Rohwert einer primitiven Eigenschaft und nicht JSON abzurufen, hängen Sie eine /$value an die URL an, zum Beispiel:

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/name/$value 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

Adventure Works (sample)

Die Verwendung des Rohwerts ist nicht allgemein üblich, es sei denn, Sie arbeiten mit Datei- oder Bilddaten. Weitere Informationen: Herunterladen einer Datei in einer einzigen Anfrage über die Web-API.

Navigations-Eigenschaftswerte abrufen

Sie können auf die Werte von Navigationseigenschaften oder Suchfeldern zugreifen, indem Sie den Namen der Navigationseigenschaft an die URI einer einzelnen Entität anhängen.

Das folgende Beispiel gibt die fullname der primären contact einer account unter Verwendung der einwertigen Navigationseigenschaft primarycontactid zurück:

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/primarycontactid?$select=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": "[Organization URI]/api/data/v9.2/$metadata#contacts(fullname)/$entity",  
"@odata.etag": "W/\"500128\"",  
"fullname": "Rene Valdes (sample)",  
"contactid": "ff390c24-9c72-e511-80d4-00155d2a68d1"  
}

Für Navigationseigenschaften mit Sammelwerten können Sie nur die Anzahl oder Referenzen auf die verbundenen Entitäten abrufen.

Das folgende Beispiel gibt Verweise auf Aufgaben zurück, die sich auf ein bestimmtes Konto beziehen, indem es der Anfrage eine /$ref hinzufügt.

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/AccountTasks/$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": "[Organization URI]/api/data/v9.2/$metadata#Collection($ref)",
    "value":
  [
    { "@odata.id": "[Organization URI]/api/data/v9.2/tasks(6b5941dd-d175-e511-80d4-00155d2a68d1)" },
    { "@odata.id": "[Organization URI]/api/data/v9.2/tasks(fcbb60ed-d175-e511-80d4-00155d2a68d1)" }
  ]
}

Das folgende Beispiel gibt die Anzahl der Aufgaben zurück, die mit einem bestimmten Konto verbunden sind, wobei die Navigationseigenschaft mit dem Sammlungswert Account_Tasks mit angehängter /$count verwendet wird:

Anforderung:

GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/Account_Tasks/$count HTTP/1.1  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Antwort:

2

Hinweis

Der zurückgegebene Wert enthält die UTF-8 Byte Order Mark (Stückliste) Zeichen (), was anzeigt, dass es sich um ein UTF-8 Dokument handelt.

Verwenden Sie die $expand-Systemabfrageoption, um zu steuern, welche Daten von den verbundenen Entitäten zurückgegeben werden. Weitere Informationen: Tabellen beitreten

Erkennen, ob sich ein Datensatz seit dem Abruf geändert hat

Als leistungsoptimales Verfahren sollten Sie nur die Daten anfordern, die Sie benötigen. Wenn Sie zuvor einen Entitätsdatensatz abgerufen haben, können Sie das ETag verwenden, das einem zuvor abgerufenen Datensatz zugeordnet ist, um bedingte Abrufe zu diesem Datensatz auszuführen. Weitere Informationen: Bedingte Abrufe.

Abrufen von formatierten Werten

Fordern Sie formatierte Werte für die Abfrage einzelner Datensätze auf die gleiche Weise an, wie Sie Entitätssets abfragen.

Siehe auch

Vorgänge mithilfe der Web-API ausführen
HTTP-Anforderungen erstellen und Fehler behandeln
Datenabfrage mit Web-API

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