BlobServiceClient Класс

Клиент для взаимодействия со Службой BLOB-объектов на уровне учетной записи.

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

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

Наследование

azure.storage.blob._shared.base_client.StorageAccountHostsMixin

BlobServiceClient

azure.storage.blob._encryption.StorageEncryptionMixin

BlobServiceClient

Конструктор

BlobServiceClient(account_url: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any)

Параметры

account_url

str

Обязательно

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

credential

значение по умолчанию: None

Учетные данные для проверки подлинности. Это необязательно, если URL-адрес учетной записи уже содержит маркер SAS. Это может быть строка маркера SAS, экземпляр AzureSasCredential или AzureNamedKeyCredential из azure.core.credentials, общий ключ доступа учетной записи или экземпляр класса TokenCredentials из azure.identity. Если URI ресурса уже содержит маркер SAS, он будет игнорироваться в пользу явных учетных данных.

• за исключением случаев AzureSasCredential, где конфликтующие маркеры SAS вызовут ValueError. При использовании экземпляра AzureNamedKeyCredential "name" должно быть именем учетной записи хранения, а "key" — ключом учетной записи хранения.

api_version

str

Версия API хранилища, используемая для запросов. Значение по умолчанию — это последняя версия службы, совместимая с текущим пакетом SDK. Установка более старой версии может привести к снижению совместимости функций.

Новые возможности в версии 12.2.0.

secondary_hostname

str

Имя узла вторичной конечной точки.

max_block_size

int

Максимальный размер блока для отправки блочного BLOB-объекта блоками. По умолчанию — 4*1024*1024 или 4 МБ.

max_single_put_size

int

Если размер большого двоичного объекта меньше или равен max_single_put_size, большой двоичный объект будет отправлен только с одним http-запросом PUT. Если размер большого двоичного объекта превышает max_single_put_size, большой двоичный объект будет отправлен блоками. По умолчанию — 64*1024*1024 или 64 МБ.

min_large_block_upload_threshold

int

Минимальный размер блока, необходимый для использования эффективного в памяти алгоритма при отправке блочного BLOB-объекта. По умолчанию — 4*1024*1024+1.

use_byte_buffer

bool

Используйте буфер байтов для передачи блочных BLOB-объектов. Значение по умолчанию — False.

max_page_size

int

Максимальный размер блока для отправки страничного BLOB-объекта. По умолчанию — 4*1024*1024 или 4 МБ.

max_single_get_size

int

Максимальный размер большого двоичного объекта, который будет скачан в одном вызове. Превышенная часть будет загружаться блоками (может быть параллельной). Значение по умолчанию — 32*1024*1024 или 32 МБ.

max_chunk_get_size

int

Максимальный размер блока, используемый для скачивания большого двоичного объекта. По умолчанию — 4*1024*1024 или 4 МБ.

Методы

close	Этот метод заключается в закрытии сокетов, открытых клиентом. Его не нужно использовать при использовании с диспетчером контекста.
create_container	Создает новый контейнер в указанной учетной записи. Если контейнер с тем же именем уже существует, будет создано свойство ResourceExistsError. Этот метод возвращает клиент, с которым будет взаимодействовать с вновь созданным контейнером.
delete_container	Помечает указанный контейнер для удаления. Контейнер и все большие двоичные объекты внутри него будут удалены позднее в процессе сборки мусора. Если контейнер не найден, создается resourceNotFoundError.
find_blobs_by_tags	Операция Фильтрации BLOB-объектов позволяет вызывающим объектам перечислять большие двоичные объекты во всех контейнерах, теги которых соответствуют заданному выражению поиска. Фильтрация больших двоичных объектов выполняет поиск по всем контейнерам в учетной записи хранения, но их можно ограничить одним контейнером в выражении.
from_connection_string	Создайте BlobServiceClient из строки подключения.
get_account_information	Возвращает сведения, связанные с учетной записью хранения. Эти сведения также можно получить, если у пользователя есть SAS для контейнера или большого двоичного объекта. Ключи в возвращенном словаре включают "sku_name" и "account_kind".
get_blob_client	Получение клиента для взаимодействия с указанным большим двоичным объектом. Большой двоичный объект еще не должен существовать.
get_container_client	Получение клиента для взаимодействия с указанным контейнером. Контейнер еще не должен существовать.
get_service_properties	Возвращает свойства службы BLOB-объектов учетной записи хранения, включая Аналитика Службы хранилища Azure.
get_service_stats	Получает статистику, связанную с репликацией службы BLOB-объектов. Она доступна, только если для учетной записи хранения включена геоизбыточная репликация с доступом на чтение. Благодаря географически избыточной репликации хранилище Azure надежно хранит ваши данные в двух расположениях. В обоих расположениях хранилище Azure поддерживает несколько работоспособных копий данных. Расположение, в котором вы читаете, создаете, обновляете или удаляете данные, является первичным расположением учетной записи хранилища. Основное расположение находится в регионе, выбранном при создании учетной записи на классическом портале Azure для управления Azure, например в центрально-северной части США. Расположение, в которое ваши данные реплицируются, — это вторичное расположение. Оно определяется автоматически, исходя из выбранного первичного расположения. Это второй центр обработки данных в том же регионе, где находится первичное расположение. Во вторичном расположении предоставляется доступ только для чтения, если для вашей учетной записи хранилища включена географически избыточная репликация с доступом только для чтения.
get_user_delegation_key	Получите ключ делегирования пользователя для подписи маркеров SAS. Для успешного выполнения этого запроса в объекте службы должны присутствовать учетные данные маркера.
list_containers	Возвращает генератор для вывода списка контейнеров в указанной учетной записи. Генератор будет отложенно следовать маркерам продолжения, возвращенным службой, и останавливаться, когда все контейнеры будут возвращены.
set_service_properties	Задает свойства службы BLOB-объектов учетной записи хранения, включая Аналитика Службы хранилища Azure. Если элемент (например, analytics_logging) остается равным None, существующие параметры службы для этой функции сохраняются.
undelete_container	Восстанавливает обратимо удаленный контейнер. Операция будет успешной, только если используется в течение указанного числа дней, заданного в политике хранения удаления. Новые возможности в версии 12.4.0: эта операция появилась в API версии 2019-12-12.

close

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

close()

create_container

Создает новый контейнер в указанной учетной записи.

Если контейнер с тем же именем уже существует, будет создано свойство ResourceExistsError. Этот метод возвращает клиент, с которым будет взаимодействовать с вновь созданным контейнером.

create_container(name: str, metadata: Dict[str, str] | None = None, public_access: PublicAccess | str | None = None, **kwargs) -> ContainerClient

Параметры

name

str

Обязательно

Имя создаваемого контейнера.

metadata

dict(str, str)

Обязательно

Словарь с парами "имя-значение" для связывания с контейнером в качестве метаданных. Пример: {'Category':'test'}

public_access

str или PublicAccess

Обязательно

Возможные значения: "container", "blob".

container_encryption_scope

dict или ContainerEncryptionScope

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

Новые возможности в версии 12.2.0.

timeout

int

Задает время ожидания на стороне сервера для операции в секундах. Дополнительные сведения см. в следующей статье: https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Это значение не отслеживается и не проверяется на клиенте. Сведения о настройке времени ожидания сети на стороне клиента см. здесь.

Возвращаемый тип

ContainerClient

delete_container

Помечает указанный контейнер для удаления.

Контейнер и все большие двоичные объекты внутри него будут удалены позднее в процессе сборки мусора. Если контейнер не найден, создается resourceNotFoundError.

delete_container(container: ContainerProperties | str, lease: BlobLeaseClient | str | None = None, **kwargs) -> None

Параметры

container

str или ContainerProperties

Обязательно

Удаляемая контейнер. Это может быть имя контейнера или экземпляр ContainerProperties.

lease

Обязательно

Если этот параметр указан, delete_container выполняется успешно, только если аренда контейнера активна и соответствует этому идентификатору. Требуется, если контейнер имеет активную аренду.

if_modified_since

datetime

Значение даты и времени. Azure ожидает, что переданное значение даты будет иметь формат UTC. Если включен часовой пояс, все значения даты и времени, отличные от UTC, будут преобразованы в формат UTC. Если дата передается без сведений о часовом поясе, предполагается, что она имеет значение UTC. Укажите этот заголовок для выполнения операции только в том случае, если ресурс был изменен в указанное время.

if_unmodified_since

datetime

Значение даты и времени. Azure ожидает, что переданное значение даты будет иметь формат UTC. Если включен часовой пояс, все значения даты и времени, отличные от UTC, будут преобразованы в формат UTC. Если дата передается без сведений о часовом поясе, предполагается, что она имеет значение UTC. Укажите этот заголовок для выполнения операции только в том случае, если ресурс не был изменен в указанные дату и время.

etag

str

Значение ETag или подстановочный знак (*). Используется для проверка, если ресурс изменился, и действует в соответствии с условием, заданным параметром match_condition.

match_condition

MatchConditions

Условие соответствия, используемое для etag.

timeout

int

Задает время ожидания на стороне сервера для операции в секундах. Дополнительные сведения см. в следующей статье: https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Это значение не отслеживается и не проверяется на клиенте. Сведения о настройке времени ожидания сети на стороне клиента см. здесь.

Возвращаемый тип

None

find_blobs_by_tags

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

find_blobs_by_tags(filter_expression: str, **kwargs: Any) -> ItemPaged[FilteredBlob]

Параметры

filter_expression

str

Обязательно

Выражение для поиска больших двоичных объектов, теги которых соответствуют указанному условию. Например: ""yourtagname"='firsttag' and "yourtagname2"='secondtag'" Чтобы указать контейнер, например "@container='containerName' и "Name"='C'"

results_per_page

int

Максимальный результат на страницу при разбиении на страницы.

timeout

int

Задает время ожидания на стороне сервера для операции в секундах. Дополнительные сведения см. в следующей статье: https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Это значение не отслеживается и не проверяется на клиенте. Сведения о настройке времени ожидания сети на стороне клиента см. здесь.

Возвращаемое значение

Итерируемый (автоматически разбиение по страницам) ответ BlobProperties.

Возвращаемый тип

ItemPaged[FilteredBlob]

from_connection_string

Создайте BlobServiceClient из строки подключения.

from_connection_string(conn_str: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any) -> Self

Параметры

conn_str

str

Обязательно

Строка подключения к учетной записи хранения Azure.

credential

значение по умолчанию: None

Учетные данные для проверки подлинности. Это необязательно, если URL-адрес учетной записи уже содержит маркер SAS или строка подключения уже содержит значения общего ключа доступа. Это может быть строка маркера SAS, экземпляр AzureSasCredential или AzureNamedKeyCredential из azure.core.credentials, общий ключ доступа учетной записи или экземпляр класса TokenCredentials из azure.identity. Предоставленные здесь учетные данные будут иметь приоритет над учетными данными в строке подключения. При использовании экземпляра AzureNamedKeyCredential "name" должно быть именем учетной записи хранения, а "key" — ключом учетной записи хранения.

Возвращаемое значение

Клиент службы BLOB-объектов.

Возвращаемый тип

BlobServiceClient

get_account_information

Возвращает сведения, связанные с учетной записью хранения.

Эти сведения также можно получить, если у пользователя есть SAS для контейнера или большого двоичного объекта. Ключи в возвращенном словаре включают "sku_name" и "account_kind".

get_account_information(**kwargs: Any) -> Dict[str, str]

Возвращаемое значение

Словарь сведений об учетной записи (SKU и тип учетной записи).

Возвращаемый тип

dict(str, str)

get_blob_client

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

Большой двоичный объект еще не должен существовать.

get_blob_client(container: ContainerProperties | str, blob: BlobProperties | str, snapshot: Dict[str, Any] | str | None = None, *, version_id: str | None = None) -> BlobClient

Параметры

container

str или ContainerProperties

Обязательно

Контейнер, в который находится BLOB-объект. Это может быть имя контейнера или экземпляр ContainerProperties.

blob

str или BlobProperties

Обязательно

Большой двоичный объект, с которым нужно взаимодействовать. Это может быть имя большого двоичного объекта или экземпляр BlobProperties.

snapshot

str или dict(str, Any)

значение по умолчанию: None

Необязательный snapshot большого двоичного объекта, с которым нужно работать. Это может быть либо идентификатор snapshot, либо выходные данные словаря, возвращаемые .create_snapshot

version_id

str

Параметр идентификатора версии — это непрозрачное значение DateTime, которое при наличии указывает версию большого двоичного объекта, с которым нужно работать.

Возвращаемое значение

A BlobClient.

Возвращаемый тип

BlobClient

get_container_client

Получение клиента для взаимодействия с указанным контейнером.

Контейнер еще не должен существовать.

get_container_client(container: ContainerProperties | str) -> ContainerClient

Параметры

container

str или ContainerProperties

Обязательно

Контейнер. Это может быть имя контейнера или экземпляр ContainerProperties.

Возвращаемое значение

A ContainerClient.

Возвращаемый тип

ContainerClient

get_service_properties

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

get_service_properties(**kwargs: Any) -> Dict[str, Any]

Параметры

timeout

int

Задает время ожидания на стороне сервера для операции в секундах. Дополнительные сведения см. в следующей статье: https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Это значение не отслеживается и не проверяется на клиенте. Сведения о настройке времени ожидания сети на стороне клиента см. здесь.

Возвращаемое значение

Объект , содержащий свойства службы BLOB-объектов, такие как ведение журнала аналитики, метрики по часам в минуту, правила cors и т. д.

Возвращаемый тип

Dict[str, Any]

get_service_stats

Получает статистику, связанную с репликацией службы BLOB-объектов.

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

Благодаря географически избыточной репликации хранилище Azure надежно хранит ваши данные в двух расположениях. В обоих расположениях хранилище Azure поддерживает несколько работоспособных копий данных. Расположение, в котором вы читаете, создаете, обновляете или удаляете данные, является первичным расположением учетной записи хранилища. Основное расположение находится в регионе, выбранном при создании учетной записи на классическом портале Azure для управления Azure, например в центрально-северной части США. Расположение, в которое ваши данные реплицируются, — это вторичное расположение. Оно определяется автоматически, исходя из выбранного первичного расположения. Это второй центр обработки данных в том же регионе, где находится первичное расположение. Во вторичном расположении предоставляется доступ только для чтения, если для вашей учетной записи хранилища включена географически избыточная репликация с доступом только для чтения.

get_service_stats(**kwargs: Any) -> Dict[str, Any]

Параметры

timeout

int

Задает время ожидания на стороне сервера для операции в секундах. Дополнительные сведения см. в следующей статье: https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Это значение не отслеживается и не проверяется на клиенте. Сведения о настройке времени ожидания сети на стороне клиента см. здесь.

Возвращаемое значение

Статистика службы BLOB-объектов.

Возвращаемый тип

Dict[str, Any]

get_user_delegation_key

Получите ключ делегирования пользователя для подписи маркеров SAS. Для успешного выполнения этого запроса в объекте службы должны присутствовать учетные данные маркера.

get_user_delegation_key(key_start_time: datetime, key_expiry_time: datetime, **kwargs: Any) -> UserDelegationKey

Параметры

key_start_time

datetime

Обязательно

Значение даты и времени. Указывает, когда ключ становится действительным.

key_expiry_time

datetime

Обязательно

Значение даты и времени. Указывает, когда ключ перестает быть действительным.

timeout

int

Задает время ожидания на стороне сервера для операции в секундах. Дополнительные сведения см. в следующей статье: https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Это значение не отслеживается и не проверяется на клиенте. Сведения о настройке времени ожидания сети на стороне клиента см. здесь.

Возвращаемое значение

Ключ делегирования пользователя.

Возвращаемый тип

UserDelegationKey

list_containers

Возвращает генератор для вывода списка контейнеров в указанной учетной записи.

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

list_containers(name_starts_with: str | None = None, include_metadata: bool | None = False, **kwargs) -> ItemPaged[ContainerProperties]

Параметры

name_starts_with

str

Обязательно

Фильтрует результаты, возвращая только контейнеры, имена которых начинаются с указанного префикса.

include_metadata

bool

Обязательно

Указывает, что метаданные контейнера, возвращаемые в ответе. Значение по умолчанию равно False.

include_deleted

bool

Указывает, что удаленные контейнеры, возвращаемые в ответе. Это предназначено для учетной записи с поддержкой восстановления контейнера. Значение по умолчанию равно False. .. versionadded:: 12.4.0

include_system

bool

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

results_per_page

int

Максимальное количество имен контейнеров для каждого вызова API. Если в запросе не указано, сервер вернет до 5000 элементов.

timeout

int

Задает время ожидания на стороне сервера для операции в секундах. Дополнительные сведения см. в следующей статье: https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Это значение не отслеживается и не проверяется на клиенте. Сведения о настройке времени ожидания сети на стороне клиента см. здесь.

Возвращаемое значение

Итерируемое (автоматическое разбиение по страницам) объекта ContainerProperties.

Возвращаемый тип

ItemPaged[ContainerProperties]

set_service_properties

Задает свойства службы BLOB-объектов учетной записи хранения, включая Аналитика Службы хранилища Azure.

Если элемент (например, analytics_logging) остается равным None, существующие параметры службы для этой функции сохраняются.

set_service_properties(analytics_logging: BlobAnalyticsLogging | None = None, hour_metrics: Metrics | None = None, minute_metrics: Metrics | None = None, cors: List[CorsRule] | None = None, target_version: str | None = None, delete_retention_policy: RetentionPolicy | None = None, static_website: StaticWebsite | None = None, **kwargs) -> None

Параметры

analytics_logging

BlobAnalyticsLogging

Обязательно

Группирует параметры ведения журнала Azure Analytics.

hour_metrics

Metrics

Обязательно

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

minute_metrics

Metrics

Обязательно

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

cors

list[CorsRule]

Обязательно

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

target_version

str

Обязательно

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

delete_retention_policy

RetentionPolicy

Обязательно

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

static_website

StaticWebsite

Обязательно

Указывает, включена ли функция статического веб-сайта, а если да, то указывает на документ индекса и документ ошибки 404 для использования.

timeout

int

Задает время ожидания на стороне сервера для операции в секундах. Дополнительные сведения см. в следующей статье: https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Это значение не отслеживается и не проверяется на клиенте. Сведения о настройке времени ожидания сети на стороне клиента см. здесь.

Возвращаемый тип

None

undelete_container

Восстанавливает обратимо удаленный контейнер.

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

Новые возможности в версии 12.4.0: эта операция появилась в API версии 2019-12-12.

undelete_container(deleted_container_name: str, deleted_container_version: str, **kwargs: Any) -> ContainerClient

Параметры

deleted_container_name

str

Обязательно

Указывает имя удаленного контейнера для восстановления.

deleted_container_version

str

Обязательно

Указывает версию удаленного контейнера для восстановления.

timeout

int

Задает время ожидания на стороне сервера для операции в секундах. Дополнительные сведения см. в следующей статье: https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Это значение не отслеживается и не проверяется на клиенте. Сведения о настройке времени ожидания сети на стороне клиента см. здесь.

Возвращаемое значение

The undeleted ContainerClient.

Возвращаемый тип

ContainerClient

Атрибуты

api_version

Версия API хранилища, используемого для запросов.

location_mode

Режим расположения, используемый клиентом в настоящее время.

По умолчанию это будет "основной". Возможные варианты: "primary" и "secondary".

primary_endpoint

Полный URL-адрес основной конечной точки.

primary_hostname

Имя узла основной конечной точки.

secondary_endpoint

Полный URL-адрес вторичной конечной точки, если он настроен.

Если он недоступен, будет вызван параметр ValueError. Чтобы явно указать имя вторичного узла, используйте необязательный аргумент secondary_hostname ключевое слово при создании экземпляра.

Исключения

ValueError

secondary_hostname

Имя узла вторичной конечной точки.

Если он недоступен, это значение будет нет. Чтобы явно указать имя вторичного узла, используйте необязательный аргумент secondary_hostname ключевое слово при создании экземпляра.

url

Полный URL-адрес конечной точки для этой сущности, включая маркер SAS, если он используется.

Это может быть основная конечная точка или вторичная конечная точка в зависимости от текущего location_mode. :returns: полный URL-адрес конечной точки для этой сущности, включая маркер SAS, если он используется. :rtype: str