Interaksi RESTful dengan Azure Cosmos DB

  • Artikel

Azure Cosmos DB adalah database multi-model yang didistribusikan secara global yang mendukung model data dokumen, grafik, dan nilai kunci. Konten di bagian ini adalah untuk membuat, mengkueri, dan mengelola sumber daya dokumen menggunakan SQL API melalui REST.

Dengan membaca artikel ini, Anda dapat menjawab pertanyaan-pertanyaan berikut:

  • Bagaimana cara kerja metode HTTP standar dengan sumber daya Azure Cosmos DB?
  • Bagaimana cara membuat sumber daya baru menggunakan POST?
  • Bagaimana cara mendaftarkan prosedur tersimpan menggunakan POST?
  • Bagaimana Azure Cosmos DB mendukung kontrol konkurensi?
  • Apa saja opsi konektivitas untuk HTTPS dan TCP?

Jika Anda mencari informasi tentang cara melakukan operasi CRUD pada sumber daya tertentu menggunakan REST, lihat Tugas umum menggunakan REST API Azure Cosmos DB. Jika Anda mencari sampel tentang cara melakukan operasi CRUD menggunakan C# dan REST, lihat REST dari Sampel .NET di GitHub.

Catatan

Anda juga dapat melakukan operasi CRUD pada sumber daya Cosmos DB menggunakan SDK Cosmos DB. Untuk sampel, lihat Contoh Azure Cosmos DB. Untuk tautan ke unduhan dan dokumentasi SDK, lihat Cosmos DB SDK.

Gambaran umum kata kerja HTTP

Sumber daya Azure Cosmos DB mendukung kata kerja HTTP berikut dengan interpretasi standarnya:

  1. POST berarti membuat sumber daya item baru.
  2. GET berarti membaca item atau sumber daya umpan yang sudah ada
  3. PUT berarti mengganti sumber daya item yang ada
  4. DELETE berarti menghapus sumber daya item yang sudah ada
  5. HEAD berarti GET membersihkan payload respons (yaitu, hanya header)

Seperti yang diilustrasikan dalam diagram kata kerja HTTP berikut, POST hanya dapat dikeluarkan terhadap sumber daya umpan; PUT dan DELETE hanya dapat dikeluarkan terhadap sumber daya item; GET dan HEAD dapat dikeluarkan terhadap sumber daya umpan atau item.

Model interaksi menggunakan metode HTTP standar

Model interaksi menggunakan metode HTTP standar

Membuat sumber daya baru menggunakan metode HTTP POST

Untuk mendapatkan nuansa yang lebih baik untuk model interaksi, mari kita pertimbangkan kasus pembuatan sumber daya baru (alias INSERT). Untuk membuat sumber daya baru, Anda diharuskan untuk mengeluarkan permintaan HTTP POST dengan isi permintaan yang berisi representasi sumber daya terhadap URI umpan kontainer tempat sumber daya berada. Satu-satunya properti yang diperlukan untuk permintaan adalah ID sumber daya.

Sebagai contoh, untuk membuat database baru, Anda MEMPOSTING sumber daya database (dengan mengatur properti ID dengan nama unik) terhadap /dbs. Demikian pula, untuk membuat koleksi baru, Anda MEMPOSTING sumber daya koleksi terhadap /dbs/_rid/colls/ dan sebagainya. Respons berisi sumber daya yang berkomitmen penuh dengan properti yang dihasilkan sistem termasuk tautan _self sumber daya yang digunakan untuk menavigasi ke sumber daya lain. Sebagai contoh model interaksi berbasis HTTP sederhana, klien dapat mengeluarkan permintaan HTTP untuk membuat database baru dalam akun.

POST https://fabrikam.documents.azure.com/dbs  
{  
    "id":"MyDb"
}

Sebagai contoh, untuk membuat database baru, Anda POST adalah sumber daya database (dengan mengatur properti ID dengan nama unik) terhadap /dbs. Demikian pula, untuk membuat koleksi baru, Anda POST memiliki sumber daya /dbs/_rid/colls/ koleksi dan sebagainya. Respons berisi sumber daya yang berkomitmen penuh dengan properti yang dihasilkan sistem termasuk _self tautan sumber daya yang digunakan untuk menavigasi ke sumber daya lain. Sebagai contoh model interaksi berbasis HTTP sederhana, klien dapat mengeluarkan permintaan HTTP untuk membuat database baru dalam akun.

Layanan Azure Cosmos DB merespons dengan respons yang berhasil dan kode status yang menunjukkan keberhasilan pembuatan database.

HTTP/1.1 201 Created  
Content-Type: application/json  
x-ms-request-charge: 4.95  
...  
  
{  
    "id": "MyDb",  
    "_rid": "UoEi5w==",  
    "_self": "dbs/UoEi5w==/",  
    "_ts": 1407370063,  
    "_etag": "00000100-0000-0000-0000-54b636600000",  
    "_colls": "colls/",  
    "_users": "users/"  
}

Mendaftarkan prosedur tersimpan menggunakan metode HTTP POST

Sebagai contoh lain dalam membuat dan menjalankan sumber daya, pertimbangkan prosedur tersimpan "HelloWorld" sederhana yang ditulis sepenuhnya dalam JavaScript.

function HelloWorld() {  
    var context = getContext();  
    var response = context.getResponse();  

    response.setBody("Hello, World");  
}

Prosedur tersimpan dapat didaftarkan ke koleksi di bawah MyDb dengan mengeluarkan POST terhadap /dbs/_rid-db/colls/_rid-coll/sprocs.

POST https://fabrikam.documents.azure.com/dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs HTTP/1.1  
  
{  
    "id": "HelloWorld",  
    "body": "function HelloWorld() {  
                var context = getContext();  
                var response = context.getResponse();  

                response.setBody("Hello, World");  
            }"  
}

Layanan Azure Cosmos DB merespons dengan respons yang berhasil dan kode status yang menunjukkan keberhasilan pendaftaran prosedur tersimpan.

HTTP/1.1 201 Created  
Content-Type: application/json  
x-ms-request-charge: 4.95  
...  
  
{  
    "body": "function HelloWorld() {  
        var context = getContext();  
        var response = context.getResponse();  

        response.setBody("Hello, World");  
        }",  
    "id": "HelloWorld"  
    "_rid": "UoEi5w+upwABAAAAAAAAgA==",  
    "_ts" :  1421227641  
    "_self": "dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs/UoEi5w+upwABAAAAAAAAgA==/",  
    "_etag": "00002100-0000-0000-0000-50f71fda0000"  
}

Menjalankan prosedur tersimpan menggunakan metode HTTP POST

Terakhir, untuk menjalankan prosedur tersimpan dalam contoh sebelumnya, seseorang perlu mengeluarkan POST terhadap URI sumber daya prosedur tersimpan (/dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs/UoEi5w+upwABAAAAAAAAgA==/) seperti yang diilustrasikan di bawah ini.

POST https://fabrikam.documents.azure.com/dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs/UoEi5w+upwABAAAAAAAAgA== HTTP/1.1

Layanan Azure Cosmos DB merespons dengan respons berikut.

HTTP/1.1 200 OK  
  
"Hello World"

Perhatikan bahwa kata kerja HTTP POST digunakan untuk membuat sumber daya baru, untuk menjalankan prosedur tersimpan, dan untuk mengeluarkan kueri SQL. Untuk mengilustrasikan eksekusi kueri SQL, pertimbangkan hal berikut.

POST https://fabrikam.documents.azure.com/dbs/UoEi5w==/colls/UoEi5w+upwA=/docs HTTP/1.1  
...  
x-ms-documentdb-isquery: True  
x-ms-documentdb-query-enable-scan: True  
Content-Type: application/query+json  
...  

{"query":"SELECT f.LastName AS Name, f.Address.City AS City FROM Families f WHERE f.id='AndersenFamily' OR f.Address.City='NY'"}

Layanan merespons dengan hasil kueri SQL.

HTTP/1.1 200 Ok  
...  
x-ms-activity-id: 83f9992c-abae-4eb1-b8f0-9f2420c520d2  
x-ms-item-count: 2  
x-ms-session-token: 4  
x-ms-request-charge: 3.1  
Content-Type: application/json1  

{"_rid":"UoEi5w+upwA=","Documents":[{"Name":"Andersen","City":"Seattle"},{"Name":"Wakefield","City":"NY"}],"_count":2}

Menggunakan kata kerja PUT, GET, dan DELETE HTTP

Mengganti atau membaca jumlah sumber daya yang dikeluarkan PUT (dengan isi permintaan yang valid) dan kata kerja GET terhadap tautan _self sumber daya masing-masing. Demikian juga, menghapus jumlah sumber daya untuk mengeluarkan DELETE kata kerja terhadap tautan _self sumber daya. Perlu ditunjukkan bahwa organisasi hierarkis sumber daya dalam model sumber daya Azure Cosmos DB mengharuskan dukungan untuk penghapusan bertingkat di mana menghapus sumber daya pemilik menyebabkan penghapusan sumber daya dependen. Sumber daya dependen dapat didistribusikan di seluruh simpul lain daripada sumber daya pemilik dan sehingga penghapusan dapat terjadi dengan malas. Terlepas dari mekanisme pengumpulan sampah, setelah penghapusan sumber daya, kuota langsung dibebaskan dan tersedia untuk Anda gunakan. Perhatikan bahwa integritas referensial dipertahankan oleh sistem. Misalnya, Anda tidak dapat menyisipkan koleksi ke database yang dihapus atau diganti atau mengkueri dokumen koleksi yang sudah tidak ada lagi.

Mengeluarkan GET terhadap umpan sumber daya atau mengkueri koleksi dapat mengakibatkan jutaan item berpotensi, sehingga membuatnya tidak praktis bagi kedua server untuk mewujudkannya dan klien untuk mengonsumsinya sebagai bagian dari satu pertukaran pulang-pergi/ permintaan dan respons. Untuk mengatasi hal ini, Azure Cosmos DB memungkinkan klien untuk paginate melalui halaman umpan besar-pada-a-time. Klien dapat menggunakan header respons [x-ms-continuation] sebagai kursor untuk menavigasi ke halaman berikutnya.

kontrol konkurensi optimis

Sebagian besar aplikasi web mengandalkan tag entitas berdasarkan kontrol konkurensi optimis untuk menghindari masalah "Lost Update" dan "Lost Delete" yang dikenal. Tag entitas adalah tanda waktu logis yang ramah HTTP yang terkait dengan sumber daya. Cosmos DB secara asli mendukung kontrol konkurensi optimis dengan memastikan bahwa setiap respons HTTP berisi versi (tahan lama) yang terkait dengan sumber daya tertentu. Konflik kontrol konkurensi terdeteksi dengan benar untuk kasus berikut:

  1. Jika dua klien secara bersamaan mengeluarkan permintaan bermutasi (melalui kata kerja PUT/DELETE) pada sumber daya dengan versi sumber daya terbaru (ditentukan melalui header permintaan [jika cocok]), mesin database Cosmos DB tunduk pada kontrol konkurensi transaksional.

  2. Jika klien menyajikan versi sumber daya yang lebih lama (ditentukan melalui header permintaan [if-match]), permintaannya akan ditolak.

Opsi konektivitas

Cosmos DB memaparkan model alamat logis di mana setiap sumber daya memiliki URI logis dan stabil yang diidentifikasi oleh tautan _self-nya . Sebagai sistem penyimpanan terdistribusi yang tersebar di seluruh wilayah, sumber daya di bawah berbagai akun database di Cosmos DB dipartisi di berbagai komputer dan setiap partisi direplikasi untuk ketersediaan tinggi. Replika yang mengelola sumber daya dari partisi tertentu mendaftarkan alamat fisik. Sementara alamat fisik berubah selama waktu karena kegagalan, alamat logis mereka tetap stabil dan konstan. Terjemahan logis ke alamat fisik disimpan dalam tabel perutean yang juga tersedia secara internal sebagai sumber daya. Cosmos DB memaparkan dua mode konektivitas:

  • Mode Gateway: Klien dilindungi dari terjemahan antara alamat logis ke fisik atau detail perutean; mereka hanya berurusan dengan URI logis dan RESTfully menavigasi model sumber daya. Klien mengeluarkan permintaan menggunakan URI logis dan mesin edge menerjemahkan URI logis ke alamat fisik replika yang mengelola sumber daya dan meneruskan permintaan. Dengan penembolokan mesin tepi (dan menyegarkan secara berkala) tabel perutean, perutean sangat efisien.

  • Mode Konektivitas Langsung: Klien secara langsung mengelola tabel perutean di ruang proses mereka dan secara berkala merefreshnya. Klien dapat langsung terhubung dengan replika dan melewati mesin edge.

Mode Konektivitas Protokol Detail SDK Azure Cosmos DB
Gateway HTTPS Aplikasi langsung terhubung dengan simpul tepi menggunakan URI logis. Ini menimbulkan hop jaringan tambahan. REST API, .NET, Node.js, Java, Python, JavaScript
Konektivitas Langsung HTTPS dan TCP Aplikasi dapat langsung mengakses tabel perutean dan melakukan perutean sisi klien untuk langsung terhubung dengan replika. .NET, Java

Lihat juga