Azure Cosmos DB Node.js SDK untuk API untuk NoSQL: Catatan rilis dan sumber daya

Artikel
01/10/2024

BERLAKU UNTUK: NoSQL

Sumber Daya	Tautan
Unduh SDK	@azure/cosmos
Dokumentasi API	Dokumentasi referensi JavaScript SDK
Instruksi pemasangan SDK	`npm install @azure/cosmos`
Kontribusi pada SDK	Panduan berkontribusi untuk repo Azure-sdk-for-js
Sampel	Sampel kode Node.js
Memulai tutorial	Mulai menggunakan JavaScript SDK
Tutorial aplikasi web	Membangun aplikasi web Node.js menggunakan Microsoft Azure Cosmos DB
Platform Node.js yang didukung saat ini	Versi LTS dari Node.js

Catatan rilis

Riwayat rilis disimpan di repo Azure-sdk-for-js, untuk daftar rilis terperinci, lihat file changelog.

Panduan migrasi untuk perubahan yang berbeda dari sebelumnya

Jika Anda menggunakan versi SDK lama, sebaiknya migrasikan ke versi 3.0. Bagian ini merinci peningkatan yang akan Anda dapatkan dengan versi ini dan perbaikan bug yang dibuat di versi 3.0.

Opsi konstruktor klien yang ditingkatkan

Opsi konstruktor telah disederhanakan:

masterKey diganti namanya menjadi kunci dan dipindahkan ke tingkat atas
Properti sebelumnya di bagian options.auth telah pindah ke tingkat atas

// v2
const client = new CosmosClient({
    endpoint: "https://your-database.cosmos.azure.com",
    auth: {
        masterKey: "your-primary-key"
    }
})

// v3
const client = new CosmosClient({
    endpoint: "https://your-database.cosmos.azure.com",
    key: "your-primary-key"
})

API iterator kueri yang disederhanakan

Di v2, ada banyak cara untuk mengulangi atau mengambil hasil dari kueri. Kami telah berusaha menyederhanakan API v3 dan menghapus API serupa atau API duplikat:

Hapus iterator.next() dan iterator.current(). Gunakan fetchNext() untuk mendapatkan halaman hasil.
Hapus iterator.forEach(). Gunakan iterator asinkron sebagai gantinya.
iterator.executeNext() diubah namanya menjadi iterator.fetchNext()
iterator.toArray() diubah namanya menjadi iterator.fetchAll()
Halaman-halaman sekarang menjadi objek Respon yang tepat, bukan objek JS biasa
kontainer const = client.database(dbId).container(containerId)

// v2
container.items.query('SELECT * from c').toArray()
container.items.query('SELECT * from c').executeNext()
container.items.query('SELECT * from c').forEach(({ body: item }) => { console.log(item.id) })

// v3
container.items.query('SELECT * from c').fetchAll()
container.items.query('SELECT * from c').fetchNext()
for await(const { result: item } in client.databases.readAll().getAsyncIterator()) {
    console.log(item.id)
}

Kontainer tetap sekarang dipartisi

Layanan Azure Cosmos DB sekarang mendukung kunci partisi pada semua kontainer, termasuk yang sebelumnya dibuat sebagai kontainer tetap. V3 SDK memperbarui ke versi API terbaru yang mengimplementasikan perubahan ini, tetapi tidak melanggar. Jika Anda tidak menyediakan kunci partisi untuk operasi, kami akan default ke kunci sistem yang berfungsi dengan semua kontainer dan dokumen yang ada.

Upsert dihapus untuk prosedur tersimpan

Sebelumnya upsert diizinkan untuk koleksi non-partisi, tetapi dengan pembaruan versi API, semua koleksi dipartisi sehingga kami dapat menghapusnya sama sekali.

Pembacaan item tidak akan dilemparkan pada 404

kontainer const = client.database(dbId).container(containerId)

// v2
try {
    container.items.read(id, undefined)
} catch (e) {
    if (e.code === 404) { console.log('item not found') }
}

// v3
const { result: item }  = container.items.read(id, undefined)
if (item === undefined) { console.log('item not found') }

Penulisan multi-wilayah default

SDK sekarang akan menulis ke beberapa wilayah secara default jika konfigurasi Azure Cosmos DB Anda mendukungnya. Ini sebelumnya adalah perilaku opsional, opt-in.

Objek kesalahan yang tepat

Permintaan yang gagal sekarang melemparkan Kesalahan atau subkelas Kesalahan yang tepat. Sebelumnya mereka melemparkan objek JS biasa.

Fitur baru

Permintaan pengguna yang dapat dibatalkan

Langkah untuk mengambil secara internal memungkinkan kami untuk menggunakan API browser AbortController untuk mendukung operasi yang dapat dibatalkan pengguna. Dalam kasus operasi saat beberapa permintaan berpotensi sedang berlangsung (seperti kueri lintas-partisi), semua permintaan untuk operasi akan dibatalkan. Pengguna browser modern sudah memiliki AbortController. Pengguna Node.js perlu menggunakan pustaka Polyfill

 const controller = new AbortController()
 const {result: item} = await items.query('SELECT * from c', { abortSignal: controller.signal});
 controller.abort()

Mengatur throughput sebagai bagian dari operasi membuat db/container

const { database }  = client.databases.create({ id: 'my-database', throughput: 10000 })
database.containers.create({ id: 'my-container', throughput: 10000 })

@azure/cosmos-sign

Pembuatan token header dipisah kedalam pustaka baru, @azure/cosmos-sign. Siapa pun yang memanggil Azure Cosmos DB REST API secara langsung dapat menggunakan ini untuk menandatangani header menggunakan kode yang sama yang kita panggil di dalam @azure/cosmos.

UUID untuk ID yang dihasilkan

v2 memiliki kode kustom untuk membuat ID item. Kami telah beralih ke uuid pustaka komunitas yang terkenal dan terpelihara.

String koneksi

Sekarang dimungkinkan untuk meneruskan string koneksi yang disalin dari portal Azure:

const client = new CosmosClient("AccountEndpoint=https://test-account.documents.azure.com:443/;AccountKey=c213asdasdefgdfgrtweaYPpgoeCsHbpRTHhxuMsTaw==;")
Add DISTINCT and LIMIT/OFFSET queries (#306)
 const { results } = await items.query('SELECT DISTINCT VALUE r.name FROM ROOT').fetchAll()
 const { results } = await items.query('SELECT * FROM root r OFFSET 1 LIMIT 2').fetchAll()

Pengalaman browser yang disempurnakan

Meskipun dimungkinkan untuk menggunakan SDK v2 di browser, itu bukan pengalaman yang ideal. Anda perlu Polyfill (mengisi bersama-sama) beberapa pustaka bawaan Node.js dan menggunakan bundler seperti webpack atau Parsel. V3 SDK membuat pengalaman tak biasa yang jauh lebih baik untuk pengguna browser.

Ganti permintaan internal dengan pengambilan (# 245)
Hapus penggunaan Buffer (#330)
Hapus penggunaan bawaan node untuk mendukung paket/API universal (# 328)
Ganti ke node-abort-controller (#294)

Perbaikan bug

Perbaikan pembacaan penawaran dan mengambil kembali uji coba penawaran (# 224)
Perbaikan EnableEndpointDiscovery (#207)
Memperbaiki RUs yang hilang pada hasil paginasi (#360)
Memperluas jenis parameter kueri SQL (#346)
Tambahkan ttl ke ItemDefinisi (#341)
Memperbaiki metrik kueri CP (#311)
Tambahkan activityId ke FeedResponse (#293)
Mengalihkan tipe _ts dari untai ke angka (#252)(#295)
Memperbaiki Agregasi Biaya Permintaan (#289)
Mengizinkan kunci partisi untai kosong (# 277)
Menambahkan untai ke jenis kueri konflik (#237)
Menambahkan uniqueKeyPolicy ke kontainer (#234)

Sistem rekayasa

Tidak selalu perubahan yang paling menonjol, tetapi perubahan itu membantu tim kami mengirim kode yag lebih baik, lebih cepat.

Gunakan rollup untuk membangun produksi (#104)
Memperbarui ke Typescript 3.5 (#327)
Konversi ke referensi proyek TS. Mengekstrak folder pengujian (#270)
Aktifkan noUnusedLocals dan noUnusedParameters (#275)
Azure Pipelines YAML untuk membangun CI (# 298)

Tanggal Rilis & Penghentian

Microsoft akan memberikan pemberitahuan minimal 12 bulan sebelum penghentian SDK guna melancarkan transisi ke versi yang lebih baru/didukung. Fitur dan fungsionalitas dan pengoptimalan baru hanya ditambahkan ke SDK saat ini, dengan demikian disarankan agar Anda selalu meningkatkan ke versi SDK terbaru sedini mungkin. Baca Kebijakan Dukungan Microsoft untuk SDK untuk detail selengkapnya.

Versi	Tanggal Rilis	Tanggal Penghentian
v3	28 Juni 2019	---
v2	24 September 2018	24 September 2021
v1	08 April 2015	30 Agustus 2020

FAQ

Bagaimana saya akan diberi tahu tentang SDK yang dihentikan?

Microsoft akan memberikan pemberitahuan 12 bulan sebelumnya sebelum akhir dukungan dari SDK yang dihentikan untuk memfasilitasi transisi yang mulus ke SDK yang didukung. Kami akan memberi tahu Anda melalui berbagai saluran komunikasi: portal Azure, pembaruan Azure, dan komunikasi langsung ke administrator layanan yang ditetapkan.

Dapatkah saya membuat aplikasi dengan menggunakan SDK Azure Cosmos DB yang akan dihentikan selama periode 12 bulan?

Ya, Anda akan dapat membuat, menyebarkan, dan mengubah aplikasi dengan menggunakan SDK Azure Cosmos DB yang akan dihentikan selama periode pemberitahuan 12 bulan. Kami menyarankan Anda untuk bermigrasi ke versi terbaru yang didukung dari SDK Azure Cosmos DB selama periode pemberitahuan 12 bulan, sebagaimana mestinya.

Setelah tanggal penghentian, apa yang terjadi pada aplikasi yang menggunakan SDK Azure Cosmos DB yang tidak didukung?

Setelah tanggal penghentian, Azure Cosmos DB tidak akan lagi melakukan perbaikan bug, menambahkan fitur baru, atau memberikan dukungan ke versi SDK yang dihentikan. Jika Anda memilih untuk tidak meningkatkan, permintaan yang dikirim dari versi SDK yang dihentikan akan terus dilayani oleh layanan Azure Cosmos DB.

Versi SDK mana yang akan memiliki fitur dan pembaruan terbaru?

Fitur dan pembaruan baru hanya akan ditambahkan ke versi minor terbaru dari versi SDK utama terbaru yang didukung. Kami menyarankan Anda untuk selalu menggunakan versi terbaru untuk memanfaatkan fitur baru, peningkatan performa, dan perbaikan bug. Jika Anda menggunakan SDK versi lama yang tidak dihentikan, permintaan Anda ke Azure Cosmos DB akan tetap berfungsi, tetapi Anda tidak akan memiliki akses ke kemampuan baru apa pun.

Apa yang harus saya lakukan jika saya tidak dapat memperbarui aplikasi saya sebelum batas waktu?

Kami menyarankan Anda meningkatkan ke SDK terbaru sedini mungkin. Setelah SDK ditandai untuk dihentikan, Anda memiliki waktu 12 bulan untuk memperbarui aplikasi. Jika Anda tidak dapat memperbarui pada tanggal penghentian, permintaan yang dikirim dari versi SDK yang dihentikan akan terus dilayani oleh Azure Cosmos DB, sehingga aplikasi Anda yang sedang berjalan akan terus berfungsi. Tetapi Azure Cosmos DB tidak akan lagi melakukan perbaikan bug, menambahkan fitur baru, atau memberikan dukungan ke versi SDK yang sudah dihentikan.

Jika Anda memiliki rencana dukungan dan memerlukan tim dukungan, hubungi kami dengan mengajukan tiket dukungan.

Bagaimana cara meminta fitur agar ditambahkan ke SDK atau konektor?

Fitur baru tidak selalu ditambahkan ke setiap SDK atau konektor dengan segera. Jika ada fitur tidak didukung yang ingin Anda tambahkan,silakan beri umpan balik ke forum komunitas kami.