你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
BlobServiceClient 类
在帐户级别与 Blob 服务交互的客户端。
此客户端提供用于检索和配置帐户属性以及列出、创建和删除帐户中的容器的操作。 对于与特定容器或 Blob 相关的操作，也可以使用 get_client 函数检索这些实体的客户端。
有关更多可选配置，请 单击此处。
- 继承
-
azure.storage.blob._shared.base_client.StorageAccountHostsMixinBlobServiceClientazure.storage.blob._encryption.StorageEncryptionMixinBlobServiceClient
构造函数
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
用于进行身份验证的凭据。 如果帐户 URL 已有 SAS 令牌，则这是可选的。 该值可以是 SAS 令牌字符串、AzureSasCredential 的实例或 azure.core.credentials 中的 AzureNamedKeyCredential、帐户共享访问密钥或 azure.identity 中的 TokenCredentials 类的实例。 如果资源 URI 已包含 SAS 令牌，则会忽略此令牌，转而使用显式凭据
- AzureSasCredential 的情况除外，其中冲突的 SAS 令牌将引发 ValueError。 如果使用 AzureNamedKeyCredential 的实例，则“name”应为存储帐户名称，“密钥”应为存储帐户密钥。
- 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参数
- container_encryption_scope
- dict 或 ContainerEncryptionScope
指定要在容器上设置的默认加密范围，并将其用于将来的所有写入。
版本 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参数
- 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参数
- credential
用于进行身份验证的凭据。 如果帐户 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参数
要对其操作的可选 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参数
返回
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 规则等）的对象。
返回类型
示例
获取 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 服务统计信息。
返回类型
示例
获取 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参数
- timeout
- int
超时参数以秒表示。
返回
用户委派密钥。
返回类型
list_containers
返回一个生成器，用于列出指定帐户下的容器。
生成器将延迟跟踪服务返回的延续令牌，并在返回所有容器后停止。
list_containers(name_starts_with: Optional[str] = None, include_metadata: Optional[bool] = False, **kwargs) -> ItemPaged[ContainerProperties]参数
- 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参数
- 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参数
- timeout
- int
超时参数以秒表示。
返回类型
反馈
提交和查看相关反馈