Mulai cepat: Membangun API untuk aplikasi Table dengan Node.js dan Azure Cosmos DB
BERLAKU UNTUK:
Meja
Dalam mulai cepat ini, Anda membuat akun Azure Cosmos DB for Table, dan menggunakan Data Explorer dan aplikasi Node.js yang dikloning dari GitHub untuk membuat tabel dan entitas. Azure Cosmos DB adalah layanan database multi-model yang memungkinkan Anda membuat dan kueri dokumen, tabel, nilai-kunci, dan database grafik dengan kemampuan distribusi global dan skala horizontal dengan cepat.
Prasyarat
- Akun Azure dengan langganan aktif. Buat akun gratis.
- Node.js 0.10.29+.
- Git.
Aplikasi sampel
Aplikasi sampel untuk tutorial ini dapat diklon atau diunduh dari https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js repositori. Baik starter dan aplikasi yang sudah selesai disertakan dalam repositori sampel.
git clone https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js
Aplikasi sampel menggunakan data cuaca sebagai contoh untuk menunjukkan kemampuan API untuk Tabel. Objek yang mewakili pengamatan cuaca disimpan dan diambil menggunakan API untuk Tabel, termasuk menyimpan objek dengan properti tambahan untuk menunjukkan kemampuan TANPA skema API untuk Tabel.
1 - Membuat akun Azure Cosmos DB
Anda harus terlebih dahulu membuat akun AZURE Cosmos DB Tables API yang akan berisi tabel yang digunakan dalam aplikasi Anda. Tindakan ini dapat dilakukan menggunakan portal Microsoft Azure, Azure CLI, atau Azure PowerShell.
Masuk ke portal Azure dan ikuti langkah-langkah ini untuk membuat akun Azure Cosmos DB.
| Instruksi | Cuplikan layar |
|---|---|
Di portal Microsoft Azure:
|
|
| Pada halaman Azure Cosmos DB, pilih +Buat. | 
|
| Pada halaman opsi Pilih API, pilih opsi Tabel Azure. | 
|
Di halaman Buat Akun Azure Cosmos DB - Tabel Azure, isi formulir sebagai berikut.
|
|
2 - Membuat tabel
Selanjutnya, Anda perlu membuat tabel dalam akun Azure Cosmos DB untuk digunakan aplikasi Anda. Tidak seperti database tradisional, Anda hanya perlu menentukan nama tabel, bukan properti (kolom) dalam tabel. Saat data dimuat ke dalam tabel Anda, properti (kolom) akan dibuat secara otomatis sesuai kebutuhan.
Di portal Azure, selesaikan langkah-langkah berikut untuk membuat tabel di dalam akun Azure Cosmos DB Anda.
| Instruksi | Cuplikan layar |
|---|---|
| Di portal Microsoft Azure, navigasikan ke halaman gambaran umum untuk akun Azure Cosmos DB. Anda dapat menavigasi ke halaman gambaran umum untuk akun Azure Cosmos DB Anda dengan mengetikkan nama (cosmos-msdocs-tables-sdk-demo-XYZ) dari akun Azure Cosmos DB Anda di bilah pencarian atas dan melihat di bawah judul sumber daya. Pilih nama akun Azure Cosmos DB Anda untuk masuk ke halaman gambaran umum. | 
|
| Di halaman ringkasan, pilih + Tambahkan Tabel. Dialog Tabel Baru akan keluar dari sisi kanan halaman. | 
|
Pada dialog Tabel Baru, isi formulir sebagai berikut.
|
|
3 - Dapatkan string koneksi Azure Cosmos DB
Untuk mengakses tabel Anda di Azure Cosmos DB, aplikasi Anda akan memerlukan string koneksi tabel untuk akun Penyimpanan CosmosDB. String koneksi dapat diambil menggunakan portal Microsoft Azure, Azure CLI atau Azure PowerShell.
| Instruksi | Cuplikan layar |
|---|---|
| Di sisi kiri halaman akun Azure Cosmos DB, temukan item menu bernama String Koneksi di bagian header Pengaturan lalu pilih. Anda akan dialihkan ke halaman tempat Anda dapat mengambil string koneksi untuk akun Azure Cosmos DB. | 
|
| Salin nilai STRING KONEKSI UTAMA untuk digunakan dalam aplikasi Anda. | 
|
4 - Memasang Azure Data Table SDK untuk JS
Untuk mengakses Azure Cosmos DB for Table dari aplikasi nodejs, instal paket Azure Data Tables SDK .
npm install @azure/data-tables
5 - Mengonfigurasi klien Tabel dalam file env.js
Salin string koneksi akun Azure Cosmos DB atau Storage Anda dari portal Azure, dan buat objek TableServiceClient menggunakan string koneksi yang disalin. Beralih ke folder 1-strater-app atau 2-completed-app. Kemudian, tambahkan nilai variabel lingkungan yang sesuai dalam file configure/env.js.
const env = {
connectionString:"A connection string to an Azure Storage or Azure Cosmos DB account.",
tableName: "WeatherData",
};
Azure SDK berkomunikasi dengan Azure menggunakan objek klien untuk menjalankan operasi yang berbeda terhadap Azure. Kelas TableClient adalah kelas yang digunakan untuk berkomunikasi dengan Azure Cosmos DB for Table. Sebuah aplikasi biasanya akan membuat satu objek serviceClient per tabel yang akan digunakan di seluruh aplikasi.
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
6 - Menerapkan operasi tabel Azure Cosmos DB
Semua operasi tabel Azure Cosmos DB untuk aplikasi sampel diimplementasikan dalam serviceClient objek yang terletak di file di tableClient.js bawah direktori layanan .
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
Mendapatkan baris dari tabel
Objek serviceClient berisi metode bernama listEntities yang memungkinkan Anda memilih baris dari tabel. Dalam contoh ini, karena tidak ada parameter yang diteruskan ke metode, semua baris akan dipilih dari tabel.
const allRowsEntities = serviceClient.listEntities();
Memfilter baris yang dikembalikan dari tabel
Untuk memfilter baris yang dikembalikan dari tabel, Anda bisa meneruskan string filter gaya OData ke metode listEntities. Misalnya, jika Anda ingin mendapatkan semua pembacaan cuaca untuk Chicago antara 1 Juli 2021 tengah malam dan 2 Juli 2021 tengah malam (inklusif), Anda harus meneruskan string filter berikut.
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00' and RowKey le '2021-07-02 12:00'
Anda dapat melihat semua operator filter OData di situs web OData di bagian Filter Opsi Kueri Sistem.
Saat parameter request.args diteruskan ke metode listEntities di kelas serviceClient, ini membuat string filter untuk setiap nilai properti non-null. Kemudian string filter gabungan akan dibuat dengan menggabungkan semua nilai bersama dengan klausul "dan". String filter gabungan ini diteruskan ke metode listEntities pada objek serviceClient dan hanya baris yang cocok dengan string filter yang akan dikembalikan. Anda dapat menggunakan metode serupa dalam kode Anda untuk membangun string filter yang sesuai seperti yang dipersyaratkan oleh aplikasi Anda.
const filterEntities = async function (option) {
/*
You can query data according to existing fields
option provides some conditions to query,eg partitionKey, rowKeyDateTimeStart, rowKeyDateTimeEnd
minTemperature, maxTemperature, minPrecipitation, maxPrecipitation
*/
const filterEntitiesArray = [];
const filters = [];
if (option.partitionKey) {
filters.push(`PartitionKey eq '${option.partitionKey}'`);
}
if (option.rowKeyDateTimeStart) {
filters.push(`RowKey ge '${option.rowKeyDateTimeStart}'`);
}
if (option.rowKeyDateTimeEnd) {
filters.push(`RowKey le '${option.rowKeyDateTimeEnd}'`);
}
if (option.minTemperature !== null) {
filters.push(`Temperature ge ${option.minTemperature}`);
}
if (option.maxTemperature !== null) {
filters.push(`Temperature le ${option.maxTemperature}`);
}
if (option.minPrecipitation !== null) {
filters.push(`Precipitation ge ${option.minPrecipitation}`);
}
if (option.maxPrecipitation !== null) {
filters.push(`Precipitation le ${option.maxPrecipitation}`);
}
const res = serviceClient.listEntities({
queryOptions: {
filter: filters.join(" and "),
},
});
for await (const entity of res) {
filterEntitiesArray.push(entity);
}
return filterEntitiesArray;
};
Menyisipkan data menggunakan objek TableEntity
Cara termudah untuk menambahkan data ke tabel adalah dengan menggunakan objek TableEntity. Dalam contoh ini, data dipetakan dari objek model input ke objek TableEntity. Properti pada objek input yang merepresentasikan nama stasiun cuaca dan tanggal/waktu pengamatan masing-masing dipetakan ke properti PartitionKey dan RowKey yang bersama-sama membentuk kunci unik untuk baris dalam tabel. Kemudian properti tambahan pada objek model input dipetakan ke properti kamus pada objek TableEntity. Terakhir, metode createEntity pada objek serviceClient digunakan untuk memasukkan data ke dalam tabel.
Ubah fungsi insertEntity dalam aplikasi contoh agar mencakup kode berikut.
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
Melakukan upsert data menggunakan objek TableEntity
Jika Anda mencoba menyisipkan baris ke dalam tabel dengan kombinasi kunci partisi/kunci baris yang sudah ada di tabel itu, Anda akan menerima kesalahan. Untuk alasan ini, sering kali lebih baik menggunakan upsertEntity daripada metode createEntity saat menambahkan baris ke tabel. Jika kombinasi kunci partisi/kunci baris yang diberikan sudah ada dalam tabel, metode upsertEntity akan memperbarui baris yang ada. Jika tidak, baris akan ditambahkan ke tabel.
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
Menyisipkan atau melakukan upsert data dengan properti variabel
Salah satu keuntungan menggunakan Azure Cosmos DB for Table adalah bahwa jika objek yang dimuat ke tabel berisi properti baru, properti tersebut secara otomatis ditambahkan ke tabel dan nilai yang disimpan di Azure Cosmos DB. Tidak perlu menjalankan pernyataan DDL seperti ALTER TABLE untuk menambahkan kolom seperti dalam database tradisional.
Model ini memberikan fleksibilitas pada aplikasi Anda ketika berhadapan dengan sumber data yang dapat menambah atau memodifikasi data apa yang perlu ditangkap dari waktu ke waktu atau ketika input yang berbeda memberikan data yang berbeda untuk aplikasi Anda. Dalam aplikasi contoh, kita dapat mensimulasikan stasiun cuaca yang mengirimkan tidak hanya data cuaca dasar tetapi juga sejumlah nilai tambahan. Ketika objek dengan properti baru ini disimpan dalam tabel untuk pertama kalinya, properti (kolom) yang sesuai akan ditambahkan secara otomatis ke tabel.
Untuk menyisipkan atau melakukan upsert objek tersebut menggunakan API untuk Tabel, petakan properti objek yang TableEntity dapat diperluas ke dalam objek dan gunakan createEntity metode atau upsertEntity pada serviceClient objek yang sesuai.
Dalam contoh aplikasi, fungsi upsertEntity juga dapat mengimplementasikan fungsi menyisipkan atau menambahkan data dengan properti variabel
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
Memperbarui entitas
Entitas dapat diperbarui dengan memanggil metode updateEntity pada objek serviceClient.
Dalam aplikasi contoh, objek ini diteruskan ke metode upsertEntity di kelas serviceClient. Metode ini kemudian memperbarui objek entitas itu dan menggunakan metode upsertEntity untuk menyimpan pembaruan ke database.
const updateEntity = async function (entity) {
await serviceClient.updateEntity(entity, "Replace");
};
7 - Menjalankan kode
Jalankan aplikasi sampel untuk berinteraksi dengan Azure Cosmos DB for Table. Saat pertama kali menjalankan aplikasi, data tidak akan tersedia karena tabel kosong. Gunakan salah satu tombol di bagian atas aplikasi untuk menambahkan data ke tabel.
Memilih tombol Sisipkan menggunakan Entitas Tabel membuka dialog yang memungkinkan Anda menyisipkan atau melakukan upsert pada baris baru menggunakan objek TableEntity.
Memilih tombol Sisipkan menggunakan Data yang Dapat Diperluas memunculkan dialog yang memungkinkan Anda menyisipkan objek dengan properti kustom, menunjukkan bagaimana Azure Cosmos DB for Table secara otomatis menambahkan properti (kolom) ke tabel saat diperlukan. Gunakan tombol Tambahkan Bidang Isian Kustom untuk menambahkan satu atau beberapa properti baru dan mendemonstrasikan kemampuan ini.
Gunakan tombol Sisipkan Data Sampel untuk memuat beberapa data sampel ke dalam Tabel Azure Cosmos DB Anda.
Pilih item Filter Hasil di menu atas yang akan membawa Anda ke halaman Filter Hasil. Pada halaman ini, isi kriteria filter untuk menunjukkan bagaimana klausa filter dapat dibuat dan diteruskan ke Azure Cosmos DB for Table.
Membersihkan sumber daya
Setelah selesai dengan aplikasi contoh, Anda harus menghapus semua sumber daya Azure yang terkait dengan artikel ini dari akun Azure Anda. Anda dapat melakukannya dengan menghapus grup sumber daya.
Anda dapat menghapus grup sumber daya di portal Microsoft Azure dengan melakukan hal berikut.
| Instruksi | Cuplikan layar |
|---|---|
| Untuk masuk ke grup sumber daya, ketik nama grup sumber daya di bilah pencarian. Lalu pada tab Grup Sumber Daya, pilih nama grup sumber daya. | 
|
| Pilih Hapus grup sumber daya dari toolbar di bagian atas halaman grup sumber daya. | 
|
Dialog akan muncul dari kanan layar yang meminta Anda untuk mengonfirmasi penghapusan grup sumber daya.
|
|
Langkah berikutnya
Dalam mulai cepat ini, Anda telah mempelajari cara membuat akun Microsoft Azure Cosmos DB, membuat tabel menggunakan Data Explorer, dan menjalankan aplikasi. Sekarang Anda dapat mengkueri data Anda menggunakan API untuk Tabel.