你当前正在访问 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: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = 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。

方法

close	此方法用于关闭客户端打开的套接字。 与上下文管理器一起使用时，不需要使用它。
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”中引入的。

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)

必需

具有名称/值对的 dict，作为元数据与容器相关联。 示例： {'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

标记要删除的指定容器。

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

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

参数

container

str 或 ContainerProperties

必需

要删除的容器。 这可以是容器的名称，也可以是 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

设置操作的服务器端超时时间（以秒为单位）。 有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时，请参阅 此处。

返回类型

None

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

设置操作的服务器端超时时间（以秒为单位）。 有关详细信息，请参阅 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 令牌字符串、azure.core.credentials 中的 AzureSasCredential 或 AzureNamedKeyCredential 的实例、帐户共享访问密钥或 azure.identity 中的 TokenCredentials 类的实例。 此处提供的凭据优先于连接字符串中的凭据。 如果使用 AzureNamedKeyCredential 的实例，“name”应为存储帐户名称，“key”应为存储帐户密钥。

返回

Blob 服务客户端。

返回类型

BlobServiceClient

get_account_information

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

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

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

返回

(SKU 和帐户类型) 帐户信息的听写。

返回类型

dict(str, str)

get_blob_client

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

Blob 不需要已经存在。

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

必需

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

snapshot

str 或 dict(str, Any)

默认值: None

要在其上运行的可选 blob 快照。 这可以是快照的 ID，也可以是 返回create_snapshot的字典输出。

version_id

str

版本 ID 参数是一个不透明的 DateTime 值，如果存在，则指定运行 Blob 的版本。

返回

BlobClient。

返回类型

BlobClient

get_container_client

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

容器不需要已经存在。

get_container_client(container: ContainerProperties | str) -> ContainerClient

参数

container

str 或 ContainerProperties

必需

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

返回

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 调用要检索的最大容器名称数。 如果请求未指定，服务器将返回最多 5,000 个项。

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 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

设置操作的服务器端超时（以秒为单位）。 有关详细信息，请参阅 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 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时，请参阅 此处。

返回

未删除的 ContainerClient。

返回类型

ContainerClient

属性

api_version

用于请求的存储 API 的版本。

location_mode

客户端当前使用的位置模式。

默认情况下，此为“主要”。 选项包括“primary”和“secondary”。

primary_endpoint

完整的主终结点 URL。

primary_hostname

主终结点的主机名。

secondary_endpoint

完整的辅助终结点 URL（如果已配置）。

如果不可用，将引发 ValueError。 若要显式指定辅助主机名，请在实例化时使用可选的 secondary_hostname 关键字 (keyword) 参数。

例外

ValueError

secondary_hostname

辅助终结点的主机名。

如果不可用，则此项将为“无”。 若要显式指定辅助主机名，请在实例化时使用可选的 secondary_hostname 关键字 (keyword) 参数。

url

此实体的完整终结点 URL，包括 SAS 令牌（如果使用）。

这可以是主终结点，也可以是辅助终结点，具体取决于当前 location_mode。 ：returns：此实体的完整终结点 URL，包括 SAS 令牌（如果使用）。 :rtype：str