Mulai cepat: Membangun API untuk aplikasi Table dengan Python SDK dan Azure Cosmos DB
BERLAKU UNTUK:
Meja
Mulai cepat ini menunjukkan cara mengakses API Azure Cosmos DB untuk Tabel dari aplikasi Python. Azure Cosmos DB for Table adalah penyimpanan data tanpa skema yang memungkinkan aplikasi menyimpan data NoSQL terstruktur di cloud. Karena data disimpan dalam desain tanpa skema, properti baru (kolom) secara otomatis ditambahkan ke tabel ketika objek dengan atribut baru ditambahkan ke tabel. Aplikasi Python dapat mengakses Azure Cosmos DB for Table menggunakan paket Azure Data Tables SDK for Python .
Prasyarat
Aplikasi sampel ditulis dalam Python 3.7 atau yang lebih baru, meskipun prinsip-prinsipnya berlaku untuk semua aplikasi Python 3.7+. Anda dapat menggunakan Visual Studio Code sebagai IDE.
Jika Anda tidak memiliki langganan Azure, buatlah akun gratis sebelum Anda memulai.
Aplikasi sampel
Aplikasi sampel untuk tutorial ini dapat diklon atau diunduh dari https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flask repositori.
git clone https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flask.git
Folder sampel 1-starter-app dan 2-completed-app disertakan dalam repositori sampel. 1-starter-app memiliki beberapa fungsionalitas yang tersisa untuk Anda selesaikan dengan baris bertanda "#TODO". Cuplikan kode yang ditampilkan dalam artikel ini adalah penambahan yang disarankan untuk menyelesaikan 1-starter-app.
Aplikasi sampel yang telah selesai 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. Gambar berikut menunjukkan aplikasi lokal yang berjalan di browser, menampilkan data cuaca yang disimpan di Azure Cosmos DB for Table.
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. Buat akun dengan portal 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) secara otomatis dibuat 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.
|
|
| Pada halaman Gambaran Umum , pilih +Tambahkan Tabel. Dialog Tabel Baru meluncur 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 memerlukan string koneksi tabel untuk akun Cosmos DB Storage. 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 bawah header Pengaturan dan pilih. Anda akan dibawa ke halaman tempat Anda dapat mengambil string koneksi untuk akun Azure Cosmos DB. | 
|
| Salin nilai STRING KONEKSI UTAMA untuk digunakan dalam aplikasi Anda. | 
|
4 - Menginstal Azure Data Tables SDK untuk Python
Setelah Anda membuat akun Azure Cosmos DB, langkah Anda selanjutnya adalah menginstal Microsoft Azure Data Tables SDK untuk Python. Untuk detail tentang memasang SDK, lihat file README.md di SDK Data Table untuk repositori Python di GitHub.
Instal pustaka klien Azure Tables untuk Python dengan pip:
pip install azure-data-tables
Jangan lupa juga untuk menginstal requirements.txt di folder 1-starter-app atau 2-completed-app .
5 - Mengonfigurasi klien Tabel dalam file .env
Salin string koneksi akun Azure Cosmos DB dari portal Microsoft Azure, dan buat objek TableServiceClient menggunakan string koneksi yang Anda salin. Beralih ke folder 1-starter-app atau 2-completed-app . Terlepas dari aplikasi mana yang Anda mulai, Anda perlu menentukan variabel lingkungan dalam .env file.
# Configuration Parameters
conn_str = "A connection string to an Azure Cosmos DB account."
table_name = "WeatherData"
project_root_path = "Project abs path"
Azure SDK berkomunikasi dengan Azure menggunakan objek klien untuk menjalankan operasi yang berbeda terhadap Azure. Objek TableServiceClient adalah objek yang digunakan untuk berkomunikasi dengan Azure Cosmos DB for Table. Aplikasi biasanya akan memiliki satu TableServiceClient secara keseluruhan, dan akan memiliki TableClient per tabel.
Misalnya, kode berikut membuat TableServiceClient objek menggunakan string koneksi dari variabel lingkungan.
self.conn_str = os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)
6 - Menerapkan operasi tabel Azure Cosmos DB
Semua operasi tabel Azure Cosmos DB untuk aplikasi sampel diimplementasikan di TableServiceHelper kelas yang terletak di file pembantu di bawah direktori webapp . Anda harus mengimpor TableServiceClient kelas di bagian atas file ini untuk bekerja dengan objek di pustaka klien azure.data.tables untuk Python.
from azure.data.tables import TableServiceClient
Pada awal kelas TableServiceHelper, buat konstruktor dan tambahkan variabel anggota untuk objek TableClient untuk memungkinkan objek TableClient dimasukkan ke dalam kelas.
def __init__(self, table_name=None, conn_str=None):
self.table_name = table_name if table_name else os.getenv("table_name")
self.conn_str = conn_str if conn_str else os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)
self.table_client = self.table_service.get_table_client(self.table_name)
Memfilter baris yang dikembalikan dari tabel
Untuk memfilter baris yang dikembalikan dari tabel, Anda bisa meneruskan string filter gaya OData ke metode query_entities. 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 AM' and RowKey le '2021-07-02 12:00 AM'
Anda dapat melihat operator filter OData terkait di situs web azure-data-tables di bagian Filter Penulisan.
Saat parameter request.args diteruskan ke metode query_entity di kelas TableServiceHelper, 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 query_entities metode pada TableClient objek dan hanya baris yang cocok dengan string filter yang dikembalikan. Anda dapat menggunakan metode serupa dalam kode Anda untuk membangun string filter yang sesuai seperti yang dipersyaratkan oleh aplikasi Anda.
def query_entity(self, params):
filters = []
if params.get("partitionKey"):
filters.append("PartitionKey eq '{}'".format(params.get("partitionKey")))
if params.get("rowKeyDateStart") and params.get("rowKeyTimeStart"):
filters.append("RowKey ge '{} {}'".format(params.get("rowKeyDateStart"), params.get("rowKeyTimeStart")))
if params.get("rowKeyDateEnd") and params.get("rowKeyTimeEnd"):
filters.append("RowKey le '{} {}'".format(params.get("rowKeyDateEnd"), params.get("rowKeyTimeEnd")))
if params.get("minTemperature"):
filters.append("Temperature ge {}".format(params.get("minTemperature")))
if params.get("maxTemperature"):
filters.append("Temperature le {}".format(params.get("maxTemperature")))
if params.get("minPrecipitation"):
filters.append("Precipitation ge {}".format(params.get("minPrecipitation")))
if params.get("maxPrecipitation"):
filters.append("Precipitation le {}".format(params.get("maxPrecipitation")))
return list(self.table_client.query_entities(" and ".join(filters)))
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 mewakili nama stasiun cuaca dan tanggal/waktu pengamatan masing-masing dipetakan ke PartitionKey properti 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 create_entity pada objek TableClient digunakan untuk memasukkan data ke dalam tabel.
Ubah fungsi insert_entity dalam aplikasi contoh agar mencakup kode berikut.
def insert_entity(self):
entity = self.deserialize()
return self.table_client.create_entity(entity)
@staticmethod
def deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
return params
Melakukan upsert data menggunakan objek TableEntity
Jika Anda mencoba menyisipkan baris ke dalam tabel dengan kombinasi kunci partisi/kunci baris yang sudah ada dalam tabel tersebut, Anda akan menerima kesalahan. Untuk alasan ini, sering lebih disukai untuk menggunakan upsert_entity alih-alih create_entity metode saat menambahkan baris ke tabel. Jika kombinasi kunci partisi/kunci baris yang diberikan sudah ada dalam tabel, metode memperbarui upsert_entity baris yang ada. Jika tidak, baris ditambahkan ke tabel.
def upsert_entity(self):
entity = self.deserialize()
return self.table_client.upsert_entity(entity)
@staticmethod
def deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
return params
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 sampel, kita dapat mensimulasikan stasiun cuaca yang mengirim tidak hanya data cuaca dasar tetapi juga beberapa nilai tambahan. Saat objek dengan properti baru ini disimpan dalam tabel untuk pertama kalinya, properti (kolom) terkait secara otomatis ditambahkan ke tabel.
Untuk menyisipkan atau melakukan upsert objek tersebut menggunakan API untuk Tabel, petakan properti objek yang dapat diperluas ke dalam TableEntity objek dan gunakan create_entity metode atau upsert_entity pada TableClient objek yang sesuai.
Dalam contoh aplikasi, fungsi upsert_entity juga dapat mengimplementasikan fungsi menyisipkan atau menambahkan data dengan properti variabel
def insert_entity(self):
entity = self.deserialize()
return self.table_client.create_entity(entity)
def upsert_entity(self):
entity = self.deserialize()
return self.table_client.upsert_entity(entity)
@staticmethod
def deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
return params
Memperbarui entitas
Entitas dapat diperbarui dengan memanggil metode update_entity pada objek TableClient.
Dalam aplikasi contoh, objek ini diteruskan ke metode upsert_entity di kelas TableClient. Metode ini kemudian memperbarui objek entitas itu dan menggunakan metode upsert_entity untuk menyimpan pembaruan ke database.
def update_entity(self):
entity = self.update_deserialize()
return self.table_client.update_entity(entity)
@staticmethod
def update_deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = params.pop("ObservationDate")
return params
Menghapus entitas
Untuk menghapus entitas dari tabel, panggil metode delete_entity pada objek TableClient dengan kunci partisi dan kunci baris objek.
def delete_entity(self):
partition_key = request.form.get("StationName")
row_key = request.form.get("ObservationDate")
return self.table_client.delete_entity(partition_key, row_key)
7 - Menjalankan kode
Jalankan aplikasi sampel untuk berinteraksi dengan Azure Cosmos DB for Table. Misalnya, mulai dari folder 2-completed-app , dengan persyaratan terinstal, Anda dapat menggunakan:
python3 run.py webapp
Lihat file README.md di akar repositori sampel untuk informasi selengkapnya tentang menjalankan aplikasi sampel.
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.
Untuk folder sampel 1-starter-app , Anda harus setidaknya menyelesaikan kode untuk
submit_transactionfungsi agar penyisipan data sampel berfungsi.Data sampel dimuat dari file sample_data.json . Variabel .env
project_root_pathmemberi tahu aplikasi tempat menemukan file ini. Misalnya, jika Anda menjalankan aplikasi dari folder 1-starter-app atau 2-completed-app , aturproject_root_pathke "" (kosong).
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 menghapus semua sumber daya 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.