Wykonywanie zapytań dotyczących tabel i jednostek

Wykonywanie zapytań dotyczących tabel i jednostek w usłudze Table service wymaga starannej konstrukcji identyfikatora URI żądania. W poniższych sekcjach opisano opcje zapytań i przedstawiono niektóre typowe scenariusze.

Podstawowa składnia zapytań

Aby zwrócić wszystkie tabele na danym koncie magazynu, wykonaj operację na zasobie Tabele zgodnie z opisem GET w operacji Tabele zapytań . Podstawowy identyfikator URI adresowania zasobu Tabele jest następujący:

https://myaccount.table.core.windows.net/Tables  

Aby zwrócić pojedynczą nazwaną tabelę, określ następującą tabelę:

https://myaccount.table.core.windows.net/Tables('MyTable')  

Aby zwrócić wszystkie jednostki w tabeli, określ nazwę tabeli w identyfikatorze URI bez zasobu Tables:

https://myaccount.table.core.windows.net/MyTable()  

Wyniki zapytania są sortowane według PartitionKeywartości , a następnie według RowKey. Kolejność wyników w inny sposób nie jest obecnie obsługiwana.

Można określić dodatkowe opcje ograniczenia zestawu zwracanych tabel lub jednostek, zgodnie z opisem w poniższej sekcji Obsługiwane opcje zapytania .

Uwaga

Liczba jednostek zwracanych dla pojedynczego żądania może być ograniczona, jeśli zapytanie przekracza maksymalną liczbę jednostek, przekracza interwał limitu czasu lub przekracza granicę partycji. Aby uzyskać więcej informacji, zobacz Limit czasu zapytania i stronicowanie.

Obsługiwane opcje zapytania

Usługa Table Service obsługuje następujące opcje zapytania, które są zgodne ze specyfikacją protokołu OData. Za pomocą tych opcji można ograniczyć zestaw tabel, jednostek lub właściwości jednostki zwracanych przez zapytanie.

Opcja zapytania systemowego Opis
$filter Zwraca tylko tabele lub jednostki, które spełniają określony filtr.

Należy pamiętać, że nie więcej niż 15 odrębnych porównań jest dozwolonych w ciągu $filter .
$top Zwraca tylko najważniejsze n tabele lub jednostki z zestawu.
$select Zwraca żądane właściwości jednostki z zestawu. Ta opcja zapytania jest obsługiwana tylko w przypadku żądań korzystających z wersji 2011-08-18 lub nowszej. Aby uzyskać więcej informacji, zobacz Pisanie zapytań LINQ względem usługi Table Service.

Uwaga

Żądanie zwracające więcej niż domyślna maksymalna lub określona maksymalna liczba wyników zwraca token kontynuacji do wykonywania stronicowania. Podczas wysyłania kolejnych żądań, które zawierają tokeny kontynuacji, pamiętaj o przekazaniu oryginalnego identyfikatora URI żądania. Jeśli na przykład określono opcję , $selectlub $top kwerendy $filterw ramach oryginalnego żądania, należy dołączyć tę opcję do kolejnych żądań. W przeciwnym razie kolejne żądania mogą zwracać nieoczekiwane wyniki. Aby uzyskać dodatkowe informacje, zobacz Limit czasu zapytania i stronicowanie .

Należy pamiętać, że $top opcja zapytania w przypadku, gdy wyniki są podzielone na strony, określa maksymalną liczbę wyników na stronę, a nie maksymalną liczbę wyników w całym zestawie odpowiedzi.

Dodatkowe opcje zapytania zdefiniowane przez OData nie są obsługiwane przez usługę Table Service.

Obsługiwane operatory porównania

$filter W ramach klauzuli można użyć operatorów porównania, aby określić kryteria filtrowania wyników zapytania.

Dla wszystkich typów właściwości obsługiwane są następujące operatory porównania:

Operator Wyrażenie identyfikatora URI
Equal eq
GreaterThan gt
GreaterThanOrEqual ge
LessThan lt
LessThanOrEqual le
NotEqual ne

Ponadto następujące operatory są obsługiwane dla właściwości logicznych:

Operator Wyrażenie identyfikatora URI
And and
Not not
Or or

Aby uzyskać więcej informacji na temat składni filtru, zobacz specyfikację protokołu OData.

Kodowanie ciągów zapytania

Następujące znaki muszą być zakodowane, jeśli mają być używane w ciągu zapytania:

  • Ukośnik do przodu (/)
  • Znak zapytania (?)
  • Dwukropek (:)
  • Symbol "At" (@)
  • Ampersand (&)
  • Znak równości (=)
  • Znak plus (+)
  • Przecinek (,)
  • Znak dolara ($)

Pojedynczy cudzysłów (')

Pojedyncze cudzysłowy w ciągach zapytania muszą być reprezentowane jako dwa kolejne pojedyncze cudzysłowy (''). Na przykład "o'clock" będzie:

o''clock

Przykładowe wyrażenia zapytań

W poniższych przykładach pokazano, jak utworzyć identyfikator URI żądania dla niektórych typowych zapytań jednostek przy użyciu składni REST. Te same zapytania można napisać przy użyciu składni LINQ. Aby uzyskać więcej informacji, zobacz Pisanie zapytań LINQ względem usługi Table Service.

Należy pamiętać, że zarówno opcje $top , jak i $filter mogą służyć do filtrowania nazw tabel, przy użyciu składni pokazanej do filtrowania właściwości typu String.

Zwracanie pierwszych n jednostek

Aby zwrócić najważniejsze n jednostki dla dowolnego zapytania, określ $top opcję zapytania. Poniższy przykład zwraca 10 pierwszych jednostek z tabeli o nazwie Customers:

https://myaccount.table.core.windows.net/Customers()?$top=10  

Filtrowanie we właściwościach PartitionKey i RowKey

PartitionKey Ponieważ właściwości i RowKey tworzą klucz podstawowy jednostki, można użyć specjalnej składni w celu zidentyfikowania jednostki w następujący sposób:

https://myaccount.table.core.windows.net/Customers(PartitionKey='MyPartition',RowKey='MyRowKey1')  

Można także określić te właściwości jako część opcji $filter, jak pokazano w poniższej sekcji.

Należy pamiętać, że w nazwach właściwości kluczy i wartościach stałych jest rozróżniana wielkość liter. PartitionKey Właściwości i RowKey są typu String.

Konstruowanie ciągów filtru

Podczas tworzenia ciągu filtru należy pamiętać o następujących regułach:

  • Użyj operatorów logicznych zdefiniowanych przez specyfikację protokołu OData , aby porównać właściwość z wartością. Należy pamiętać, że nie można porównać właściwości z wartością dynamiczną; jedna strona wyrażenia musi być stałą.

  • Nazwa właściwości, operator i wartość stała muszą być oddzielone spacjami zakodowanymi w adresie URL. Spacja jest zakodowana w adresie URL jako %20.

  • We wszystkich częściach ciągu filtru jest rozróżniana wielkość liter.

  • Wartość stała musi mieć ten sam typ danych co właściwość, aby filtr zwracał prawidłowe wyniki. Aby uzyskać szczegółowe informacje na temat obsługiwanych typów właściwości, zobacz Omówienie modelu danych usługi Table service.

Uwaga

Pamiętaj, aby sprawdzić, czy właściwość została jawnie wpisana przed założeniem, że jest to typ inny niż ciąg. Jeśli właściwość została jawnie wpisana, typ jest wskazywany w odpowiedzi po powrocie jednostki. Jeśli właściwość nie została jawnie wpisana, będzie Stringona typu , a typ nie będzie wskazywany w odpowiedzi po powrocie jednostki.

Filtrowanie we właściwościach ciągu

Podczas filtrowania właściwości ciągu należy ująć stałą ciągu w pojedyncze cudzysłowy.

Poniższy przykład filtruje PartitionKey właściwości i RowKey . Dodatkowe właściwości inne niż klucz można również dodać do ciągu zapytania.

https://myaccount.table.core.windows.net/Customers()?$filter=PartitionKey%20eq%20'MyPartitionKey'%20and%20RowKey%20eq%20'MyRowKey1'  

Poniższy przykład filtruje właściwość FirstName i LastName :

https://myaccount.table.core.windows.net/Customers()?$filter=LastName%20eq%20'Smith'%20and%20FirstName%20eq%20'John'  

Należy pamiętać, że usługa Table Service nie obsługuje zapytań z symbolami wieloznacznymi. Można jednak wykonać dopasowywanie prefiksów przy użyciu operatorów porównania w żądanym prefiksie. Poniższy przykład zwraca jednostki z właściwością rozpoczynającą się literą LastName "A":

https://myaccount.table.core.windows.net/Customers()?$filter=LastName%20ge%20'A'%20and%20LastName%20lt%20'B'  

Filtrowanie we właściwościach liczbowych

Aby filtrować liczbę całkowitą lub zmiennoprzecinkową, określ stałą wartość identyfikatora URI bez cudzysłowów.

W tym przykładzie zwracane są wszystkie jednostki z właściwością Age , której wartość jest większa niż 30:

https://myaccount.table.core.windows.net/Customers()?$filter=Age%20gt%2030  

Ten przykład zwraca wszystkie jednostki z właściwością AmountDue , której wartość jest mniejsza lub równa 100,25:

https://myaccount.table.core.windows.net/Customers()?$filter=AmountDue%20le%20100.25%20  

Filtrowanie właściwości logicznych

Aby filtrować wartość logiczną, określ true lub false bez cudzysłowów.

Poniższy przykład zwraca wszystkie jednostki, w których właściwość jest ustawiona IsActive na true:

https://myaccount.table.core.windows.net/Customers()?$filter=IsActive%20eq%20true  

Filtrowanie we właściwościach daty/godziny

Aby filtrować wartość DateTime , określ datetime słowo kluczowe w identyfikatorze URI, a następnie stałą daty/godziny w cudzysłowach pojedynczych. Stała data/godzina musi być w formacie UTC w połączeniu, zgodnie z opisem w temacie Formatowanie wartości DateTime.

Poniższy przykład zwraca jednostki, w których CustomerSince właściwość jest równa 10 lipca 2008 r.:

https://myaccount.table.core.windows.net/Customers()?$filter=CustomerSince%20eq%20datetime'2008-07-10T00:00:00Z'  

Filtrowanie we właściwościach identyfikatora GUID

Aby filtrować wartość identyfikatora GUID, określ guid słowo kluczowe w identyfikatorze URI, a następnie stałą guid w cudzysłowach pojedynczych.

Poniższy przykład zwraca jednostki, w których GuidValue właściwość jest równa :

https://myaccount.table.core.windows.net/Customers()?$filter=GuidValue%20eq%20guid'a455c695-df98-5678-aaaa-81d3367e5a34'  

Zobacz też

Pojęcia dotyczące usługi Table service
Opis modelu danych usługi Table Service
Adresowanie zasobów usługi Table Service
Przekroczenie limitu czasu zapytania i stronicowanie
Pisanie zapytań LINQ względem usługi Table Service