Rychlý start: Klientská knihovna služby Azure Blob Storage pro Go

  • Článek

Začínáme s klientskou knihovnou Azure Blob Storage pro Go pro správu objektů blob a kontejnerů Pomocí těchto kroků nainstalujte balíček a vyzkoušejte si ukázkový kód pro základní úlohy.

Referenční dokumentace k | rozhraní API – Balíček zdrojového kódu | knihovny (pkg.go.dev)

Předpoklady

Nastavení

Tato část vás provede přípravou projektu pro práci s klientskou knihovnou služby Azure Blob Storage pro Go.

Stažení ukázkové aplikace

Ukázková aplikace použitá v tomto rychlém startu je základní aplikace v jazyce Go.

Pomocí gitu stáhněte kopii aplikace do svého vývojového prostředí.

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

Tento příkaz naklonuje úložiště do vaší místní složky gitu. Pokud chcete otevřít ukázku Go pro Blob Storage, vyhledejte soubor s názvem storage-quickstart.go.

Instalace balíčků

Pokud chcete pracovat s prostředky objektů blob a kontejneru v účtu úložiště, nainstalujte balíček azblob pomocí následujícího příkazu:

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

Pokud chcete provést ověření pomocí Microsoft Entra ID (doporučeno), nainstalujte modul azidentity pomocí následujícího příkazu:

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

Ověřování v Azure a autorizace přístupu k datům objektů blob

Žádosti aplikací do služby Azure Blob Storage musí být autorizované. Použití DefaultAzureCredential a klientská knihovna Azure Identity je doporučeným přístupem k implementaci bez hesel připojení ke službám Azure ve vašem kódu, včetně služby Blob Storage.

Žádosti o službu Azure Blob Storage můžete také autorizovat pomocí přístupového klíče účtu. Tento přístup by však měl být používán s opatrností. Vývojáři musí být usilovní, aby nikdy nezpřístupnil přístupový klíč v nezabezpečeném umístění. Každý, kdo má přístupový klíč, může autorizovat požadavky na účet úložiště a efektivně má přístup ke všem datům. DefaultAzureCredential nabízí vylepšené výhody správy a zabezpečení oproti klíči účtu, které umožňují ověřování bez hesla. Obě možnosti jsou demonstrována v následujícím příkladu.

DefaultAzureCredential je implementace řetězu přihlašovacích údajů poskytovaná klientskou knihovnou Azure Identity for Go. DefaultAzureCredential podporuje více metod ověřování a určuje, kterou metodu použít za běhu. Tento přístup umožňuje vaší aplikaci používat různé metody ověřování v různých prostředích (místní a produkční) bez implementace kódu specifického pro prostředí.

Další informace o pořadí a umístěních, ve kterých DefaultAzureCredential se hledají přihlašovací údaje, najdete v přehledu knihovny identit Azure.

Vaše aplikace se například může ověřit pomocí přihlašovacích údajů Azure CLI při místním vývoji. Po nasazení do Azure může vaše aplikace používat spravovanou identitu. Tento přechod mezi prostředími nevyžaduje žádné změny kódu.

Přiřazení rolí k uživatelskému účtu Microsoft Entra

Při místním vývoji se ujistěte, že uživatelský účet, který přistupuje k datům objektů blob, má správná oprávnění. K čtení a zápisu dat objektů blob budete potřebovat Přispěvatel dat objektů blob služby Storage. Abyste mohli tuto roli přiřadit sami sobě, musíte mít přiřazenou roli User Access Správa istrator nebo jinou roli, která zahrnuje akci Microsoft.Authorization/roleAssignments/write. Role Azure RBAC můžete uživateli přiřadit pomocí webu Azure Portal, Azure CLI nebo Azure PowerShellu. Další informace o dostupných oborech pro přiřazení rolí najdete na stránce přehledu oboru.

V tomto scénáři přiřadíte oprávnění k vašemu uživatelskému účtu s vymezeným oborem účtu úložiště, abyste postupovali podle zásady nejnižších oprávnění. Tento postup poskytuje uživatelům jenom minimální potřebná oprávnění a vytváří bezpečnější produkční prostředí.

Následující příklad přiřadí roli Přispěvatel dat v objektech blob služby Storage k vašemu uživatelskému účtu, který poskytuje přístup ke čtení i zápisu k datům objektů blob v účtu úložiště.

Důležité

Ve většině případů bude trvat minutu nebo dvě, než se přiřazení role rozšíří v Azure, ale ve výjimečných případech může trvat až osm minut. Pokud při prvním spuštění kódu dojde k chybám ověřování, chvíli počkejte a zkuste to znovu.

  1. Na webu Azure Portal vyhledejte svůj účet úložiště pomocí hlavního panelu hledání nebo levé navigace.

  2. Na stránce přehledu účtu úložiště v nabídce vlevo vyberte Řízení přístupu (IAM ).

  3. Na stránce Řízení přístupu (IAM) vyberte kartu Přiřazení rolí.

  4. V horní nabídce vyberte + Přidat a potom přidejte přiřazení role z výsledné rozevírací nabídky.

    A screenshot showing how to assign a role.

  5. Pomocí vyhledávacího pole vyfiltrujte výsledky podle požadované role. V tomto příkladu vyhledejte Přispěvatel dat objektů blob služby Storage a vyberte odpovídající výsledek a pak zvolte Další.

  6. V části Přiřadit přístup vyberte Uživatel, skupina nebo instanční objekt a pak zvolte + Vybrat členy.

  7. V dialogovém okně vyhledejte své uživatelské jméno Microsoft Entra (obvykle vaše user@domain e-mailová adresa) a pak v dolní části dialogového okna zvolte Vybrat .

  8. Vyberte Zkontrolovat a přiřadit přejděte na poslední stránku a pak proces dokončete opětovnou kontrolou a přiřazením .

Přihlášení a připojení kódu aplikace k Azure pomocí DefaultAzureCredential

Přístup k datům v účtu úložiště můžete autorizovat pomocí následujícího postupu:

  1. Ujistěte se, že jste ověřeni pomocí stejného účtu Microsoft Entra, ke kterému jste přiřadili roli k účtu úložiště. Následující příklad ukazuje, jak provést ověření pomocí Azure CLI:

    az login

  2. Pokud chcete použít DefaultAzureCredential v aplikaci Go, nainstalujte modul azidentity pomocí následujícího příkazu::

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

Ověřování Azure CLI se nedoporučuje pro aplikace spuštěné v Azure. Při nasazení do Azure můžete použít stejný kód k autorizaci požadavků na Azure Storage z aplikace spuštěné v Azure. Musíte ale ve své aplikaci v Azure povolit spravovanou identitu a nakonfigurovat účet úložiště tak, aby se tato spravovaná identita mohla připojit. Podrobné pokyny ke konfiguraci tohoto připojení mezi službami Azure najdete v kurzu ověřování z aplikací hostovaných v Azure.

Další informace o různých metodách ověřování najdete v tématu Ověřování Azure pomocí sady Azure SDK for Go.

Spuštění ukázky

Příklad kódu provádí následující akce:

  • Vytvoří objekt klienta autorizovaný pro přístup k datům prostřednictvím DefaultAzureCredential
  • Vytvoří kontejner v účtu úložiště.
  • Nahraje objekt blob do kontejneru.
  • Vypíše objekty blob v kontejneru.
  • Stáhne data objektu blob do vyrovnávací paměti.
  • Odstraní objekt blob a prostředky kontejneru vytvořené aplikací.

Před spuštěním ukázky otevřete soubor storage-quickstart.go . Nahraďte <storage-account-name> názvem svého účtu úložiště Azure.

Pak aplikaci spusťte pomocí následujícího příkazu:

go run storage-quickstart.go

Výstup aplikace je podobný následujícímu příkladu:

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

Když na příkazovém řádku stisknete klávesu Enter, ukázkový program odstraní prostředky objektů blob a kontejneru vytvořené aplikací.

Tip

K zobrazení souborů v úložišti objektů blob můžete použít také nástroj, jako je Průzkumník služby Azure Storage. Průzkumník služby Azure Storage je bezplatný nástroj pro více platforem, který umožňuje přístup k informacím o účtu úložiště.

Vysvětlení vzorového kódu

Dále si projdeme vzorový kód, abychom pochopili, jak funguje.

Autorizace přístupu a vytvoření objektu klienta

Práce s libovolným prostředkem Azure pomocí sady SDK začíná vytvořením objektu klienta. Pokud chcete vytvořit objekt klienta, vzorový kód volá azblob. NewClient s následujícími hodnotami:

  • serviceURL – adresa URL účtu úložiště
  • cred – přihlašovací údaje Microsoft Entra získané prostřednictvím azidentity modulu
  • options - client options; pass nil to accept the default values

Následující příklad kódu vytvoří objekt klienta pro interakci s prostředky kontejneru a objektů blob v účtu úložiště:

// 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)

Vytvoření kontejneru

Ukázka kódu vytvoří nový prostředek kontejneru v účtu úložiště. Pokud kontejner se stejným názvem již existuje, ResourceExistsError vyvolá se.

Důležité

Názvy kontejnerů musí být malými písmeny. Další informace o požadavcích na pojmenování kontejnerů a objektů blob najdete v tématu Pojmenování a odkazování na kontejnery, objekty blob a metadata.

Následující příklad kódu vytvoří nový kontejner s názvem quickstart-sample-container v účtu úložiště:

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

Nahrání objektů blob do kontejneru

Ukázka kódu vytvoří pole bajtů s některými daty a nahraje data jako vyrovnávací paměť do nového prostředku objektu blob v zadaném kontejneru.

Následující příklad kódu nahraje data objektu blob do zadaného kontejneru pomocí 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)

Seznam objektů blob v kontejneru

Ukázka kódu vypíše objekty blob v zadaném kontejneru. Tento příklad používá NewListBlobsFlatPager, který vrátí pager pro objekty blob počínaje zadanou značkou. Tady použijeme prázdnou značku k zahájení výčtu od začátku a pokračujeme ve stránkování, dokud nebudou k dispozici žádné další výsledky. Tato metoda vrací názvy objektů blob v lexicografickém pořadí.

Následující příklad kódu uvádí objekty blob v zadaném kontejneru:

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

Stažení objektu blob

Ukázka kódu stáhne objekt blob pomocí metody DownloadStream a vytvoří čtečku opakování pro čtení dat. Pokud se připojení při čtení nezdaří, čtečka opakování provede další požadavky na opětovné navázání připojení a pokračovat ve čtení. Možnosti čtečky opakování můžete zadat pomocí struktury RetryReaderOptions .

Následující příklad kódu stáhne objekt blob a zapíše obsah do konzoly:

// 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())

Vyčištění prostředků

Pokud už nepotřebujete objekty blob nahrané v tomto rychlém startu, můžete jednotlivé objekty blob odstranit pomocí metody DeleteBlob nebo celého kontejneru a jeho obsahu pomocí 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)

Další kroky

V tomto rychlém startu jste se naučili nahrávat, stahovat a vypisovat objekty blob pomocí Jazyka Go.

Pokud chcete zobrazit ukázkové aplikace Blob Storage, pokračujte následujícími:

Ukázky služby Azure Blob Storage pro Go