Краткое руководство: клиентский модуль Azure Blob Storage для Go

Начните работать с модулем клиента Azure Blob Storage для Go для управления BLOB и контейнерами. Выполните приведенные здесь действия, чтобы установить пакет и протестировать пример кода для выполнения базовых задач.

Справочная документация по | APIИсходный код | библиотекиПакет (pkg.go.dev)

Prerequisites

• Подписка Azure — создайте бесплатную учетную запись.
• Учетная запись хранения Azure — создайте такую учетную запись.
• Go 1.18+

Настройка

В этом разделе описывается подготовка проекта для работы с клиентским модулем хранилища BLOB-объектов Azure для Go.

Скачивание примера приложения

Пример приложения, используемого в этом кратком руководстве, является базовым приложением Go.

Используйте git , чтобы скачать копию приложения в среду разработки.

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

Эта команда клонирует репозиторий в локальную папку Git. Чтобы открыть пример Go для хранилища BLOB-объектов, найдите файл с именем storage-quickstart.go.

Установка пакетов

Чтобы работать с ресурсами BLOB-объектов и контейнеров в учетной записи хранения, установите пакет azblob с помощью следующей команды:

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

Чтобы пройти проверку подлинности с помощью идентификатора Microsoft Entra (рекомендуется), установите модуль azidentity с помощью следующей команды:

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

Проверка подлинности в Azure и авторизация доступа к данным BLOB

Запросы приложений к Хранилищу BLOB-объектов Azure должны быть авторизованы. Использование DefaultAzureCredential и клиентской библиотеки удостоверений Azure — это рекомендуемый подход для реализации беспарольных подключений к службам Azure в вашем коде, включая хранилище объектов Blob.

Вы также можете авторизовать запросы к Хранилищу BLOB-объектов Azure с помощью ключа доступа к учетной записи. Однако этот подход следует использовать с осторожностью. Разработчики должны тщательно следить за тем, чтобы не раскрыть ключи доступа в незащищенном расположении. Любой пользователь, имеющий ключ доступа, может авторизовать запросы к учетной записи хранения и эффективно иметь доступ ко всем данным. DefaultAzureCredential предлагает улучшенные преимущества управления и безопасности по сравнению с ключом учетной записи, чтобы разрешить проверку подлинности без пароля. Оба варианта показаны в следующем примере.

DefaultAzureCredential — это реализация цепочки учетных данных, предоставляемая клиентской библиотекой удостоверений Azure для Go. DefaultAzureCredential поддерживает несколько методов проверки подлинности и определяет, какой метод следует использовать во время выполнения. Такой подход позволяет приложению использовать различные способы проверки подлинности в разных средах (локальной и рабочей) без реализации кода для конкретной среды.

Дополнительные сведения о порядке и расположениях, в которых DefaultAzureCredential ищет учетные данные, см. в обзоре библиотеки удостоверений Azure.

Например, ваше приложение может пройти аутентификацию, используя ваши учетные данные для входа в Azure CLI, при разработке на локальном компьютере. После развертывания в Azure приложение может использовать управляемое удостоверение. Этот переход между средами не требует каких-либо изменений кода.

Назначение ролей учетной записи пользователя Microsoft Entra

Если вы выполняете разработку локально, убедитесь, что учетная запись пользователя, через которую осуществляется доступ к данным BLOB-объектов, имеет правильные разрешения. Вам потребуется роль Storage Blob Data Contributor для чтения и записи данных BLOB-объектов. Чтобы назначить себе эту роль, вам потребуется, чтобы вам назначили роль администратора доступа пользователей или другую роль, включающую действие Microsoft.Authorization/roleAssignments/write. Роли Azure RBAC можно назначить пользователю с помощью портала Azure, Azure CLI или Azure PowerShell. Дополнительные сведения о роли участника данных BLOB-объектов хранилища см. в разделе "Участник данных BLOB-объектов хранилища". Дополнительные сведения о доступных областях назначения ролей см. в статье "Общие сведения о области для Azure RBAC".

В этом сценарии вы назначите разрешения для вашей пользовательской учетной записи, ограничив их учетной записью хранения, чтобы обеспечить соблюдение принципа наименьших привилегий. В рамках этой практики пользователям предоставляются только минимальные необходимые разрешения, что позволяет создавать более защищенные рабочие среды.

В следующем примере вашему пользовательскому аккаунту назначается роль Участник данных BLOB-объектов хранилища, предоставляющая доступ как для чтения, так и для записи данных BLOB в вашей учетной записи хранилища.

Important

В большинстве случаев для распространения назначения ролей в Azure потребуется минута или две, но в редких случаях может потребоваться до восьми минут. Если при первом запуске кода возникают ошибки аутентификации, подождите несколько минут и повторите попытку.

Портал Azure

1. На портале Azure найдите свою учетную запись хранения, воспользовавшись основной панелью поиска или областью навигации слева.

2. На странице обзора учетной записи хранения выберите Контроль доступа (IAM) в меню слева.

3. На странице Контроль доступа (IAM) откройте вкладку Назначения ролей.

4. Выберите +Добавить из верхнего меню и добавьте назначение ролей из результирующего раскрывающегося меню.

   

5. Используйте поле поиска, чтобы отфильтровать результаты для отображения нужной роли. В этом примере найдите участника данных BLOB-объектов хранилища и выберите соответствующий результат, а затем нажмите кнопку Далее.

6. В разделе Назначение доступа выберите Пользователь, группа или сервисный принципал, а затем нажмите + Выбрать участников.

7. В диалоговом окне найдите имя пользователя Microsoft Entra (обычно ваш адрес электронной почты user@domain), а затем выберите Select в нижней части диалогового окна.

8. Нажмите кнопку Проверить и назначить, чтобы перейти на последнюю страницу, а затем еще раз Проверить и назначить, чтобы завершить процесс.

Azure CLI

Чтобы назначить роль на уровне ресурсов с помощью Azure CLI, сначала необходимо получить идентификатор ресурса с помощью команды az storage account show. Вы можете отфильтровать выходные свойства с помощью параметра --query.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

Скопируйте результат Id из предыдущей команды. Затем можно назначить роли с помощью команды az role в Azure CLI.

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

PowerShell

Чтобы назначить роль на уровне ресурсов с помощью Azure PowerShell, сначала необходимо получить идентификатор ресурса с помощью Get-AzResource команды.

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

Скопируйте значение Id из выходных данных предыдущей команды. После этого можно назначить роли с помощью команды New-AzRoleAssignment в PowerShell.

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

Вход и подключение кода приложения к Azure с помощью DefaultAzureCredential

Чтобы авторизовать доступ к данным в учетной записи хранения, выполните следующие действия:

1. Убедитесь, что вы прошли проверку подлинности с той же учетной записью Microsoft Entra, которой присвоена роль в вашей учетной записи хранилища. В следующем примере показано, как пройти проверку подлинности с помощью Azure CLI:

   az login
   

2. Чтобы использовать DefaultAzureCredential в приложении Go, установите модуль azidentity с помощью следующей команды:

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

Проверка подлинности Azure CLI не рекомендуется для приложений, работающих в Azure. При развертывании в Azure можно использовать тот же код для авторизации запросов в службу хранилища Azure из приложения, работающего в Azure. Однако необходимо включить управляемое удостоверение в приложении в Azure и настроить учетную запись хранения, чтобы разрешить подключение к управляемому удостоверению. Подробные инструкции по настройке этого подключения между службами Azure см. в учебнике по проверке подлинности в приложениях, размещенных в Azure.

Чтобы узнать больше о различных методах проверки подлинности, ознакомьтесь с методами проверки подлинности Azure с помощью Azure SDK для Go.

Запустите пример

В примере кода выполняются следующие действия:

• Создает клиентский объект, авторизованный для доступа к данным с помощью DefaultAzureCredential
• Создание контейнера в учетной записи хранения
• Загружает большой двоичный объект в контейнер
• Перечисление объектов в контейнере
• Загружает BLOB-данные в буфер
• Удаляет ресурсы объектов BLOB и контейнеров, созданные приложением

Перед запуском примера откройте файл storage-quickstart.go . Замените <storage-account-name> именем учетной записи хранения Azure.

Затем запустите приложение с помощью следующей команды:

go run storage-quickstart.go

Выходные данные приложения похожи на следующий пример:

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

При нажатии клавиши ВВОД в командной строке пример программы удаляет ресурсы блобов и контейнеров, созданные приложением.

Tip

Вы также можете использовать средство, например обозреватель службы хранилища Azure , для просмотра файлов в хранилище BLOB-объектов. Обозреватель службы хранилища Azure — это бесплатное кроссплатформенное средство, позволяющее получить доступ к сведениям учетной записи хранения.

Разбор примера кода

Далее мы рассмотрим пример кода, чтобы понять, как это работает.

Авторизация доступа и создание клиентского объекта

Работа с любым ресурсом Azure с помощью пакета SDK начинается с создания клиентского объекта. Для создания клиентского объекта пример кода вызывает azblob. NewClient со следующими значениями:

• serviceURL — URL-адрес учетной записи хранения
• cred — учетные данные Microsoft Entra, полученные с помощью azidentity модуля
• параметры — параметры клиента; передайте nil, чтобы принять значения по умолчанию

В следующем примере кода создается клиентский объект для взаимодействия с ресурсами контейнера и BLOB-объектов в учетной записи хранения:

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

Создание контейнера

В примере кода создается новый ресурс контейнера в учетной записи хранения. Если контейнер с тем же именем уже существует, возникает ошибка ResourceExistsError.

Important

Имена контейнеров должны состоять из знаков нижнего регистра. Дополнительные сведения о требованиях к именованию контейнеров и больших двоичных объектов см. в статье "Именование и ссылка на контейнеры", "Большие двоичные объекты" и "Метаданные".

В следующем примере кода создается новый контейнер с именем quickstart-sample-container в учетной записи хранения:

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

Дополнительные сведения о создании контейнера и изучении дополнительных примеров кода см. в статье "Создание контейнера BLOB-объектов с помощью Go".

Загрузка блобов в контейнер

Пример кода создает массив байтов с некоторыми данными, которые загружаются в виде буфера в новый ресурс Blob в указанном контейнере.

В следующем примере кода данные BLOB-объектов передаются в указанный контейнер с помощью метода 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)

Дополнительные сведения о отправке больших двоичных объектов и изучении дополнительных примеров кода см. в статье "Отправка большого двоичного объекта с помощью Go".

Перечисление BLOB-объектов в контейнере

В примере кода перечислены блобы в указанном контейнере. В этом примере используется NewListBlobsFlatPager, который возвращает механизм постраничной навигации для BLOB-объектов, начинающийся от указанного маркера. Здесь мы используем пустой маркер для запуска перечисления с самого начала и продолжаем разбиение по страницам, пока не будет больше результатов. Этот метод возвращает имена BLOB-объектов в лексографическом порядке.

В следующем примере кода перечислены блобы (BLOB) в указанном контейнере:

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

Дополнительные сведения о перечислении больших двоичных объектов и дополнительные примеры кода см. в разделе "Список больших двоичных объектов" с помощью Go.

Загрузите блоб

Пример кода загружает большой двоичный объект с помощью метода DownloadStream и создает читатель с повторными попытками для чтения данных. Если подключение завершается ошибкой при чтении, средство повторных попыток делает другие запросы, чтобы восстановить подключение и продолжить чтение. Параметры повторного чтения можно указать с помощью структуры RetryReaderOptions.

В следующем примере кода загружается блоб, а его содержимое выводится на консоль.

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

Дополнительные сведения о скачивании больших двоичных объектов и дополнительные примеры кода см. в статье "Скачать большой двоичный объект с помощью Go".

Очистите ресурсы

Если вам больше не нужны блобы, загруженные в этом кратком руководстве, можно удалить отдельный блоб с помощью метода DeleteBlob или удалить весь контейнер вместе с его содержимым с помощью метода 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)

Дополнительные сведения об удалении больших двоичных объектов и контейнеров и изучении дополнительных примеров кода см. в статье "Удаление большого двоичного объекта с помощью Go " и "Удаление контейнера" с помощью Go.

Следующий шаг

Руководства разработчика по Azure Blob-хранилищу на языке Go