Python için Azure Depolama Blobları istemci kitaplığı - sürüm 12.19.0

  • Makale

Azure Blob depolama, Microsoft’un buluta yönelik nesne depolama çözümüdür. Blob depolama, metin veya ikili veri gibi çok miktarda yapılandırılmamış veriyi depolamak için iyileştirilmiştir.

Blob depolama aşağıdaki durumlar için idealdir:

  • Görüntülerin veya belgelerin doğrudan bir tarayıcıya sunulması
  • Dosyaların dağıtılmış erişim için depolanması
  • Video ve ses akışları
  • Yedekleme ve geri yükleme, olağanüstü durum kurtarma ve arşivleme için veri depolama
  • Şirket içi veya Azure’da barındırılan bir hizmetle analiz için verilerin depolanması

Kaynak kodu | Paket (PyPI) | Paket (Conda) | API başvuru belgeleri | Ürün belgeleri | Örnekleri

Başlarken

Önkoşullar

Paketi yükleme

Pip ile Python için Azure Depolama Blobları istemci kitaplığını yükleyin:

pip install azure-storage-blob

Depolama hesabı oluşturma

Yeni bir depolama hesabı oluşturmak istiyorsanız Azure Portalı, Azure PowerShell veya Azure CLI'yı kullanabilirsiniz:

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

İstemci oluşturma

Python için Azure Depolama Blobları istemci kitaplığı üç tür kaynakla etkileşim kurmanızı sağlar: depolama hesabının kendisi, blob depolama kapsayıcıları ve bloblar. Bu kaynaklarla etkileşim bir istemci örneğiyle başlar. İstemci nesnesi oluşturmak için depolama hesabının blob hizmet hesabı URL'sine ve depolama hesabına erişmenizi sağlayan bir kimlik bilgilerine ihtiyacınız olacaktır:

from azure.storage.blob import BlobServiceClient

service = BlobServiceClient(account_url="https://<my-storage-account-name>.blob.core.windows.net/", credential=credential)

Hesap URL'sini arama

Depolama hesabının blob hizmeti URL'sini Azure Portal, Azure PowerShell veya Azure CLI kullanarak bulabilirsiniz:

# Get the blob service account url for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.blob"

Kimlik bilgisi türleri

Parametresi credential , kullanmak istediğiniz yetkilendirme türüne bağlı olarak bir dizi farklı biçimde sağlanabilir:

  1. Azure Active Directory (AAD) belirteci kimlik bilgilerini kullanmak için azure-identity kitaplığından alınan istenen kimlik bilgisi türünün bir örneğini sağlayın. Örneğin, istemcinin kimliğini doğrulamak için DefaultAzureCredential kullanılabilir.

    Bunun için bazı ilk kurulumlar gerekir:

    İstemcinin kimliğini doğrulamak için döndürülen belirteç kimlik bilgilerini kullanın:

        from azure.identity import DefaultAzureCredential
    from azure.storage.blob import BlobServiceClient
    token_credential = DefaultAzureCredential()

    blob_service_client = BlobServiceClient(
        account_url="https://<my_account_name>.blob.core.windows.net",
        credential=token_credential
    )

  2. Paylaşılan erişim imzası (SAS) belirteci kullanmak için belirteci dize olarak sağlayın. Hesap URL'niz SAS belirtecini içeriyorsa kimlik bilgisi parametresini atla. Azure Portalı'ndan "Paylaşılan erişim imzası" altında bir SAS belirteci oluşturabilir veya işlevlerden birini generate_sas() kullanarak depolama hesabı, kapsayıcı veya blob için sas belirteci oluşturabilirsiniz:

    from datetime import datetime, timedelta
from azure.storage.blob import BlobServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

blob_service_client = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential=sas_token)

  3. Depolama hesabı paylaşılan anahtarı (diğer adıyla hesap anahtarı veya erişim anahtarı) kullanmak için anahtarı dize olarak sağlayın. Bu, Azure Portal'da "Erişim Anahtarları" bölümünün altında veya aşağıdaki Azure CLI komutunu çalıştırarak bulunabilir:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    İstemcinin kimliğini doğrulamak için kimlik bilgisi parametresi olarak anahtarını kullanın:

    from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential="<account_access_key>")

    Özelleştirilmiş url kullanıyorsanız (bu, url'nin bu biçimde <my_account_name>.blob.core.windows.netolmadığı anlamına gelir) aşağıdaki kimlik bilgilerini kullanarak istemcinin örneğini oluşturun:

    from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", 
   credential={"account_name": "<your_account_name>", "account_key":"<account_access_key>"})

  4. Anonim genel okuma erişimini kullanmak için kimlik bilgisi parametresini atla.

İstemciyi bir bağlantı dizesi oluşturma

Kullanım örneğinize ve yetkilendirme yönteminize bağlı olarak, hesap URL'sini ve kimlik bilgilerini ayrı olarak sağlamak yerine bir depolama bağlantı dizesi ile bir istemci örneği başlatmayı tercih edebilirsiniz. Bunu yapmak için depolama bağlantı dizesi istemcinin from_connection_string sınıf yöntemine geçirin:

from azure.storage.blob import BlobServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = BlobServiceClient.from_connection_string(conn_str=connection_string)

Depolama hesabınıza bağlantı dizesi Azure Portal'da "Erişim Anahtarları" bölümünde veya aşağıdaki CLI komutunu çalıştırarak bulabilirsiniz:

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

Önemli kavramlar

Aşağıdaki bileşenler Azure Blob Hizmeti'ni oluşturur:

  • Depolama hesabının kendisi
  • Depolama hesabı içindeki bir kapsayıcı
  • Kapsayıcı içindeki blob

Python için Azure Depolama Blobları istemci kitaplığı, ayrılmış bir istemci nesnesi kullanarak bu bileşenlerin her biriyle etkileşim kurmanızı sağlar.

İstemciler

Blob Hizmeti'nin çeşitli bileşenleriyle etkileşime geçmek için dört farklı istemci sağlanır:

  1. BlobServiceClient - bu istemci Azure depolama hesabının kendisiyle etkileşimi temsil eder ve içindeki kapsayıcılara ve bloblara erişmek için önceden yapılandırılmış istemci örnekleri almanıza olanak tanır. Hesap özelliklerini alma ve yapılandırmanın yanı sıra hesap içindeki kapsayıcıları listeleme, oluşturma ve silme işlemlerini sağlar. Belirli bir kapsayıcı veya blob üzerinde işlem gerçekleştirmek için veya get_blob_client yöntemlerini kullanarak get_container_client bir istemci alın.
  2. ContainerClient - bu istemci belirli bir kapsayıcıyla etkileşimi temsil eder (henüz mevcut değildir) ve içindeki bloblara erişmek için önceden yapılandırılmış istemci örnekleri almanıza olanak tanır. Kapsayıcı oluşturma, silme veya yapılandırma işlemlerini sağlar ve içindeki blobları listeleme, karşıya yükleme ve silme işlemlerini içerir. Kapsayıcı içindeki belirli bir blob üzerinde işlem gerçekleştirmek için yöntemini kullanarak get_blob_client bir istemci alın.
  3. BlobClient - bu istemci belirli bir blobla (henüz mevcut olmayan) etkileşimi temsil eder. Blobun anlık görüntülerini karşıya yükleme, indirme, silme ve oluşturma işlemlerinin yanı sıra blob türüne göre belirli işlemler sağlar.
  4. BlobLeaseClient - bu istemci veya ContainerClientBlobClientile kira etkileşimlerini temsil eder. Belirtilen bir kaynakta kira alma, yenileme, serbest bırakma, değiştirme ve kesme işlemleri sağlar.

Zaman Uyumsuz İstemciler

Bu kitaplık, Python 3.5+ üzerinde desteklenen tam bir zaman uyumsuz API içerir. Bunu kullanmak için önce aiohttp gibi bir zaman uyumsuz aktarım yüklemeniz gerekir. Daha fazla bilgi için bkz. azure-core belgeleri .

Zaman uyumsuz istemciler ve kimlik bilgileri artık gerekli olmadığında kapatılmalıdır. Bu nesneler zaman uyumsuz bağlam yöneticileridir ve zaman uyumsuz close yöntemler tanımlar.

Blob Türleri

İstemciyi başlatdıktan sonra farklı blob türleri arasından seçim yapabilirsiniz:

  • Blok blobları , yaklaşık 4,75 TiB'a kadar metin ve ikili veri depolar. Blok blobları, tek tek yönetilebilen veri bloklarından oluşur
  • Ekleme blobları blok blobları gibi bloklardan oluşur, ancak ekleme işlemleri için iyileştirilmiştir. Ekleme blobları, sanal makinelerden alınan verileri günlüğe kaydetme gibi senaryolar için idealdir
  • Sayfa blobları , boyutu 8 TiB'a kadar olan rastgele erişim dosyalarını depolar. Sayfa blobları sanal sabit sürücü (VHD) dosyalarını depolar ve Azure sanal makineleri için disk görevi görür

Örnekler

Aşağıdaki bölümlerde, aşağıdakiler de dahil olmak üzere en yaygın Depolama Blobu görevlerinden bazılarını kapsayan çeşitli kod parçacıkları sağlanır:

Blobu karşıya yüklemek veya indirmek için önce bir kapsayıcı oluşturulması gerektiğini unutmayın.

Kapsayıcı oluşturma

Blobları karşıya yükleyebileceğiniz veya indirebileceğiniz bir kapsayıcı oluşturun.

from azure.storage.blob import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

container_client.create_container()

Blobu karşıya yüklemek için zaman uyumsuz istemciyi kullanma

from azure.storage.blob.aio import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

await container_client.create_container()

Blobu karşıya yükleme

Kapsayıcınıza blob yükleme

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    blob.upload_blob(data)

Blobu karşıya yüklemek için zaman uyumsuz istemciyi kullanma

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    await blob.upload_blob(data)

Blob indirme

Kapsayıcınızdan blob indirme

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    blob_data = blob.download_blob()
    blob_data.readinto(my_blob)

Blobu zaman uyumsuz olarak indirme

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    stream = await blob.download_blob()
    data = await stream.readall()
    my_blob.write(data)

Blobları listeleme

Kapsayıcınızdaki blobları listeleme

from azure.storage.blob import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = container.list_blobs()
for blob in blob_list:
    print(blob.name + '\n')

Blobları zaman uyumsuz olarak listeleme

from azure.storage.blob.aio import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = []
async for blob in container.list_blobs():
    blob_list.append(blob)
print(blob_list)

İsteğe Bağlı Yapılandırma

İstemcide ve işlem düzeyinde geçirilebilen isteğe bağlı anahtar sözcük bağımsız değişkenleri.

İlke yapılandırmasını yeniden deneme

Yeniden deneme ilkesini yapılandırmak için bir istemci örneği oluştururken aşağıdaki anahtar sözcük bağımsız değişkenlerini kullanın:

  • retry_total (int): İzin vermek için toplam yeniden deneme sayısı. Diğer sayılardan önceliklidir. İstekleri retry_total=0 yeniden denemek istemiyorsanız geçiş yapın. Varsayılan değer 10'dır.
  • retry_connect (int): Bağlantıyla ilgili kaç hatanın yeniden denenebileceği. Varsayılan değer 3'tir.
  • retry_read (int): Okuma hatalarında yeniden deneme sayısı. Varsayılan değer 3'tir.
  • retry_status (int): Hatalı durum kodları üzerinde yeniden deneme sayısı. Varsayılan değer 3'tir.
  • retry_to_secondary (bool): mümkünse isteğin ikincil olarak yeniden denenip denenmeyeceği. Bu yalnızca RA-GRS hesaplarının etkinleştirilmesi gerekir ve eski olabilecek veriler işlenebilir. Varsayılan olarak olarak Falsegösterilir.

Şifreleme yapılandırması

Şifrelemeyi yapılandırmak için istemci örneği oluştururken aşağıdaki anahtar sözcük bağımsız değişkenlerini kullanın:

  • require_encryption (bool): True olarak ayarlanırsa, nesnelerin şifrelenmesini ve şifresinin çözülmesini zorunlu kılar.
  • encryption_version (str): Kullanılacak şifreleme sürümünü belirtir. Geçerli seçenekler veya'1.0', '2.0' varsayılan değer ise şeklindedir'1.0'. Sürüm 1.0 kullanım dışıdır ve 2.0 sürümünün kullanılması kesinlikle önerilir .
  • key_encryption_key (nesne): Kullanıcı tarafından sağlanan anahtar-şifreleme anahtarı. Örneğin aşağıdaki yöntemleri uygulaması gerekir:
    • wrap_key(key)--, kullanıcının seçtiği bir algoritmayı kullanarak belirtilen anahtarı sarmalar.
    • get_key_wrap_algorithm()--, belirtilen simetrik anahtarı sarmalamada kullanılan algoritmayı döndürür.
    • get_kid()--, bu anahtar-encryption-key için bir dize anahtarı kimliği döndürür.
  • key_resolver_function (çağrılabilir): Kullanıcı tarafından sağlanan anahtar çözümleyici. Yukarıda tanımlanan arabirimi uygulayan bir anahtar-şifreleme anahtarı döndürmek için çocuk dizesini kullanır.

Diğer istemci /işlem başına yapılandırma

İstemcide veya işlem başına belirtilebilen diğer isteğe bağlı yapılandırma anahtar sözcük bağımsız değişkenleri.

İstemci anahtar sözcük bağımsız değişkenleri:

  • connection_timeout (int): İstemcinin sunucuyla bağlantı kurmak için bekleyeceği saniye sayısı. Varsayılan değer 20 saniyedir.
  • read_timeout (int): İstemcinin sunucudan gelen bir yanıt için ardışık okuma işlemleri arasında bekleyeceği saniye sayısı. Bu bir yuva düzeyi zaman aşımıdır ve genel veri boyutundan etkilenmez. İstemci tarafı okuma zaman aşımları otomatik olarak yeniden denenecek. Varsayılan değer 60 saniyedir.
  • transport (Any): HTTP isteğini göndermek için kullanıcı tarafından sağlanan aktarım.

İşlem başına anahtar sözcük bağımsız değişkenleri:

  • raw_response_hook (çağrılabilir): Verilen geri arama, hizmetten döndürülen yanıtı kullanır.
  • raw_request_hook (çağrılabilir): Verilen geri arama, hizmete gönderilmeden önce isteği kullanır.
  • client_request_id (str): İsteğin kullanıcı tarafından belirtilen isteğe bağlı kimliği.
  • user_agent (str): İstekle birlikte gönderilecek kullanıcı aracısı üst bilgisine özel değeri ekler.
  • logging_enable (bool): HATA AYıKLAMA düzeyinde günlüğe kaydetmeyi etkinleştirir. Varsayılan değer False'tur. Tüm istekler için etkinleştirmek üzere istemci düzeyinde de geçirilebilir.
  • logging_body (bool): İsteğin ve yanıt gövdesinin günlüğe kaydedilmesini sağlar. Varsayılan değer False'tur. Tüm istekler için etkinleştirmek üzere istemci düzeyinde de geçirilebilir.
  • headers (dict): Özel üst bilgileri anahtar, değer çiftleri olarak geçirin. Örneğin. headers={'CustomValue': value}

Sorun giderme

Genel

Depolama Blobu istemcileri Azure Core'da tanımlanan özel durumları tetikler.

Bu liste, atılan özel durumları yakalamak için başvuru için kullanılabilir. Özel durumun belirli hata kodunu almak için özniteliğini error_code kullanın, örneğin. exception.error_code

Günlüğe Kaydetme

Bu kitaplık , günlüğe kaydetme için standart günlük kitaplığını kullanır. HTTP oturumları (URL'ler, üst bilgiler vb.) hakkındaki temel bilgiler BİlGİ düzeyinde günlüğe kaydedilir.

İstek/yanıt gövdeleri ve kaydedilmemiş üst bilgiler de dahil olmak üzere ayrıntılı HATA AYıKLAMA düzeyi günlüğü, bir istemcide şu bağımsız değişkenle logging_enable etkinleştirilebilir:

import sys
import logging
from azure.storage.blob import BlobServiceClient

# Create a logger for the 'azure.storage.blob' SDK
logger = logging.getLogger('azure.storage.blob')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = BlobServiceClient.from_connection_string("your_connection_string", logging_enable=True)

Benzer şekilde, logging_enable istemci için etkinleştirilmemiş olsa bile tek bir işlem için ayrıntılı günlüğe kaydetmeyi etkinleştirebilir:

service_client.get_service_stats(logging_enable=True)

Sonraki adımlar

Daha fazla örnek kod

Blob örneklerimizi kullanmaya başlayın.

SDK'nın GitHub deposunda birkaç Depolama Blobu Python SDK'sı örneği mevcuttur. Bu örnekler, Depolama Blobları ile çalışırken yaygın olarak karşılaşılan ek senaryolar için örnek kod sağlar:

  • blob_samples_container_access_policy.py (zaman uyumsuz sürüm) - Erişim ilkelerini ayarlama örnekleri:

    • Kapsayıcı için Erişim İlkesi'ni ayarlama

  • blob_samples_hello_world.py (zaman uyumsuz sürüm) - Yaygın Depolama Blobu görevleri için örnekler:

    • Kapsayıcı ayarlama
    • Blok, sayfa veya ekleme blobu oluşturma
    • Blobları karşıya yükleme
    • Blob’ları indirme
    • Blob’ları silme

  • blob_samples_authentication.py (zaman uyumsuz sürüm) - İstemcinin kimliğini doğrulama ve oluşturma örnekleri:

    • bir bağlantı dizesi
    • Paylaşılan erişim anahtarından
    • Paylaşılan erişim imzası belirtecinden
    • Active Directory'den

  • blob_samples_service.py (zaman uyumsuz sürüm) - Blob hizmetiyle etkileşime yönelik örnekler:

    • Hesap bilgilerini alma
    • Hizmet özelliklerini alma ve ayarlama
    • Hizmet istatistiklerini alma
    • Kapsayıcı oluşturma, listeleme ve silme
    • Blob veya Kapsayıcı istemcisini alma

  • blob_samples_containers.py (zaman uyumsuz sürüm) - Kapsayıcılarla etkileşime yönelik örnekler:

    • Kapsayıcı oluşturma ve kapsayıcıları silme
    • Kapsayıcılarda meta verileri ayarlama
    • Kapsayıcı özelliklerini alma
    • Kapsayıcıda kiralama alma
    • Kapsayıcıda erişim ilkesi ayarlama
    • Kapsayıcıdaki blobları karşıya yükleme, listeleme, silme
    • Belirli bir blobla etkileşime geçmek için blob istemcisini alma

  • blob_samples_common.py (zaman uyumsuz sürüm) - Tüm blob türleri için ortak örnekler:

    • Anlık görüntü oluşturma
    • Blob anlık görüntüsünü silme
    • Blobu geçici olarak silme
    • Blobu silme
    • Blob üzerinde kira alma
    • URL'den blob kopyalama

  • blob_samples_directory_interface.py - Blob depolama ile dosya sistemindeki bir dizinmiş gibi araya ekleme örnekleri:

    • Tek bir dosyayı veya dizini kopyalama (karşıya yükleme veya indirme)
    • Dosyaları veya dizinleri tek bir düzeyde veya özyinelemeli olarak listeleme
    • Tek bir dosyayı silme veya dizini yinelemeli olarak silme

Diğer belgeler

Azure Blob depolama hakkında daha kapsamlı belgeler için docs.microsoft.com ile ilgili Azure Blob depolama belgelerine bakın .

Katkıda bulunma

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için bkz. https://cla.microsoft.com.

Bir çekme isteği gönderdiğinizde, CLA robotu bir CLA sağlamanız gerekip gerekmediğini otomatik olarak belirler ve çekme isteğini uygun şekilde donatır (örn. etiket, açıklama). Robot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Bu işlemi, CLA’mızı kullanarak tüm depolarda yalnızca bir kere yapmanız gerekir.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları SSS bölümüne bakın veya ek sorular veya yorumlarla iletişime geçin opencode@microsoft.com .