Wyświetl obiekty blob przy użyciu Go

Ten artykuł pokazuje, jak wymieniać bloby za pomocą modułu klienta Azure Storage dla Go.

Wymagania wstępne

• Subskrypcja platformy Azure — utwórz jedną bezpłatnie
• Konto usługi Azure Storage — utwórz konto magazynowe
• Przejdź do wersji 1.18 lub nowszej

Konfigurowanie środowiska

Jeśli nie masz istniejącego projektu, w tej sekcji pokazano, jak skonfigurować projekt do pracy z modułem klienta usługi Azure Blob Storage dla języka Go. Kroki obejmują instalację modułu, dodawanie import ścieżek i tworzenie autoryzowanego obiektu klienta. Aby uzyskać szczegółowe informacje, zobacz Wprowadzenie do usługi Azure Blob Storage i Go.

Instalowanie modułów

Zainstaluj moduł azblob przy użyciu następującego polecenia:

go get github.com/Azure/azure-sdk-for-go/sdk/storage/azblob

Aby uwierzytelnić się przy użyciu identyfikatora Entra firmy Microsoft (zalecane), zainstaluj azidentity moduł przy użyciu następującego polecenia:

go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

Dodawanie ścieżek importu

W pliku kodu dodaj następujące ścieżki importu:

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
)

Te ścieżki importu reprezentują minimum wymagane do rozpoczęcia pracy. Niektóre przykłady kodu w tym artykule mogą wymagać dodatkowych ścieżek importu. Aby uzyskać szczegółowe informacje i przykładowe użycie, zobacz Przykłady kodu.

Tworzenie obiektu klienta

Aby połączyć aplikację z usługą Blob Storage, utwórz obiekt klienta przy użyciu polecenia azblob. NewClient. W poniższym przykładzie pokazano, jak utworzyć obiekt klienta przy użyciu DefaultAzureCredential autoryzacji:

func getServiceClientTokenCredential(accountURL string) *azblob.Client {
    // Create a new service client with token credential
    credential, err := azidentity.NewDefaultAzureCredential(nil)
    handleError(err)

    client, err := azblob.NewClient(accountURL, credential, nil)
    handleError(err)

    return client
}

Autoryzacja

Mechanizm autoryzacji musi mieć niezbędne uprawnienia do załadowania blobu. 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, zapoznaj się z wytycznymi autoryzacji dotyczącymi List Blobs (REST API).

Informacje o opcjach wyświetlania blobów

Podczas wyświetlania listy obiektów blob z kodu można określić wiele opcji zarządzania sposobem 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 wymieniać bloby w płaskiej strukturze lub hierarchicznie. Hierarchiczna lista zwraca bloby tak, jakby były zorganizowane w foldery.

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

• NewListBlobsFlatPager

Aby wypisać bloby w kontenerze za pomocą hierarchicznego listingu, wywołaj następującą metodę z kontenerowego obiektu klienta:

• NewListBlobsHierarchyPager

Zarządzanie liczbą zwracanych wyników

Domyślnie operacja wyświetlania listy zwraca maksymalnie 5000 wyników jednocześnie. Aby zwrócić mniejszy zestaw wyników, podaj wartość niezerową dla MaxResults pola w listBlobsFlatOptions lub ListBlobsHierarchyOptions.

Filtrowanie wyników za pomocą prefiksu

Aby przefiltrować listę zwracanych obiektów blob, określ ciąg lub znak dla Prefix pola w ListBlobsFlatOptions lub ListBlobsHierarchyOptions. 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.

Dołącz metadane obiektu blob lub inne informacje

Aby uwzględnić metadane obiektu blob z wynikami, ustaw pole Metadata na true jako część ListBlobsInclude. Usługa Azure Storage zawiera metadane z każdym zwracanym obiektem blob, więc nie trzeba pobierać metadanych obiektu blob oddzielnie.

Zobacz ListBlobsInclude, aby uzyskać dodatkowe opcje dołączania migawek, wersji, tagów indeksu obiektów blob i innych informacji do wyników.

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 obiektu blob i jest wskazywany przez znak ogranicznika.

Aby zorganizować obiekty blob w katalogach wirtualnych, użyj znaku separatora 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 ogranicznika, możesz wybrać hierarchiczne wyświetlanie listy obiektów blob. W przypadku operacji listy hierarchicznej usługa Azure Storage zwraca dowolne 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 wyświetlania listy zwraca obiekty blob w płaskiej liście. Na liście płaskiej obiekty "blob" nie są zorganizowane według katalogu wirtualnego.

W poniższym przykładzie wymieniono obiekty blob w określonym kontenerze używając listy jednopoziomowej. Ten przykład obejmuje migawki obiektów blob i wersje obiektów blob, jeśli istnieją:

func listBlobsFlat(client *azblob.Client, containerName string) {
    // List the blobs in the container
    pager := client.NewListBlobsFlatPager(containerName, &azblob.ListBlobsFlatOptions{
        Include: azblob.ListBlobsInclude{Snapshots: true, Versions: true},
    })

    fmt.Println("List blobs flat:")
    for pager.More() {
        resp, err := pager.NextPage(context.TODO())
        handleError(err)

        for _, blob := range resp.Segment.BlobItems {
            fmt.Println(*blob.Name)
        }
    }
}

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

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

W poniższym przykładzie wymieniono obiekty blob w kontenerze, które rozpoczynają się od określonego prefiksu:

func listBlobsFlatOptions(client *azblob.Client, containerName string, prefix string) {
    // List the blobs in the container with a prefix
    pager := client.NewListBlobsFlatPager(containerName, &azblob.ListBlobsFlatOptions{
        Prefix: to.Ptr(prefix),
    })

    fmt.Println("List blobs with prefix:")
    for pager.More() {
        resp, err := pager.NextPage(context.TODO())
        handleError(err)

        for _, blob := range resp.Segment.BlobItems {
            fmt.Println(*blob.Name)
        }
    }
}

Gdy przekazujesz ciąg znaków „sample” jako prefiks, dane wyjściowe są podobne do:

List blobs with prefix:
sample-blob1.txt
sample-blob2.txt
sample-blob3.txt

Używanie listy hierarchicznej

Po hierarchicznym wywołaniu operacji listowania, usługa 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:

• NewListBlobsHierarchyPager

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 blobów 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.

func listBlobsHierarchy(client *azblob.Client, containerName string, prefix string) {
    // Reference the container as a client object
    containerClient := client.ServiceClient().NewContainerClient(containerName)

    pager := containerClient.NewListBlobsHierarchyPager("/", &container.ListBlobsHierarchyOptions{
        Prefix:     to.Ptr(prefix),
        MaxResults: to.Ptr(int32(1)), // MaxResults set to 1 for demonstration purposes
    })

    for pager.More() {
        resp, err := pager.NextPage(context.TODO())
        handleError(err)

        if resp.Segment.BlobPrefixes != nil {
            for _, prefix := range resp.Segment.BlobPrefixes {
                fmt.Println("Virtual directory prefix:", *prefix.Name)

                // Recursively list blobs in the prefix
                listBlobsHierarchy(client, containerName, *prefix.Name)
            }
        }

        for _, blob := range resp.Segment.BlobItems {
            fmt.Println("Blob:", *blob.Name)
        }
    }
}

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

Virtual directory prefix: folderA/
Blob: folderA/file1.txt
Blob: folderA/file2.txt
Blob: folderA/file3.txt
Virtual directory prefix: folderA/folderB/
Blob: folderA/folderB/file1.txt
Blob: folderA/folderB/file2.txt
Blob: folderA/folderB/file3.txt

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

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. SDK Go dekoduje Apache Arrow za kulisami i nadal zwraca te same BlobItem wartości. 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.

Aby zażądać wyników sformatowanych w Apache Arrow, ustaw ResponseFormat pole ListBlobsFlatOptions na StorageResponseFormatArrow, a następnie przekaż te opcje do NewListBlobsFlatPager. Korzystając z formatu wyjściowego Apache Arrow, możesz także ustawić pola StartFrom i EndBefore, 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:

import (
    "context"

    "github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob/container"
)

pager := client.NewListBlobsFlatPager("sample-container", &azblob.ListBlobsFlatOptions{
    Prefix:         to.Ptr("folderA/"),
    ResponseFormat: container.StorageResponseFormatArrow,
})

for pager.More() {
    resp, err := pager.NextPage(context.TODO())
    handleError(err)

    for _, blob := range resp.Segment.BlobItems {
        fmt.Println(*blob.Name)
    }
}

Zasoby

Aby dowiedzieć się więcej na temat wyświetlania listy obiektów blob przy użyciu modułu klienta usługi Azure Blob Storage dla języka Go, zobacz następujące zasoby.

Przykłady kodu

• Wyświetlanie przykładów kodu z tego artykułu (GitHub)

Operacje interfejsu API REST

Azure SDK for Go zawiera biblioteki budujące się na Azure REST API. Korzystając z tych bibliotek, możesz wchodzić w interakcje z operacjami REST API za pomocą znanych paradygmatów Go. 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 modułu klienta

• Dokumentacja referencyjna modułu klienta
• Kod źródłowy modułu klienta
• Pakiet (pkg.go.dev)

Zobacz też

• Wyliczanie zasobów Blob
• Wersjonowanie obiektów blob

Powiązana zawartość

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