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. Wenn Sie eine Tabellenzeile (Entitätsdatensatz) abrufen, können Sie auch bestimmte Eigenschaften anfordern und Navigationseigenschaften erweitern, um Eigenschaften aus verwandten Datensätzen in verschiedenen Tabellen zurückzugeben.

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 für den Kontodatensatz zurückgegeben, was keine optimale Praxis für die Leistung ist. Verwenden Sie immer die $select Systemabfrageoption, um die beim Abrufen von Daten zurückgegebenen Eigenschaften einzuschränken. Diese Vorgehensweise ist besonders wichtig, wenn Sie mehrere Datenzeilen abrufen. Weitere Informationen finden Sie unter Datenabfrage mit 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. Fordern Sie nur die Eigenschaften an, die Sie für eine bessere Leistung benötigen. Wenn Sie keine eigenschaften angeben, die zurückgegeben werden sollen, gibt die Anforderung alle Eigenschaften zurück.

Im folgenden Beispiel werden die name- und revenue-Eigenschaften für die Kontoentität mit dem Primärschlüsselwert 00000000-0000-0000-0000-000000000001 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 Eigenschaftentypen anfordern, werden automatisch mehr schreibgeschützte Eigenschaften zurückgegeben.

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 verwenden können, um Informationen über die Währung mithilfe der Transactioncurrency EntityType abzurufen. 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 Datensätzen 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, fügen Sie den Namen der Eigenschaft an den Entitäts-URI an. 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 an die URL an /$value . 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 üblich, es sei denn, Sie arbeiten mit Datei- oder Bilddaten. Weitere Informationen finden Sie unter Herunterladen einer Datei in einer einzigen Anforderung mithilfe der Web-API.

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.

Im folgenden Beispiel wird die fullname des primären contact eines account mithilfe der primarycontactid einzelwertigen Navigationseigenschaft zurückgegeben.

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 mit einem bestimmten Konto in Verbindung stehen, indem /$ref zur Anforderung hinzugefügt wird.

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

Im folgenden Beispiel wird die Anzahl der Vorgänge zurückgegeben, die mit einem bestimmten Konto verknüpft sind, indem die Account_Tasks-Auflistungsnavigations-Eigenschaft mit angefügtem /$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

Abrufen verwandter Datensätze durch Erweitern von Navigationseigenschaften

Verwenden Sie die $expand Systemabfrageoption, um zu steuern, welche Daten aus verwandten Entitäten zurückgegeben werden. Weitere Informationen finden Sie unter Verknüpfungstabellen.

Erkennen, ob ein Datensatz seit dem Abrufen geändert wurde

Als bewährte Methode zur Leistung fordern Sie nur die benötigten Daten an. Wenn Sie zuvor einen Entitätsdatensatz abgerufen haben, verwenden Sie das diesem Datensatz zugeordnete ETag , um bedingte Abrufe durchzuführen. Weitere Informationen finden Sie unter "Bedingte Abrufe".

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