Pustaka klien Azure Cosmos DB untuk JavaScript - versi 4.0.0

Artikel
09/13/2023

/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 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 menyediakan id, 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 melempar CredentialUnavailableError.

Berikut ini adalah contoh untuk menangani kesalahan jenis ErrorResponse, , TimeoutErrorAbortError, 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 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 verbose tingkat . Jadi, jika Anda mengatur Tingkat diagnostik ke debug atau debug-unsafe dan @azure/logger tingkat ke verbose, 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

Batasan Sarana Kontrol:

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

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

Berkontribusi

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

Tayangan