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

Примечание.

В разделе "Сборка с нуля " пошаговые инструкции по созданию проекта, установке пакетов, написанию кода и запуску базового консольного приложения. Этот подход рекомендуется, если вы хотите понять все сведения, связанные с созданием приложения, которое подключается к Хранилище BLOB-объектов Azure. Если вы предпочитаете автоматизировать задачи развертывания и начинать работу с завершенным проектом, выберите "Начать с шаблона".

Примечание.

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

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

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

В этой статье вы используете интерфейс командной строки разработчика Azure для развертывания ресурсов Azure и запуска полного консольного приложения с несколькими командами.

Примеры пакета исходного кода библиотеки исходного кода | библиотеки | API (PyPi) |

В этом видео показано, как начать использовать клиентская библиотека Хранилище BLOB-объектов Azure для Python.

Действия в видео также описаны в следующих разделах.

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

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

• Подписка Azure — создайте бесплатную учетную запись.
• Python 3.8+
• Интерфейс командной строки разработчика Azure

Установка

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

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

Создайте приложение Python с именем BLOB-quickstart.

1. В окне консоли (например, PowerShell или Bash) создайте новый каталог для проекта:

   mkdir blob-quickstart
   

2. Перейдите в только что созданный каталог blob-quickstart :

   cd blob-quickstart
   

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

В каталоге проекта установите пакеты для клиентских библиотек Хранилище BLOB-объектов Azure и удостоверений Azure с помощью pip install команды. Пакет azure-identity необходим для бессерверных подключений к службам Azure.

pip install azure-storage-blob azure-identity

Настройка платформы приложения

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

1. Откройте новый текстовый файл в редакторе кода.
2. Добавьте import инструкции, создайте структуру для программы и включите базовую обработку исключений, как показано ниже.
3. Сохраните новый файл как blob_quickstart.py в каталоге blob-quickstart .

import os, uuid
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobClient, ContainerClient

try:
    print("Azure Blob Storage Python quickstart sample")

    # Quickstart code goes here

except Exception as ex:
    print('Exception:')
    print(ex)

С установленным интерфейсом командной строки разработчика Azure можно создать учетную запись хранения и запустить пример кода с помощью нескольких команд. Проект можно запустить в локальной среде разработки или в DevContainer.

Инициализация шаблона интерфейса командной строки разработчика Azure и развертывание ресурсов

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

• Клонируйте ресурсы репозитория быстрого запуска из GitHub и инициализирует шаблон локально:

  azd init --template blob-storage-quickstart-python
  

  Вам будет предложено получить следующие сведения:

  • Имя среды: это значение используется в качестве префикса для всех ресурсов Azure, созданных Azure Developer CLI. Имя должно быть уникальным для всех подписок Azure и должно составлять от 3 до 24 символов. Имя может содержать только цифры и строчные буквы.

• Войдите в Azure:

  azd auth login
  

• Подготовка и развертывание ресурсов в Azure:

  azd up
  

  Вам будет предложено получить следующие сведения:

  • Подписка: подписка Azure, в которую развертываются ваши ресурсы.
  • Расположение: регион Azure, в котором развернуты ресурсы.

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

Запуск примера кода

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

• Установите пакеты: в локальном каталоге установите пакеты для клиентских библиотек Хранилище BLOB-объектов Azure и удостоверений Azure с помощью следующей команды:pip install azure-storage-blob azure-identity
• Обновите имя учетной записи хранения: в локальном каталоге измените файл с именем blob_quickstart.py. <storage-account-name> Найдите заполнитель и замените его фактическим именем учетной записи хранения, созданной командойazd up. Сохраните изменения.
• Запустите проект: выполните следующую команду, чтобы запустить приложение: python blob_quickstart.py
• Просмотрите выходные данные: это приложение создает тестовый файл в локальной папке данных и отправляет его в контейнер в учетной записи хранения. После этого выводится список больших двоичных объектов в контейнере, а затем файл загружается с новым именем, чтобы можно было сравнить старый и новый файлы.

Дополнительные сведения о работе примера кода см . в примерах кода.

После завершения тестирования кода см . раздел "Очистка ресурсов ", чтобы удалить ресурсы, созданные командой azd up .

Объектная модель

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

• учетная запись хранения;
• контейнер в учетной записи хранения;
• большой двоичный объект в контейнере.

На следующей схеме показана связь между этими ресурсами:

Используйте следующие классы Python для взаимодействия с этими ресурсами.

• BlobServiceClient: класс BlobServiceClient позволяет управлять ресурсами службы хранилища Azure и контейнерами BLOB-объектов.
• ContainerClient: класс ContainerClientпозволяет управлять контейнерами службы хранилища Azure и содержащимися в них большими двоичными объектами.
• BlobClient: класс BlobClient позволяет управлять BLOB-объектами службы хранилища Azure.

Примеры кода

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

• Проверка подлинности в Azure и авторизация доступа к данным BLOB-объектов
• Создание контейнера
• отправка больших двоичных объектов в контейнер;
• перечисление больших двоичных объектов в контейнере;
• скачивание больших двоичных объектов;
• Удаление контейнера

Примечание.

Шаблон ИНТЕРФЕЙСА командной строки разработчика Azure содержит файл с примером кода. В следующих примерах приведены подробные сведения для каждой части примера кода. Шаблон реализует рекомендуемый метод проверки подлинности без пароля, как описано в разделе "Проверка подлинности в Azure ". Метод строка подключения отображается как альтернатива, но не используется в шаблоне и не рекомендуется для рабочего кода.

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

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

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

Без пароля (рекомендуется)

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

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

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

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

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

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

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

Внимание

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

Портал Azure

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

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

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

4. Выберите + Добавить в верхнем меню, а затем выберите Добавить назначение роли в появившемся раскрывающемся меню.

   

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

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

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

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, Visual Studio Code или Azure PowerShell.

   Azure CLI

   Войдите в Azure с помощью Azure CLI, выполнив следующую команду:

   az login
   

   Visual Studio Code

   Для работы с DefaultAzureCredential Visual Studio Code необходимо установить Azure CLI.

   В главном меню Visual Studio Code выберите Терминал > Создать терминал.

   Войдите в Azure с помощью Azure CLI, выполнив следующую команду:

   az login
   

   PowerShell

   Войдите в Azure через PowerShell с помощью следующей команды:

   Connect-AzAccount
   

2. Чтобы использоватьDefaultAzureCredential, убедитесь, что установлен пакет удостоверений Azure и класс импортируется:

   from azure.identity import DefaultAzureCredential
   from azure.storage.blob import BlobServiceClient
   

3. Добавьте этот код в try блок. При запуске кода на локальной рабочей станции DefaultAzureCredential используются учетные данные разработчика, вошедшего в систему, для проверки подлинности в Azure. Примерами этих средств являются Azure CLI или Visual Studio Code.

   account_url = "https://<storageaccountname>.blob.core.windows.net"
   default_credential = DefaultAzureCredential()
   
   # Create the BlobServiceClient object
   blob_service_client = BlobServiceClient(account_url, credential=default_credential)
   

4. Обязательно обновите имя учетной записи хранения в URI объекта BlobServiceClient . Имя учетной записи хранения можно найти на странице обзора портала Azure.

   

   Примечание.

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

Строка подключения

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

Примечание.

Чтобы авторизовать доступ к данным с помощью ключа доступа к учетной записи хранения, вам потребуются разрешения для следующих действий Azure RBAC: Microsoft.Storage/storageAccounts/listkeys/action. Наименее привилегированная встроенная роль с разрешениями для этого действия — читатель и доступ к данным, но любая роль, которая включает это действие, будет работать.

Портал Azure

1. Войдите на портал Azure.

2. Перейдите к учетной записи хранения.

3. На панели меню учетной записи хранения в разделе Безопасность и сети выберите Ключи доступа. На этой странице вы увидите ключи доступа к учетной записи и полную строку подключения для каждого ключа.

4. В области Ключи доступа выберите команду Показать ключи.

5. В разделе key1 выберите значение Строка подключения. Нажмите значок Копировать в буфер обмена, чтобы скопировать строку подключения. В следующем разделе вы добавите значение строки подключения в переменную среды.

   

Azure CLI

Строку подключения для своей учетной записи хранения можно просмотреть, выполнив команду az storage account show-connection-string.

az storage account show-connection-string --name "<your-storage-account-name>"

PowerShell

Вы можете собрать строку подключения с помощью PowerShell, выполнив команды Get-AzStorageAccount и Get-AzStorageAccountKey.

$saName = "yourStorageAccountName"
$rgName = "yourResourceGroupName"
$sa = Get-AzStorageAccount -StorageAccountName $saName -ResourceGroupName $rgName

$saKey = (Get-AzStorageAccountKey -ResourceGroupName $rgName -Name $saName)[0].Value

'DefaultEndpointsProtocol=https;AccountName=' + $saName + ';AccountKey=' + $saKey + ';EndpointSuffix=core.windows.net'

Настройка строки подключения хранилища

После копирования строки подключения запишите ее в переменной среды на локальном компьютере, где выполняется приложение. Чтобы задать переменную среды, откройте окно консоли и следуйте инструкциям для используемой операционной системы. Замените <yourconnectionstring> фактической строкой подключения.

Windows:

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

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

Linux:

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

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

Добавьте этот код в блок try.

# Retrieve the connection string for use with the application. The storage
# connection string is stored in an environment variable on the machine
# running the application called AZURE_STORAGE_CONNECTION_STRING. If the environment variable is
# created after the application is launched in a console or with Visual Studio,
# the shell or application needs to be closed and reloaded to take the
# environment variable into account.
connect_str = os.getenv('AZURE_STORAGE_CONNECTION_STRING')

# Create the BlobServiceClient object
blob_service_client = BlobServiceClient.from_connection_string(connect_str)

Внимание

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

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

Создайте контейнер в учетной записи хранения, вызвав метод create_container объекта blob_service_client . В этом примере код добавляет значение GUID к имени контейнера, чтобы убедиться, что он уникальный.

Добавьте следующий код в конец блока try.

# Create a unique name for the container
container_name = str(uuid.uuid4())

# Create the container
container_client = blob_service_client.create_container(container_name)

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

Внимание

Имена контейнеров должны состоять из знаков нижнего регистра. Дополнительные сведения об именовании контейнеров и больших двоичных объектов см. в статье Naming and Referencing Containers, Blobs, and Metadata (Именование контейнеров, больших двоичных объектов и метаданных и ссылка на них).

отправка больших двоичных объектов в контейнер;

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

Добавьте следующий код в конец блока try.

# Create a local directory to hold blob data
local_path = "./data"
os.mkdir(local_path)

# Create a file in the local data directory to upload and download
local_file_name = str(uuid.uuid4()) + ".txt"
upload_file_path = os.path.join(local_path, local_file_name)

# Write text to the file
file = open(file=upload_file_path, mode='w')
file.write("Hello, World!")
file.close()

# Create a blob client using the local file name as the name for the blob
blob_client = blob_service_client.get_blob_client(container=container_name, blob=local_file_name)

print("\nUploading to Azure Storage as blob:\n\t" + local_file_name)

# Upload the created file
with open(file=upload_file_path, mode="rb") as data:
    blob_client.upload_blob(data)

Дополнительные сведения о отправке БОЛЬШИХ двоичных объектов и изучении дополнительных примеров кода см. в статье "Отправка большого двоичного объекта с помощью Python".

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

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

Добавьте следующий код в конец блока try.

print("\nListing blobs...")

# List the blobs in the container
blob_list = container_client.list_blobs()
for blob in blob_list:
    print("\t" + blob.name)

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

скачивание больших двоичных объектов;

Скачайте созданный ранее большой двоичный объект, вызвав метод download_blob. Пример кода добавляет суффикс "DOWNLOAD" к имени файла, чтобы в локальной файловой системе можно было просмотреть оба файла.

Добавьте следующий код в конец блока try.

# Download the blob to a local file
# Add 'DOWNLOAD' before the .txt extension so you can see both files in the data directory
download_file_path = os.path.join(local_path, str.replace(local_file_name ,'.txt', 'DOWNLOAD.txt'))
container_client = blob_service_client.get_container_client(container= container_name) 
print("\nDownloading blob to \n\t" + download_file_path)

with open(file=download_file_path, mode="wb") as download_file:
 download_file.write(container_client.download_blob(blob.name).readall())

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

Удаление контейнера

Следующий код очищает созданные приложением ресурсы, полностью удаляя контейнер с помощью метода delete_container. Кроме того, при необходимости можно удалить локальные файлы.

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

Добавьте следующий код в конец блока try.

# Clean up
print("\nPress the Enter key to begin clean up")
input()

print("Deleting blob container...")
container_client.delete_container()

print("Deleting the local source and downloaded files...")
os.remove(upload_file_path)
os.remove(download_file_path)
os.rmdir(local_path)

print("Done")

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

Выполнение кода

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

Перейдите в каталог, содержащий файл blob_quickstart.py , а затем выполните следующую python команду, чтобы запустить приложение:

python blob_quickstart.py

Выходные данные приложения аналогичны следующему примеру (значения UUID, пропущенные для удобочитаемости):

Azure Blob Storage Python quickstart sample

Uploading to Azure Storage as blob:
        quickstartUUID.txt

Listing blobs...
        quickstartUUID.txt

Downloading blob to
        ./data/quickstartUUIDDOWNLOAD.txt

Press the Enter key to begin clean up

Deleting blob container...
Deleting the local source and downloaded files...
Done

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

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

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

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

azd down

Вам будет предложено подтвердить удаление ресурсов. Введите y для подтверждения.

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

служба хранилища Azure примеры и руководства разработчиков для Python