你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

BlobServiceClient 类

在帐户级别与 Blob 服务交互的客户端。

此客户端提供用于检索和配置帐户属性以及列出、创建和删除帐户中的容器的操作。 对于与特定容器或 Blob 相关的操作,也可以使用 get_client 函数检索这些实体的客户端。

有关更多可选配置,请 单击此处

继承
azure.storage.blob._shared.base_client.StorageAccountHostsMixin
BlobServiceClient
azure.storage.blob._encryption.StorageEncryptionMixin
BlobServiceClient

构造函数

BlobServiceClient(account_url: str, credential: Optional[Union[str, Dict[str, str], AzureNamedKeyCredential, AzureSasCredential, "TokenCredential"]] # pylint: disable=line-too-long = None, **kwargs: Any)

参数

account_url
str
必需

Blob 存储帐户的 URL。 URL 路径中包含的任何其他实体 ((例如容器或 blob) )将被丢弃。 可以选择使用 SAS 令牌对此 URL 进行身份验证。

credential
默认值: None

用于进行身份验证的凭据。 如果帐户 URL 已有 SAS 令牌,则这是可选的。 该值可以是 SAS 令牌字符串、AzureSasCredential 的实例或 azure.core.credentials 中的 AzureNamedKeyCredential、帐户共享访问密钥或 azure.identity 中的 TokenCredentials 类的实例。 如果资源 URI 已包含 SAS 令牌,则会忽略此令牌,转而使用显式凭据

  • AzureSasCredential 的情况除外,其中冲突的 SAS 令牌将引发 ValueError。 如果使用 AzureNamedKeyCredential 的实例,则“name”应为存储帐户名称,“密钥”应为存储帐户密钥。
api_version
str

用于请求的存储 API 版本。 默认值是与当前 SDK 兼容的最新服务版本。 设置为较旧版本可能会导致功能兼容性降低。

版本 12.2.0 中的新增功能。

secondary_hostname
str

辅助终结点的主机名。

max_block_size
int

用于以区块为单位上传块 Blob 的最大区块大小。 默认为 4*1024*1024 或 4MB。

max_single_put_size
int

如果 blob 大小小于或等于 max_single_put_size,则只上传一个 http PUT 请求的 blob。 如果 blob 大小大于 max_single_put_size,则 Blob 将以区块上传。 默认为 64*1024*1024 或 64MB。

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 或 4MB。

max_single_get_size
int

单个调用中要下载的 Blob 的最大大小,超出的部分将以区块 (可以并行) 下载。 默认为 32*1024*1024 或 32MB。

max_chunk_get_size
int

用于下载 Blob 的最大区块大小。 默认为 4*1024*1024 或 4MB。

示例

使用帐户 URL 和凭据创建 BlobServiceClient。


   from azure.storage.blob import BlobServiceClient
   blob_service_client = BlobServiceClient(account_url=self.url, credential=self.shared_access_key)

使用 Azure 标识凭据创建 BlobServiceClient。


   # Get a token credential for authentication
   from azure.identity import ClientSecretCredential
   token_credential = ClientSecretCredential(
       self.active_directory_tenant_id,
       self.active_directory_application_id,
       self.active_directory_application_secret
   )

   # Instantiate a BlobServiceClient using a token credential
   from azure.storage.blob import BlobServiceClient
   blob_service_client = BlobServiceClient(account_url=self.oauth_url, credential=token_credential)

方法

create_container

在指定的帐户下创建新容器。

如果已存在同名的容器,则会引发 ResourceExistsError。 此方法返回与新创建的容器交互的客户端。

delete_container

标记要删除的指定容器。

在稍后的垃圾回收期间,将删除该容器及其包含的任何 Blob。 如果未找到容器,则会引发 ResourceNotFoundError。

find_blobs_by_tags

“筛选 Blob”操作使调用方能够列出标记与给定搜索表达式匹配的所有容器中的 Blob。 筛选器 Blob 在存储帐户中的所有容器中进行搜索,但可以在表达式中限定为单个容器。

from_connection_string

从连接字符串创建 BlobServiceClient。

get_account_information

获取与存储帐户相关的信息。

如果用户具有对容器或 Blob 的 SAS,也可以检索该信息。 返回的字典中的键包括“sku_name”和“account_kind”。

get_blob_client

获取客户端以与指定的 Blob 交互。

Blob 不需要已经存在。

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”中引入的。

create_container

在指定的帐户下创建新容器。

如果已存在同名的容器,则会引发 ResourceExistsError。 此方法返回与新创建的容器交互的客户端。

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

参数

name
str
必需

要创建的容器的名称。

metadata
dict(str, str)
必需

具有名称/值对的 dict,作为元数据与容器相关联。 示例: {'Category':'test'}

public_access
strPublicAccess
必需

可能的值包括:“container”、“blob”。

container_encryption_scope
dictContainerEncryptionScope

指定要在容器上设置的默认加密范围,并将其用于将来的所有写入。

版本 12.2.0 中的新增功能。

timeout
int

超时参数以秒表示。

返回类型

示例

在 Blob 服务中创建容器。


   try:
       new_container = blob_service_client.create_container("containerfromblobservice")
       properties = new_container.get_container_properties()
   except ResourceExistsError:
       print("Container already exists.")

delete_container

标记要删除的指定容器。

在稍后的垃圾回收期间,将删除该容器及其包含的任何 Blob。 如果未找到容器,则会引发 ResourceNotFoundError。

delete_container(container: Union[ContainerProperties, str], lease: Optional[Union[BlobLeaseClient, str]] = None, **kwargs) -> None

参数

container
strContainerProperties
必需

要删除的容器。 这可以是容器的名称,也可以是 ContainerProperties 的实例。

lease
必需

如果指定,则仅当容器的租约处于活动状态并且与此 ID 匹配时,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

超时参数以秒表示。

返回类型

示例

删除 Blob 服务中的容器。


   # Delete container if it exists
   try:
       blob_service_client.delete_container("containerfromblobservice")
   except ResourceNotFoundError:
       print("Container already deleted.")

find_blobs_by_tags

“筛选 Blob”操作使调用方能够列出标记与给定搜索表达式匹配的所有容器中的 Blob。 筛选器 Blob 在存储帐户中的所有容器中进行搜索,但可以在表达式中限定为单个容器。

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

参数

filter_expression
str
必需

用于查找其标记与指定条件匹配的 blob 的表达式。 例如 “”yourtagname“='firsttag' and ”yourtagname2“='secondtag'” 若要指定容器,例如 “@container='containerName' and ”Name“='C'”

results_per_page
int

分页时每页的最大结果。

timeout
int

超时参数以秒表示。

返回

BlobProperties 的可迭代 (自动分页) 响应。

返回类型

from_connection_string

从连接字符串创建 BlobServiceClient。

from_connection_string(conn_str: str, credential: Optional[Union[str, Dict[str, str], AzureNamedKeyCredential, AzureSasCredential, "TokenCredential"]] # pylint: disable=line-too-long = None, **kwargs: Any) -> ClassType

参数

conn_str
str
必需

Azure 存储帐户的连接字符串。

credential
默认值: None

用于进行身份验证的凭据。 如果帐户 URL 已有 SAS 令牌,或者连接字符串已具有共享访问密钥值,则这是可选的。 该值可以是 SAS 令牌字符串、AzureSasCredential 的实例或 azure.core.credentials 中的 AzureNamedKeyCredential、帐户共享访问密钥或 azure.identity 中的 TokenCredentials 类的实例。 此处提供的凭据优先于连接字符串中的凭据。 如果使用 AzureNamedKeyCredential 的实例,则“name”应为存储帐户名称,“密钥”应为存储帐户密钥。

返回

Blob 服务客户端。

返回类型

示例

从连接字符串创建 BlobServiceClient。


   from azure.storage.blob import BlobServiceClient
   blob_service_client = BlobServiceClient.from_connection_string(self.connection_string)

get_account_information

获取与存储帐户相关的信息。

如果用户具有对容器或 Blob 的 SAS,也可以检索该信息。 返回的字典中的键包括“sku_name”和“account_kind”。

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

返回

帐户信息 (SKU 和帐户类型) 。

返回类型

示例

获取 Blob 服务的帐户信息。


   account_info = blob_service_client.get_account_information()
   print('Using Storage SKU: {}'.format(account_info['sku_name']))

get_blob_client

获取客户端以与指定的 Blob 交互。

Blob 不需要已经存在。

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

参数

container
strContainerProperties
必需

Blob 位于的容器。 这可以是容器的名称,也可以是 ContainerProperties 的实例。

blob
strBlobProperties
必需

要与之交互的 Blob。 这可以是 Blob 的名称,也可以是 BlobProperties 的实例。

snapshot
strdict(str, <xref:Any>)
默认值: None

要对其操作的可选 Blob 快照。 这可以是快照的 ID,也可以是 返回 create_snapshot的字典输出。

返回

BlobClient。

返回类型

示例

让 Blob 客户端与特定 Blob 交互。


   blob_client = blob_service_client.get_blob_client(container="containertest", blob="my_blob")
   try:
       stream = blob_client.download_blob()
   except ResourceNotFoundError:
       print("No blob found.")

get_container_client

获取客户端以与指定容器交互。

容器不需要已经存在。

get_container_client(container: Union[ContainerProperties, str]) -> ContainerClient

参数

container
strContainerProperties
必需

容器。 这可以是容器的名称,也可以是 ContainerProperties 的实例。

返回

ContainerClient。

返回类型

示例

让容器客户端与特定容器交互。


   # Get a client to interact with a specific container - though it may not yet exist
   container_client = blob_service_client.get_container_client("containertest")
   try:
       for blob in container_client.list_blobs():
           print("Found blob: ", blob.name)
   except ResourceNotFoundError:
       print("Container not found.")

get_service_properties

获取存储帐户的 Blob 服务的属性,包括 Azure 存储分析。

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

参数

timeout
int

超时参数以秒表示。

返回

包含 Blob 服务属性(例如分析日志记录、小时/分钟指标、cors 规则等)的对象。

返回类型

<xref:Dict>[str, <xref:Any>]

示例

获取 Blob 服务的服务属性。


   properties = blob_service_client.get_service_properties()

get_service_stats

检索与 Blob 服务的复制有关的统计信息。

仅当为存储帐户启用了读取访问异地冗余复制时,它才可用。

通过地域冗余复制,Azure 存储服务在两个位置维护你的持久数据。 在这两个位置,Azure 存储始终维护您数据的多个运行正常副本。 读取、创建、更新或删除数据的位置称为“主”存储帐户位置。 主要位置存在于你通过 Azure 管理 Azure 经典门户(例如美国中北部)创建帐户时选择的区域。 数据复制到的位置为“辅助”位置。 根据主位置自动确定辅助位置,它在主位置所在区域中的第二个数据中心内。 如果为存储帐户启用了“读访问的地域冗余复制”,则可对辅助位置执行只读访问。

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

参数

timeout
int

超时参数以秒表示。

返回

Blob 服务统计信息。

返回类型

<xref:Dict>[str, <xref:Any>]

示例

获取 Blob 服务的服务统计信息。


   stats = blob_service_client.get_service_stats()

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

超时参数以秒表示。

返回

用户委派密钥。

返回类型

list_containers

返回一个生成器,用于列出指定帐户下的容器。

生成器将延迟跟踪服务返回的延续令牌,并在返回所有容器后停止。

list_containers(name_starts_with: Optional[str] = None, include_metadata: Optional[bool] = 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 调用要检索的最大容器名称数。 如果请求未指定,服务器将返回最多 5,000 个项。

timeout
int

超时参数以秒表示。

返回

ContainerProperties 的可迭代 (自动分页) 。

返回类型

示例

列出 Blob 服务中的容器。


   # List all containers
   all_containers = blob_service_client.list_containers(include_metadata=True)
   for container in all_containers:
       print(container['name'], container['metadata'])

   # Filter results with name prefix
   test_containers = blob_service_client.list_containers(name_starts_with='test-')
   for container in test_containers:
       print(container['name'], container['metadata'])

set_service_properties

设置存储帐户的 Blob 服务的属性,包括 Azure 存储分析。

如果元素 (例如,analytics_logging) 保留为 None,则会保留该服务上针对该功能的现有设置。

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

参数

analytics_logging
BlobAnalyticsLogging
必需

对 Azure Analytics Logging 设置进行分组。

hour_metrics
Metrics
必需

小时指标设置提供请求统计信息的摘要,这些统计信息按 API 按 Blob 的每小时聚合进行分组。

minute_metrics
Metrics
必需

分钟指标设置提供 Blob 每分钟的请求统计信息。

cors
list[CorsRule]
必需

列表中最多可以包含五个 CorsRule 元素。 如果指定了空列表,则将删除所有 CORS 规则,并且将禁用该服务的 CORS。

target_version
str
必需

指示如果未指定传入请求的版本,则用于请求的默认版本。

delete_retention_policy
RetentionPolicy
必需

删除保留策略指定是否保留已删除的 Blob。 它还指定要保留的 Blob 的天数和版本。

static_website
StaticWebsite
必需

指定是否启用静态网站功能,如果是,则指示要使用的索引文档和 404 错误文档。

timeout
int

超时参数以秒表示。

返回类型

示例

设置 Blob 服务的服务属性。


   # Create service properties
   from azure.storage.blob import BlobAnalyticsLogging, Metrics, CorsRule, RetentionPolicy

   # Create logging settings
   logging = BlobAnalyticsLogging(read=True, write=True, delete=True, retention_policy=RetentionPolicy(enabled=True, days=5))

   # Create metrics for requests statistics
   hour_metrics = Metrics(enabled=True, include_apis=True, retention_policy=RetentionPolicy(enabled=True, days=5))
   minute_metrics = Metrics(enabled=True, include_apis=True,
                            retention_policy=RetentionPolicy(enabled=True, days=5))

   # Create CORS rules
   cors_rule = CorsRule(['www.xyz.com'], ['GET'])
   cors = [cors_rule]

   # Set the service properties
   blob_service_client.set_service_properties(logging, hour_metrics, minute_metrics, cors)

undelete_container

还原软删除的容器。

只有在删除保留策略中设置的指定天数内使用时,操作才会成功。

版本 12.4.0 中的新增功能:此操作是在 API 版本“2019-12-12”中引入的。

undelete_container(deleted_container_name: str, deleted_container_version: str, **kwargs: Any) -> azure.storage.blob._container_client.ContainerClient

参数

deleted_container_name
str
必需

指定要还原的已删除容器的名称。

deleted_container_version
str
必需

指定要还原的已删除容器的版本。

timeout
int

超时参数以秒表示。

返回类型