Mengkueri tabel dan entitas

  • Artikel

Mengkueri tabel dan entitas dalam layanan Tabel memerlukan konstruksi URI permintaan yang cermat. Bagian berikut ini menjelaskan opsi kueri dan menunjukkan beberapa skenario umum.

Sintaks Kueri Dasar

Untuk mengembalikan semua tabel di akun penyimpanan tertentu, lakukan GET operasi pada sumber daya Tabel, seperti yang dijelaskan dalam operasi Tabel Kueri . URI dasar untuk mengatasi sumber daya Tabel adalah sebagai berikut:

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

Untuk mengembalikan satu tabel bernama, tentukan tabel tersebut sebagai berikut:

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

Untuk mengembalikan semua entitas dalam tabel, tentukan nama tabel pada URI, tanpa sumber daya Tabel:

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

Hasil kueri diurutkan menurut PartitionKey, lalu menurut RowKey. Pengurutan menghasilkan dengan cara lain saat ini tidak didukung.

Anda bisa menentukan opsi tambahan untuk membatasi kumpulan tabel atau entitas yang dikembalikan, seperti yang dijelaskan di bagian Opsi Kueri yang Didukung berikut ini.

Catatan

Jumlah entitas yang dikembalikan untuk satu permintaan mungkin dibatasi, jika kueri melebihi jumlah maksimum entitas, melebihi interval batas waktu, atau melewati batas partisi. Untuk informasi selengkapnya, lihat Batas Waktu Kueri dan Penomoran Halaman.

Opsi Kueri yang Didukung

Layanan Tabel mendukung opsi kueri berikut, yang sesuai dengan Spesifikasi Protokol OData. Anda dapat menggunakan opsi ini untuk membatasi kumpulan tabel, entitas, atau properti entitas yang dikembalikan oleh kueri.

Opsi kueri sistem Deskripsi
$filter Mengembalikan hanya tabel atau entitas yang memenuhi filter yang ditentukan.

Perhatikan bahwa tidak lebih dari 15 perbandingan diskrit diizinkan dalam $filter string.
$top Hanya mengembalikan tabel atau entitas teratas n dari set.
$select Mengembalikan properti entitas yang diinginkan dari set. Opsi kueri ini hanya didukung untuk permintaan yang menggunakan versi 2011-08-18 atau yang lebih baru. Untuk informasi selengkapnya, lihat Menulis Kueri LINQ Terhadap Layanan Tabel.

Catatan

Permintaan yang mengembalikan lebih dari maksimum default atau jumlah hasil maksimum yang ditentukan mengembalikan token kelanjutan untuk melakukan pagination. Saat membuat permintaan berikutnya yang menyertakan token kelanjutan, pastikan untuk meneruskan URI asli atas permintaan. Misalnya, jika Anda telah menentukan $filteropsi kueri , , $selectatau $top sebagai bagian dari permintaan asli, Anda akan ingin menyertakan opsi tersebut pada permintaan berikutnya. Jika tidak, permintaan Anda berikutnya dapat mengembalikan hasil yang tidak terduga. Lihat Batas Waktu Kueri dan Penomoran Halaman untuk informasi tambahan.

Perhatikan bahwa $top opsi kueri dalam kasus di mana hasil dipaginasi menentukan jumlah hasil maksimum per halaman, bukan jumlah maksimum hasil di seluruh set respons.

Opsi kueri tambahan yang ditentukan oleh OData tidak didukung oleh layanan Tabel.

Operator Perbandingan yang Didukung

$filter Dalam klausa, Anda dapat menggunakan operator perbandingan untuk menentukan kriteria untuk memfilter hasil kueri.

Untuk semua jenis properti, operator perbandingan berikut didukung:

Operator Ekspresi URI
Equal eq
GreaterThan gt
GreaterThanOrEqual ge
LessThan lt
LessThanOrEqual le
NotEqual ne

Selain itu, operator berikut didukung untuk properti Boolean:

Operator Ekspresi URI
And and
Not not
Or or

Untuk informasi selengkapnya tentang sintaks filter, lihat Spesifikasi Protokol OData.

Pengodean String Kueri

Karakter berikut harus dikodekan jika akan digunakan dalam string kueri:

  • Garis miring (/)
  • Tanda tanya (?)
  • Titik dua (:)
  • Simbol 'At' (@)
  • Ampersand (&)
  • Tanda sama dengan (=)
  • Tanda plus (+)
  • Koma (,)
  • Tanda dolar ($)

Kutipan tunggal (')

Tanda kutip tunggal dalam string kueri harus direpresentasikan sebagai dua tanda kutip tunggal berturut-turut (''). Misalnya, "jam" adalah:

o''clock

Contoh Ekspresi Kueri

Sampel berikut menunjukkan cara membuat URI permintaan untuk beberapa kueri entitas umum menggunakan sintaks REST. Kueri yang sama dapat ditulis menggunakan sintaks LINQ. Untuk informasi selengkapnya, lihat Menulis Kueri LINQ Terhadap Layanan Tabel.

Perhatikan bahwa opsi $top dan $filter juga dapat digunakan untuk memfilter nama tabel, menggunakan sintaks yang ditunjukkan untuk pemfilteran pada properti jenis String.

Mengembalikan Entitas n Teratas

Untuk mengembalikan entitas teratas n untuk kueri apa pun, tentukan $top opsi kueri. Contoh berikut mengembalikan 10 entitas teratas dari tabel bernama Pelanggan:

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

Pemfilteran pada Properti PartitionKey dan RowKey

PartitionKey Karena properti dan RowKey membentuk kunci utama entitas, Anda dapat menggunakan sintaks khusus untuk mengidentifikasi entitas, sebagai berikut:

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

Atau, Anda dapat menentukan properti ini sebagai bagian dari opsi $filter, seperti yang diperlihatkan di bagian berikut.

Perhatikan bahwa nama properti kunci dan nilai konstanta peka huruf besar/kecil. PartitionKey Baik properti dan RowKey berjenis String.

Membuat String Filter

Saat membuat string filter, ingatlah aturan ini:

  • Gunakan operator logis yang ditentukan oleh Spesifikasi Protokol OData untuk membandingkan properti dengan nilai. Perhatikan bahwa Anda tidak dapat membandingkan properti dengan nilai dinamis; satu sisi ekspresi harus berupa konstanta.

  • Nama properti, operator, dan nilai konstanta harus dipisahkan dengan spasi yang dikodekan URL. Spasi dikodekan URL sebagai %20.

  • Semua bagian string filter peka huruf besar/kecil.

  • Nilai konstanta harus memiliki jenis data yang sama dengan properti agar filter mengembalikan hasil yang valid. Untuk informasi selengkapnya tentang jenis properti yang didukung, lihat lihat Memahami Model Data Layanan Tabel.

Catatan

Pastikan untuk memeriksa apakah properti telah ditik secara eksplisit sebelum mengasumsikan properti tersebut adalah jenis selain string. Jika properti telah ditik secara eksplisit, jenis ditunjukkan dalam respons saat entitas dikembalikan. Jika properti belum ditik secara eksplisit, properti akan berjenis String, dan jenisnya tidak akan ditunjukkan dalam respons ketika entitas dikembalikan.

Pemfilteran pada Properti String

Saat memfilter properti string, sertakan konstanta string dalam tanda kutip tunggal.

Contoh filter berikut pada PartitionKey properti dan RowKey ; properti non-kunci tambahan juga dapat ditambahkan ke string kueri.

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

Contoh berikut memfilter properti FirstName dan LastName :

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

Perhatikan bahwa layanan Tabel tidak mendukung kueri kartubebas. Namun, Anda dapat melakukan pencocokan awalan dengan menggunakan operator perbandingan pada awalan yang diinginkan. Contoh berikut mengembalikan entitas dengan properti yang LastName dimulai dengan huruf 'A':

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

Pemfilteran pada Properti Numerik

Untuk memfilter bilangan bulat atau angka floating-point, tentukan nilai konstanta pada URI tanpa tanda kutip.

Contoh ini mengembalikan semua entitas dengan properti yang Age nilainya lebih besar dari 30:

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

Contoh ini mengembalikan semua entitas dengan AmountDue properti yang nilainya kurang dari atau sama dengan 100,25:

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

Pemfilteran pada Properti Boolean

Untuk memfilter nilai Boolean, tentukan true atau false tanpa tanda kutip.

Contoh berikut mengembalikan semua entitas di mana IsActive properti diatur ke true:

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

Pemfilteran pada Properti DateTime

Untuk memfilter DateTime nilai, tentukan datetime kata kunci pada URI, diikuti dengan konstanta tanggal/waktu dalam tanda kutip tunggal. Konstanta tanggal/waktu harus dalam format UTC gabungan, seperti yang dijelaskan dalam Memformat nilai DateTime.

Contoh berikut mengembalikan entitas di mana CustomerSince properti sama dengan 10 Juli 2008:

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

Pemfilteran pada Properti GUID

Untuk memfilter nilai GUID, tentukan guid kata kunci pada URI, diikuti dengan konstanta guid dalam tanda kutip tunggal.

Contoh berikut mengembalikan entitas di mana GuidValue properti sama dengan :

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

Lihat juga

Konsep Layanan Tabel
Memahami Model Data Layanan Tabel
Mengatasi Sumber Daya Layanan Tabel
Batas Waktu Kueri dan Penomoran Halaman
Menulis Kueri LINQ Terhadap Layanan Tabel