Udostępnij za pośrednictwem

Wykonywanie zapytań dotyczących tabel i jednostek

  • Artykuł

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