Freigeben über

Abrufen einer Tabellenzeile mithilfe der Web-API

Verwenden Sie eine GET Anforderung zum Abrufen von Daten für einen Datensatz, der als Ressource mit einem eindeutigen Bezeichner angegeben ist. Beim Abrufen einer Tabellenzeile (Entitätsdatensatz) können Sie auch bestimmte Eigenschaften anfordern und Navigationseigenschaften erweitern, um Eigenschaften aus verwandten Datensätzen in verschiedenen Tabellen zurückzugeben.

Hinweis

Informationen zum Abrufen von Tabellendefinitionen finden Sie unter Abfragetabellendefinitionen mithilfe 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 $select Systemabfrageoption verwenden, um die beim Abrufen von Daten zurückgegebenen Eigenschaften einzuschränken. Dies ist besonders wichtig beim Abrufen mehrerer Datenzeilen. Mehr Informationen: Datenabfrage über die Web-API.

Abrufen bestimmter Eigenschaften

Wenn Sie die zurückgegebenen Eigenschaften beim Abrufen von Daten mit einer GET-Anforderung einschränken möchten, verwenden Sie die $select Systemabfrageoption mit einer durch Trennzeichen getrennten Liste von Eigenschaftsnamen. Das Anfordern nur der benötigten Eigenschaften ist eine wichtige bewährte Methode für die Leistung. Wenn Sie keine eigenschaften angeben, die zurückgegeben werden sollen, werden alle Eigenschaften zurückgegeben.

Im folgenden Beispiel werden die name- und revenue-Eigenschaften der Kontoentität mit dem Primärschlüsselwert 00000000-0000-0000-0000-0000-000000001 abgerufen.

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 money-Wert anfordern, wird die _transactioncurrencyid_value Sucheigenschaft zurückgegeben. Diese Eigenschaft enthält nur den GUID-Wert der Transaktionswährung, sodass Sie sie zum Abrufen von Informationen über die Währung mit dem Transactioncurrency EntityType verwenden können. Alternativ können Sie weitere Daten in derselben Anforderung abrufen, 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 beispielsweise die address1_line1 Eigenschaft für einen Kontakt anfordert, wird die address1_composite Eigenschaft ebenfalls zurückgegeben.

Abrufen eines Datensatzes mithilfe eines alternativen Schlüssels

Wenn eine Entität einen alternativen Schlüssel definiert hat, können Sie ihn 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 Ihre Organisation 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 über eine alternative Schlüsseldefinition verfügt, die sowohl die Eigenschaften firstname als auch die emailaddress1 Eigenschaften enthält, können Sie den Kontakt mithilfe einer Abfrage mit den für diese Schlüssel bereitgestellten Daten abrufen:

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)

Abrufen von Dokumenten in Speicherpartitionen

Wenn Sie einen Datensatz in einer elastischen Tabelle abrufen , die in einer Partition gespeichert ist, müssen Sie unbedingt den Partitionsschlüssel angeben.

Abrufen eines einzelnen Eigenschaftswerts

Wenn Sie nur den Wert einer einzelnen Eigenschaft abrufen müssen, können Sie den Namen der Eigenschaft an den Entitäts-URI anfügen. Das Verringern der zurückgegebenen Datenmenge ist eine bewährte Methode für die Leistung.

Im folgenden Beispiel wird nur der Wert der name Eigenschaft für eine account Entität zurückgegeben:

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)"
}

Abrufen des Rohwerts einer Eigenschaft

Um den Rohwert einer primitiven Eigenschaft anstelle von JSON abzurufen, fügen Sie /$value sie an die URL an, z. B.:

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 üblich, es sei denn, Sie arbeiten mit Datei- oder Bilddaten. Weitere Informationen: Laden Sie eine Datei in einer einzigen Anforderung mithilfe der Web-API herunter.

Abrufen von Navigationseigenschaftswerten

Sie können auf die Werte von Navigationseigenschaften oder Nachschlagefeldern zugreifen, indem Sie den Namen der Navigationseigenschaft an den URI einer einzelnen Entität anfügen.

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.

Im folgenden Beispiel werden durch das Hinzufügen von /$ref zur Anforderung Verweise auf Aufgaben im Zusammenhang mit einem bestimmten Konto zurückgegeben.

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-Bytereihenfolgezeichen (BOM) (), die angibt, dass es sich um ein UTF-8-Dokument handelt.

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

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

Als bewährte Methode für die Leistung sollten Sie nur 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 für diesen Datensatz durchzuführen. Weitere Informationen: Bedingte Abfragen.

Abrufen formatierter Werte

Fordern Sie formatierte Werte für einzelne Datensatzabrufe auf die gleiche Weise an, wie Sie Entitätssätze abfragen.

Siehe auch

Ausführen von Vorgängen mithilfe der Web-API
HTTP-Anforderungen erstellen und Fehlern behandeln
Datenabfrage mit Web-API

  • Last updated on