JavaScript ile blobları listeleme

Bu makale, JavaScript için Azure Depolama istemci kitaplığını kullanarak blobların nasıl listeleneceğini gösterir.

Önkoşullar

Bu makaledeki örneklerde JavaScript için Azure Blob Depolama istemci kitaplığıyla çalışmak üzere ayarlanmış bir projeniz olduğu varsayılır. Paket yükleme, modülleri içeri aktarma ve veri kaynaklarıyla çalışmak üzere yetkili bir istemci nesnesi oluşturma gibi projenizi ayarlama hakkında bilgi edinmek için bkz. Azure Blob Depolama ve JavaScript'i kullanmaya başlama.
Yetkilendirme mekanizmasının blobları listeleme izinleri olmalıdır. Daha fazla bilgi edinmek için aşağıdaki REST API işlemi için yetkilendirme kılavuzuna bakın:
- Blobları Listeleme

Blob listeleme seçenekleri hakkında

Kodunuzdan blobları listelediğinizde, sonuçların Azure Depolama'dan nasıl döndürüleceğini yönetmek için çeşitli seçenekler 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. Ayrıca blobları düz 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 liste kullanarak kapsayıcıdaki blobları listelemek için aşağıdaki yöntemi çağırın:

ContainerClient.listBlobsFlat

Hiyerarşik liste kullanarak kapsayıcıdaki blobları listelemek için aşağıdaki yöntemi çağırın:

ContainerClient.listBlobsByHierarchy

Döndürülecek sonuç sayısını yönetin

Varsayılan olarak, bir listeleme işlemi bir kerede en çok 5000 sonuç döndürür, ancak her listeleme işleminin döndürmesini istediğiniz sonuç sayısını belirtebilirsiniz. Bu makalede sunulan örnekler, sonuçları sayfalarda nasıl döndürebileceğinizi gösterir. Sayfalandırma kavramları hakkında daha fazla bilgi edinmek için bkz . JavaScript için Azure SDK ile sayfalandırma.

Sonuçları ön ek ile filtreleme

Blob listesini filtrelemek için ContainerListBlobsOptionsprefixözelliği için 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. Örneğin, ön ek dizesini sample- geçirmek yalnızca adları ile sample-başlayan blobları döndürür.

Blob meta verilerini veya diğer bilgileri ekleme

Blob meta verilerini sonuçlara eklemek için, ContainerListBlobsOptions’ın bir parçası olarak includeMetadata özelliğini true olarak ayarlayın. Ayrıca, uygun özelliği trueolarak ayarlayarak sonuçlara anlık görüntüler, etiketler veya sürümler de ekleyebilirsiniz.

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, belirtilen konteynerdeki blobları düz bir listeleme kullanılarak listeler. Bu örnek, varsa blob anlık görüntülerini ve blob meta verilerini içerir:

JavaScript
TypeScript

async function listBlobsFlat(containerClient) {

  const maxPageSize = 2;

  // Some options for filtering results
  const listOptions = {
    includeMetadata: true,
    includeSnapshots: true,
    prefix: '' // Filter results by blob name prefix
  };

  console.log("Blobs flat list (by page):");
  for await (const response of containerClient
    .listBlobsFlat(listOptions)
    .byPage({ maxPageSize })) {
    console.log("- Page:");
    if (response.segment.blobItems) {
      for (const blob of response.segment.blobItems) {
        console.log(`  - ${blob.name}`);
      }
    }
  }
}

async function listBlobsFlat(
  containerClient: ContainerClient
): Promise<void> {
  
  const maxPageSize = 2;

  // Some options for filtering results
  const listOptions: ContainerListBlobsOptions = {
    includeMetadata: true,
    includeSnapshots: true,
    prefix: '' // Filter results by blob name prefix
  };

  console.log("Blobs flat list(by page):");
  for await (const response of containerClient
    .listBlobsFlat(listOptions)
    .byPage({ maxPageSize })) {
    console.log("- Page:");
    if (response.segment.blobItems) {
      for (const blob of response.segment.blobItems) {
        console.log(`  - ${blob.name}`);
      }
    }
  }
}

Örnek çıktı şuna benzer:

Blobs flat list (by page):
- Page:
  - a1
  - a2
- Page:
  - folder1/b1
  - folder1/b2
- Page:
  - folder2/sub1/c
  - folder2/sub1/d

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:

BlobContainerClient.listBlobsByHierarchy

Aşağıdaki örnek, hiyerarşik bir liste kullanarak belirtilen kapsayıcıdaki blobları listeler. Bu örnekte, kapsayıcıdaki tüm blobları listelemek için ön ek parametresi başlangıçta boş bir dizeye ayarlanır. Örnek daha sonra sanal dizin hiyerarşisi ve liste blobları arasında geçiş yapmak için listeleme işlemini yinelemeli olarak çağırır.

JavaScript
TypeScript

// Recursively list virtual folders and blobs
async function listBlobHierarchical(containerClient, delimiter='/') {
  
  const maxPageSize = 20;

  // Some options for filtering list
  const listOptions = {
    prefix: '' // Filter results by blob name prefix   
  };

  let i = 1;
  console.log(`Folder ${delimiter}`);

  for await (const response of containerClient
    .listBlobsByHierarchy(delimiter, listOptions)
    .byPage({ maxPageSize })) {

    console.log(`   Page ${i++}`);
    const segment = response.segment;

    if (segment.blobPrefixes) {

      // Do something with each virtual folder
      for await (const prefix of segment.blobPrefixes) {

        // Build new delimiter from current and next
        await listBlobHierarchical(containerClient, `${delimiter}${prefix.name}`);
      }
    }

    for (const blob of response.segment.blobItems) {

      // Do something with each blob
      console.log(`\tBlobItem: name - ${blob.name}`);
    }
  }
}

// Recursively list virtual folders and blobs
async function listBlobHierarchical(
  containerClient: ContainerClient,
  delimiter = '/'
): Promise<void> {

  const maxPageSize = 20;

  // Some options for filtering results
  const listOptions: ContainerListBlobsOptions = {
    prefix: '' // Filter results by blob name prefix
  };

  let i = 1;
  console.log(`Folder ${delimiter}`);

  for await (const response of containerClient
    .listBlobsByHierarchy(delimiter, listOptions)
    .byPage({ maxPageSize })) {
    console.log(`   Page ${i++}`);
    const segment = response.segment;

    if (segment.blobPrefixes) {
      // Do something with each virtual folder
      for await (const prefix of segment.blobPrefixes) {
        // Build new delimiter from current and next
        await listBlobHierarchical(
          containerClient,
          `${delimiter}${prefix.name}`
        );
      }
    }

    for (const blob of response.segment.blobItems) {
      // Do something with each blob
      console.log(`\tBlobItem: name - ${blob.name}`);
    }
  }
}

Örnek çıktı şuna benzer:

Folder /
   Page 1
        BlobItem: name - a1
        BlobItem: name - a2
   Page 2
Folder /folder1/
   Page 1
        BlobItem: name - folder1/b1
        BlobItem: name - folder1/b2
Folder /folder2/
   Page 1
Folder /folder2/sub1/
   Page 1
        BlobItem: name - folder2/sub1/c
        BlobItem: name - folder2/sub1/d
   Page 2
        BlobItem: name - folder2/sub1/e

Not

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

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

Important

Apache Arrow formatında blobların listelenmesi şu anda PREVIEW'da. Bu senaryo, JavaScript için Azure Blob Depolama istemci kütüphanesinin beta (önizleme) sürümünü gerektirir (örneğin, @azure/storage-blob12.34.0-beta.1 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. JavaScript SDK, Apache Arrow'u perde arkasında çözüyor ve yine de aynı blob item nesnelerini döndürüyor. 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 biçimindeki sonuçları istemek için, listeleme seçeneklerindeki responseFormat özelliğini StorageResponseFormat.Arrow olarak ayarlayın, ardından seçenekleri ContainerClient.listBlobsFlat yöntemine geçirin. Enum'u StorageResponseFormat 'den @azure/storage-blobiçe aktarın.

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

const { StorageResponseFormat } = require("@azure/storage-blob");

const options = {
  prefix: "FolderA/",
  responseFormat: StorageResponseFormat.Arrow,
};

for await (const blob of containerClient.listBlobsFlat(options)) {
  console.log("Blob name: " + blob.name);
}

Kaynaklar

JavaScript için Azure Blob Depolama istemci kütüphanesini kullanarak blobların nasıl listeleneceği hakkında daha fazla bilgi edinmek için aşağıdaki kaynaklara bakınız.

Kod örnekleri

Bu makaleden JavaScript ve TypeScript kod örneklerini GitHub'da görüntüleyin.

REST API işlemleri

JavaScript için Azure SDK, Azure REST API'si üzerine inşa edilen kütüphaneler içerir. Bu kütüphaneleri kullanarak, tanıdık JavaScript 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:

Blobları Listeleme (REST API)

İstemci kitaplığı kaynakları

Ayrıca bkz.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-08-27