Szybki start: biblioteka klienta usługi Azure Blob Storage dla języka Go

  • Artykuł

Rozpocznij pracę z biblioteką klienta usługi Azure Blob Storage dla języka Go, aby zarządzać obiektami blob i kontenerami. Wykonaj następujące kroki, aby zainstalować pakiet i wypróbować przykładowy kod dla podstawowych zadań.

Dokumentacja interfejsu API — pakiet | kodu | źródłowego biblioteki (pkg.go.dev)

Wymagania wstępne

Konfigurowanie

Ta sekcja przeprowadzi Cię przez proces przygotowywania projektu do pracy z biblioteką klienta usługi Azure Blob Storage dla języka Go.

Pobieranie przykładowej aplikacji

Przykładowa aplikacja używana w tym przewodniku Szybki start to podstawowa aplikacja w języku Go.

Użyj narzędzia git, aby pobrać kopię tej aplikacji do swojego środowiska projektowego.

git clone https://github.com/Azure-Samples/storage-blobs-go-quickstart

To polecenie klonuje repozytorium do lokalnego folderu git. Aby otworzyć przykład języka Go dla usługi Blob Storage, poszukaj pliku o nazwie storage-quickstart.go.

Instalowanie pakietów

Aby pracować z zasobami obiektów blob i kontenerów na koncie magazynu, zainstaluj pakiet 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 moduł azidentity przy użyciu następującego polecenia:

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

Uwierzytelnianie na platformie Azure i autoryzacja dostępu do danych obiektów blob

Żądania aplikacji do usługi Azure Blob Storage muszą być autoryzowane. Użycie DefaultAzureCredential biblioteki klienta tożsamości platformy Azure to zalecane podejście do implementowania połączeń bez hasła z usługami platformy Azure w kodzie, w tym usługi Blob Storage.

Możesz również autoryzować żądania do usługi Azure Blob Storage przy użyciu klucza dostępu do konta. Należy jednak zachować ostrożność przy użyciu tego podejścia. Deweloperzy muszą być sumienni, aby nigdy nie ujawniać klucza dostępu w niezabezpieczonej lokalizacji. Każdy, kto ma klucz dostępu, może autoryzować żądania względem konta magazynu i efektywnie ma dostęp do wszystkich danych. DefaultAzureCredential oferuje ulepszone korzyści związane z zarządzaniem i zabezpieczeniami za pośrednictwem klucza konta, aby umożliwić uwierzytelnianie bez hasła. Obie opcje przedstawiono w poniższym przykładzie.

DefaultAzureCredential to implementacja łańcucha poświadczeń dostarczana przez bibliotekę klienta tożsamości platformy Azure dla języka Go. DefaultAzureCredential obsługuje wiele metod uwierzytelniania i określa, która metoda ma być używana w czasie wykonywania. Takie podejście umożliwia aplikacji używanie różnych metod uwierzytelniania w różnych środowiskach (lokalnych i produkcyjnych) bez implementowania kodu specyficznego dla środowiska.

Aby dowiedzieć się więcej o kolejności i lokalizacjach, w których DefaultAzureCredential szukasz poświadczeń, zobacz Omówienie biblioteki tożsamości platformy Azure.

Na przykład aplikacja może uwierzytelniać się przy użyciu poświadczeń logowania interfejsu wiersza polecenia platformy Azure w środowisku lokalnym. Po wdrożeniu na platformie Azure aplikacja może następnie użyć tożsamości zarządzanej. To przejście między środowiskami nie wymaga żadnych zmian w kodzie.

Przypisywanie ról do konta użytkownika usługi Microsoft Entra

Podczas tworzenia aplikacji lokalnie upewnij się, że konto użytkownika, które uzyskuje dostęp do danych obiektów blob, ma odpowiednie uprawnienia. Będziesz potrzebować współautora danych obiektu blob usługi Storage, aby odczytywać i zapisywać dane obiektów blob. Aby przypisać sobie tę rolę, musisz przypisać rolę Administracja istratora dostępu użytkowników lub inną rolę obejmującą akcję Microsoft.Authorization/roleAssignments/write. Role RBAC platformy Azure można przypisać użytkownikowi przy użyciu witryny Azure Portal, interfejsu wiersza polecenia platformy Azure lub programu Azure PowerShell. Więcej informacji na temat dostępnych zakresów przypisań ról można znaleźć na stronie przeglądu zakresu.

W tym scenariuszu przypiszesz uprawnienia do konta użytkownika w zakresie konta magazynu, aby postępować zgodnie z zasadą najniższych uprawnień. Ta praktyka zapewnia użytkownikom tylko minimalne wymagane uprawnienia i tworzy bezpieczniejsze środowiska produkcyjne.

W poniższym przykładzie do konta użytkownika zostanie przypisana rola Współautor danych obiektu blob usługi Storage, która zapewnia zarówno dostęp do odczytu, jak i zapisu do danych obiektów blob na koncie magazynu.

Ważne

W większości przypadków propagacja przypisania roli na platformie Azure potrwa minutę lub dwie, ale w rzadkich przypadkach może upłynąć do ośmiu minut. Jeśli podczas pierwszego uruchomienia kodu wystąpią błędy uwierzytelniania, zaczekaj chwilę i spróbuj ponownie.

  1. W witrynie Azure Portal znajdź konto magazynu przy użyciu głównego paska wyszukiwania lub nawigacji po lewej stronie.

  2. Na stronie przeglądu konta magazynu wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami) z menu po lewej stronie.

  3. Na stronie Kontrola dostępu (Zarządzanie dostępem i tożsamościami) wybierz kartę Przypisania ról.

  4. Wybierz pozycję + Dodaj z górnego menu, a następnie pozycję Dodaj przypisanie roli z wyświetlonego menu rozwijanego.

    A screenshot showing how to assign a role.

  5. Użyj pola wyszukiwania, aby filtrować wyniki do żądanej roli. W tym przykładzie wyszukaj pozycję Współautor danych obiektu blob usługi Storage i wybierz pasujący wynik, a następnie wybierz pozycję Dalej.

  6. W obszarze Przypisz dostęp do wybierz pozycję Użytkownik, grupa lub jednostka usługi, a następnie wybierz pozycję + Wybierz członków.

  7. W oknie dialogowym wyszukaj nazwę użytkownika firmy Microsoft Entra (zazwyczaj adres e-mail user@domain ), a następnie wybierz pozycję Wybierz w dolnej części okna dialogowego.

  8. Wybierz pozycję Przejrzyj i przypisz , aby przejść do ostatniej strony, a następnie ponownie przejrzyj i przypisz, aby ukończyć proces.

Zaloguj się i połącz kod aplikacji z platformą Azure przy użyciu opcji DefaultAzureCredential

Dostęp do danych na koncie magazynu można autoryzować, wykonując następujące czynności:

  1. Upewnij się, że uwierzytelniasz się przy użyciu tego samego konta Microsoft Entra, do którego przypisano rolę na koncie magazynu. W poniższym przykładzie pokazano, jak uwierzytelniać się za pośrednictwem interfejsu wiersza polecenia platformy Azure:

    az login

  2. Aby użyć DefaultAzureCredential w aplikacji Języka Go, zainstaluj moduł azidentity przy użyciu następującego polecenia::

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

Uwierzytelnianie interfejsu wiersza polecenia platformy Azure nie jest zalecane w przypadku aplikacji działających na platformie Azure. Po wdrożeniu na platformie Azure można użyć tego samego kodu, aby autoryzować żądania do usługi Azure Storage z poziomu aplikacji działającej na platformie Azure. Należy jednak włączyć tożsamość zarządzaną w aplikacji na platformie Azure i skonfigurować konto magazynu, aby umożliwić nawiązywanie połączenia z tożsamością zarządzaną. Aby uzyskać szczegółowe instrukcje dotyczące konfigurowania tego połączenia między usługami platformy Azure, zobacz samouczek Auth from Azure-hosted apps (Uwierzytelnianie z poziomu aplikacji hostowanych na platformie Azure).

Aby dowiedzieć się więcej na temat różnych metod uwierzytelniania, zapoznaj się z tematem Uwierzytelnianie platformy Azure za pomocą zestawu Azure SDK dla języka Go.

Uruchamianie aplikacji przykładowej

Przykładowy kod wykonuje następujące akcje:

  • Tworzy obiekt klienta autoryzowany do uzyskiwania dostępu do danych za pośrednictwem DefaultAzureCredential
  • Tworzy kontener na koncie magazynu
  • Przekazuje obiekt blob do kontenera
  • Wyświetla listę obiektów blob w kontenerze
  • Pobiera dane obiektu blob do buforu
  • Usuwa zasoby obiektu blob i kontenera utworzone przez aplikację

Przed uruchomieniem przykładu otwórz plik storage-quickstart.go . Zastąp <storage-account-name> ciąg nazwą konta usługi Azure Storage.

Następnie uruchom aplikację przy użyciu następującego polecenia:

go run storage-quickstart.go

Dane wyjściowe aplikacji są podobne do następującego przykładu:

Azure Blob storage quick start sample
Creating a container named quickstart-sample-container
Uploading a blob named sample-blob
Listing the blobs in the container:
sample-blob
Blob contents:

Hello, world! This is a blob.

Press enter key to delete resources and exit the application.

Cleaning up.
Deleting the blob sample-blob
Deleting the container quickstart-sample-container

Po naciśnięciu klawisza Enter w wierszu polecenia przykładowy program usuwa zasoby obiektu blob i kontenera utworzone przez aplikację.

Napiwek

Możesz również wyświetlić pliki w usłudze Blob Storage za pomocą narzędzia takiego jak Eksplorator usługi Azure Storage. Eksplorator usługi Azure Storage to darmowe narzędzie międzyplatformowe, które umożliwia dostęp do informacji na koncie magazynu.

Omówienie przykładowego kodu

Następnie omówimy przykładowy kod, aby zrozumieć, jak działa.

Autoryzowanie dostępu i tworzenie obiektu klienta

Praca z dowolnym zasobem platformy Azure przy użyciu zestawu SDK rozpoczyna się od utworzenia obiektu klienta. Aby utworzyć obiekt klienta, przykładowy kod wywołuje polecenie azblob. NewClient z następującymi wartościami:

  • serviceURL — adres URL konta magazynu
  • cred — poświadczenia entra firmy Microsoft uzyskane za pośrednictwem modułu azidentity
  • opcje — opcje klienta; przekaż zero, aby zaakceptować wartości domyślne

Poniższy przykład kodu tworzy obiekt klienta do interakcji z zasobami kontenera i obiektów blob na koncie magazynu:

// TODO: replace <storage-account-name> with your actual storage account name
url := "https://<storage-account-name>.blob.core.windows.net/"
ctx := context.Background()

credential, err := azidentity.NewDefaultAzureCredential(nil)
handleError(err)

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

Tworzenie kontenera

Przykładowy kod tworzy nowy zasób kontenera na koncie magazynu. Jeśli kontener o tej samej nazwie już istnieje, ResourceExistsError zostanie zgłoszony element .

Ważne

Nazwy kontenerów muszą być zapisane małymi literami. Aby dowiedzieć się więcej na temat wymagań dotyczących nazewnictwa kontenerów i obiektów blob, zobacz Nazewnictwo i odwoływanie się do kontenerów, obiektów blob i metadanych.

Poniższy przykład kodu tworzy nowy kontener o nazwie quickstart-sample-container na koncie magazynu:

// Create the container
containerName := "quickstart-sample-container"
fmt.Printf("Creating a container named %s\n", containerName)
_, err = client.CreateContainer(ctx, containerName, nil)
handleError(err)

Przekazywanie obiektów blob do kontenera

Przykładowy kod tworzy tablicę bajtów z pewnymi danymi i przekazuje dane jako bufor do nowego zasobu obiektu blob w określonym kontenerze.

Poniższy przykład kodu przekazuje dane obiektu blob do określonego kontenera przy użyciu metody UploadBuffer :

data := []byte("\nHello, world! This is a blob.\n")
blobName := "sample-blob"

// Upload to data to blob storage
fmt.Printf("Uploading a blob named %s\n", blobName)
_, err = client.UploadBuffer(ctx, containerName, blobName, data, &azblob.UploadBufferOptions{})
handleError(err)

Wyświetlanie listy obiektów blob w kontenerze

Przykładowy kod wyświetla listę obiektów blob w określonym kontenerze. W tym przykładzie użyto polecenia NewListBlobsFlatPager, który zwraca pager dla obiektów blob rozpoczynających się od określonego znacznika. W tym miejscu użyjemy pustego znacznika, aby rozpocząć wyliczanie od początku i kontynuować stronicowanie, dopóki nie będzie już żadnych wyników. Ta metoda zwraca nazwy obiektów blob w kolejności leksykograficznej.

Poniższy przykład kodu zawiera listę obiektów blob w określonym kontenerze:

// List the blobs in the container
fmt.Println("Listing the blobs in the container:")

pager := client.NewListBlobsFlatPager(containerName, &azblob.ListBlobsFlatOptions{
	Include: azblob.ListBlobsInclude{Snapshots: true, Versions: true},
})

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

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

Pobieranie obiektu blob

Przykładowy kod pobiera obiekt blob przy użyciu metody DownloadStream i tworzy czytnik ponawiania prób odczytu danych. Jeśli połączenie nie powiedzie się podczas odczytywania, czytnik ponawia prób wysyła inne żądania, aby ponownie nawiązać połączenie i kontynuować odczytywanie. Opcje czytnika ponawiania można określić przy użyciu struktury RetryReaderOptions .

Poniższy przykładowy kod pobiera obiekt blob i zapisuje zawartość w konsoli:

// Download the blob
get, err := client.DownloadStream(ctx, containerName, blobName, nil)
handleError(err)

downloadedData := bytes.Buffer{}
retryReader := get.NewRetryReader(ctx, &azblob.RetryReaderOptions{})
_, err = downloadedData.ReadFrom(retryReader)
handleError(err)

err = retryReader.Close()
handleError(err)

// Print the contents of the blob we created
fmt.Println("Blob contents:")
fmt.Println(downloadedData.String())

Czyszczenie zasobów

Jeśli nie potrzebujesz już obiektów blob przekazanych w tym przewodniku Szybki start, możesz usunąć pojedynczy obiekt blob przy użyciu metody DeleteBlob lub całego kontenera i jego zawartości przy użyciu metody DeleteContainer.

// Delete the blob
fmt.Printf("Deleting the blob " + blobName + "\n")

_, err = client.DeleteBlob(ctx, containerName, blobName, nil)
handleError(err)

// Delete the container
fmt.Printf("Deleting the container " + containerName + "\n")
_, err = client.DeleteContainer(ctx, containerName, nil)
handleError(err)

Następne kroki

W tym przewodniku Szybki start przedstawiono sposób przekazywania, pobierania i wyświetlania listy obiektów blob przy użyciu języka Go.

Aby wyświetlić przykładowe aplikacje usługi Blob Storage, przejdź do:

Biblioteka usługi Azure Blob Storage dla przykładów języka Go