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 zapytania i przedstawiono niektóre typowe scenariusze.
Podstawowa składnia zapytań
Aby zwrócić wszystkie tabele na danym koncie magazynu, wykonaj operację GET na zasobie Tabele zgodnie z opisem w operacji Tabele zapytań . Podstawowy identyfikator URI do adresowania zasobu Tables 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 PartitionKey, a następnie według RowKey. Kolejność wyników w inny sposób nie jest obecnie obsługiwana.
Można określić dodatkowe opcje, aby ograniczyć zestaw 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 w ciągu $filter dozwolone jest nie więcej niż 15 odrębnych porównań. |
$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 na potrzeby wykonywania stronicowania. Podczas wprowadzania kolejnych żądań zawierających tokeny kontynuacji pamiętaj o przekazaniu oryginalnego identyfikatora URI w żądaniu. Jeśli na przykład w ramach oryginalnego żądania określono $filteropcję , $selectlub $top kwerendy, 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 usługę 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.
W przypadku 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ągu zapytania
Następujące znaki muszą być zakodowane, jeśli mają być używane w ciągu zapytania:
- Ukośnik (/)
- Znak zapytania (?)
- Dwukropek (:)
- Symbol "At" (@)
- Ampersand (&)
- Znak równości (=)
- Znak plus (+)
- Przecinek (,)
- Znak dolara ($)
Pojedynczy cudzysłów (')
Apostrofy w ciągach zapytania muszą być reprezentowane jako dwa kolejne apostrofy (''). 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ń dotyczących jednostek przy użyciu składni REST. Te same zapytania można pisać 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 $top opcje , jak i $filter mogą służyć do filtrowania nazw tabel, korzystając ze składni przedstawionej 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 właściwości PartitionKey i RowKey
PartitionKey Ponieważ właściwości i RowKey tworzą klucz podstawowy jednostki, możesz użyć specjalnej składni, aby zidentyfikować jednostkę 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
Przed założeniem, że właściwość jest typu innego niż ciąg, upewnij się, że właściwość została jawnie wpisana. Jeśli właściwość została jawnie wpisana, typ jest wskazywany w odpowiedzi po zwróceniu jednostki. Jeśli właściwość nie została jawnie wpisana, będzie mieć typ String, a typ nie będzie wskazywany w odpowiedzi po zwróceniu jednostki.
Filtrowanie we właściwościach ciągu
Podczas filtrowania właściwości ciągu należy ująć stałą ciągu w apostrofy.
Poniższy przykład filtruje PartitionKey właściwości i RowKey . Do ciągu zapytania można również dodać dodatkowe właściwości inne niż klucz.
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'
Pamiętaj, że usługa Table Service nie obsługuje zapytań wieloznacznych. 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ć według liczby całkowitej lub liczby zmiennoprzecinkowej, określ stałą wartość identyfikatora URI bez cudzysłowów.
Ten przykład zwraca 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
W tym przykładzie zwracane są 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ć według wartości logicznej, 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 truewartość :
https://myaccount.table.core.windows.net/Customers()?$filter=IsActive%20eq%20true
Filtrowanie we właściwościach daty/godziny
Aby filtrować według DateTime wartości, określ datetime słowo kluczowe w identyfikatorze URI, a następnie stałą daty/godziny w apostrofach. 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