Cara menggunakan penyimpanan Azure Table atau Azure Cosmos DB for Table dari Node.js

Artikel
03/25/2023

BERLAKU UNTUK: Meja

Tip

Konten dalam artikel ini berlaku untuk penyimpanan Azure Table dan Azure Cosmos DB for Table. API untuk Tabel adalah penawaran premium untuk penyimpanan tabel yang menawarkan tabel yang dioptimalkan throughput, distribusi global, dan indeks sekunder otomatis.

Artikel ini menunjukkan cara membuat tabel, menyimpan data Anda, dan melakukan operasi CRUD pada data tersebut. Sampel ditulis dalam Node.js.

Membuat akun layanan Azure

Anda dapat bekerja dengan tabel menggunakan penyimpanan Azure Table atau Azure Cosmos DB. Untuk mempelajari selengkapnya tentang perbedaan antara penawaran tabel di kedua layanan ini, lihat gambaran umum API untuk Tabel. Anda harus membuat akun untuk layanan yang akan Anda gunakan. Bagian berikut menunjukkan cara membuat penyimpanan Azure Table dan akun Azure Cosmos DB, tetapi Anda bisa menggunakan salah satunya.

Membuat akun Azure Storage

Cara termudah untuk membuat akun penyimpanan Azure adalah dengan menggunakan portal Azure. Untuk mempelajari selengkapnya, lihat Buat akun penyimpanan.

Anda juga bisa membuat akun penyimpanan Azure dengan menggunakan Azure PowerShell atau Azure CLI.

Jika Anda lebih suka tidak membuat akun penyimpanan saat ini, Anda juga dapat menggunakan Azure Storage emulator untuk menjalankan dan menguji kode Anda di lingkungan lokal. Untuk informasi selengkapnya, lihat Menggunakan Azure Storage Emulator untuk pengembangan dan pengujian.

Membuat akun Azure Cosmos DB for Table

Untuk instruksi tentang membuat akun Azure Cosmos DB for Table, lihat Membuat akun database.

Konfigurasikan aplikasi Anda untuk mengakses Table Storage

Untuk menggunakan Azure Storage atau Azure Cosmos DB, Anda memerlukan Azure Table SDK for Node.js, yang mencakup serangkaian pustaka kenyamanan yang berkomunikasi dengan layanan Storage REST.

Gunakan NPM untuk menginstal paketnya

Gunakan antarmuka baris perintah seperti PowerShell (Windows), Terminal (Mac), atau Bash (Unix), dan navigasikan ke folder tempat Anda membuat aplikasi.
Ketik hal berikut di jendela perintah:

   npm install @azure/data-tables

Anda dapat menjalankan perintah ls secara manual untuk memverifikasi bahwa folder node_modules telah dibuat. Di dalam folder itu Anda akan menemukan paket @azure/data-tables, yang berisi pustaka yang Anda perlukan untuk mengakses penyimpanan.

Mengimpor paket

Tambahkan kode berikut ke bagian atas file server.js di aplikasi Anda:

const { TableServiceClient, TableClient, AzureNamedKeyCredential, odata } = require("@azure/data-tables");

Menyambungkan ke layanan Tabel Azure

Anda dapat menyambungkan ke akun penyimpanan Azure atau akun Azure Cosmos DB for Table. Dapatkan kunci bersama atau string koneksi berdasarkan jenis akun yang Anda gunakan.

Membuat klien layanan Tabel dari kunci bersama

Modul Azure membaca variabel lingkungan AZURE_ACCOUNT dan AZURE_ACCESS_KEY dan AZURE_TABLES_ENDPOINT untuk informasi yang diperlukan untuk menyambungkan ke akun Azure Storage atau Azure Cosmos DB Anda. Jika variabel lingkungan ini tidak diatur, Anda harus menentukan informasi akun saat memanggilTableServiceClient. Contohnya, kode berikut membuat objek TableServiceClient:

const endpoint = "<table-endpoint-uri>";
const credential = new AzureNamedKeyCredential(
  "<account-name>",
  "<account-key>"
);

const tableService = new TableServiceClient(
  endpoint,
  credential
);

Membuat klien layanan Tabel dari string koneksi

Untuk menambahkan koneksi akun penyimpanan atau Azure Cosmos DB, buat TableServiceClient objek dan tentukan nama akun, kunci utama, dan titik akhir Anda. Anda dapat menyalin nilai-nilai ini dari String Pengaturan> Koneksi ion di portal Azure untuk akun Azure Cosmos DB atau akun Penyimpanan Anda. Contohnya:

const tableService = TableServiceClient.fromConnectionString("<connection-string>");

Buat tabel

Panggilan ke createTable membuat tabel baru dengan nama yang ditentukan jika belum ada. Contoh berikut membuat tabel baru bernama 'mytable' jika belum ada:

await tableService.createTable('<table-name>');

Membuat klien Tabel

Untuk berinteraksi dengan tabel, Anda harus membuat TableClient objek menggunakan kredensial yang sama dengan yang Anda gunakan untuk membuat TableServiceClient. juga TableClient memerlukan nama tabel target.

const tableClient = new TableClient(
  endpoint,
  '<table-name>',
  credential
);

Menambahkan entitas pada tabel

Untuk menambahkan entitas, pertama-tama buat objek yang mendefinisikan properti entitas Anda. Semua entitas harus berisi partitionKey dan rowKey, yang merupakan pengenal unik untuk entitas tersebut.

partitionKey - Menentukan partisi tempat entitas disimpan.
rowKey - Secara unik mengidentifikasi entitas dalam partisi.

Baik partitionKey dan rowKey harus berupa nilai string.

Berikut ini adalah contoh pendefinisian entitas. dueDate didefinisikan sebagai jenis Date. Menentukan tipe bersifat opsional, dan tipe disimpulkan jika tidak ditentukan.

const task = {
  partitionKey: "hometasks",
  rowKey: "1",
  description: "take out the trash",
  dueDate: new Date(2015, 6, 20)
};

Catatan

Ada juga bidang Timestamp untuk setiap rekaman, yang ditetapkan oleh Azure saat entitas disisipkan atau diperbarui.

Untuk menambahkan entitas ke tabel Anda, teruskan objek entitas ke metode createEntity.

let result = await tableClient.createEntity(task);
    // Entity create

Jika operasi berhasil, result berisi ETag dan informasi tentang operasi.

Contoh respons:

{ 
  clientRequestId: '94d8e2aa-5e02-47e7-830c-258e050c4c63',
  requestId: '08963b85-1002-001b-6d8c-12ae5d000000',
  version: '2019-02-02',
  date: 2022-01-26T08:12:32.000Z,
  etag: `W/"datetime'2022-01-26T08%3A12%3A33.0180348Z'"`,
  preferenceApplied: 'return-no-content',
  'cache-control': 'no-cache',
  'content-length': '0'
}

Memperbarui entitas

Berbagai mode untuk updateEntity dan upsertEntity metode

Gabungkan: Memperbarui entitas dengan memperbarui properti entitas tanpa mengganti entitas yang ada.
Ganti: Memperbarui entitas yang sudah ada dengan mengganti seluruh entitas.

Contoh berikut menunjukkan pembaruan entitas menggunakan upsertEntity:

// Entity doesn't exist in table, so calling upsertEntity will simply insert the entity.
let result = await tableClient.upsertEntity(task, "Replace");

Jika entitas yang diperbarui tidak ada, maka operasi pembaruan gagal; oleh karena itu, jika Anda ingin menyimpan entitas terlepas dari apakah entitas itu sudah ada, gunakan upsertEntity.

result untuk operasi pembaruan yang berhasil berisi Etag dari entitas yang diperbarui.

Bekerja dengan grup entitas

Terkadang masuk akal untuk mengirimkan beberapa operasi bersama-sama dalam batch untuk memastikan pemrosesan atom oleh server. Untuk mencapainya, buat serangkaian operasi dan sampaikan ke metode submitTransaction di TableClient.

Contoh berikut menunjukkan pengiriman dua entitas dalam satu batch:

const task1 = {
  partitionKey: "hometasks",
  rowKey: "1",
  description: "Take out the trash",
  dueDate: new Date(2015, 6, 20)
};
const task2 = {
  partitionKey: "hometasks",
  rowKey: "2",
  description: "Wash the dishes",
  dueDate: new Date(2015, 6, 20)
};

const tableActions = [
  ["create", task1],
  ["create", task2]
];

let result = await tableClient.submitTransaction(tableActions);
    // Batch completed

Untuk operasi batch yang berhasil, result berisi informasi untuk setiap operasi dalam batch.

Mengambil entitas berdasarkan kunci

Untuk mengembalikan entitas tertentu berdasarkan PartitionKey dan RowKey, gunakan metode getEntity.

let result = await tableClient.getEntity("hometasks", "1")
  .catch((error) => {
    // handle any errors
  });
  // result contains the entity

Setelah operasi ini selesai, result berisi entitas.

Meng-kueri set entitas

Contoh berikut membuat kueri yang mengembalikan lima item teratas dengan PartitionKey dari 'hometasks' dan daftar semua entitas di dalam tabel.

const topN = 5;
const partitionKey = "hometasks";

const entities = tableClient.listEntities({
  queryOptions: { filter: odata`PartitionKey eq ${partitionKey}` }
});

let topEntities = [];
const iterator = entities.byPage({ maxPageSize: topN });

for await (const page of iterator) {
  topEntities = page;
  break;
}

// Top entities: 5
console.log(`Top entities: ${topEntities.length}`);

// List all the entities in the table
for await (const entity of entities) {
console.log(entity);
}

Mengkueri subset properti entitas

Kueri ke tabel dapat mengambil hanya beberapa bidang dari entitas. Teknik ini dapat mengurangi bandwidth dan meningkatkan kinerja kueri, terutama untuk entitas besar. Gunakan klausul pilih dan teruskan nama bidang yang akan dikembalikan. Misalnya, kueri berikut hanya mengembalikan deskripsi dan bidang dueDate.

const topN = 5;
const partitionKey = "hometasks";

const entities = tableClient.listEntities({
  queryOptions: { filter: odata`PartitionKey eq ${partitionKey}`,
                  select: ["description", "dueDate"]  }
});

let topEntities = [];
const iterator = entities.byPage({ maxPageSize: topN });

for await (const page of iterator) {
  topEntities = page;
  break;
}

Menghapus entitas

Anda dapat menghapus entitas menggunakan tombol partisi dan barisnya. Dalam contoh ini, objek task1 berisi nilai rowKey dan partitionKey dari entitas yang akan dihapus. Kemudian objek diteruskan ke metode deleteEntity.

const tableClient = new TableClient(
  tablesEndpoint,
  tableName,
  new AzureNamedKeyCredential("<accountName>", "<accountKey>")
);

await tableClient.deleteEntity("hometasks", "1");
    // Entity deleted

Catatan

Pertimbangkan untuk menggunakan ETags saat menghapus item, untuk memastikan bahwa item tersebut belum dimodifikasi oleh proses lain. Lihat Perbarui entitas untuk informasi tentang penggunaan ETags.

Menghapus tabel

Kode berikut menghapus tabel dari akun penyimpanan.

await tableClient.deleteTable(mytable);
        // Table deleted

Gunakan token kelanjutan

Saat Anda mengkueri tabel untuk hasil dalam jumlah besar, cari token kelanjutan. Mungkin ada sejumlah besar data yang tersedia untuk kueri yang mungkin tidak Anda sadari jika Anda tidak membangun untuk mengenali saat token kelanjutan ada.

Objek hasil yang dikembalikan selama entitas kueri menetapkan properti continuationToken saat token seperti itu ada. Anda kemudian dapat menggunakan ini saat melakukan kueri untuk terus berpindah di seluruh entitas partisi dan tabel.

Saat mengkueri, Anda dapat memberikan parameter continuationToken antara instans objek kueri dan fungsi panggilan balik:

let iterator = tableClient.listEntities().byPage({ maxPageSize: 2 });
let interestingPage;

const page = await tableClient
   .listEntities()
   .byPage({ maxPageSize: 2, continuationToken: interestingPage })
   .next();

 if (!page.done) {
   for (const entity of page.value) {
     console.log(entity.rowKey);
   }
 }

Bekerja dengan tanda tangan akses bersama

Tanda tangan akses bersama (SAS) adalah cara yang aman untuk menyediakan akses terperinci ke tabel tanpa memberikan nama atau kunci akun Penyimpanan Anda. SAS sering digunakan untuk menyediakan akses terbatas ke data Anda, seperti mengizinkan aplikasi seluler untuk meminta rekaman.

Aplikasi tepercaya seperti layanan berbasis cloud menghasilkan SAS menggunakan generateTableSas dari TableClient, dan menyediakannya ke aplikasi yang tidak tepercaya atau semi-tepercaya seperti aplikasi seluler. SAS dihasilkan menggunakan kebijakan, yang menjelaskan tanggal mulai dan akhir di mana SAS berlaku, serta tingkat akses yang diberikan kepada pemegang SAS.

Contoh berikut menghasilkan kebijakan akses bersama baru yang akan memungkinkan pemegang SAS untuk mengkueri ('r') tabel.

const tablePermissions = {
    query: true
// Allows querying entities
};

// Create the table SAS token
const tableSAS = generateTableSas('mytable', cred, {
  expiresOn: new Date("2022-12-12"),
  permissions: tablePermissions
});

Aplikasi klien kemudian menggunakan SAS dengan AzureSASCredential untuk melakukan operasi terhadap tabel. Contoh berikut ini tersambung ke tabel dan melakukan kueri. Lihat artikel Berikan akses terbatas ke sumber daya Azure Storage menggunakan tanda tangan akses bersama (SAS) untuk format tableSAS.

// Note in the following command, tablesUrl is in the format: `https://<your_storage_account_name>.table.core.windows.net` and the tableSAS is in the format: `sv=2018-03-28&si=saspolicy&tn=mytable&sig=9aCzs76n0E7y5BpEi2GvsSv433BZa22leDOZXX%2BXXIU%3D`;

const tableService = new TableServiceClient(tablesUrl, new AzureSASCredential(tableSAS));
const partitionKey = "hometasks";

const entities = tableService.listTables({
  queryOptions: { filter: odata`PartitionKey eq ${partitionKey}` }
});

Karena SAS dihasilkan hanya dengan akses kueri, kesalahan akan dikembalikan jika Anda mencoba memasukkan, memperbarui, atau menghapus entitas.

Daftar Kontrol Akses

Anda juga bisa menggunakan Daftar Kontrol Akses (ACL, Access Control List) untuk mengatur kebijakan akses SAS. Ini berguna jika Anda ingin mengizinkan beberapa klien mengakses tabel, tetapi memberikan kebijakan akses yang berbeda untuk setiap klien.

ACL diimplementasikan menggunakan array kebijakan akses, dengan ID yang terkait dengan setiap kebijakan. Contoh berikut mendefinisikan dua kebijakan, satu untuk 'user1' dan satu untuk 'user2':

var sharedAccessPolicy = [{
  id:"user1",
  accessPolicy:{
    permission: "r" ,
    Start: startsOn,
    Expiry: expiresOn,
  }},
  {
  id:"user2",
  accessPolicy:{
    permissions: "a",
    Start: startsOn,
    Expiry: expiresOn,
  }},
]

Contoh berikut mendapatkan ACL saat ini untuk tabel hometasks, lalu menambahkan kebijakan baru menggunakan setAccessPolicy. Pendekatan ini memungkinkan:

tableClient.getAccessPolicy();
tableClient.setAccessPolicy(sharedAccessPolicy);

Setelah ACL ditetapkan, Anda kemudian dapat membuat SAS berdasarkan ID untuk kebijakan. Contoh berikut membuat SAS baru untuk 'user2':

tableSAS = generateTableSas("hometasks",cred,{identifier:'user2'});

Langkah berikutnya

Untuk informasi selengkapnya, lihat sumber berikut ini:

Explorer Microsoft Azure Storage adalah aplikasi mandiri gratis dari Microsoft yang memungkinkan Anda bekerja secara visual dengan data Azure Storage di Windows, macOS, dan Linux.
Repositori Azure Data Tables SDK for Node.js di GitHub.
Membuat aplikasi web Node.js di Azure
Menyusun dan menerapkan aplikasi Node.js ke Azure Cloud Service (menggunakan Windows PowerShell)