Python ile blobları listeleme

Bu makale, Python için Azure Depolama istemci kütüphanesi kullanılarak blobların nasıl listeleneceğini gösterir.

Blob’ları zaman uyumsuz API’leri kullanarak listeleme hakkında bilgi edinmek için Blob’ları zaman uyumsuz olarak listeleme konusuna bakın.

Önkoşullar

Ortamınızı ayarlama

Mevcut bir projeniz yoksa, bu bölümde Python için Azure Blob Depolama istemci kitaplığıyla çalışmak üzere bir projenin nasıl ayarlanacağı gösterilir. Diğer ayrıntılar için bkz. Azure Blob Depolama ve Python'ı kullanmaya başlama.

Bu makaledeki kod örnekleriyle çalışmak için projenizi ayarlamak için bu adımları izleyin.

Paketleri yükleme

kullanarak pip installaşağıdaki paketleri yükleyin:

pip install azure-storage-blob azure-identity

İçe aktarma deyimlerini ekle

Aşağıdaki import deyimlerini ekleyin:

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, ContainerClient, BlobPrefix

Yetkilendirme

Yetkilendirme mekanizması, bir blobu listelemek için gerekli izinlere sahip olmalıdır. Microsoft Entra ID ile yetkilendirme için (önerilir), Azure RBAC yerleşik rolü olan Storage Blob Data Reader veya daha yüksek bir role sahip olmanız gerekir. Daha fazla bilgi edinmek için Bkz. Liste Blobları (REST API) için yetkilendirme kılavuzu.

İstemci nesnesi oluşturma

Bir uygulamayı Blob Depolama'ya bağlamak için bir BlobServiceClient örneği oluşturun. Aşağıdaki örnekte yetkilendirme için kullanarak DefaultAzureCredential bir istemci nesnesinin nasıl oluşturulacağı gösterilmektedir:

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

# Create the BlobServiceClient object
blob_service_client = BlobServiceClient(account_url, credential=credential)

Ayrıca, doğrudan veya nesneden belirli kapsayıcılar veya BlobServiceClient için istemci nesneleri oluşturabilirsiniz. İstemci nesneleri oluşturma ve yönetme hakkında daha fazla bilgi edinmek için bkz . Veri kaynaklarıyla etkileşim kuran istemci nesneleri oluşturma ve yönetme.

Blob listeleme seçenekleri hakkında

Kodunuzdaki blobları listelediğinizde, Azure Depolama'dan sonuçların nasıl geri döndüğünü yönetmek için birçok seçenek belirtebilirsiniz. Her sonuç kümesinde döndürülecek sonuç sayısını belirtebilir ve ardından sonraki kümeleri alabilirsiniz. Adları bu karakter veya dizeyle başlayan blobları döndürmek için bir ön ek belirtebilirsiniz. Blobları düz bir listeleme yapısında veya hiyerarşik olarak listeleyebilirsiniz. Hiyerarşik liste, blobları klasörler halinde düzenlenmiş gibi döndürür.

Düz bir listeleme kullanarak bir konteynerdeki blobları listelemek için şu yöntemlerden birini çağırın:

  • ContainerClient.list_blobs (isimle birlikte, isteğe bağlı olarak her blob'a ait meta veriler, etiketler ve diğer bilgileri de dahil edin)
  • ContainerClient.list_blob_names (yalnızca blob adını döndürür)

Bir konteynerdeki blobları hiyerarşik bir listeleme kullanarak listelemek için aşağıdaki yöntemi çağırın:

  • ContainerClient.walk_blobs (isimle birlikte, isteğe bağlı olarak her blobla ilgili meta veriler, etiketler ve diğer bilgileri de ekleyin)

Sonuçları ön ek ile filtreleme

Blob listesini filtrelemek için name_starts_with anahtar sözcük argümanına bir dize belirtin. Ön ek dizesi bir veya daha fazla karakter içerebilir. Azure Depolama yalnızca isimleri bu önekle başlayan blobları döndürür.

Düz listeleme ve hiyerarşik listeleme karşılaştırması

Azure Depolama'daki bloblar hiyerarşik paradigma (klasik dosya sistemi gibi) yerine düz bir paradigma içinde düzenlenir. Ancak, blobları sanal dizinlere düzenleyerek bir klasör yapısını taklit edebilirsiniz. Sanal dizin, blob adının bir bölümünü oluşturur ve sınırlayıcı karakteriyle gösterilir.

Blobları sanal dizinler halinde düzenlemek için blob adında bir sınırlayıcı karakteri kullanın. Varsayılan sınırlayıcı karakteri eğik çizgidir (/) ancak sınırlayıcı olarak herhangi bir karakteri belirtebilirsiniz.

Blob'larınızı bir ayırıcı kullanarak adlandırırsanız, blobları hiyerarşik olarak listeleyebilirsiniz. Hiyerarşik listeleme işlemi için Azure Depolama, üst nesnenin altındaki tüm sanal dizinleri ve blobları döndürür. Hiyerarşide geçiş yapmak için listeleme işlemini yinelemeli olarak çağırabilirsiniz. Örneğin, klasik dosya sisteminde program aracılığıyla geçiş yapabilirsiniz.

Düz liste kullanma

Varsayılan olarak, listeleme işlemi düz bir listede bloblar döndürür. Düz bir listede bloblar sanal dizine göre düzenlenemez.

Aşağıdaki örnek, belirlenen konteynerdeki blobları düz bir listeleme kullanılarak listeler:

def list_blobs_flat(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    blob_list = container_client.list_blobs()

    for blob in blob_list:
        print(f"Name: {blob.name}")

Örnek çıktı şuna benzer:

List blobs flat:
Name: file4.txt
Name: folderA/file1.txt
Name: folderA/file2.txt
Name: folderA/folderB/file3.txt

Ayrıca sonuçları filtrelemek veya daha fazla bilgi göstermek için seçenekler de belirtebilirsiniz. Aşağıdaki örnek blobları ve blob etiketlerini listeler:

def list_blobs_flat_options(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    blob_list = container_client.list_blobs(include=['tags'])

    for blob in blob_list:
        print(f"Name: {blob['name']}, Tags: {blob['tags']}")

Örnek çıktı şuna benzer:

List blobs flat:
Name: file4.txt, Tags: None
Name: folderA/file1.txt, Tags: None
Name: folderA/file2.txt, Tags: None
Name: folderA/folderB/file3.txt, Tags: {'tag1': 'value1', 'tag2': 'value2'}

Not

Gösterilen örnek çıktı, düz ad alanına sahip bir depolama hesabınız olduğunu varsayar. Depolama hesabınız için hiyerarşik isim alanı özelliğini etkinleştirirseniz, dizinler sanal değildir. Bunun yerine, somut, bağımsız nesnelerdir. Sonuç olarak, dizinler listede sıfır uzunlukta bloblar olarak görünür.

Hiyerarşik ad alanıyla çalışırken alternatif listeleme seçeneği için bkz . Dizin içeriğini listeleme (Azure Data Lake Storage).

Hiyerarşik liste kullanma

Listeleme işlemini hiyerarşik olarak çağırdığınızda, Azure Depolama hiyerarşinin ilk düzeyindeki sanal dizinleri ve blobları döndürür.

Blobları hiyerarşik olarak listelemek için aşağıdaki yöntemi kullanın:

Aşağıdaki örnek, hiyerarşik bir liste kullanarak belirtilen kapsayıcıdaki blobları listeler:

depth = 0
indent = "  "
def list_blobs_hierarchical(self, container_client: ContainerClient, prefix):
    for blob in container_client.walk_blobs(name_starts_with=prefix, delimiter='/'):
        if isinstance(blob, BlobPrefix):
            # Indentation is only added to show nesting in the output
            print(f"{self.indent * self.depth}{blob.name}")
            self.depth += 1
            self.list_blobs_hierarchical(container_client, prefix=blob.name)
            self.depth -= 1
        else:
            print(f"{self.indent * self.depth}{blob.name}")

Örnek çıktı şuna benzer:

folderA/
  folderA/folderB/
    folderA/folderB/file3.txt
  folderA/file1.txt
  folderA/file2.txt
file4.txt

Not

Blob anlık görüntüleri hiyerarşik bir listeleme işleminde listelenemez.

Blobları zaman uyumsuz olarak listeleme

Python için Azure Blob Depolama istemci kitaplığı, blobları zaman uyumsuz olarak listelemeyi destekler. Proje kurulum gereksinimleri hakkında daha fazla bilgi edinmek için bkz . Zaman uyumsuz programlama.

Blobları asenkron API'ler kullanarak listelemek için şu adımları izleyin:

  1. Aşağıdaki ithalat ifadelerini ekleyin:

    import asyncio

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

  2. Programı çalıştırmak için kod ekleyin.asyncio.run Bu işlev, bu örnekte main() olan aktarılan coroutine'i çalıştırır ve asyncio olay döngüsünü yönetir. Korutinler, asenkron/await sözdizimi kullanılarak ilan edilir. Bu örnekte, main() korutin önce en üst seviyeyi BlobServiceClient , kullanarak async witholuşturur, ardından blobları listeleyen metodu çağırır. Yalnızca en üst düzey istemcinin kullanması async withgerekir; bu istemciden oluşturulan diğer istemciler aynı bağlantı havuzunu paylaşır.

    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.list_blobs_flat(blob_service_client, "sample-container")

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

  3. Blobları listelemek için kod ekleyin. Aşağıdaki kod örneği, düz bir listeleme kullanılarak blobları listeler. Kod, senkron örnekle aynıdır, ancak metod anahtar async kelime kullanılarak ilan edilir ve async for metod çağrılırken list_blobs kullanılır.

    async def list_blobs_flat(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    async for blob in container_client.list_blobs():
        print(f"Name: {blob.name}")

Bu temel kurulum tamamlandığında, bu makaledeki diğer örnekleri async/await söz dizimini kullanarak eş yordamlar olarak uygulayabilirsiniz.

Apache Arrow formatında liste blobları (önizleme)

Important

Apache Arrow formatında blobların listelenmesi şu anda PREVIEW'da. Bu senaryo, Python için Azure Blob Depolama istemci kütüphanesinin beta (önizleme) sürümünü gerektirir (örneğin, azure-storage-blob12.31.0b1 veya daha sonraki önizleme sürümleri). Önizleme özellikleri hizmet düzeyi sözleşmesi olmadan sağlanır ve üretim iş yükleri için önerilmez. Bazı özellikler desteklenmeyebilir veya kısıtlı yeteneklere sahip olabilir. Daha fazla bilgi için bkz. Microsoft Azure Önizlemeleri için Ek Kullanım Koşulları.

Bu yetenek mevcut List Blobs API üzerine inşa edilmiştir. Varsayılan XML kullanmak yerine, tel üzerinde yanıt formatı olarak kompakt, sütunlu Apache Arrow formatını kullanır. Konteyner listeleme çağrısında tek bir seçenek ayarlayarak etkinleştirirsiniz. Python SDK, Apache Arrow’u arka planda çözümler ve yine de aynı BlobProperties nesnelerini döndürür. Bu yaklaşım, listeleme verimliliğini artırır ve büyük konteynerler sıralanırken istemci tarafı CPU'yu azaltır. Başvuruların dayandığı yanıt sözleşmesini korur.

Warning

Apache Arrow formatında blobların listelenmesi, hiyerarşik namespace (Azure Data Lake Storage) etkin olan depolama hesaplarında desteklenmiyor.

Apache Arrow formatlı sonuç istemek için, anahtar kelime argümanını response_format"arrow"ContainerClient.list_blobs veya ContainerClient.list_blob_names çağırdığınızda ayarlayın. Apache Arrow çıktısını kullandığınızda, geri dönen yolların aralığını kontrol etmek için anahtar kelime argümanlarını da end_before ayarlayabilirsinizstart_from.

Not

response_format="arrow" kullanmak için nanoarrow paketinin kurulu olması gerekir.

Aşağıdaki örnek, bir konteynerdeki blobları listeler ve sonuçları Apache Arrow formatında ister:

# response_format="arrow" requires the nanoarrow package to be installed
blob_list = container_client.list_blobs(
    name_starts_with="folderA/",
    response_format="arrow",
)

for blob in blob_list:
    print("Name: " + blob.name)

Kaynaklar

Python için Azure Blob Depolama istemci kütüphanesini kullanarak blobları listeleme yöntemleri hakkında daha fazla bilgi edinmek için aşağıdaki kaynaklara bakabilirsiniz.

Kod örnekleri

  • Bu makaleden (GitHub) senkron veya asenkron kod örneklerini görüntüleyin.

REST API işlemleri

Azure SDK for Python, Azure REST API'si üzerine inşa edilen kütüphaneler içerir. Bu kütüphaneleri kullanarak, tanıdık Python paradigmaları aracılığıyla REST API işlemleriyle etkileşime girebilirsiniz. Blobları listelemek için istemci kitaplığı yöntemleri aşağıdaki REST API işlemini kullanır:

İstemci kütüphane kaynakları

Ayrıca bkz.

İlgili içerik

  • Bu makale, Python için Blob Depolama geliştirici kılavuzunun bir parçasıdır. Daha fazla bilgi edinmek için Python uygulamanızı oluşturma makalesinde geliştirici kılavuzu makalelerinin tam listesine bakın.
  • Last updated on