Mengkueri sumber daya Azure Cosmos DB menggunakan REST API

Artikel
07/19/2023

Azure Cosmos DB adalah database multi-model yang didistribusikan secara global dengan dukungan untuk beberapa API. Artikel ini menjelaskan cara menggunakan REST untuk mengkueri sumber daya menggunakan SQL API.

Bagaimana cara mengkueri sumber daya dengan menggunakan REST?

Untuk melakukan kueri SQL pada sumber daya, lakukan hal berikut:

Jalankan POST metode terhadap jalur sumber daya menggunakan JSON dengan properti yang query diatur ke string kueri SQL, dan properti "parameter" diatur ke array nilai parameter opsional.
Atur header x-ms-documentdb-isquery ke True.
Atur header Content-Type ke application/query+json.

Untuk sampel yang menunjukkan cara melakukan kueri SQL pada sumber daya menggunakan .NET, lihat REST dari Sampel .NET.

Contoh

Di bawah ini adalah contoh operasi kueri REST pada sumber daya dokumen. Dalam contoh ini, kami ingin menemukan semua dokumen yang memiliki "Don" sebagai penulis.

POST https://contosomarketing.documents.azure.com/dbs/XP0mAA==/colls/XP0mAJ3H-AA=/docs HTTP/1.1  
x-ms-documentdb-isquery: True  
x-ms-date: Mon, 18 Apr 2015 13:05:49 GMT  
authorization: type%3dmaster%26ver%3d1.0%26sig%3dkOU%2bBn2vkvIlHypfE8AA5fulpn8zKjLwdrxBqyg0YGQ%3d  
x-ms-version: 2015-12-16  
x-ms-query-enable-crosspartition: True  
Accept: application/json  
Content-Type: application/query+json  
Host: contosomarketing.documents.azure.com  
Content-Length: 50  

{  
    "query": "SELECT * FROM root WHERE (root.Author.id = 'Don')",  
    "parameters": []  
}

Detail Permintaan

Metode	URI Permintaan
KIRIM	Wajib Diisi. Jenis autentikasi dan token tanda tangan. Hanya token kunci master yang diizinkan untuk operasi ini. Untuk informasi selengkapnya, lihat Access Control tentang Cosmos DB Resources.

Judul Permintaan

Tabel berikut berisi header umum yang digunakan untuk melakukan operasi kueri.

Header Standar	Deskripsi
Authorization	Wajib Diisi. Jenis autentikasi dan token tanda tangan. Hanya token kunci master yang diizinkan untuk operasi ini. Untuk informasi selengkapnya, lihat Access Control tentang Cosmos DB Resources.
Tipe-Konten	Wajib Diisi. Harus diatur ke application/query+json.
Terima	Opsional. Saat ini, Cosmos DB selalu mengembalikan payload respons dalam format JSON standar. Klien harus dapat menerima isi respons dalam format JSON standar.
User-Agent	Opsional. Agen pengguna yang melakukan permintaan. Format yang disarankan adalah {nama agen pengguna}/{versi}. Misalnya, SQL API .NET SDK mengatur string User-Agent ke Microsoft.Document.Client/1.0.0.0.

Header Kustom	Deskripsi
x-ms-date	Wajib Diisi. Tanggal permintaan, seperti yang ditentukan dalam RFC 1123. Format tanggal dinyatakan dalam Waktu Universal Terkoordinasi (UTC), misalnya. Jum, 08 Apr 2015 03:52:31 GMT.
x-ms-documentdb-isquery	Wajib Diisi. Properti ini harus diatur ke true.
x-ms-max-item-count	Opsional. Untuk halaman melalui kumpulan hasil, atur header ini ke angka maksimum untuk item yang akan dikembalikan dalam satu halaman.
x-ms-continuation	Opsional. Untuk menavigasi ke halaman item berikutnya, atur header ini ke token kelanjutan untuk halaman berikutnya.
x-ms-version	Opsional. Versi layanan Cosmos DB REST. Versi terbaru digunakan ketika header tidak disediakan. Untuk informasi selengkapnya, lihat Referensi REST API Azure Cosmos DB.
x-ms-documentdb-query-enable-scan	Opsional. Gunakan pemindaian indeks untuk memproses kueri jika jalur indeks jenis yang tepat tidak tersedia.
x-ms-session-token	Opsional. Token sesi untuk permintaan. Digunakan untuk konsistensi sesi.
x-ms-partition-key	Opsional. Jika ditentukan, kueri hanya dijalankan pada dokumen yang cocok dengan nilai kunci partisi di header .
x-ms-documentdb-query-enablecrosspartition	Opsional. Harus diatur ke true untuk kueri apa pun yang tidak memfilter terhadap satu kunci partisi. Kueri yang memfilter terhadap nilai kunci partisi tunggal akan dijalankan hanya terhadap satu partisi bahkan jika ini diatur ke true.
x-ms-documentdb-populatequerymetrics	Opsional. Harus diatur ke `True` untuk mengembalikan metrik kueri

Isi Permintaan

Isi permintaan harus berupa dokumen JSON yang valid yang berisi kueri dan parameter SQL. Jika input salah format atau sintaks SQL tidak valid, operasi dengan gagal dengan kesalahan 400 Permintaan Buruk.

Anda juga akan mendapatkan 400 permintaan buruk jika kueri tidak dapat dilayani oleh gateway.

Properti	Deskripsi
query	Wajib Diisi. String kueri SQL untuk kueri. Untuk informasi selengkapnya, lihat Referensi sintaks Azure Cosmos DB SQL.
parameter	Wajib Diisi. Array parameter JSON yang ditentukan sebagai pasangan nilai nama. Array parameter dapat berisi dari nol hingga banyak parameter. Setiap parameter harus memiliki nilai:name berikut: nama parameter. Nama parameter harus berupa literal string yang valid dan dimulai dengan '@'. nilai: nilai parameter. Dapat berupa nilai JSON yang valid (string, angka, objek, array, Boolean atau null).

Properti

Deskripsi

query

Wajib Diisi. String kueri SQL untuk kueri. Untuk informasi selengkapnya, lihat Referensi sintaks Azure Cosmos DB SQL.

parameter

Wajib Diisi. Array parameter JSON yang ditentukan sebagai pasangan nilai nama. Array parameter dapat berisi dari nol hingga banyak parameter. Setiap parameter harus memiliki nilai:name berikut: nama parameter. Nama parameter harus berupa literal string yang valid dan dimulai dengan '@'. nilai: nilai parameter. Dapat berupa nilai JSON yang valid (string, angka, objek, array, Boolean atau null).

Contoh Permintaan

Contoh berikut membuat permintaan SQL berparameter dengan parameter string untuk @author.

POST https://contosomarketing.documents.azure.com/dbs/XP0mAA==/colls/XP0mAJ3H-AA=/docs HTTP/1.1  
x-ms-documentdb-isquery: True  
x-ms-date: Mon, 18 Apr 2015 13:05:49 GMT  
authorization: type%3dmaster%26ver%3d1.0%26sig%3dkOU%2bBn2vkvIlHypfE8AA5fulpn8zKjLwdrxBqyg0YGQ%3d  
x-ms-version: 2015-04-08  
Accept: application/json  
Content-Type: application/query+json  
Host: contosomarketing.documents.azure.com  
Content-Length: 50  
  
{  
    "query": "SELECT * FROM root WHERE (root.Author.id = @author)",  
    "parameters":   
    [  
        { "name": "@author", "value": "Leo Tolstoy"}  
    ]  
}

Untuk informasi selengkapnya tentang kueri SQL, lihat Kueri SQL untuk Azure Cosmos DB.

Detail Respons

Berikut ini adalah kode status umum yang dikembalikan oleh operasi ini. Untuk informasi tentang kode status kesalahan, silakan lihat Kode Status HTTP untuk Azure Cosmos DB.

Kode	Deskripsi
200 Ok	Operasi berhasil.
400 Permintaan Buruk	Sintaks pernyataan SQL salah.
401 Tidak Sah	Header Otorisasi atau x-ms-date tidak diatur. 401 juga dikembalikan ketika header Otorisasi diatur ke token otorisasi yang tidak valid.
403 Dilarang	Token otorisasi telah kedaluwarsa.
404 Tidak ditemukan	Koleksi bukan lagi sumber daya. Misalnya, sumber daya mungkin telah dihapus.

Header Respons

Operasi ini mengembalikan header umum berikut. Mungkin ada header standar dan umum tambahan yang dikembalikan.

Header Standar	Deskripsi
Tipe-Konten	Jenis Konten adalah aplikasi/json. Cosmos DB selalu mengembalikan isi respons dalam format JSON standar.
Tanggal	Tanggal-waktu operasi respons. Format waktu tanggal ini sesuai dengan format waktu tanggal [RFC1123] yang dinyatakan dalam UTC.

Header Kustom	Deskripsi
x-ms-item-count	Jumlah item yang dikembalikan oleh operasi.
x-ms-continuation	Ini adalah string buram yang dikembalikan ketika kueri berpotensi memiliki lebih banyak item yang akan diambil. Kelanjutan x-ms dapat disertakan dalam permintaan berikutnya sebagai header permintaan untuk melanjutkan eksekusi kueri.
x-ms-request-charge	Ini adalah jumlah unit permintaan (RU) yang dikonsumsi oleh operasi. Untuk informasi selengkapnya tentang unit permintaan, lihat Unit Permintaan di Azure Cosmos DB.
x-ms-activity-id	Ini adalah pengidentifikasi unik untuk operasi. Ini dapat digunakan untuk melacak eksekusi permintaan Cosmos DB.
x-ms-session-token	Token sesi yang akan digunakan untuk permintaan berikutnya. Digunakan untuk konsistensi sesi.

Isi Respons

Isi respons untuk operasi kueri terdiri dari _rid sumber daya induk sumber daya yang dikueri, dan array sumber daya yang berisi properti sumber daya untuk proyeksi dan pemilihan. Sesuai contoh, jika kueri dilakukan pada jalur dokumen koleksi dengan _rid XP0mAJ3H-AA=, responsnya adalah sebagai berikut:

{"_rid":" XP0mAJ3H-AA=","Documents":   [  ….  ….   ],"_count":10}

Properti	Deskripsi
_rid	ID sumber daya untuk koleksi yang digunakan dalam kueri.
_Menghitung	Jumlah item yang dikembalikan.
Array sumber daya	Array yang berisi hasil kueri.

Membangun isi permintaan kueri

Permintaan kueri harus berupa dokumen JSON yang valid yang berisi properti kueri yang berisi string kueri SQL yang valid dan properti parameter yang berisi array parameter opsional. Setiap parameter harus memiliki properti nama dan nilai parameter yang ditentukan dalam kueri. Nama parameter harus dimulai dengan karakter "@". Nilai dapat berupa nilai JSON yang valid – string, bilangan bulat, Boolean, dan null.

Ini valid untuk menentukan hanya subset parameter yang ditentukan dalam teks kueri . Ekspresi yang mereferensikan parameter yang tidak ditentukan ini akan mengevaluasi ke tidak terdefinisi. Ini juga valid untuk menentukan parameter tambahan yang tidak digunakan dalam teks kueri .

Beberapa contoh permintaan kueri yang valid diperlihatkan di bawah ini. Misalnya, kueri berikut memiliki satu parameter @id.

{  
    "query": "select * from docs d where d.id = @id",   
    "parameters": [   
        {"@id": "newdoc"}   
     ]  
}

Contoh berikut memiliki dua parameter, satu dengan nilai string dan satu lagi dengan nilai bilangan bulat.

{  
    "query": "select * from docs d where d.id = @id and d.prop = @prop",   
    "parameters": [   
        {"@id": "newdoc"},  
        {"@prop": 5}   
     ]  
}

Contoh berikut menggunakan parameter dalam klausa SELECT, serta properti yang diakses melalui nama parameter sebagai parameter.

{  
    "query": "select @id, d[@propName] from docs d",   
    "parameters": [   
        {"@id": "newdoc"},  
        {"@propName": "prop"}  
     ]  
}

Kueri yang tidak dapat dilayani oleh gateway

Kueri apa pun yang memerlukan status di seluruh kelanjutan tidak dapat dilayani oleh gateway. Drive ini termasuk:

TOP
ORDER BY
BATAS OFFSET
Agregat
DISTINCT
KELOMPOKKAN MENURUT

Kueri yang dapat dilayani oleh gateway meliputi:

Proyeksi sederhana
Filter

Saat respons dikembalikan untuk kueri yang tidak dapat dilayani oleh gateway, respons akan berisi kode status 400 (BadRequest) dan pesan berikut:

{"code":"BadRequest","message":"The provided cross partition query can not be directly served by the gateway. 
This is a first chance (internal) exception that all newer clients will know how to handle gracefully. 
This exception is traced, but unless you see it bubble up as an exception (which only happens on older SDK clients), 
then you can safely ignore this message.\r\nActivityId: db660ee4-350a-40e9-bc2c-99f92f2b445d, Microsoft.Azure.Documents.Common/2.2.0.0",
"additionalErrorInfo":"{\"partitionedQueryExecutionInfoVersion\":2,\"queryInfo\":{\"distinctType\":\"None\",\"top\":null,\"offset\":null,\"limit\":null,
\"orderBy\":[\"Ascending\"],\"orderByExpressions\":[\"c._ts\"],\"aggregates\":[],
\"rewrittenQuery\":\"SELECT c._rid, [{\\\"item\\\": c._ts}] AS orderByItems, 
c AS payload\\nFROM c\\nWHERE ({documentdb-formattableorderbyquery-filter})\\nORDER BY c._ts\"},
\"queryRanges\":[{\"min\":\"\",\"max\":\"FF\",\"isMinInclusive\":true,\"isMaxInclusive\":false}]}"}

Penomoran halaman hasil kueri

Permintaan kueri mendukung penomoran halaman melalui header permintaan x-ms-max-item-count dan x-ms-continuation . Header x-ms-max-item-count menentukan jumlah maksimum nilai yang dapat dikembalikan oleh eksekusi kueri. Ini bisa antara 1 dan 1000, dan dikonfigurasi dengan default 100.

Kueri akan kembali dari nol hingga nilai jumlah item x-ms-max-max yang ditentukan maksimum dari hasil eksekusi. Hasil kueri menyertakan header x-ms-item-count yang menentukan jumlah aktual dokumen yang dikembalikan oleh kueri. Jika ada hasil tambahan yang dapat diambil dari kueri, maka respons menyertakan nilai yang tidak kosong untuk header x-ms-continuation .

Klien dapat mengambil halaman hasil berikutnya dengan menggemakan header x-ms-continuation sebagai permintaan lain. Untuk membaca semua hasil, klien harus mengulangi proses ini sampai x-ms-continuation kosong dikembalikan.

Eksekusi kueri Cosmos DB tanpa status di sisi server, dan dapat dilanjutkan kapan saja menggunakan header x-ms-continuation . Nilai x-ms-continuation menggunakan ID sumber daya dokumen terakhir yang diproses (_rid) untuk melacak kemajuan eksekusi. Oleh karena itu jika dokumen dihapus dan disisipkan kembali antara pengambilan halaman, maka dokumen berpotensi dikecualikan dari salah satu batch kueri. Namun, perilaku dan format header x-ms-continuation mungkin berubah dalam pembaruan layanan di masa mendatang.