Entitäten abfragen

  • Artikel

Der Query Entities-Vorgang fragt Entitäten einer Tabelle ab und enthält die Optionen $filter und $select.

Anforderung

Für Anforderungen, die die $select Abfrageoption verwenden, müssen Sie Version 2011-08-18 oder höher verwenden. Darüber hinaus müssen der DataServiceVersion-Header und der MaxDataServiceVersion-Header auf 2.0 festgelegt werden.

Um projektion zu verwenden, müssen Sie die Anforderung mit Version 2013-08-15 oder höher stellen. Die DataServiceVersion Header und MaxDataServiceVersion müssen auf 3.0festgelegt werden. Weitere Informationen finden Sie unter Festlegen der OData-Datendienst-Versionsheader.

Sie können die Query Entities Anforderung wie folgt erstellen. Wir empfehlen HTTPS. Ersetzen Sie myaccount durch den Namen Ihres Speicherkontos und mytable durch den Namen Ihrer Tabelle.

Methode Anforderungs-URI HTTP-Version
GET https://myaccount.table.core.windows.net/mytable(PartitionKey='<partition-key>',RowKey='<row-key>')?$select=<comma-separated-property-names>

https://myaccount.table.core.windows.net/mytable()?$filter=<query-expression>&$select=<comma-separated-property-names>		 HTTP/1.1

Die Adresse der abzufragenden Entität kann im Anforderungs-URI verschiedene Formen annehmen. Weitere Informationen finden Sie unter Abfragen von Tabellen und Entitäten.

Emulierter Speicherdienst-URI

Wenn Sie eine Anforderung an den emulierten Speicherdienst stellen, geben Sie den Hostnamen des Emulators und den Port des Tabellendiensts als an 127.0.0.1:10002. Folgen Sie diesen Informationen mit dem Namen des emulierten Speicherkontos.

Methode Anforderungs-URI HTTP-Version
GET http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey='<partition-key>',RowKey='<row-key>')?$select=<comma-separated-property-names>

http://127.0.0.1:10002/devstoreaccount1/mytable()?$filter=<query-expression>?$select=<comma-separated-property-names>		 HTTP/1.1

Der Tabellendienst im Speicheremulator unterscheidet sich auf verschiedene Weise von Azure Table Storage. Weitere Informationen finden Sie unter Unterschiede zwischen dem Speicheremulator und den Azure Storage-Diensten.

URI-Parameter

Der Query Entities Vorgang unterstützt die Abfrageoptionen, die in der OData-Protokollspezifikation definiert sind.

Anforderungsheader

In der folgenden Tabelle werden die erforderlichen und optionalen Anforderungsheader beschrieben:

Anforderungsheader BESCHREIBUNG
Authorization Erforderlich. Gibt das Autorisierungsschema, den Kontonamen und die Signatur an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage.
Date oder x-ms-date Erforderlich. Gibt die koordinierte Weltzeit (Coordinated Universal Time, UTC) für die Anforderung an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage.
x-ms-version Optional. Gibt die Version des für die Anforderung zu verwendenden Vorgangs an. Weitere Informationen finden Sie unter Versionsverwaltung für die Azure-Speicherdienste.
Accept Optional. Gibt den akzeptierten Inhaltstyp der Antwortnutzlast an. Mögliche Werte:

- application/atom+xml (Nur Versionen vor dem 11.12.2015)
- application/json;odata=nometadata
- application/json;odata=minimalmetadata
- application/json;odata=fullmetadata

Weitere Informationen finden Sie unter Nutzlastformat für Table Storage-Vorgänge.
x-ms-client-request-id Optional. Stellt einen vom Client generierten, undurchsichtigen Wert mit einem Zeichenlimit von 1 Kibibyte (KiB) bereit, der in den Protokollen aufgezeichnet wird, wenn die Protokollierung konfiguriert ist. Es wird dringend empfohlen, diesen Header zu verwenden, um clientseitige Aktivitäten mit Anforderungen zu korrelieren, die der Server empfängt.

Anforderungstext

Keine.

Beispiel für eine Anforderung

Request Syntax:  
GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince  HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-12-11  
x-ms-date: Mon, 27 Jun 2016 15:25:14 GMT  
Authorization: SharedKeyLite myaccount:<some key>  
Accept: application/json;odata=nometadata  
Accept-Charset: UTF-8  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx

Antwort

Die Antwort enthält den HTTP-Statuscode, einen Satz von Antwortheadern und einen Antworttext.

Statuscode

Bei einem erfolgreichen Vorgang wird der Statuscode 200 (OK) zurückgegeben.

Informationen zu status-Codes finden Sie unter Status- und Fehlercodes und Tabellenspeicherfehlercodes.

Antwortheader

Die Antwort für diesen Vorgang umfasst die folgenden Header. Die Antwort kann auch zusätzliche HTTP-Standardheader enthalten. Alle Standardheader entsprechen der HTTP/1.1-Protokollspezifikation.

Antwortheader BESCHREIBUNG
x-ms-continuation-NextPartitionKey

x-ms-continuation-NextRowKey		 Gibt Folgendes an:

– Die Anzahl der zurückzugebenden Entitäten übersteigt 1.000.
– Das Servertimeoutintervall wird überschritten.
– Eine Servergrenze wird erreicht, wenn die Abfrage Daten zurückgibt, die auf mehrere Server verteilt sind.

Weitere Informationen zur Verwendung der Fortsetzungstoken finden Sie unter Abfragetimeout und Paginierung.
x-ms-request-id Identifiziert die durchgeführte Anforderung eindeutig. Sie können ihn verwenden, um probleme mit der Anforderung zu beheben. Weitere Informationen finden Sie unter Problembehandlung für API-Vorgänge.
x-ms-version Gibt die Version von Table Storage an, die zum Ausführen der Anforderung verwendet wurde. Dieser Header wird für Anforderungen zurückgegeben, die für Version 2009-09-19 und höher erfolgen.
Date Ein UTC-Datums-/Uhrzeitwert, der den Zeitpunkt angibt, zu dem der Dienst die Antwort gesendet hat.
Content-Type Gibt den Inhaltstyp der Nutzlast an. Der Wert dieses Headers hängt vom Wert des Accept-Anforderungsheaders ab. Mögliche Werte:

- application/atom+xml (Nur Versionen vor dem 11.12.2015)
- application/json;odata=nometadata
- application/json;odata=minimalmetadata
- application/json;odata=fullmetadata

Weitere Informationen zu gültigen Inhaltstypen finden Sie unter Nutzlastformat für Table Storage-Vorgänge.
x-ms-client-request-id Kann zur Problembehandlung von Anforderungen und entsprechenden Antworten verwendet werden. Der Wert dieses Headers ist gleich dem Wert des x-ms-client-request-id Headers, wenn er in der Anforderung vorhanden ist und der Wert höchstens 1.024 sichtbare ASCII-Zeichen umfasst. Wenn der x-ms-client-request-id Header in der Anforderung nicht vorhanden ist, ist dieser Header in der Antwort nicht vorhanden.

Beispiel für eine Antwort

Response Status:  
HTTP/1.1 200 OK  
  
Response Headers:  
Content-Type: application/json  
x-ms-request-id: 87f178c0-44fe-4123-a4c1-96c8fa6d9654  
Date: Mon, 27 Jun 2016 15:25:14 GMT  
x-ms-version: 2015-12-11  
Connection: close

Antworttext

Der Query Entities Vorgang gibt die Liste der Entitäten in einer Tabelle als OData-Entitätssatz zurück. Die Liste der Entitäten ist je nach Accept Header der Anforderung entweder im JSON-Format oder in einem Atom-Feed enthalten.

Hinweis

Wir empfehlen JSON als Nutzlastformat. Dies ist das einzige unterstützte Format für Version 2015-12-11 und höher.

JSON (Version 2013-08-15 und höher)

Hier sehen Sie einen Beispielanforderungs-URI für einen Query Entities Vorgang in einer Kundentabelle:

GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince

Dies ist die Antwortnutzlast in JSON ohne Metadaten:

{  
   "value":[  
      {  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}

Dies ist die Antwortnutzlast in JSON mit minimalen Metadaten:

{  
   "odata.metadata":"https://myaccount.table.core.windows.net/$metadata#Customers",  
   "value":[  
      {  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince@odata.type":"Edm.DateTime",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}

Hier sehen Sie die Antwortnutzlast in JSON mit vollständigen Metadaten:

{  
   "odata.metadata":" https://myaccount.table.core.windows.net/metadata#Customers",  
   "value":[  
      {  
         "odata.type":"myaccount.Customers",  
         "odata.id":"https://myaccount.table.core.windows.net/Customers(PartitionKey=Customer',RowKey='Name')",  
         "odata.etag":"W/\"0x5B168C7B6E589D2\"",  
         "odata.editLink":"Customers(PartitionKey=Customer',RowKey='Name')",  
         "PartitionKey":"Customer",  
         "RowKey":"Name",  
         "Timestamp@odata.type":"Edm.DateTime",  
         "Timestamp":"2013-08-22T00:20:16.3134645Z",  
         "CustomerSince@odata.type":"Edm.DateTime",  
         "CustomerSince":"2008-10-01T15:25:05.2852025Z"  
      }  
   ]  
}

Atom-Feed (Versionen vor 2015-12-11)

Hier sehen Sie einen Beispielanforderungs-URI für einen Query Entities Vorgang in einer Kundentabelle:

GET /myaccount/Customers()?$filter=(Rating%20ge%203)%20and%20(Rating%20le%206)&$select=PartitionKey,RowKey,Address,CustomerSince

Hier sehen Sie eine Atom-Beispielantwort für den Query Entities Vorgang:

<?xml version="1.0" encoding="UTF-8"?>  
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xml:base="https://myaccount.table.core.windows.net">  
   <id>https://myaccount.table.core.windows.net/Customers</id>  
   <title type="text">Customers</title>  
   <updated>2013-08-22T00:50:32Z</updated>  
   <link rel="self" title="Customers" href="Customers" />  
   <entry m:etag="W/"0x5B168C7B6E589D2"">  
      <id>https://myaccount.table.core.windows.net/Customers(PartitionKey='Customer',RowKey='Name')</id>  
      <category term="myaccount.Customers" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />  
      <link rel="edit" title="Customers" href="Customers(PartitionKey='Customer',RowKey='Name')" />  
      <title />  
      <updated>2013-08-22T00:50:32Z</updated>  
      <author>  
         <name />  
      </author>  
      <content type="application/xml">  
         <m:properties>  
            <d:PartitionKey>Customer</d:PartitionKey>  
            <d:RowKey>Name</d:RowKey>  
            <d:Timestamp m:type="Edm.DateTime">2013-08-22T00:20:16.3134645Z</d:Timestamp>  
            <d:CustomerSince m:type="Edm.DateTime">2008-10-01T15:25:05.2852025Z</d:CustomerSince>  
         </m:properties>  
      </content>  
   </entry>  
</feed>

Authorization

Dieser Vorgang kann durch den Kontobesitzer und von jedem Benutzer mit einer SAS (Shared Access Signature) ausgeführt werden, der über die Berechtigung zum Ausführen des Vorgangs verfügt.

Hinweise

Eine Abfrage für Table Storage kann maximal 1.000 Entitäten gleichzeitig zurückgeben und maximal fünf Sekunden lang ausgeführt werden. Die Antwort enthält benutzerdefinierte Header, die einen Satz von Fortsetzungstoken in einem der folgenden Fälle enthalten:

  • Das Resultset enthält mehr als 1.000 Entitäten.
  • Die Abfrage wurde nicht innerhalb von fünf Sekunden abgeschlossen.
  • Die Abfrage überschreitet die Partitionsgrenze.

Sie können die Fortsetzungstoken verwenden, um eine nachfolgende Anforderung für die nächste Datenseite zu erstellen. Weitere Informationen zu Fortsetzungstoken finden Sie unter Abfragetimeout und Paginierung.

Hinweis

Wenn Sie nachfolgende Anforderungen ausführen, die Fortsetzungstoken enthalten, stellen Sie sicher, dass Sie den ursprünglichen URI für die Anforderung übergeben. Wenn Sie beispielsweise eine $filterAbfrageoption , $selectoder $top als Teil der ursprünglichen Anforderung angegeben haben, fügen Sie diese Option in nachfolgende Anforderungen ein. Andernfalls geben Ihre nachfolgenden Anforderungen möglicherweise unerwartete Ergebnisse zurück.

Die $top Abfrageoption gibt in diesem Fall die maximale Anzahl von Ergebnissen pro Seite an. Es gibt nicht die maximale Anzahl von Ergebnissen im gesamten Antwortsatz an.

Weitere Informationen finden Sie unter Abfragen von Tabellen und Entitäten.

Für Projektionsanforderungen, die die $select Abfrageoption verwenden, muss die Version 2011-08-18 oder höher sein. Die maximale Anzahl zurückgegebener Eigenschaften beträgt 255. Der Antworttext enthält alle projizierten Eigenschaften, auch wenn Eigenschaften nicht Teil der zurückgegebenen Entität sind.

Wenn die Anforderung beispielsweise eine Eigenschaft enthält, die in der projizierten Entität nicht enthalten ist, wird die fehlende Eigenschaft mit einem NULL-Attribut gekennzeichnet. Der obige Beispielantworttext enthält die Address -Eigenschaft, die nicht Teil der projizierten Entität ist. Der Wert der -Eigenschaft ist daher NULL: <d:Address m:null="true" />.

Die der Anforderung für die Planung und Verarbeitung der Abfrage zugewiesene Gesamtzeit beträgt 30 Sekunden. Diese Summe umfasst die fünf Sekunden für die Abfrageausführung.

Beachten Sie, dass die rechte Seite eines Abfrageausdrucks eine Konstante sein muss. Sie können nicht auf eine Eigenschaft auf der rechten Seite des Ausdrucks verweisen. Ausführliche Informationen zum Erstellen von Abfrageausdrücken finden Sie unter Abfragetabellen und Entitäten.

Ein Abfrageausdruck darf keine Werte enthalten null . Die folgenden Zeichen müssen codiert werden, wenn Sie sie in einer Abfragezeichenfolge verwenden:

  • Schrägstrich (/)

  • Fragezeichen (?)

  • Doppelpunkt (:)

  • At-Zeichen (@)

  • Kaufmännisches Und-Zeichen (&)

  • Gleichheitszeichen (=)

  • Pluszeichen (+)

  • Komma (,)

  • Dollarzeichen ($)

Jede Anwendung, die eine HTTP-Anforderung GET autorisieren und senden kann, kann Entitäten in einer Tabelle abfragen.

Weitere Informationen zu unterstützten Abfragevorgängen für Table Storage über LINQ finden Sie unter Unterstützte Abfrageoperatoren für Table Storage und Schreiben von LINQ-Abfragen für Table Storage.

Weitere Informationen

Tabellenspeicherfehlercodes
Autorisieren von Anforderungen an Azure Storage
Status- und Fehlercodes
Adressieren von Table Storage-Ressourcen
Abfragen von Tabellen und Entitäten
Festlegen der OData-Datendienst-Versionsheader
Entität einfügen
Entität aktualisieren
Entität löschen