Wyświetlanie obiektów blob przy użyciu języka Java

W tym artykule pokazano, jak wyświetlać obiekty blob za pomocą biblioteki klienta usługi Azure Storage dla języka Java.

Wymagania wstępne

Konfigurowanie środowiska

Jeśli nie masz istniejącego projektu, w tej sekcji pokazano, jak skonfigurować projekt do pracy z biblioteką klienta usługi Azure Blob Storage dla języka Java. Aby uzyskać więcej informacji, zobacz Rozpoczynanie pracy z usługami Azure Blob Storage i Java.

Aby pracować z przykładami kodu w tym artykule, wykonaj następujące kroki, aby skonfigurować projekt.

Uwaga

W tym artykule użyto narzędzia kompilacji maven do skompilowania i uruchomienia przykładowego kodu. Inne narzędzia kompilacji, takie jak Gradle, współpracują również z zestawem Azure SDK dla języka Java.

Instalowanie pakietów

pom.xml Otwórz plik w edytorze tekstów. Zainstaluj pakiety, dołączając plik BOM lub uwzględniając bezpośrednią zależność.

Dodaj instrukcje importu

Dodaj następujące import instrukcje:

import com.azure.core.http.rest.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;

Autoryzacja

Mechanizm autoryzacji musi mieć niezbędne uprawnienia do wyświetlenia obiektu blob. Aby uzyskać autoryzację z Microsoft Entra ID (zalecane), potrzebujesz wbudowanej roli Azure RBAC Storage Blob Data Reader lub wyższej. Aby dowiedzieć się więcej, zobacz wskazówki dotyczące autoryzacji dla List Blobs (interfejs API REST).

Tworzenie obiektu klienta

Aby połączyć aplikację z usługą Blob Storage, utwórz wystąpienie klasy BlobServiceClient.

Poniższy przykład używa obiektu BlobServiceClientBuilder do utworzenia obiektu BlobServiceClient przy użyciu DefaultAzureCredential oraz pokazuje, jak w razie potrzeby utworzyć klientów kontenerów i obiektów blob:

// Azure SDK client builders accept the credential as a parameter
// TODO: Replace <storage-account-name> with your actual storage account name
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .endpoint("https://<storage-account-name>.blob.core.windows.net/")
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

// If needed, you can create a BlobContainerClient object from the BlobServiceClient
BlobContainerClient containerClient = blobServiceClient
        .getBlobContainerClient("<container-name>");

// If needed, you can create a BlobClient object from the BlobContainerClient
BlobClient blobClient = containerClient
        .getBlobClient("<blob-name>");

Aby dowiedzieć się więcej na temat tworzenia obiektów klienta i zarządzania nimi, zobacz Tworzenie obiektów klienta korzystających z zasobów danych i zarządzanie nimi.

Informacje o opcjach listowania obiektów blob

Gdy w kodzie wyświetlasz listę obiektów blob, możesz określić opcje decydujące o sposobie 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. Możesz wyświetlić obiekty blob w strukturze listy płaskiej lub hierarchicznej. Lista hierarchiczna zwraca obiekty blob tak, jakby były zorganizowane w folderach.

Aby wyświetlić listę obiektów blob na koncie magazynowym, wywołaj jedną z następujących metod:

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. Przykłady przedstawione w tym artykule pokazują, jak zwracać wyniki stronicami. Aby dowiedzieć się więcej na temat pojęć dotyczących stronicowania, zobacz Pagination with the Azure SDK for Java (Stronicowanie przy użyciu zestawu Azure SDK dla języka Java).

Filtrowanie wyników za pomocą prefiksu

Aby filtrować listę obiektów blob, przekaż ciąg jako parametr prefix do metody ListBlobsOptions.setPrefix(String prefix). Ciąg prefiksu może zawierać co najmniej jeden znak. Następnie usługa Azure Storage zwraca tylko obiekty blob, których nazwy zaczynają się od tego prefiksu.

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żna jednak organizować obiekty blob w katalogach wirtualnych , aby naśladować strukturę folderów. Katalog wirtualny stanowi część nazwy blobu i jest oznaczony znakiem ogranicznika.

Aby uporządkować obiekty blob w katalogi wirtualne, użyj znaku rozdzielającego w nazwie obiektu blob. Domyślny znak ogranicznika to ukośnik (/), ale można określić dowolny znak jako ogranicznik.

Jeśli nazwiesz obiekty blob przy użyciu separatora, możesz wybrać hierarchiczne wyświetlanie listy obiektów blob. W przypadku operacji wyświetlania hierarchicznego usługa Azure Storage zwraca wszystkie katalogi wirtualne 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 listowania zwraca obiekty blob w postaci listy płaskiej. Na płaskiej liście obiekty blob nie są uporządkowane według katalogu wirtualnego.

Poniższy przykład wyświetla obiekty blob w określonym kontenerze przy użyciu listowania płaskiego:

public void listBlobsFlat(BlobContainerClient blobContainerClient) {
    System.out.println("List blobs flat:");

    blobContainerClient.listBlobs()
            .forEach(blob -> System.out.printf("Name: %s%n", blob.getName()));
}

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

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

Możesz także określić opcje filtrowania wyników listy lub wyświetlania większej ilości informacji. W poniższym przykładzie wymieniono obiekty blob z określonym prefiksem, a także wyświetla listę usuniętych obiektów blob:

public void listBlobsFlatWithOptions(BlobContainerClient blobContainerClient) {
    ListBlobsOptions options = new ListBlobsOptions()
            .setMaxResultsPerPage(2) // Low number for demonstration purposes
            .setDetails(new BlobListDetails()
                    .setRetrieveDeletedBlobs(true));

    System.out.println("List blobs flat:");

    int i = 0;
    Iterable<PagedResponse<BlobItem>> blobPages = blobContainerClient.listBlobs(options, null).iterableByPage();
    for (PagedResponse<BlobItem> page : blobPages) {
        System.out.printf("Page %d%n", ++i);
        page.getElements().forEach(blob -> {
            System.out.printf("Name: %s, Is deleted? %b%n",
                    blob.getName(),
                    blob.isDeleted());
        });
    }
}

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

List blobs flat:
Page 1
Name: file4.txt, Is deleted? false
Name: file5-deleted.txt, Is deleted? true
Page 2
Name: folderA/file1.txt, Is deleted? false
Name: folderA/file2.txt, Is deleted? false
Page 3
Name: folderA/folderB/file3.txt, Is deleted? false

Uwaga

Pokazane przykładowe dane wyjściowe zakładają, że masz konto magazynu 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

Po wywołaniu operacji wyliczania w sposób hierarchiczny usługa Azure Storage zwraca katalogi wirtualne i obiekty blob na pierwszym poziomie tej hierarchii.

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

W poniższym przykładzie wymieniono obiekty blob w określonym kontenerze przy użyciu listy hierarchicznej:

public void listBlobsHierarchicalListing(BlobContainerClient blobContainerClient, String prefix/* ="" */) {
    String delimiter = "/";
    ListBlobsOptions options = new ListBlobsOptions()
            .setPrefix(prefix);

    blobContainerClient.listBlobsByHierarchy(delimiter, options, null)
            .forEach(blob -> {
                if (blob.isPrefix()) {
                    System.out.printf("Virtual directory prefix: %s%n", delimiter + blob.getName());
                    listBlobsHierarchicalListing(blobContainerClient, blob.getName());
                } else {
                    System.out.printf("Blob name: %s%n", blob.getName());
                }
            });
}

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

List blobs hierarchical:
Blob name: file4.txt
Virtual directory prefix: /folderA/
Blob name: folderA/file1.txt
Blob name: folderA/file2.txt
Virtual directory prefix: /folderA/folderB/
Blob name: folderA/folderB/file3.txt

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 Java (na przykład azure-storage-blobwersja 12.36.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. Java SDK dekoduje Apache Arrow za kulisami i nadal zwraca te same BlobItem obiekty. 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 format serializacji odpowiedzi na ListBlobsOptions na StorageResponseSerializationFormat.ARROW , wywołując setStorageResponseSerializationFormat, a następnie przekaż opcje do BlobContainerClient.listBlobs. Korzystając z danych wyjściowych Apache Arrow, możesz także wywołać setStartFrom i setEndBefore, aby określić zakres zwracanych ścieżek.

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

ListBlobsOptions options = new ListBlobsOptions()
    .setPrefix("folderA/")
    .setStorageResponseSerializationFormat(StorageResponseSerializationFormat.ARROW);

for (BlobItem blobItem : containerClient.listBlobs(options, null)) {
    System.out.println("Blob name: " + blobItem.getName());
}

Zasoby

Aby dowiedzieć się więcej o tym, jak wymieniać bloby za pomocą biblioteki klienta Azure Blob Storage dla Java, zobacz następujące materiały.

Przykłady kodu

Operacje interfejsu API REST

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

Zasoby biblioteki klienta

Zobacz też

Powiązana zawartość

  • Ten artykuł jest częścią przewodnika dla deweloperów usługi Blob Storage dla języka Java. Aby dowiedzieć się więcej, zobacz pełną listę artykułów z przewodnika dla deweloperów w temacie Tworzenie aplikacji Java.
  • Last updated on