Pustaka klien Azure Cosmos DB untuk JavaScript - versi 4.2.0

Artikel
11/20/2024

/TypeScript

Status Build

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 untuk aplikasi JavaScript/TypeScript untuk berinteraksi dengan database API SQL dan dokumen JSON yang dikandungnya:

Membuat database Cosmos DB dan mengubah pengaturannya
Membuat dan memodifikasi kontainer untuk menyimpan koleksi dokumen JSON
Membuat, membaca, memperbarui, dan menghapus item (dokumen JSON) di kontainer Anda
Mengkueri dokumen dalam database Anda menggunakan sintaks seperti SQL

Tautan kunci:

Paket (npm)
dokumentasi referensi API
dokumentasi produk

Persiapan

Prasyarat

Langganan Azure dan Akun Cosmos DB SQL API

Anda harus memilikiLangganan Azure , dan akun Cosmos DB (SQL API) untuk menggunakan paket ini.

Jika Anda memerlukan akun Cosmos DB SQL API, Anda dapat menggunakan Azure Cloud Shell untuk membuatnya 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 menggunakan versi LTS.

CORS

Anda perlu menyiapkan aturan Cross-Origin Resource Sharing (CORS) untuk akun Cosmos DB Anda jika Anda perlu mengembangkan browser. Ikuti instruksi dalam dokumen tertaut untuk membuat aturan CORS baru untuk Cosmos DB Anda.

Instal paket ini

npm install @azure/cosmos

Dapatkan Kredensial Akun

Anda akan memerlukan Titik Akhir Akun Cosmos DB danKunci . Anda dapat menemukannya di Portal Azure atau menggunakan cuplikan azure CLI di bawah ini. 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 langsung dalam kode tetapi Anda mungkin ingin memuatnya dari file yang tidak 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 menginisialisasi CosmosClient, Anda dapat berinteraksi dengan jenis sumber daya utama di Cosmos DB:

Database: Akun Cosmos DB dapat berisi beberapa database. Saat membuat database, Anda menentukan API yang ingin Anda gunakan saat berinteraksi dengan dokumennya: SQL, MongoDB, Gremlin, Cassandra, atau Azure Table. Gunakan objek Database untuk mengelola kontainernya.
Container: 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 dalam kontainer. Jika Anda tidak memberikan id, SDK akan menghasilkannya 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
Sisipkan item
dokumen Kueri
Membaca item
Menghapus item
CRUD pada Kontainer dengan kunci partisi hierarkis

Membuat database

Setelah mengautentikasiCosmosClient, Anda dapat bekerja dengan sumber daya apa pun di akun. Cuplikan kode di bawah ini membuat database API NOSQL.

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
console.log(database.id);

Membuat 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();

Sisipkan item

Untuk menyisipkan item ke dalam kontainer, teruskan objek yang berisi data Anda ke Items.upsert. Layanan Azure Cosmos DB mengharuskan setiap item memiliki kunci id. 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. Ini adalah operasi yang lebih murah daripada menggunakan SQL untuk mengkueri dengan 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} `);
}

Menghapus 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 Cosmos DB SQL API mendukung kueri item dalam 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 nilainya 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 SQL API, 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 changeFeedStartFrom yang diperlukan 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 nilai changeFeedStartFrom 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 status NotModified.

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 Batal 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. Untuk Eg. paket @azure/identity dapat melemparkan CredentialUnavailableError.

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 dikembalikan oleh layanan sesuai dengan kode status HTTP yang sama yang dikembalikan untuk permintaan REST API:

Kode Status HTTP untuk Azure Cosmos DB

Konflik

Misalnya, jika Anda mencoba membuat item menggunakan id yang sudah digunakan dalam database Cosmos DB Anda, kesalahan 409 dikembalikan, menunjukkan konflik. Dalam cuplikan berikut, kesalahan ditangani dengan anggun dengan menangkap pengecualian dan menampilkan informasi tambahan tentang kesalahan.

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");
  }
}

Menerjemahkan

Azure SDK dirancang untuk mendukung sintaksis JavaScript ES5 dan versi LTS Node.js. Jika Anda memerlukan dukungan untuk runtime JavaScript sebelumnya seperti Internet Explorer atau Node 6, Anda harus menerjemahkan kode SDK sebagai bagian dari proses build Anda.

Menangani kesalahan sementara dengan percobaan ulang

Saat bekerja dengan Cosmos DB, Anda mungkin mengalami kegagalan sementara yang disebabkan oleh batas laju diberlakukan oleh layanan, atau masalah sementara lainnya seperti pemadaman jaringan. Untuk informasi tentang menangani jenis kegagalan ini, lihat pola Coba Lagi dalam panduan Pola Desain Cloud, dan pola pemutus sirkuit terkait.

Penebangan

Mengaktifkan pengelogan dapat membantu mengungkap 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 teruskan melalui baris perintah, jika menggunakan pustaka seperti dotenv pastikan 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 ditingkatkan tentang semua operasi klien Anda. Objek CosmosDiagnostics ditambahkan ke respons semua operasi klien. misalnya

Respons operasi pencarian titik - item.read(), container.create(), database.delete()
Reponse 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 dalam 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 dengan har rekaman yang ada di browser. Fitur ini dinonaktifkan secara default dan ditujukan untuk men-debug lingkungan non-produksi saja. (dikumpulkan pada debug tingkat diagnostik dan debug-tidak aman)
ClientConfig: Menangkap 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 ini CosmosDiagnostics menangkap payload permintaan dan respons dan jika Anda memilih untuk mencatatnya (secara default dicatat oleh @azure/logger pada tingkat verbose). Payload ini mungkin ditangkap di sink log Anda.

Mengonsumsi Diagnostik

Karena diagnostics ditambahkan ke semua objek Respons. Anda dapat mengakses CosmosDiagnostic 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 pada tingkat verbose. Jadi, jika Anda mengatur Tingkat diagnostik ke tingkat debug atau debug-unsafe dan @azure/logger ke verbose, diagnostics akan dicatat.

Langkah berikutnya

Kode sampel lainnya

Beberapa sampel tersedia untuk Anda di repositori GitHub SDK. Sampel ini menyediakan contoh kode untuk skenario tambahan yang umum 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

Keterbatasan

Saat ini fitur di bawah ini tidak didukung. Untuk opsi alternatif, periksa bagian Solusi di bawah ini.

Batasan Data Plane:

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.
Ubah Umpan: Prosesor
Ubah Umpan: Membaca beberapa nilai kunci partisi
Ubah dukungan model penarikan Umpan untuk kunci partisi hierarki parsial #27059
ORDER LINTAS partisi BY untuk jenis campuran

Batasan Sarana Kontrol:

Mendapatkan metrik CollectionSizeUsage, DatabaseUsage, dan DocumentUsage
Membuat Indeks Geospasial
Memperbarui throughput Skala Otomatis

Solusi sementara

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 c.status, COUNT(c.id) AS count FROM c GROUP BY c.status",
};
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 Azure Portal, REST API Penyedia Sumber Daya Azure Cosmos DB, Azure CLI atau PowerShell untuk batasan bidang kontrol yang tidak didukung.

Dokumentasi tambahan

Untuk dokumentasi yang lebih luas tentang layanan Cosmos DB, lihat dokumentasi Azure Cosmos DB di docs.microsoft.com.

Tautan yang berguna

Selamat Datang di Azure Cosmos DB
mulai cepat
Tutorial
Sampel
Pengenalan Model Sumber Daya Azure Cosmos DB Service
Pengenalan SQL API dari Azure Cosmos DB Service
Pemartisian
Dokumentasi API

Berkontribusi

Jika Anda ingin berkontribusi pada pustaka ini, baca panduan berkontribusi untuk mempelajari selengkapnya tentang cara membuat dan menguji kode.

Tayangan

Bagikan melalui