Краткое руководство. Хранилище BLOB-объектов Azure клиентская библиотека для Go

Статья
08/29/2023

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

Пакет исходного кода библиотеки исходного кода | библиотеки | API (pkg.go.dev)

Необходимые компоненты

Подписка 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-объектов, имеет правильные разрешения. Вам потребуется служба хранилища участник данных BLOB-объектов для чтения и записи данных BLOB-объектов. Чтобы назначить себе эту роль, вам потребуется назначить роль Администратор istrator для доступа пользователей или другую роль, включающую действие Microsoft.Authorization/roleAssignments/write. Роли Azure RBAC можно назначить пользователю с помощью портала Azure, Azure CLI или Azure PowerShell. Дополнительные сведения о доступных областях назначения ролей можно узнать на странице обзора области.

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

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

Важно!

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

На портале Azure найдите свою учетную запись хранения, воспользовавшись основной панелью поиска или областью навигации слева.
На странице обзора учетной записи хранения выберите Контроль доступа (IAM) в меню слева.
На странице Контроль доступа (IAM) откройте вкладку Назначения ролей.
Выберите + Добавить в верхнем меню, а затем выберите Добавить назначение роли в появившемся раскрывающемся меню.
Используйте поле поиска, чтобы отфильтровать результаты для отображения нужной роли. В этом примере найдите участника данных BLOB-объектов хранилища и выберите соответствующий результат, а затем нажмите кнопку Далее.
В разделе Назначение доступа для выберите Пользователь, группа или субъект-служба и + Выбрать членов.
В диалоговом окне найдите имя пользователя Microsoft Entra (обычно ваш user@domain адрес электронной почты), а затем выберите в нижней части диалогового окна.
Нажмите кнопку Проверить и назначить, чтобы перейти на последнюю страницу, а затем еще раз Проверить и назначить, чтобы завершить процесс.

Чтобы назначить роль на уровне ресурсов с помощью 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>"

Чтобы назначить роль на уровне ресурсов с помощью 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>

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

Убедитесь, что вы прошли проверку подлинности с той же учетной записью Microsoft Entra, которую вы назначили роль учетной записи хранения. В следующем примере показано, как пройти проверку подлинности с помощью Azure CLI:
```
az login
```
Чтобы использовать DefaultAzureCredential в приложении Go, установите модуль azidentity с помощью следующей команды::
```
go get github.com/Azure/azure-sdk-for-go/sdk/azidentity
```

Не рекомендуем выполнять аутентификацию Azure CLI для приложений, работающих в 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

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

Совет

Для просмотра файлов в хранилище BLOB-объектов можно также воспользоваться таким средством, как обозреватель службы хранилища Azure. Обозреватель службы хранилища 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 создается контейнер.

Важно!

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

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

Пример кода создает массив байтов с некоторыми данными и отправляет данные в качестве буфера в новый ресурс большого двоичного объекта в указанном контейнере.

В следующем примере кода данные 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)

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

В примере кода перечислены большие двоичные объекты в указанном контейнере. В этом примере используется NewListBlobsFlatPager, который возвращает пейджер для больших двоичных объектов, начиная с указанного маркера. Здесь мы используем пустой маркер для запуска перечисления с самого начала и продолжаем разбиение по страницам, пока не будет больше результатов. Этот метод возвращает имена 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)
	}
}

Скачивание большого двоичного объекта

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

Очистка ресурсов

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

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

библиотека Хранилище BLOB-объектов Azure для примеров Go

Дополнительные сведения см. в клиентской библиотеке Хранилище BLOB-объектов Azure для Go.
Руководства, примеры, краткие руководства и другие документы см. в Azure для разработчиков Go.