Mengunggah blob blok dengan Python

Artikel
11/16/2023

Artikel ini memperlihatkan cara mengunggah blob menggunakan pustaka klien Azure Storage untuk Python. Anda dapat mengunggah data ke blob blok dari jalur file, aliran, objek biner, atau string teks. Anda juga dapat mengunggah blob dengan tag indeks.

Untuk mempelajari tentang mengunggah blob menggunakan API asinkron, lihat Mengunggah blob secara asinkron.

Prasyarat

Artikel ini mengasumsikan Anda sudah menyiapkan proyek untuk bekerja dengan pustaka klien Azure Blob Storage untuk Python. Untuk mempelajari tentang menyiapkan proyek Anda, termasuk penginstalan paket, menambahkan import pernyataan, dan membuat objek klien resmi, lihat Mulai menggunakan Azure Blob Storage dan Python.
Untuk menggunakan API asinkron dalam kode Anda, lihat persyaratan di bagian Pemrograman asinkron.
Mekanisme otorisasi harus memiliki izin untuk melakukan operasi unggahan. Untuk mempelajari lebih lanjut, lihat panduan otorisasi untuk operasi REST API berikut:
- Put Blob
- Masukkan Blok

Mengunggah data ke blob blok

Untuk mengunggah blob menggunakan aliran atau objek biner, gunakan metode berikut:

upload_blob

Metode ini membuat blob baru dari sumber data dengan potongan otomatis, yang berarti bahwa sumber data dapat dibagi menjadi potongan yang lebih kecil dan diunggah. Untuk melakukan unggahan, pustaka klien dapat menggunakan Put Blob atau serangkaian panggilan Put Block diikuti oleh Put Block List. Perilaku ini tergantung pada ukuran keseluruhan objek dan bagaimana opsi transfer data diatur.

Mengunggah blob blok dari jalur file lokal

Contoh berikut mengunggah file ke blob blok menggunakan BlobClient objek:

def upload_blob_file(self, blob_service_client: BlobServiceClient, container_name: str):
    container_client = blob_service_client.get_container_client(container=container_name)
    with open(file=os.path.join('filepath', 'filename'), mode="rb") as data:
        blob_client = container_client.upload_blob(name="sample-blob.txt", data=data, overwrite=True)

Mengunggah blob blok dari aliran

Contoh berikut membuat byte data acak dan mengunggah BytesIO objek ke blob blok menggunakan BlobClient objek:

def upload_blob_stream(self, blob_service_client: BlobServiceClient, container_name: str):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    input_stream = io.BytesIO(os.urandom(15))
    blob_client.upload_blob(input_stream, blob_type="BlockBlob")

Mengunggah data biner ke blob blok

Contoh berikut mengunggah data biner ke blob blok menggunakan BlobClient objek:

def upload_blob_data(self, blob_service_client: BlobServiceClient, container_name: str):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    data = b"Sample data for blob"

    # Upload the blob data - default blob type is BlockBlob
    blob_client.upload_blob(data, blob_type="BlockBlob")

Mengunggah blob blok dengan tag indeks

Contoh berikut mengunggah blob blok dengan tag indeks:

def upload_blob_tags(self, blob_service_client: BlobServiceClient, container_name: str):
    container_client = blob_service_client.get_container_client(container=container_name)
    sample_tags = {"Content": "image", "Date": "2022-01-01"}
    with open(file=os.path.join('filepath', 'filename'), mode="rb") as data:
        blob_client = container_client.upload_blob(name="sample-blob.txt", data=data, tags=sample_tags)

Mengunggah blob blok dengan opsi konfigurasi

Anda dapat menentukan opsi konfigurasi pustaka klien saat mengunggah blob. Opsi ini dapat disetel untuk meningkatkan performa, meningkatkan keandalan, dan mengoptimalkan biaya. Contoh kode berikut menunjukkan cara menentukan opsi konfigurasi untuk unggahan baik di tingkat metode, maupun di tingkat klien saat membuat instans BlobClient. Opsi ini juga dapat dikonfigurasi untuk instans ContainerClient atau instans BlobServiceClient .

Tentukan opsi transfer data untuk diunggah

Anda dapat mengatur opsi konfigurasi saat membuat instans klien untuk mengoptimalkan performa operasi transfer data. Anda dapat meneruskan argumen kata kunci berikut saat membuat objek klien di Python:

max_block_size - Ukuran gugus maksimum untuk mengunggah blob blok dalam gugus. Default ke 4 MiB.
max_single_put_size - Jika ukuran blob kurang dari atau sama dengan max_single_put_size, blob diunggah dengan satu Put Blob permintaan. Jika ukuran blob lebih besar dari max_single_put_size atau tidak diketahui, blob diunggah dalam gugus menggunakan Put Block dan diterapkan menggunakan Put Block List. Default ke 64 MiB.

Untuk informasi selengkapnya tentang batas ukuran transfer untuk Blob Storage, lihat Menskalakan target untuk penyimpanan Blob.

Untuk operasi pengunggahan, Anda juga dapat meneruskan max_concurrency argumen saat memanggil upload_blob. Argumen ini menentukan jumlah maksimum koneksi paralel yang akan digunakan ketika ukuran blob melebihi 64 MiB.

Contoh kode berikut menunjukkan cara menentukan opsi transfer data saat membuat BlobClient objek, dan cara mengunggah data menggunakan objek klien tersebut. Nilai yang disediakan dalam sampel ini tidak dimaksudkan untuk menjadi rekomendasi. Untuk menyetel nilai-nilai ini dengan benar, Anda perlu mempertimbangkan kebutuhan spesifik aplikasi Anda.

def upload_blob_transfer_options(self, account_url: str, container_name: str, blob_name: str):
    # Create a BlobClient object with data transfer options for upload
    blob_client = BlobClient(
        account_url=account_url, 
        container_name=container_name, 
        blob_name=blob_name,
        credential=DefaultAzureCredential(),
        max_block_size=1024*1024*4, # 4 MiB
        max_single_put_size=1024*1024*8 # 8 MiB
    )
    
    with open(file=os.path.join(r'file_path', blob_name), mode="rb") as data:
        blob_client = blob_client.upload_blob(data=data, overwrite=True, max_concurrency=2)

Untuk mempelajari selengkapnya tentang menyetel opsi transfer data, lihat Penyetelan performa untuk unggahan dan unduhan dengan Python.

Mengatur tingkat akses blob saat diunggah

Anda dapat mengatur tingkat akses blob saat diunggah dengan meneruskan standard_blob_tier argumen kata kunci ke upload_blob. Azure Storage menawarkan tingkat akses yang berbeda sehingga Anda dapat menyimpan data blob anda dengan cara yang paling hemat biaya berdasarkan cara penggunaannya.

Contoh kode berikut menunjukkan cara mengatur tingkat akses saat mengunggah blob:

def upload_blob_access_tier(self, blob_service_client: BlobServiceClient, container_name: str, blob_name: str):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob=blob_name)
    
    #Upload blob to the cool tier
    with open(file=os.path.join(r'file_path', blob_name), mode="rb") as data:
        blob_client = blob_client.upload_blob(data=data, overwrite=True, standard_blob_tier=StandardBlobTier.COOL)

Mengatur tingkat akses hanya diperbolehkan untuk blob blok. Anda dapat mengatur tingkat akses untuk blob blok ke Hot, , CoolCold, atau Archive. Untuk mengatur tingkat akses ke Cold, Anda harus menggunakan versi pustaka klien minimum 12.15.0.

Untuk mempelajari selengkapnya tentang tingkat akses, lihat Gambaran umum tingkat akses.

Unggah blob blok dengan blok penahapan dan penerapan

Anda dapat memiliki kontrol yang lebih besar atas cara membagi unggahan menjadi blok dengan melakukan penahapan data secara manual. Ketika semua blok yang membentuk blob disiapkan, Anda dapat memasukkannya ke Blob Storage.

Gunakan metode berikut untuk membuat blok baru yang akan diterapkan sebagai bagian dari blob:

stage_block

Gunakan metode berikut untuk menulis blob dengan menentukan daftar ID blok yang membentuk blob:

commit_block_list

Contoh berikut membaca data dari blok file dan tahapan yang akan diterapkan sebagai bagian dari blob:

def upload_blocks(self, blob_container_client: ContainerClient, local_file_path: str, block_size: int):
    file_name = os.path.basename(local_file_path)
    blob_client = blob_container_client.get_blob_client(file_name)

    with open(file=local_file_path, mode="rb") as file_stream:
        block_id_list = []

        while True:
            buffer = file_stream.read(block_size)
            if not buffer:
                break

            block_id = uuid.uuid4().hex
            block_id_list.append(BlobBlock(block_id=block_id))

            blob_client.stage_block(block_id=block_id, data=buffer, length=len(buffer))

        blob_client.commit_block_list(block_id_list)

Mengunggah blob secara asinkron

Pustaka klien Azure Blob Storage untuk Python mendukung pengunggahan blob secara asinkron. Untuk mempelajari selengkapnya tentang persyaratan penyiapan proyek, lihat Pemrograman asinkron.

Ikuti langkah-langkah ini untuk mengunggah blob menggunakan API asinkron:

Tambahkan pernyataan import berikut:

import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient, BlobClient, ContainerClient

Tambahkan kode untuk menjalankan program menggunakan asyncio.run. Fungsi ini menjalankan coroutine yang diteruskan, main() dalam contoh kami, dan mengelola perulangan asyncio peristiwa. Koroutin dinyatakan dengan sintaks asinkron/tunggu. Dalam contoh ini, coroutine pertama-tama main() membuat tingkat BlobServiceClient atas menggunakan async with, lalu memanggil metode yang mengunggah blob. Perhatikan bahwa hanya klien tingkat atas yang perlu menggunakan async with, karena klien lain yang dibuat darinya berbagi kumpulan koneksi yang sama.
```
async def main():
    sample = BlobSamples()

    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    credential = DefaultAzureCredential()

    async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
        await sample.upload_blob_file(blob_service_client, "sample-container")

if __name__ == '__main__':
    asyncio.run(main())
```

Tambahkan kode untuk mengunggah blob. Contoh berikut mengunggah blob dari jalur file lokal menggunakan ContainerClient objek. Kode sama dengan contoh sinkron, kecuali bahwa metode dideklarasikan dengan async kata kunci dan await kata kunci digunakan saat memanggil upload_blob metode .

async def upload_blob_file(self, blob_service_client: BlobServiceClient, container_name: str):
    container_client = blob_service_client.get_container_client(container=container_name)
    with open(file=os.path.join('filepath', 'filename'), mode="rb") as data:
        blob_client = await container_client.upload_blob(name="sample-blob.txt", data=data, overwrite=True)

Dengan pengaturan dasar ini, Anda dapat menerapkan contoh lain dalam artikel ini sebagai koroutin menggunakan sintaks asinkron/tunggu.

Sumber daya

Untuk mempelajari selengkapnya tentang mengunggah blob menggunakan pustaka klien Azure Blob Storage untuk Python, lihat sumber daya berikut ini.

Operasi REST API

Azure SDK untuk Python berisi pustaka yang dibangun di atas Azure REST API, memungkinkan Anda berinteraksi dengan operasi REST API melalui paradigma Python yang sudah dikenal. Metode pustaka klien untuk mengunggah blob menggunakan operasi REST API berikut:

Memasukkan Blob (REST API)
Put Block (REST API)

Sampel kode

Lihat sampel kode sinkron atau asinkron dari artikel ini (GitHub)