Pustaka klien Azure Cosmos DB untuk JavaScript - versi 4.0.0
/TypeScript
Azure Cosmos DB adalah layanan database multi model yang didistribusikan secara global yang mendukung database dokumen, nilai kunci, kolom lebar, dan grafik. Paket ini ditujukan bagi aplikasi JavaScript/TypeScript untuk berinteraksi dengan database SQL API dan dokumen JSON yang dikandungnya:
- Membuat database Cosmos DB dan mengubah pengaturannya
- Membuat dan mengubah kontainer untuk menyimpan kumpulan dokumen JSON
- Membuat, membaca, memperbarui, dan menghapus item (dokumen JSON) di kontainer Anda
- Mengkueri dokumen dalam database Anda menggunakan sintaks seperti SQL
Tautan utama:
Memulai
Prasyarat
Langganan Azure dan Akun API SQL Cosmos DB
Anda harus memiliki Langganan Azure, dan akun DB Cosmos (API SQL) untuk menggunakan paket ini.
Jika Anda memerlukan akun API SQL Cosmos DB, Anda dapat menggunakan Azure Cloud Shell untuk membuat akun dengan perintah Azure CLI ini:
az cosmosdb create --resource-group <resource-group-name> --name <cosmos-database-account-name>
Atau Anda dapat membuat akun di Portal Azure
NodeJS
Paket ini didistribusikan melalui npm yang telah diinstal sebelumnya dengan NodeJS. Anda harus menggunakan Node v10 atau lebih tinggi.
CORS
Anda perlu menyiapkan aturan Cross-Origin Resource Sharing (CORS) untuk akun Cosmos DB jika Anda perlu mengembangkan untuk browser. Ikuti instruksi dalam dokumen tertaut untuk membuat aturan CORS baru untuk Cosmos DB Anda.
Menginstal paket ini
npm install @azure/cosmos
Mendapatkan Kredensial Akun
Anda memerlukan Titik Akhir Akun dan Kunci Cosmos DB Anda. Anda dapat menemukannya di Portal Azure atau menggunakan cuplikan Azure CLI di bawah. Cuplikan diformat untuk shell Bash.
az cosmosdb show --resource-group <your-resource-group> --name <your-account-name> --query documentEndpoint --output tsv
az cosmosdb keys list --resource-group <your-resource-group> --name <your-account-name> --query primaryMasterKey --output tsv
Membuat instans CosmosClient
Interaksi dengan Cosmos DB dimulai dengan instans kelas CosmosClient
const { CosmosClient } = require("@azure/cosmos");
const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });
async function main() {
// The rest of the README samples are designed to be pasted into this function body
}
main().catch((error) => {
console.error(error);
});
Untuk kesederhanaan, kami telah menyertakan key
dan endpoint
secara langsung dalam kode, tetapi Anda mungkin perlu memuatnya dari file yang tidak berada dalam kontrol sumber menggunakan proyek seperti dotenv atau memuat dari variabel lingkungan
Di lingkungan produksi, rahasia seperti kunci harus disimpan di Azure Key Vault
Konsep utama
Setelah Anda menginisialisasi CosmosClient, Anda dapat berinteraksi dengan jenis sumber daya utama di Cosmos DB:
Database: Akun Cosmos DB dapat berisi banyak database. Saat membuat database, Anda menentukan API yang ingin Anda gunakan saat berinteraksi dengan dokumen database: SQL, MongoDB, Gremlin, Cassandra, atau Azure Table. Gunakan objek Database untuk mengelola kontainer objek.
Kontainer: Kontainer adalah kumpulan dokumen JSON. Anda membuat (menyisipkan), membaca, memperbarui, dan menghapus item dalam kontainer dengan menggunakan metode pada objek Kontainer.
Item: Item adalah dokumen JSON yang disimpan dalam kontainer. Setiap Item harus menyertakan kunci
id
dengan nilai yang secara unik mengidentifikasi item di dalam kontainer. Jika Anda tidak menyediakanid
, SDK akan membuatnya secara otomatis.
Untuk informasi selengkapnya tentang sumber daya ini, lihat Bekerja dengan database, kontainer, dan item Azure Cosmos.
Contoh
Bagian berikut menyediakan beberapa cuplikan kode yang mencakup beberapa tugas Cosmos DB yang paling umum, termasuk:
- Membuat database
- Membuat kontainer
- Menggunakan Kunci Partisi
- Menyisipkan item
- Meminta dokumen
- Membaca item
- Menghapus item
- CRUD pada Kontainer dengan kunci partisi hierarkis
Buat database
Setelah mengautentikasi CosmosClient, Anda dapat bekerja dengan semua sumber daya di akun. Cuplikan kode di bawah ini membuat database API NOSQL.
const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
console.log(database.id);
Buat kontainer
Contoh ini membuat kontainer dengan pengaturan default
const { container } = await database.containers.createIfNotExists({ id: "Test Database" });
console.log(container.id);
Menggunakan Kunci Partisi
Contoh ini menunjukkan berbagai jenis Kunci partisi yang didukung.
await container.item("id", "1").read(); // string type
await container.item("id", 2).read(); // number type
await container.item("id", true).read(); // boolean type
await container.item("id", {}).read(); // None type
await container.item("id", undefined).read(); // None type
await container.item("id", null).read(); // null type
Jika Kunci Partisi terdiri dari satu nilai, kunci tersebut dapat disediakan baik sebagai nilai harfiah, atau array.
await container.item("id", "1").read();
await container.item("id", ["1"]).read();
Jika Kunci Partisi terdiri dari lebih dari satu nilai, kunci tersebut harus disediakan sebagai array.
await container.item("id", ["a", "b"]).read();
await container.item("id", ["a", 2]).read();
await container.item("id", [{}, {}]).read();
await container.item("id", ["a", {}]).read();
await container.item("id", [2, null]).read();
Menyisipkan item
Untuk menyisipkan item ke dalam kontainer, teruskan objek yang berisi data Anda ke Items.upsert. Layanan Azure Cosmos DB mengharuskan setiap item memiliki id
kunci. Jika Anda tidak menyediakannya, SDK akan menghasilkan id
secara otomatis.
Contoh ini menyisipkan beberapa item ke dalam kontainer
const cities = [
{ id: "1", name: "Olympia", state: "WA", isCapitol: true },
{ id: "2", name: "Redmond", state: "WA", isCapitol: false },
{ id: "3", name: "Chicago", state: "IL", isCapitol: false }
];
for (const city of cities) {
await container.items.create(city);
}
Membaca item
Untuk membaca satu item dari kontainer, gunakan Item.read. Hal ini merupakan operasi yang lebih murah daripada menggunakan SQL untuk mengkueri berdasarkan id
.
await container.item("1", "1").read();
CRUD pada Kontainer dengan kunci partisi hierarkis
Membuat Kontainer dengan kunci partisi hierarkis
const containerDefinition = {
id: "Test Database",
partitionKey: {
paths: ["/name", "/address/zip"],
version: PartitionKeyDefinitionVersion.V2,
kind: PartitionKeyKind.MultiHash,
},
}
const { container } = await database.containers.createIfNotExists(containerDefinition);
console.log(container.id);
Sisipkan item dengan kunci partisi hierarkis yang didefinisikan sebagai - ["/name", "/address/zip"]
const item = {
id: 1,
name: 'foo',
address: {
zip: 100
},
active: true
}
await container.items.create(item);
Untuk membaca satu item dari kontainer dengan kunci partisi hierarkis yang didefinisikan sebagai - ["/name", "/address/zip"],
await container.item("1", ["foo", 100]).read();
Mengkueri item dengan kunci partisi hierarkis dengan kunci partisi hierarkis yang didefinisikan sebagai - ["/name", "/address/zip"],
const { resources } = await container.items
.query("SELECT * from c WHERE c.active = true", {
partitionKey: ["foo", 100],
})
.fetchAll();
for (const item of resources) {
console.log(`${item.name}, ${item.address.zip} `);
}
Hapus item
Untuk menghapus item dari kontainer, gunakan Item.delete.
// Delete the first item returned by the query above
await container.item("1").delete();
Mengkueri database
Database API SQL Cosmos DB mendukung dalam mengkueri item di kontainer dengan Items.query menggunakan sintaks seperti SQL:
const { resources } = await container.items
.query("SELECT * from c WHERE c.isCapitol = true")
.fetchAll();
for (const city of resources) {
console.log(`${city.name}, ${city.state} is a capitol `);
}
Lakukan kueri berparameter dengan meneruskan objek yang berisi parameter dan nilai kueri ke Items.query:
const { resources } = await container.items
.query({
query: "SELECT * from c WHERE c.isCapitol = @isCapitol",
parameters: [{ name: "@isCapitol", value: true }]
})
.fetchAll();
for (const city of resources) {
console.log(`${city.name}, ${city.state} is a capitol `);
}
Untuk informasi selengkapnya tentang mengkueri database Cosmos DB menggunakan API SQL, lihat Mengkueri data Azure Cosmos DB dengan kueri SQL.
Ubah Model Penarikan Umpan
Umpan perubahan dapat diambil untuk kunci partisi, rentang umpan, atau seluruh kontainer.
Untuk memproses umpan perubahan, buat instans ChangeFeedPullModelIterator
. Ketika Anda awalnya membuat ChangeFeedPullModelIterator
, Anda harus menentukan nilai yang diperlukan changeFeedStartFrom
di dalam ChangeFeedIteratorOptions
yang terdiri dari posisi awal untuk membaca perubahan dan sumber daya (kunci partisi atau FeedRange) yang perubahannya akan diambil. Anda dapat secara opsional menggunakan maxItemCount
di ChangeFeedIteratorOptions
untuk mengatur jumlah maksimum item yang diterima per halaman.
Catatan: Jika tidak ada changeFeedStartFrom
nilai yang ditentukan, changefeed akan diambil untuk seluruh kontainer dari Now().
Ada empat posisi awal untuk umpan perubahan:
Beginning
// Signals the iterator to read changefeed from the beginning of time.
const options = {
changeFeedStartFrom: ChangeFeedStartFrom.Beginning();
}
const iterator = container.getChangeFeedIterator(options);
Time
// Signals the iterator to read changefeed from a particular point of time.
const time = new Date("2023/09/11") // some sample date
const options = {
changeFeedStartFrom: ChangeFeedStartFrom.Time(time);
}
Now
// Signals the iterator to read changefeed from this moment onward.
const options = {
changeFeedStartFrom: ChangeFeedStartFrom.Now();
}
Continuation
// Signals the iterator to read changefeed from a saved point.
const continuationToken = "some continuation token recieved from previous request";
const options = {
changeFeedStartFrom: ChangeFeedStartFrom.Continuation(continuationToken);
}
Berikut adalah contoh pengambilan umpan perubahan untuk kunci partisi
const partitionKey = "some-partition-Key-value";
const options = {
changeFeedStartFrom: ChangeFeedStartFrom.Beginning(partitionKey),
};
const iterator = container.items.getChangeFeedIterator(options);
while (iterator.hasMoreResults) {
const response = await iterator.readNext();
// process this response
}
Karena umpan perubahan secara efektif merupakan daftar item tak terbatas yang mencakup semua penulisan dan pembaruan di masa mendatang, nilai hasMoreResults
selalu true
. Ketika Anda mencoba membaca umpan perubahan dan tidak ada perubahan baru yang tersedia, Anda menerima respons dengan NotModified
status.
Panduan penggunaan yang lebih rinci dan contoh umpan perubahan dapat ditemukan di sini.
Penanganan Kesalahan
SDK menghasilkan berbagai jenis kesalahan yang dapat terjadi selama operasi.
ErrorResponse
dilemparkan jika respons operasi mengembalikan kode >kesalahan =400.TimeoutError
dilemparkan jika Pembatalakuan dipanggil secara internal karena waktu habis.AbortError
dilemparkan jika ada sinyal yang dilewatkan pengguna yang menyebabkan pembatalan.RestError
dilemparkan jika terjadi kegagalan panggilan sistem yang mendasar karena masalah jaringan.- Kesalahan yang dihasilkan oleh devDependencies apa pun. Misalnya.
@azure/identity
paket bisa melemparCredentialUnavailableError
.
Berikut ini adalah contoh untuk menangani kesalahan jenis ErrorResponse
, , TimeoutError
AbortError
, dan RestError
.
try {
// some code
} catch (err) {
if (err instanceof ErrorResponse) {
// some specific error handling.
} else if (err instanceof RestError) {
// some specific error handling.
}
// handle other type of errors in similar way.
else {
// for any other error.
}
}
Penting untuk menangani kesalahan ini dengan benar untuk memastikan bahwa aplikasi Anda dapat pulih dengan baik dari kegagalan apa pun dan terus berfungsi seperti yang diharapkan. Detail selengkapnya tentang beberapa kesalahan ini dan kemungkinan solusinya dapat ditemukan di sini.
Pemecahan Masalah
Umum
Saat Anda berinteraksi dengan kesalahan Cosmos DB yang ditampilkan oleh layanan sesuai dengan kode status HTTP yang sama yang ditampilkan untuk permintaan REST API:
Kode Status HTTP untuk Azure Cosmos DB
Konflik
Misalnya, jika Anda mencoba membuat item menggunakan id
yang sudah digunakan di database Cosmos DB Anda, kesalahan 409
akan ditampilkan, yang menunjukkan konflik. Dalam cuplikan berikut, kesalahan ditangani dengan baik dengan menangkap pengecualian dan menampilkan informasi tambahan tentang kesalahan tersebut.
try {
await containers.items.create({ id: "existing-item-id" });
} catch (error) {
if (error.code === 409) {
console.log("There was a conflict with an existing item");
}
}
Transpiling
Azure SDK dirancang untuk mendukung sintaks ES5 JavaScript dan versi LTS dari Node.js. Jika Anda memerlukan dukungan untuk runtime JavaScript sebelumnya seperti Internet Explorer atau Node 6, Anda perlu menerjemahkan kode SDK sebagai bagian dari proses pembangunan Anda.
Menangani kesalahan sementara dengan percobaan kembali
Saat bekerja dengan Cosmos DB, Anda mungkin mengalami kegagalan sementara yang disebabkan oleh batas kecepatan yang diberlakukan oleh layanan, atau masalah sementara lainnya seperti pemadaman jaringan. Untuk informasi tentang penanganan jenis kegagalan ini, lihat Coba lagi pola di panduan Pola Desain Cloud, dan pola Pemutus Sirkuit terkait.
Pencatatan
Mengaktifkan pengelogan dapat membantu menemukan informasi yang berguna tentang kegagalan. Untuk melihat log permintaan dan respons HTTP, atur variabel lingkungan AZURE_LOG_LEVEL
ke info
. Atau, pengelogan dapat diaktifkan saat runtime dengan memanggil setLogLevel
di @azure/logger
. Saat menggunakan AZURE_LOG_LEVEL
pastikan untuk mengaturnya sebelum pustaka pengelogan diinisialisasi.
Idealnya melewati baris perintah, jika menggunakan pustaka seperti dotenv
memastikan pustaka tersebut diinisialisasi sebelum pustaka pengelogan.
const { setLogLevel } = require("@azure/logger");
setLogLevel("info");
Untuk instruksi lebih rinci tentang cara mengaktifkan log, Anda dapat melihat dokumen paket @azure/pencatat.
Diagnostik
Fitur Diagnostik Cosmos memberikan wawasan yang disempurnakan tentang semua operasi klien Anda. Objek CosmosDiagnostics ditambahkan ke respons semua operasi klien. seperti
- Reponse operasi pencarian titik -
item.read()
, ,container.create()
database.delete()
- Respons operasi kueri -
queryIterator.fetchAll()
, - Operasi massal dan Batch -
item.batch()
. - Objek respons Kesalahan/Pengecualian.
Objek CosmosDiagnostics ditambahkan ke respons semua operasi klien. Ada 3 tingkat Diagnostik Cosmos, info, debug, dan debug-tidak aman. Di mana hanya info yang dimaksudkan untuk sistem produksi dan debug dan debug-tidak aman yang dimaksudkan untuk digunakan selama pengembangan dan penelusuran kesalahan, karena mereka mengonsumsi sumber daya yang jauh lebih tinggi. Tingkat Diagnostik Cosmos dapat diatur dengan 2 cara
- Secara terprogram
const client = new CosmosClient({ endpoint, key, diagnosticLevel: CosmosDbDiagnosticLevel.debug });
- Menggunakan variabel lingkungan. (Tingkat diagnostik yang ditetapkan oleh variabel Lingkungan memiliki prioritas yang lebih tinggi daripada mengaturnya melalui opsi klien.)
export AZURE_COSMOSDB_DIAGNOSTICS_LEVEL="debug"
Cosmos Diagnostic memiliki tiga anggota
Jenis ClientSideRequestStatistics: Berisi detail diagnostik agregat, termasuk pencarian metadata, percobaan ulang, titik akhir yang dihubungi, dan statistik permintaan dan respons seperti ukuran dan durasi payload. (selalu dikumpulkan, dapat digunakan dalam sistem produksi.)
DiagnosticNode: Adalah struktur seperti pohon yang menangkap informasi diagnostik terperinci. Mirip
har
dengan perekaman yang ada di browser. Fitur ini dinonaktifkan secara default dan hanya ditujukan untuk penelusuran kesalahan lingkungan non-produksi. (dikumpulkan pada debug tingkat diagnostik dan debug-tidak aman)ClientConfig: Mengambil informasi penting yang terkait dengan pengaturan konfigurasi klien selama inisialisasi klien. (dikumpulkan pada debug tingkat diagnostik dan debug-tidak aman)
Pastikan untuk tidak pernah mengatur tingkat diagnostik ke debug-unsafe
di lingkungan produksi, karena tingkat CosmosDiagnostics
ini menangkap payload permintaan dan respons dan jika Anda memilih untuk mencatatnya (secara default dicatat oleh @azure/logger pada verbose
tingkat). Payload ini mungkin ditangkap di sink log Anda.
Mengonsumsi Diagnostik
- Karena
diagnostics
ditambahkan ke semua objek Respons. Anda dapat mengaksesCosmosDiagnostic
secara terprogram sebagai berikut.
// For point look up operations
const { container, diagnostics: containerCreateDiagnostic } =
await database.containers.createIfNotExists({
id: containerId,
partitionKey: {
paths: ["/key1"],
},
});
// For Batch operations
const operations: OperationInput[] = [
{
operationType: BulkOperationType.Create,
resourceBody: { id: 'A', key: "A", school: "high" },
},
];
const response = await container.items.batch(operations, "A");
// For query operations
const queryIterator = container.items.query("select * from c");
const { resources, diagnostics } = await queryIterator.fetchAll();
// While error handling
try {
// Some operation that might fail
} catch (err) {
const diagnostics = err.diagnostics
}
- Anda juga dapat mencatat
diagnostics
menggunakan@azure/logger
, diagnostik selalu dicatat menggunakan@azure/logger
padaverbose
tingkat . Jadi, jika Anda mengatur Tingkat diagnostik kedebug
ataudebug-unsafe
dan@azure/logger
tingkat keverbose
,diagnostics
akan dicatat.
Langkah berikutnya
Lebih banyak kode sampel
Beberapa sampel tersedia untuk Anda di repositori GitHub SDK. Sampel ini memberikan kode contoh untuk skenario tambahan yang biasa ditemui saat bekerja dengan Cosmos DB:
- Operasi Database.
- Operasi Kontainer
- Operasi Item
- Mengonfigurasi Pengindeksan
- Membaca Umpan Perubahan kontainer
- Prosedur Tersimpan
- Mengubah pengaturan throughput Database/Kontainer
- Operasi Penulisan Multi Wilayah
Batasan
Saat ini fitur di bawah ini tidak didukung. Untuk opsi alternatif, periksa bagian Solusi di bawah ini.
Batasan Sarana Data:
- Kueri dengan COUNT dari subkueri DISTINCT
- Akses Mode TCP Langsung
- Kueri lintas partisi agregat, seperti pengurutan, penghitungan, dan perbedaan, tidak mendukung token kelanjutan. Kueri yang dapat dialirkan, seperti SELECT * FROM WHERE , mendukung token kelanjutan. Lihat bagian "Solusi" untuk menjalankan kueri yang tidak dapat dialirkan tanpa token kelanjutan.
- Umpan Perubahan: Prosesor
- Umpan Perubahan: Membaca beberapa nilai kunci partisi
- Ubah model penarikan Umpan semua versi dan mode hapus #27058
- Ubah dukungan model penarikan Umpan untuk kunci partisi hierarkis parsial #27059
- ORDER BY lintas partisi untuk jenis campuran
- Mendapatkan metrik CollectionSizeUsage, DatabaseUsage, dan DocumentUsage
- Membuat Indeks Geospasial
- Perbarui throughput Skala Otomatis
Batasan Sarana Kontrol:
Penyelesaian masalah
Token kelanjutan untuk kueri lintas partisi
Anda dapat mencapai kueri lintas partisi dengan dukungan token kelanjutan dengan menggunakan pola Side car. Pola ini juga dapat memungkinkan aplikasi terdiri dari komponen dan teknologi heterogen.
Menjalankan kueri lintas partisi yang tidak dapat diperkuat
Untuk menjalankan kueri yang tidak dapat dialirkan tanpa menggunakan token kelanjutan, Anda dapat membuat iterator kueri dengan spesifikasi dan opsi kueri yang diperlukan. Contoh kode berikut menunjukkan cara menggunakan iterator kueri untuk mengambil semua hasil tanpa perlu token kelanjutan:
const querySpec = {
query: "SELECT * FROM c WHERE c.status = @status",
parameters: [{ name: "@status", value: "active" }],
};
const queryOptions = {
maxItemCount: 10, // maximum number of items to return per page
enableCrossPartitionQuery: true,
};
const querIterator = await container.items.query(querySpec, queryOptions);
while (querIterator.hasMoreResults()) {
const { resources: result } = await querIterator.fetchNext();
//Do something with result
}
Pendekatan ini juga dapat digunakan untuk kueri yang dapat dialirkan.
Operasi sarana kontrol
Biasanya, Anda dapat menggunakan Portal Microsoft Azure, REST API Penyedia Sumber Daya Azure Cosmos DB, Azure CLI , atau PowerShell untuk batasan sarana kontrol yang tidak didukung.
Dokumentasi tambahan
Untuk dokumentasi yang lebih lengkap tentang layanan Cosmos DB, lihat dokumentasi Azure Cosmos DB di docs.microsoft.com.
Tautan yang Berguna
- Selamat datang di Microsoft Azure Cosmos DB
- Mulai cepat
- Tutorial
- Sampel
- Pengantar tentang Model Sumber Daya Layanan Azure Cosmos DB
- Pengantar tentang API SQL Layanan Azure Cosmos DB
- Partisi
- Dokumentasi API
Berkontribusi
Jika Anda ingin berkontribusi pada pustaka ini, baca panduan berkontribusi untuk mempelajari selengkapnya tentang cara membuat dan menguji kode.
Azure SDK for JavaScript