Mulai cepat: Pustaka klien Azure Blob Storage untuk Python
Catatan
Opsi Build from scratch memandu Anda selangkah demi selangkah melalui proses pembuatan proyek baru, menginstal paket, menulis kode, dan menjalankan aplikasi konsol dasar. Pendekatan ini direkomendasikan jika Anda ingin memahami semua detail yang terlibat dalam membuat aplikasi yang terhubung ke Azure Blob Storage. Jika Anda lebih suka mengotomatiskan tugas penyebaran dan memulai dengan proyek yang telah selesai, pilih Mulai dengan templat.
Catatan
Opsi Mulai dengan templat menggunakan Azure Developer CLI untuk mengotomatiskan tugas penyebaran dan memulai Anda dengan proyek yang telah selesai. Pendekatan ini direkomendasikan jika Anda ingin menjelajahi kode secepat mungkin tanpa melalui tugas penyiapan. Jika Anda lebih suka instruksi langkah demi langkah untuk membangun aplikasi, pilih Bangun dari awal.
Mulai menggunakan pustaka klien Azure Blob Storage untuk Python untuk mengelola blob dan kontainer.
Dalam artikel ini, Anda mengikuti langkah-langkah untuk menginstal paket dan mencoba contoh kode untuk tugas dasar.
Dalam artikel ini, Anda menggunakan Azure Developer CLI untuk menyebarkan sumber daya Azure dan menjalankan aplikasi konsol lengkap hanya dengan beberapa perintah.
Dokumentasi | referensi API Paket kode | sumber pustaka (PyPi)Sampel |
Video ini menunjukkan kepada Anda cara mulai menggunakan pustaka klien Azure Blob Storage untuk Python.
Langkah-langkah dalam video juga dijelaskan di bagian berikut.
Prasyarat
- Akun Azure dengan langganan aktif - buat akun secara gratis
- Akun Azure Storage - buat akun penyimpanan
- Python 3.8+
- Langganan Azure - buat akun secara gratis
- Python 3.8+
- Azure Developer CLI
Menyiapkan
Bagian ini memandu Anda menyiapkan proyek untuk bekerja dengan pustaka klien Azure Blob Storage untuk Python.
Membuat proyek
Buat aplikasi Python bernama blob-quickstart.
Di jendela konsol (seperti PowerShell atau Bash), buat direktori baru untuk proyek:
mkdir blob-quickstart
Beralih ke direktori blob-quickstart yang baru dibuat:
cd blob-quickstart
Menginstal paket
Dari direktori proyek, instal paket untuk pustaka klien Azure Blob Storage dan Azure Identity menggunakan pip install
perintah . Paket identitas azure diperlukan untuk koneksi tanpa kata sandi ke layanan Azure.
pip install azure-storage-blob azure-identity
Menyiapkan kerangka kerja aplikasi
Dari direktori proyek, ikuti langkah-langkah untuk membuat struktur dasar aplikasi:
- Buka file teks baru di editor kode Anda.
- Tambahkan
import
pernyataan, buat struktur untuk program, dan sertakan penanganan pengecualian dasar, seperti yang ditunjukkan di bawah ini. - Simpan file baru sebagai blob_quickstart.py di direktori blob-quickstart .
import os, uuid
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobClient, ContainerClient
try:
print("Azure Blob Storage Python quickstart sample")
# Quickstart code goes here
except Exception as ex:
print('Exception:')
print(ex)
Dengan Azure Developer CLI terinstal, Anda dapat membuat akun penyimpanan dan menjalankan kode sampel hanya dengan beberapa perintah. Anda dapat menjalankan proyek di lingkungan pengembangan lokal Anda, atau di DevContainer.
Menginisialisasi templat Azure Developer CLI dan menyebarkan sumber daya
Dari direktori kosong, ikuti langkah-langkah ini untuk menginisialisasi azd
templat, memprovisikan sumber daya Azure, dan mulai menggunakan kode:
Kloning aset repositori mulai cepat dari GitHub dan inisialisasi templat secara lokal:
azd init --template blob-storage-quickstart-python
Anda akan dimintai informasi berikut:
- Nama lingkungan: Nilai ini digunakan sebagai awalan untuk semua sumber daya Azure yang dibuat oleh Azure Developer CLI. Nama harus unik di semua langganan Azure dan panjangnya harus antara 3 dan 24 karakter. Nama hanya dapat berisi angka dan huruf kecil.
Masuk ke Azure:
azd auth login
Provisikan dan sebarkan sumber daya ke Azure:
azd up
Anda akan dimintai informasi berikut:
- Langganan: Langganan Azure tempat sumber daya Anda disebarkan.
- Lokasi: Wilayah Azure tempat sumber daya Anda disebarkan.
Penyebaran mungkin perlu waktu beberapa menit untuk diselesaikan. Output dari
azd up
perintah mencakup nama akun penyimpanan yang baru dibuat, yang akan Anda perlukan nanti untuk menjalankan kode.
Jalankan kode sampel
Pada titik ini, sumber daya disebarkan ke Azure dan kode hampir siap untuk dijalankan. Ikuti langkah-langkah ini untuk menginstal paket, memperbarui nama akun penyimpanan dalam kode, dan menjalankan aplikasi konsol sampel:
- Instal paket: Di direktori lokal, instal paket untuk pustaka klien Azure Blob Storage dan Azure Identity menggunakan perintah berikut:
pip install azure-storage-blob azure-identity
- Perbarui nama akun penyimpanan: Di direktori lokal, edit file bernama blob_quickstart.py.
<storage-account-name>
Temukan tempat penampung dan ganti dengan nama aktual akun penyimpanan yang dibuat olehazd up
perintah . Simpan perubahan. - Jalankan proyek: Jalankan perintah berikut untuk menjalankan aplikasi:
python blob_quickstart.py
. - Amati output: Aplikasi ini membuat file pengujian di folder data lokal Anda dan mengunggahnya ke kontainer di akun penyimpanan. Contoh kemudian mencantumkan blob dalam kontainer dan mengunduh file dengan nama baru sehingga Anda dapat membandingkan file lama dan baru.
Untuk mempelajari selengkapnya tentang cara kerja kode sampel, lihat Contoh kode.
Setelah selesai menguji kode, lihat bagian Bersihkan sumber daya untuk menghapus sumber daya yang azd up
dibuat oleh perintah .
Model objek
Azure Blob Storage dioptimalkan untuk menyimpan data tidak terstruktur dalam jumlah besar. Data tidak terstruktur adalah data yang tidak mematuhi model atau definisi data tertentu, seperti data teks atau biner. Penyimpanan Blob menawarkan tiga jenis sumber daya:
- Akun penyimpanan
- Kontainer di akun penyimpanan
- Blob di dalam kontainer
Diagram berikut menunjukkan hubungan antara sumber daya ini:
Gunakan kelas Python berikut untuk berinteraksi dengan sumber daya ini:
- BlobServiceClient: Kelas
BlobServiceClient
memungkinkan Anda memanipulasi sumber daya Microsoft Azure Storage dan kontainer blob. - ContainerClient:
ContainerClient
Kelas ini memungkinkan Anda memanipulasi kontainer Azure Storage dan blobnya. - BlobClient: Kelas
BlobClient
ini memungkinkan Anda memanipulasi blob Azure Storage.
Contoh kode
Contoh cuplikan kode ini menunjukkan cara melakukan tugas berikut dengan pustaka klien Azure Blob Storage untuk Python:
- Mengautentikasi ke Azure dan mengotorisasi akses ke data blob
- Membuat kontainer
- Unggah blob ke kontainer
- Cantumkan blob di kontainer
- Unduh blob
- Menghapus kontainer
Catatan
Templat Azure Developer CLI menyertakan file dengan kode sampel yang sudah ada. Contoh berikut memberikan detail untuk setiap bagian kode sampel. Templat mengimplementasikan metode autentikasi tanpa kata sandi yang direkomendasikan, seperti yang dijelaskan di bagian Autentikasi ke Azure . Metode string koneksi ditampilkan sebagai alternatif, tetapi tidak digunakan dalam templat dan tidak disarankan untuk kode produksi.
Mengautentikasi ke Azure dan mengotorisasi akses ke data blob
Permintaan aplikasi ke Azure Blob Storage harus diotorisasi. Menggunakan kelas yang DefaultAzureCredential
disediakan oleh pustaka klien Azure Identity adalah pendekatan yang direkomendasikan untuk menerapkan koneksi tanpa kata sandi ke layanan Azure dalam kode Anda, termasuk Blob Storage.
Anda juga dapat mengotorisasi permintaan untuk Azure Blob Storage menggunakan kunci akses akun. Namun, pendekatan ini harus digunakan dengan hati-hati. Pengembang harus rajin untuk tidak pernah mengekspos kunci akses di lokasi yang tidak aman. Siapa pun yang memiliki kunci akses dapat mengotorisasi permintaan terhadap akun penyimpanan, dan secara efektif memiliki akses ke semua data. DefaultAzureCredential
menawarkan keuntungan pengelolaan dan keamanan yang ditingkatkan melalui kunci akun untuk memungkinkan autentikasi tanpa kata sandi. Kedua opsi diperlihatkan dalam contoh berikut.
DefaultAzureCredential
mendukung beberapa metode autentikasi dan menentukan metode autentikasi yang harus digunakan saat runtime bahasa umum. Pendekatan ini memungkinkan aplikasi Anda menggunakan metode autentikasi yang berbeda di lingkungan yang berbeda (lokal vs. produksi) tanpa menerapkan kode spesifik per lingkungan.
Urutan dan lokasi tempat DefaultAzureCredential
mencari kredensial dapat ditemukan di ringkasan pustaka Azure Identity.
Misalnya, aplikasi Anda dapat mengautentikasi menggunakan info masuk Azure CLI Anda saat mengembangkan secara lokal. Aplikasi Anda kemudian dapat menggunakan identitas terkelola setelah disebarkan ke Azure. Tidak diperlukan perubahan kode untuk transisi ini.
Menetapkan peran ke akun pengguna Microsoft Entra Anda
Saat mengembangkan secara lokal, pastikan bahwa akun pengguna yang mengakses data blob memiliki izin yang benar. Anda akan memerlukan Kontributor Data Blob Penyimpanan untuk membaca dan menulis data blob. Untuk menetapkan sendiri peran ini, Anda harus diberi peran Administrator Akses Pengguna, atau peran lain yang menyertakan tindakan Microsoft.Authorization/roleAssignments/write . Anda dapat menetapkan peran Azure RBAC kepada pengguna menggunakan portal Azure, Azure CLI, atau Azure PowerShell. Anda dapat mempelajari selengkapnya tentang cakupan yang tersedia untuk penetapan peran di halaman gambaran umum cakupan.
Dalam skenario ini, Anda akan menetapkan izin ke akun pengguna, yang tercakup ke akun penyimpanan, untuk mengikuti Prinsip Hak Istimewa Paling Rendah. Praktik ini hanya memberi pengguna izin minimum yang diperlukan dan menciptakan lingkungan produksi yang lebih aman.
Contoh berikut akan menetapkan peran Kontributor Data Blob Penyimpanan ke akun pengguna Anda, yang menyediakan akses baca dan tulis ke data blob di akun penyimpanan Anda.
Penting
Dalam kebanyakan kasus, dibutuhkan satu atau dua menit agar penetapan peran disebarluaskan di Azure, tetapi dalam kasus yang jarang terjadi mungkin perlu waktu hingga delapan menit. Jika Anda menerima kesalahan autentikasi saat pertama kali menjalankan kode, tunggu beberapa saat dan coba lagi.
Di portal Azure, temukan akun penyimpanan Anda menggunakan bilah pencarian utama atau navigasi kiri.
Di halaman gambaran umum akun penyimpanan, pilih Kontrol akses (IAM) dari menu kiri.
Di halaman Kontrol akses (IAM), pilih tab Penetapan peran.
Pilih + Tambahkan dari menu atas lalu Tambahkan penetapan peran dari menu drop-down yang dihasilkan.
Gunakan kotak pencarian untuk memfilter hasil ke peran yang diinginkan. Untuk contoh ini, cari Kontributor Data Blob Penyimpanan dan pilih hasil yang cocok, lalu pilih Berikutnya.
Di bagian Tetapkan akses ke, pilih Pengguna, grup, atau perwakilan layanan, lalu pilih + Pilih anggota.
Dalam dialog, cari nama pengguna Microsoft Entra Anda (biasanya alamat email user@domain Anda) lalu pilih Pilih di bagian bawah dialog.
Pilih Tinjau + tetapkan untuk masuk ke halaman akhir, lalu Tinjau + tetapkan lagi untuk menyelesaikan proses.
Masuk dan sambungkan kode aplikasi Anda ke Azure menggunakan DefaultAzureCredential
Anda dapat mengotorisasi akses ke data di akun penyimpanan Anda menggunakan langkah-langkah berikut:
Pastikan Anda diautentikasi dengan akun Microsoft Entra yang sama dengan yang Anda tetapkan perannya di akun penyimpanan Anda. Anda dapat mengautentikasi melalui Azure CLI, Visual Studio Code, atau Azure PowerShell.
Masuk ke Azure melalui Azure CLI menggunakan perintah berikut:
az login
Untuk menggunakan
DefaultAzureCredential
, pastikan bahwa paket identitas azure diinstal, dan kelas diimpor:from azure.identity import DefaultAzureCredential from azure.storage.blob import BlobServiceClient
Tambahkan kode ini di
try
dalam blok. Saat kode berjalan di stasiun kerja lokal Anda,DefaultAzureCredential
menggunakan kredensial pengembang alat yang diprioritaskan yang Anda masuki untuk mengautentikasi ke Azure. Contoh alat ini termasuk Azure CLI atau Visual Studio Code.account_url = "https://<storageaccountname>.blob.core.windows.net" default_credential = DefaultAzureCredential() # Create the BlobServiceClient object blob_service_client = BlobServiceClient(account_url, credential=default_credential)
Pastikan untuk memperbarui nama akun penyimpanan di URI objek Anda
BlobServiceClient
. Nama akun penyimpanan dapat ditemukan di halaman gambaran umum portal Azure.Catatan
Saat disebarkan ke Azure, kode yang sama ini dapat digunakan untuk mengotorisasi permintaan ke Azure Storage dari aplikasi yang berjalan di Azure. Namun, Anda harus mengaktifkan identitas terkelola di aplikasi Anda di Azure. Kemudian konfigurasikan akun penyimpanan Anda untuk memungkinkan identitas terkelola tersebut tersambung. Untuk petunjuk detail tentang mengonfigurasi koneksi ini antara layanan Azure, lihat tutorial Auth dari aplikasi yang dihosting Azure.
Membuat kontainer
Buat kontainer baru di akun penyimpanan Anda dengan memanggil metode create_container pada blob_service_client
objek. Dalam contoh ini, kode menambahkan nilai GUID ke nama kontainer untuk memastikan bahwa kode tersebut unik.
Tambahkan kode ini ke akhir blok try
:
# Create a unique name for the container
container_name = str(uuid.uuid4())
# Create the container
container_client = blob_service_client.create_container(container_name)
Untuk mempelajari selengkapnya tentang membuat kontainer, dan untuk menjelajahi lebih banyak sampel kode, lihat Membuat kontainer blob dengan Python.
Penting
Nama kontainer harus menggunakan huruf kecil. Untuk informasi selengkapnya tentang penamaan kontainer dan blob, lihat Menamai dan Mereferensikan Kontainer, Blob, dan Metadata.
Unggah blob ke kontainer
Unggah blob ke kontainer menggunakan upload_blob. Kode contoh membuat file teks di direktori data lokal untuk diunggah ke kontainer.
Tambahkan kode ini ke akhir blok try
:
# Create a local directory to hold blob data
local_path = "./data"
os.mkdir(local_path)
# Create a file in the local data directory to upload and download
local_file_name = str(uuid.uuid4()) + ".txt"
upload_file_path = os.path.join(local_path, local_file_name)
# Write text to the file
file = open(file=upload_file_path, mode='w')
file.write("Hello, World!")
file.close()
# Create a blob client using the local file name as the name for the blob
blob_client = blob_service_client.get_blob_client(container=container_name, blob=local_file_name)
print("\nUploading to Azure Storage as blob:\n\t" + local_file_name)
# Upload the created file
with open(file=upload_file_path, mode="rb") as data:
blob_client.upload_blob(data)
Untuk mempelajari selengkapnya tentang mengunggah blob, dan untuk menjelajahi sampel kode lainnya, lihat Mengunggah blob dengan Python.
Cantumkan blob di kontainer
Cantumkan blob di kontainer dengan memanggil metode list_blobs. Dalam kasus ini, hanya satu blob yang telah ditambahkan ke kontainer, sehingga operasi pencantuman hanya mengembalikan satu blob itu.
Tambahkan kode ini ke akhir blok try
:
print("\nListing blobs...")
# List the blobs in the container
blob_list = container_client.list_blobs()
for blob in blob_list:
print("\t" + blob.name)
Untuk mempelajari selengkapnya tentang mencantumkan blob, dan untuk menjelajahi sampel kode lainnya, lihat Mencantumkan blob dengan Python.
Unduh blob
Unduh blob yang dibuat sebelumnya dengan memanggil metode download_blob. Kode contoh menambahkan akhiran "DOWNLOAD" ke nama file sehingga Anda dapat melihat kedua file dalam sistem file lokal.
Tambahkan kode ini ke akhir blok try
:
# Download the blob to a local file
# Add 'DOWNLOAD' before the .txt extension so you can see both files in the data directory
download_file_path = os.path.join(local_path, str.replace(local_file_name ,'.txt', 'DOWNLOAD.txt'))
container_client = blob_service_client.get_container_client(container= container_name)
print("\nDownloading blob to \n\t" + download_file_path)
with open(file=download_file_path, mode="wb") as download_file:
download_file.write(container_client.download_blob(blob.name).readall())
Untuk mempelajari selengkapnya tentang mengunduh blob, dan untuk menjelajahi lebih banyak sampel kode, lihat Mengunduh blob dengan Python.
Menghapus kontainer
Kode berikut membersihkan sumber daya yang dibuat aplikasi dengan menghapus seluruh kontainer menggunakan metode delete_container. Anda juga dapat menghapus file lokal, jika mau.
Aplikasi berhenti sejenak untuk input pengguna dengan memanggil input()
sebelum menghapus blob, kontainer, dan file lokal. Verifikasi bahwa sumber daya dibuat dengan benar sebelum dihapus.
Tambahkan kode ini ke akhir blok try
:
# Clean up
print("\nPress the Enter key to begin clean up")
input()
print("Deleting blob container...")
container_client.delete_container()
print("Deleting the local source and downloaded files...")
os.remove(upload_file_path)
os.remove(download_file_path)
os.rmdir(local_path)
print("Done")
Untuk mempelajari selengkapnya tentang menghapus kontainer, dan untuk menjelajahi sampel kode lainnya, lihat Menghapus dan memulihkan kontainer blob dengan Python.
Menjalankan kode
Aplikasi ini membuat file uji di folder lokal Anda dan mengunggahnya ke Azure Blob Storage. Contoh tersebut kemudian mencantumkan blob di dalam kontainer, dan mengunduh file dengan nama baru. Anda dapat membandingkan file lama dan baru.
Navigasi ke direktori yang berisi file blob_quickstart.py , lalu jalankan perintah berikut python
untuk menjalankan aplikasi:
python blob_quickstart.py
Output aplikasi mirip dengan contoh berikut (nilai UUID yang dihilangkan untuk keterbacaan):
Azure Blob Storage Python quickstart sample
Uploading to Azure Storage as blob:
quickstartUUID.txt
Listing blobs...
quickstartUUID.txt
Downloading blob to
./data/quickstartUUIDDOWNLOAD.txt
Press the Enter key to begin clean up
Deleting blob container...
Deleting the local source and downloaded files...
Done
Sebelum memulai proses pembersihan, periksa folder data Anda untuk kedua file tersebut. Anda dapat membandingkannya dan mengamati bahwa mereka identik.
Membersihkan sumber daya
Setelah Anda memverifikasi file dan selesai menguji, tekan tombol Enter untuk menghapus file pengujian bersama dengan kontainer yang Anda buat di akun penyimpanan. Anda juga dapat menggunakan Azure CLI untuk menghapus sumber daya.
Setelah selesai dengan mulai cepat, Anda dapat membersihkan sumber daya yang Anda buat dengan menjalankan perintah berikut:
azd down
Anda akan diminta untuk mengonfirmasi penghapusan sumber daya. Masukkan y
untuk mengonfirmasi.
Langkah berikutnya
Di mulai cepat ini, Anda belajar cara mengunggah, mengunduh, dan mencantumkan blob menggunakan Python.
Untuk melihat aplikasi sampel penyimpanan Blob, lanjutkan ke:
- Untuk mempelajari selengkapnya, lihat pustaka klien Azure Blob Storage untuk Python.
- Untuk tutorial, sampel, mulai cepat, dan dokumentasi lainnya, kunjungi Azure untuk Pengembang Python.