Wykonywanie zapytań o jednostki

  • Artykuł

Operacja Query Entities wykonuje zapytanie o jednostki w tabeli i zawiera $filter opcje i $select .

Żądanie

W przypadku żądań korzystających $select z opcji zapytania należy użyć wersji 2011-08-18 lub nowszej. Ponadto DataServiceVersion nagłówki i MaxDataServiceVersion muszą być ustawione na 2.0wartość .

Aby użyć projekcji, musisz wysłać żądanie przy użyciu wersji 2013-08-15 lub nowszej. Nagłówki DataServiceVersion i MaxDataServiceVersion muszą być ustawione na 3.0. Aby uzyskać więcej informacji, zobacz Ustawianie nagłówków wersji usługi danych OData.

Żądanie można skonstruować Query Entities w następujący sposób. Zalecamy użycie protokołu HTTPS. Zastąp ciąg myaccount nazwą konta magazynu i zastąp ciąg mytable nazwą tabeli.

Metoda Identyfikator URI żądania Wersja PROTOKOŁU HTTP
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

Adres zestawu jednostek do odpytowania może mieć różne formy w identyfikatorze URI żądania. Aby uzyskać więcej informacji, zobacz Query tables and entities (Wykonywanie zapytań o tabele i jednostki).

Identyfikator URI usługi magazynu emulowanego

Gdy wysyłasz żądanie względem usługi magazynu emulowanego, określ nazwę hosta emulatora i port usługi table service jako 127.0.0.1:10002. Postępuj zgodnie z informacjami o nazwie emulowanego konta magazynu.

Metoda Identyfikator URI żądania Wersja PROTOKOŁU HTTP
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

Usługa Table Service w emulatorze magazynu różni się od usługi Azure Table Storage na kilka sposobów. Aby uzyskać więcej informacji, zobacz Różnice między emulatorem magazynu i usługami Azure Storage.

Parametry identyfikatora URI

Operacja Query Entities obsługuje opcje zapytania zdefiniowane przez specyfikację protokołu OData .

Nagłówki żądań

W poniższej tabeli opisano wymagane i opcjonalne nagłówki żądań:

Nagłówek żądania Opis
Authorization Wymagane. Określa schemat autoryzacji, nazwę konta i podpis. Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage.
Date lub x-ms-date Wymagane. Określa dla żądania godzinę w formacie uniwersalnego czasu koordynowanego (UTC). Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage.
x-ms-version Opcjonalny. Określa wersję operacji do użycia dla tego żądania. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji dla usług Azure Storage.
Accept Opcjonalny. Określa akceptowany typ zawartości ładunku odpowiedzi. Możliwe wartości:

- application/atom+xml (wersje wcześniejsze niż 2015-12-11)
- application/json;odata=nometadata
- application/json;odata=minimalmetadata
- application/json;odata=fullmetadata

Aby uzyskać więcej informacji, zobacz Format ładunku dla operacji usługi Table Storage.
x-ms-client-request-id Opcjonalny. Zapewnia nieprzezroczystą wartość wygenerowaną przez klienta z limitem znaków 1-kibibyte (KiB) rejestrowanym w dziennikach podczas konfigurowania rejestrowania. Zdecydowanie zalecamy używanie tego nagłówka do korelowania działań po stronie klienta z żądaniami odbieranymi przez serwer.

Treść żądania

Brak.

Przykładowe żądanie

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

Reakcja

Odpowiedź zawiera kod stanu HTTP, zestaw nagłówków odpowiedzi i treść odpowiedzi.

Kod stanu

Pomyślna operacja zwraca kod stanu 200 (OK).

Aby uzyskać informacje o kodach stanu, zobacz Kody stanu i błędów oraz Kody błędów usługi Table Storage.

Nagłówki odpowiedzi

Odpowiedź na tę operację zawiera następujące nagłówki. Odpowiedź może również zawierać dodatkowe standardowe nagłówki HTTP. Wszystkie standardowe nagłówki są zgodne ze specyfikacją protokołu HTTP/1.1.

Nagłówek odpowiedzi Opis
x-ms-continuation-NextPartitionKey

x-ms-continuation-NextRowKey		 Wskazuje, że:

— Liczba zwracanych jednostek przekracza 1000.
— Przekroczono interwał limitu czasu serwera.
— Osiągnięto granicę serwera, jeśli zapytanie zwraca dane rozłożone na wiele serwerów.

Aby uzyskać więcej informacji na temat korzystania z tokenów kontynuacji, zobacz Limit czasu zapytań i stronicowanie.
x-ms-request-id Unikatowo identyfikuje żądanie, które zostało wykonane. Można go użyć do rozwiązywania problemów z żądaniem. Aby uzyskać więcej informacji, zobacz Rozwiązywanie problemów z operacjami interfejsu API.
x-ms-version Wskazuje wersję usługi Table Storage, która została użyta do wykonania żądania. Ten nagłówek jest zwracany w przypadku żądań wysyłanych w wersji 2009-09-19 lub nowszej.
Date Wartość daty/godziny UTC wskazująca godzinę, o której usługa wysłała odpowiedź.
Content-Type Wskazuje typ zawartości ładunku. Wartość tego nagłówka zależy od wartości nagłówka Accept żądania. Możliwe wartości:

- application/atom+xml (wersje wcześniejsze niż 2015-12-11)
- application/json;odata=nometadata
- application/json;odata=minimalmetadata
- application/json;odata=fullmetadata

Aby uzyskać więcej informacji na temat prawidłowych typów zawartości, zobacz Format ładunku dla operacji usługi Table Storage.
x-ms-client-request-id Może służyć do rozwiązywania problemów z żądaniami i odpowiadającymi odpowiedziami. Wartość tego nagłówka jest równa wartości nagłówka x-ms-client-request-id , jeśli jest obecna w żądaniu, a wartość wynosi najwyżej 1024 widoczne znaki ASCII. x-ms-client-request-id Jeśli nagłówek nie istnieje w żądaniu, ten nagłówek nie będzie obecny w odpowiedzi.

Przykładowa odpowiedź

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

Treść odpowiedzi

Operacja Query Entities zwraca listę jednostek w tabeli jako zestaw jednostek OData. Lista jednostek znajduje się w formacie JSON lub kanale informacyjnym Atom w zależności od Accept nagłówka żądania.

Uwaga

Zalecamy użycie formatu JSON jako formatu ładunku. Jest to jedyny obsługiwany format dla wersji 2015-12-11 lub nowszej.

JSON (wersja 2013-08-15 i nowsze)

Oto przykładowy identyfikator URI żądania dla Query Entities operacji w tabeli klientów:

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

Oto ładunek odpowiedzi w formacie JSON bez metadanych:

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

Oto ładunek odpowiedzi w formacie JSON z minimalnymi metadanymi:

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

Oto ładunek odpowiedzi w formacie JSON z pełnymi metadanymi:

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

Źródło danych Atom (wersje przed 2015-12-11)

Oto przykładowy identyfikator URI żądania dla Query Entities operacji w tabeli klientów:

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

Oto przykładowa odpowiedź Atom dla Query Entities operacji:

<?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>

Autoryzacja

Ta operacja może być wykonywana przez właściciela konta i przez każdego, kto ma sygnaturę dostępu współdzielonego, która ma uprawnienia do wykonania tej operacji.

Uwagi

Zapytanie względem usługi Table Storage może zwrócić maksymalnie 1000 jednostek jednocześnie i może działać przez maksymalnie pięć sekund. Odpowiedź zawiera nagłówki niestandardowe zawierające zestaw tokenów kontynuacji w dowolnym z następujących przypadków:

  • Zestaw wyników zawiera ponad 1000 jednostek.
  • Zapytanie nie zostało zakończone w ciągu pięciu sekund.
  • Zapytanie przekracza granicę partycji.

Możesz użyć tokenów kontynuacji, aby utworzyć kolejne żądanie dla następnej strony danych. Aby uzyskać więcej informacji na temat tokenów kontynuacji, zobacz Limit czasu zapytania i stronicowanie.

Uwaga

Podczas wykonywania kolejnych żądań zawierających tokeny kontynuacji pamiętaj o przekazaniu oryginalnego identyfikatora URI w żądaniu. Jeśli na przykład określono $filteropcję , $selectlub $top kwerendy w ramach oryginalnego żądania, dołącz tę opcję do kolejnych żądań. W przeciwnym razie kolejne żądania mogą zwracać nieoczekiwane wyniki.

Opcja $top zapytania w tym przypadku określa maksymalną liczbę wyników na stronę. Nie określa maksymalnej liczby wyników w całym zestawie odpowiedzi.

Aby uzyskać więcej informacji, zobacz Wykonywanie zapytań dotyczących tabel i jednostek.

W przypadku żądań projekcji korzystających z $select opcji zapytania wersja musi mieć wartość 2011-08-18 lub nowszą. Maksymalna liczba zwracanych właściwości to 255. Treść odpowiedzi zawiera wszystkie przewidywane właściwości, nawet jeśli właściwości nie są częścią zwracanej jednostki.

Jeśli na przykład żądanie zawiera właściwość, która nie zawiera przewidywanej jednostki, brakująca właściwość jest oznaczona atrybutem null. Poprzednia przykładowa treść odpowiedzi zawiera Address właściwość, która nie jest częścią przewidywanej jednostki. Wartość właściwości ma wartość null: <d:Address m:null="true" />.

Łączny czas przydzielony do żądania planowania i przetwarzania zapytania wynosi 30 sekund. Ta suma obejmuje pięć sekund wykonywania zapytań.

Należy pamiętać, że prawa strona wyrażenia zapytania musi być stałą. Nie można odwołać się do właściwości po prawej stronie wyrażenia. Aby uzyskać szczegółowe informacje na temat tworzenia wyrażeń zapytań, zobacz Tworzenie tabel i jednostek zapytań.

Wyrażenie zapytania nie może zawierać null wartości. Następujące znaki muszą być zakodowane, jeśli są one używane w ciągu zapytania:

  • Ukośnik do przodu (/)

  • Znak zapytania (?)

  • Dwukropek (:)

  • Pod znakiem (@)

  • Ampersand (&)

  • Znak równości (=)

  • Znak plus (+)

  • Przecinek (,)

  • Znak dolara ($)

Każda aplikacja, która może autoryzować i wysyłać żądanie HTTP GET , może wysyłać zapytania do jednostek w tabeli.

Aby uzyskać więcej informacji na temat obsługiwanych operacji zapytań w usłudze Table Storage za pośrednictwem LINQ, zobacz Operatory zapytań obsługiwanych dla usługi Table Storage i zapisu zapytań LINQ w usłudze Table Storage.

Zobacz też

Kody błędów usługi Table Storage
Autoryzowanie żądań do usługi Azure Storage
Kody stanu i błędów
Adresowanie zasobów usługi Table Storage
Wykonywanie zapytań dotyczących tabel i jednostek
Ustawianie nagłówków wersji usługi danych OData
Wstaw jednostkę
Aktualizowanie jednostki
Usuwanie jednostki