Szybki start: moduł klienta usługi Azure Blob Storage dla języka Go
Rozpocznij pracę z modułem 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
- Subskrypcja platformy Azure — utwórz jedną bezpłatnie
- Konto usługi Azure Storage — tworzenie konta magazynu
- Przejdź do wersji 1.18 lub nowszej
Konfigurowanie
Ta sekcja przeprowadzi Cię przez proces przygotowywania projektu do pracy z modułem 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 mieć przypisaną rolę Administratora 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.
W witrynie Azure Portal znajdź konto magazynu przy użyciu głównego paska wyszukiwania lub nawigacji po lewej stronie.
Na stronie przeglądu konta magazynu wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami) z menu po lewej stronie.
Na stronie Kontrola dostępu (Zarządzanie dostępem i tożsamościami) wybierz kartę Przypisania ról.
Wybierz pozycję + Dodaj z górnego menu, a następnie pozycję Dodaj przypisanie roli z wyświetlonego menu rozwijanego.
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.
W obszarze Przypisz dostęp do wybierz pozycję Użytkownik, grupa lub jednostka usługi, a następnie wybierz pozycję + Wybierz członków.
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.
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:
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 loginAby użyć
DefaultAzureCredentialw 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 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)
Aby dowiedzieć się więcej o tworzeniu kontenera i eksplorować więcej przykładów kodu, zobacz Tworzenie kontenera obiektów blob za pomocą języka Go.
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)
Aby dowiedzieć się więcej na temat przekazywania obiektów blob i eksplorowania dodatkowych przykładów kodu, zobacz Przekazywanie obiektu blob za pomocą języka Go.
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)
}
}
Aby dowiedzieć się więcej o wyświetlaniu listy obiektów blob i poznać więcej przykładów kodu, zobacz Wyświetlanie listy obiektów blob za pomocą języka Go.
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())
Aby dowiedzieć się więcej na temat pobierania obiektów blob i eksplorowania dodatkowych przykładów kodu, zobacz Pobieranie obiektu blob za pomocą języka Go.
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)
Aby dowiedzieć się więcej o usuwaniu obiektów blob i kontenerów oraz poznać więcej przykładów kodu, zobacz Usuwanie obiektu blob przy użyciu języka Go i Usuwanie kontenera za pomocą języka Go.