Поделиться через

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

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

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

Prerequisites

Настройка

В этом разделе описывается подготовка проекта для работы с клиентским модулем хранилища 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 потребуется минута или две, но в редких случаях может потребоваться до восьми минут. Если при первом запуске кода возникают ошибки аутентификации, подождите несколько минут и повторите попытку.

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

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

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

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

    Снимок экрана, на котором продемонстрировано назначение роли.

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

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

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

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

Вход и подключение кода приложения к 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

  • Last updated on