Wyświetlanie listy obiektów blob za pomocą języka JavaScript

W tym artykule pokazano, jak wyświetlić listę obiektów blob przy użyciu biblioteki klienta usługi Azure Storage dla języka JavaScript.

Wymagania wstępne

W przykładach w tym artykule założono, że masz już skonfigurowany projekt do pracy z biblioteką klienta usługi Azure Blob Storage dla języka JavaScript. Aby dowiedzieć się więcej o konfigurowaniu projektu, w tym instalacji pakietu, importowaniu modułów i tworzeniu autoryzowanego obiektu klienta do pracy z zasobami danych, zobacz Rozpoczynanie pracy z usługami Azure Blob Storage i JavaScript.
Mechanizm autoryzacji musi mieć uprawnienia do wyświetlania listy obiektów blob. Aby dowiedzieć się więcej, zobacz wskazówki dotyczące autoryzacji dla następującej operacji interfejsu API REST:
- Lista blobów

Informacje dotyczące opcji wyświetlania listy obiektów blob

Podczas wyświetlania listy obiektów blob z kodu, możesz określić kilka opcji kontrolowania sposobu zwracania wyników z usługi Azure Storage. Możesz określić liczbę wyników, które mają być zwracane w każdym zestawie wyników, a następnie pobrać kolejne zestawy. Można określić prefiks do zwracania obiektów blob, których nazwy zaczynają się od tego znaku lub ciągu. Obiekty blob można również wyświetlać w płaskiej strukturze listy lub hierarchicznie. Hierarchiczna lista zwraca obiekty blob tak, jakby zostały zorganizowane w foldery.

Aby wyświetlić listę obiektów blob w kontenerze przy użyciu listy płaskiej, wywołaj następującą metodę:

ContainerClient.listBlobsFlat

Aby wyświetlić listę blobów w kontenerze przy użyciu listy hierarchicznej, wywołaj następującą metodę.

ContainerClient.listBlobsByHierarchy

Zarządzanie liczbą zwracanych wyników

Domyślnie operacja wyświetlania listy zwraca maksymalnie 5000 wyników jednocześnie, ale można określić liczbę wyników, które mają zostać zwrócone przez każdą operację listy. W przykładach przedstawionych w tym artykule pokazano, jak wyświetlać wyniki strona po stronie. Aby dowiedzieć się więcej na temat pojęć dotyczących stronicowania, zobacz Pagination with the Azure SDK for JavaScript (Stronicowanie przy użyciu zestawu Azure SDK dla języka JavaScript).

Filtrowanie wyników za pomocą prefiksu

Aby filtrować listę obiektów blob, określ ciąg dla właściwości prefix w ContainerListBlobsOptions. Ciąg prefiksu może zawierać co najmniej jeden znak. Azure Storage zwraca tylko te bloby, których nazwy zaczynają się od tego prefiksu. Na przykład, przekazanie prefiksu w postaci ciągu sample- zwraca tylko te obiekty blob, których nazwy zaczynają się od sample-.

Dołącz metadane obiektu blob lub inne informacje

Aby uwzględnić metadane obiektu blob z wynikami, ustaw includeMetadata właściwość na true jako część ContainerListBlobsOptions. Możesz również uwzględnić migawki, tagi lub wersje w wynikach, ustawiając odpowiednią właściwość na true wartość.

Lista płaska a lista hierarchiczna

Obiekty blob w usłudze Azure Storage są zorganizowane w modelu płaskim, a nie w modelu hierarchicznym (np. klasycznym systemie plików). Możesz jednak organizować bloby w wirtualne katalogi , aby naśladować strukturę folderów. Katalog wirtualny stanowi część nazwy obiektu blob i jest wskazywany przez znak rozdzielający.

Aby zorganizować obiekty blob w katalogach wirtualnych, użyj znaku ogranicznika w nazwie obiektu blob. Domyślny znak ogranicznika to ukośnik (/), ale można określić dowolny znak jako ogranicznik.

Jeśli nazywasz swoje bloby za pomocą separatora, możesz wybrać hierarchiczną listę bloków. W przypadku operacji wyświetlania hierarchicznego usługa Azure Storage zwraca dowolne wirtualne katalogi i obiekty blob znajdujące się pod obiektem nadrzędnym. Operację wyświetlania listy można wywołać rekursywnie, aby przejść przez hierarchię, podobnie jak w przypadku programowego przechodzenia przez klasyczny system plików.

Używanie listy płaskiej

Domyślnie operacja wyświetlania listy zwraca obiekty blob w płaskiej liście. Na liście płaskiej obiekty blob nie są zorganizowane przez katalog wirtualny.

Poniższy przykład przedstawia plamy w określonym kontenerze przy użyciu płaskiej listy. Ten przykład zawiera migawki obiektów blob i metadane obiektów blob, jeśli istnieją.

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}`);
      }
    }
  }
}

Przykładowe dane wyjściowe są podobne do następujących:

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

Uwaga

Przedstawione przykładowe dane wyjściowe zakładają, że masz konto magazynowe z płaską przestrzenią nazw. Jeśli włączysz funkcję hierarchicznej przestrzeni nazw dla swojego konta pamięciowego, katalogi nie są wirtualne. Zamiast tego są konkretnymi, niezależnymi obiektami. W związku z tym katalogi są wyświetlane na liście jako obiekty blob o zerowej długości.

Aby uzyskać alternatywną opcję wyświetlania listy podczas pracy z hierarchiczną przestrzenią nazw, zobacz List directory contents (Azure Data Lake Storage).

Używanie listy hierarchicznej

Gdy wywołujesz operację listowania hierarchicznie, Azure Storage zwraca katalogi wirtualne i obiekty blob na pierwszym poziomie hierarchii.

Aby wyświetlić hierarchicznie listę obiektów blob, użyj następującej metody:

BlobContainerClient.listBlobsByHierarchy

W poniższym przykładzie wymieniono obiekty blob w określonym kontenerze przy użyciu listy hierarchicznej. W tym przykładzie parametr prefiksu jest początkowo ustawiony na pusty ciąg, aby wyświetlić listę wszystkich obiektów blob w kontenerze. W tym przykładzie operacja wyświetlania listy jest cyklicznie wywoływana, aby przejść przez hierarchię katalogów wirtualnych i wyświetlić listę obiektów blob.

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}`);
    }
  }
}

Przykładowe dane wyjściowe są podobne do następujących:

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

Uwaga

Migawek blobów nie można wyświetlić w operacji listowania hierarchicznego.

Lista blobów w formacie Apache Arrow (podgląd)

Ważna

Wyświetlanie listy obiektów blob w formacie Apache Arrow jest obecnie w WERSJI ZAPOZNAWCZEJ. Ten scenariusz wymaga wersji beta (podglądowej) biblioteki klienta Azure Blob Storage dla JavaScript (na przykład @azure/storage-blobwersja 12.34.0-beta.1 lub nowsza). Funkcje w wersji zapoznawczej są udostępniane bez umowy dotyczącej poziomu usług i nie są zalecane w przypadku obciążeń produkcyjnych. Niektóre funkcje mogą nie być obsługiwane lub mieć ograniczone możliwości. Aby uzyskać więcej informacji, zobacz Warunki dodatkowe korzystania z testowych wersji Microsoft Azure.

Ta funkcja opiera się na istniejącym List Blobs API. Zamiast używać domyślnego XML, używa kompaktowego, kolumnowego formatu Apache Arrow jako formatu odpowiedzi na przewodzie. Włączasz tę funkcję, ustawiając pojedynczą opcję w wywołaniu listowania kontenerów. Zestaw SDK języka JavaScript dekoduje dane Apache Arrow za kulisami i nadal zwraca te same obiekty elementów blob. Takie podejście poprawia przepustowość listowania i zmniejsza ilość procesora po stronie klienta podczas wyliczania dużych kontenerów. Zachowuje kontrakt odpowiedzi, od którego zależą aplikacje.

Warning

Wyświetlanie blobów w formacie Apache Arrow nie jest obsługiwane na kontach pamięci masowej, które mają włączoną hierarchiczną przestrzeń nazw (Azure Data Lake Storage).

Aby zażądać wyników sformatowanych w Apache Arrow, ustaw responseFormat właściwość opcji listingu na StorageResponseFormat.Arrow, a następnie przekaż te opcje do ContainerClient.listBlobsFlat. Zaimportuj StorageResponseFormat enum z @azure/storage-blob.

Poniższy przykład wyświetla listę obiektów blob w kontenerze i żąda wyników w formacie Apache Arrow:

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);
}

Zasoby

Aby dowiedzieć się więcej o tym, jak wymieniać bloby za pomocą biblioteki klienta Azure Blob Storage dla JavaScript, zobacz poniższe materiały.

Przykłady kodu

Zobacz przykłady kodu JavaScript i TypeScript z tego artykułu na GitHub.

Operacje interfejsu API REST

Azure SDK dla JavaScript zawiera biblioteki budujące się na Azure REST API. Dzięki tym bibliotekom możesz wchodzić w interakcje z operacjami REST API za pomocą znanych paradygmatów JavaScript. Metody biblioteki klienta do wyświetlania listy obiektów blob używają następującej operacji interfejsu API REST:

Wyświetlanie listy obiektów blob (interfejs API REST)

Zasoby biblioteki klienta

Zobacz też

Opinia

Czy ta strona była pomocna?

Last updated on 2026-08-27