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

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.

  1. Di jendela konsol (seperti PowerShell atau Bash), buat direktori baru untuk proyek:

    mkdir blob-quickstart
    
  2. 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:

  1. Buka file teks baru di editor kode Anda.
  2. Tambahkan import pernyataan, buat struktur untuk program, dan sertakan penanganan pengecualian dasar, seperti yang ditunjukkan di bawah ini.
  3. 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 oleh azd 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:

Diagram of Blob storage architecture

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:

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.

  1. Di portal Azure, temukan akun penyimpanan Anda menggunakan bilah pencarian utama atau navigasi kiri.

  2. Di halaman gambaran umum akun penyimpanan, pilih Kontrol akses (IAM) dari menu kiri.

  3. Di halaman Kontrol akses (IAM), pilih tab Penetapan peran.

  4. Pilih + Tambahkan dari menu atas lalu Tambahkan penetapan peran dari menu drop-down yang dihasilkan.

    A screenshot showing how to assign a role.

  5. 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.

  6. Di bagian Tetapkan akses ke, pilih Pengguna, grup, atau perwakilan layanan, lalu pilih + Pilih anggota.

  7. Dalam dialog, cari nama pengguna Microsoft Entra Anda (biasanya alamat email user@domain Anda) lalu pilih Pilih di bagian bawah dialog.

  8. 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:

  1. 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
    
  2. Untuk menggunakan DefaultAzureCredential, pastikan bahwa paket identitas azure diinstal, dan kelas diimpor:

    from azure.identity import DefaultAzureCredential
    from azure.storage.blob import BlobServiceClient
    
  3. 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)
    
  4. Pastikan untuk memperbarui nama akun penyimpanan di URI objek Anda BlobServiceClient . Nama akun penyimpanan dapat ditemukan di halaman gambaran umum portal Azure.

    A screenshot showing how to find the storage account name.

    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: