azure.storage.blob.ContainerClient class

请求新的租约。如果容器没有活动租约，则 BLOB 服务会在该容器上创建一个租约，并返回新的租约 ID。

acquire_lease(lease_duration: int = -1, lease_id: str | None = None, **kwargs) -> BlobLeaseClient

参数

lease_duration: int

必需

指定租约的持续时间（秒），或者指定 -1 以表示永不过期的租约。有限期租约在 15 到 60 秒之间。不能使用续订或更改来更改租约持续时间。默认值为 -1 (无限租用) 。

lease_id: str

必需

建议的租约 ID，采用 GUID 字符串格式。如果建议的租用 ID 格式不正确，Blob 服务将返回 400 (无效请求) 。

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 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。

返回

BlobLeaseClient 对象，可在上下文管理器中运行。

返回类型

BlobLeaseClient

此方法用于关闭客户端打开的套接字。与上下文管理器一起使用时，不需要使用它。

close()

在指定的帐户下创建新容器。如果已存在同名的容器，操作将失败。

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

参数

metadata: dict[str, str]

必需

包含name_value对的 dict，这些对作为元数据与容器相关联。示例：{'Category'：'test'}

public_access: 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 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。

返回

响应标头的字典。

返回类型

Dict[str, Union[str, datetime]]

标记要删除的指定 blob 或快照。

该 Blob 将在稍后的垃圾回收期间删除。请注意，要删除 Blob，必须删除其所有快照。可以使用delete_blob操作同时删除这两者。

如果为服务启用了删除保留策略，则此操作将软删除 blob 或快照并将 blob 或快照保留指定的天数。在指定的天数后，Blob 的数据在垃圾回收期间会从服务中删除。可通过list_blobs指定 include=[“deleted”] 选项访问软删除的 blob 或快照。可以使用还原软删除的 blob 或快照<xref:azure.storage.blob.BlobClient.undelete>

delete_blob(blob: str | BlobProperties, delete_snapshots: str | None = None, **kwargs) -> None

参数

blob: str 或 BlobProperties

必需

要与之交互的 Blob。如果指定，此值将替代 Blob URL 中指定的 Blob 值。

delete_snapshots: str

必需

如果 Blob 有关联快照，则是必需的。值包括：

“only”：仅删除 Blob 快照。
“include”：删除 Blob 以及所有快照。

version_id: str

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

版本 12.4.0 中的新增功能。

此关键字 (keyword) 参数是在 API 版本“2019-12-12”中引入的。

lease: BlobLeaseClient 或 str

如果 Blob 具有活动租约，则是必需的。值可以是 BlobLeaseClient 对象，也可以是字符串格式的租约 ID。

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 使用的匹配条件。

if_tags_match_condition: str

将 blob 标记上的 SQL where 子句指定为仅在具有匹配值的 Blob 上运行。例如 "\"tagname\"='my tag'"

版本 12.4.0 中的新增功能。

timeout: int

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

返回类型

None

标记要删除的指定 blob 或快照。

稍后在垃圾回收期间删除这些 Blob。请注意，若要删除 Blob，必须删除其所有快照。可以使用delete_blobs操作同时删除这两者。

如果为服务启用了删除保留策略，则此操作将软删除 Blob 或快照，并将 Blob 或快照保留指定的天数。在指定的天数后，Blob 的数据在垃圾回收期间会从服务中删除。软 list_blobs 删除的 blob 或快照可通过指定 include=[“deleted”] 软删除的 blob 或快照进行还原 <xref:azure.storage.blob.BlobClient.undelete>

单个请求中可删除的最大 Blob 数为 256。

delete_blobs(*blobs: str | Dict[str, Any] | BlobProperties, **kwargs: Any) -> Iterator[HttpResponse]

参数

blobs: str 或 dict(str, Any) 或 BlobProperties

必需

要删除的 Blob。这可以是单个 Blob，也可以提供多个值，其中每个值都是 blob (str) 或 BlobProperties 的名称。

注意

当 blob 类型为 dict 时，下面是键和值规则的列表。

Blob 名称：

key： 'name'， value type： str

要删除快照：

键：“快照”，值类型：str

版本 ID：

key： 'version_id'，值类型： str

删除 Blob 时是否删除快照：

key：“delete_snapshots”，值：“include”或“only”

如果 Blob 已修改或未修改：

key：“if_modified_since”、“if_unmodified_since”，值类型：datetime

Etag：

key： 'etag'， value type： str

匹配或不匹配 etag：

key：“match_condition”，值类型：MatchConditions

标记匹配条件：

key： 'if_tags_match_condition'，值类型： str

租赁：

key：“lease_id”，值类型：Union[str， LeaseClient]

子请求超时：

key： 'timeout'， value type： int

delete_snapshots: str

如果 Blob 具有关联的快照，则为必需。值包括：

“only”：仅删除 Blob 快照。
“include”：删除 Blob 以及所有快照。

if_modified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的时间后修改了资源时才执行操作。

if_unmodified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的日期/时间后未修改资源时才执行操作。

if_tags_match_condition: str

将 blob 标记上的 SQL where 子句指定为仅在具有匹配值的 Blob 上运行。例如 "\"tagname\"='my tag'"

版本 12.4.0 中的新增功能。

raise_on_any_failure: bool

这是一个布尔参数，默认为 True。设置此项后，即使出现单个操作失败，也会引发异常。

timeout: int

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

返回

响应的迭代器，每个 Blob 按顺序对应一个

返回类型

Iterator[HttpResponse]

标记要删除的指定容器。在稍后的垃圾回收期间，将删除该容器及其包含的任何 Blob。

delete_container(**kwargs: Any) -> None

参数

lease: BlobLeaseClient 或 str

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

将 Blob 下载到 StorageStreamDownloader。 readall () 方法必须用于读取所有内容，或者必须使用 readinto () 将 Blob 下载到流中。使用区块 () 返回一个迭代器，该迭代器允许用户循环访问区块中的内容。

download_blob(blob: str | BlobProperties, offset: int = None, length: int = None, *, encoding: str, **kwargs) -> StorageStreamDownloader[str]

参数

blob: str 或 BlobProperties

必需

要与之交互的 Blob。如果指定，此值将替代 Blob URL 中指定的 Blob 值。

offset: int

必需

用于下载 Blob 部分的字节范围的起始。如果提供了长度，则必须设置。

length: int

必需

要从流中读取的字节数。这是可选的，但为了获得最佳性能，应提供此选项。

version_id: str

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

版本 12.4.0 中的新增功能。

此关键字 (keyword) 参数是在 API 版本“2019-12-12”中引入的。

validate_content: bool

如果为 true，则计算 blob 的每个区块的 MD5 哈希。存储服务会检查已随发送的哈希一起到达的内容的哈希。如果使用 http 而不是 https，这主要适用于检测网络上的 bitflips，因为 https (默认) ，已得到验证。请注意，此 MD5 哈希值不与 Blob 一起存储。另请注意，如果启用，将不会使用内存高效上传算法，因为计算 MD5 哈希需要缓冲整个块，这样做会破坏内存高效算法的用途。

lease: BlobLeaseClient 或 str

如果 Blob 具有活动租约，则是必需的。如果指定，download_blob仅当 blob 的租约处于活动状态且与此 ID 匹配时才会成功。值可以是 BlobLeaseClient 对象，也可以是作为字符串的租约 ID。

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 上使用的匹配条件。

if_tags_match_condition: str

指定 Blob 标记上的 SQL where 子句，以便仅在具有匹配值的 Blob 上运行。例如 "\"tagname\"='my tag'"

版本 12.4.0 中的新增功能。

cpk: CustomerProvidedEncryptionKey

使用给定密钥加密服务端的数据。客户提供的密钥的使用必须通过 HTTPS 完成。由于加密密钥本身是在请求中提供的，因此必须建立安全连接才能传输密钥。

max_concurrency: int

要下载的并行连接数。

encoding: str

用于解码下载的字节的编码。默认值为 None，即不解码。

progress_hook: Callable[[int, int], None]

用于跟踪长时间运行的下载进度的回调。签名函数 (current： int，total： int) 其中 current 是到目前为止传输的字节数，total 是下载的总大小。

timeout: int

设置操作的服务器端超时（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。此方法可能会对服务进行多次调用，超时将单独应用于每个调用。对 Azure 服务的多次调用，超时将分别应用于每个调用。

返回

(StorageStreamDownloader) 流式处理对象

返回类型

StorageStreamDownloader

如果容器存在，则返回 True，否则返回 False。

exists(**kwargs: Any) -> bool

参数

timeout: int

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

返回

boolean

返回类型

bool

返回一个生成器，用于列出指定容器下的 blob，其标记与给定的搜索表达式匹配。生成器将延迟跟踪服务返回的继续标记。

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

参数

filter_expression: str

必需

用于查找其标记与指定条件匹配的 blob 的表达式。例如 “”yourtagname“='firsttag'和”yourtagname2“='secondtag'”

results_per_page: int

分页时每页的最大结果。

timeout: int

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

返回

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

返回类型

ItemPaged[BlobProperties]

从连接字符串创建 ContainerClient。

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

参数

conn_str: str

必需

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

container_name: str

必需

Blob 的容器名称。

credential

默认值: None

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

返回

容器客户端。

返回类型

ContainerClient

从容器 URL 创建 ContainerClient。

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

参数

container_url: str

必需

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

credential

默认值: None

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

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

返回

容器客户端。

返回类型

ContainerClient

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

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

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

返回

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

返回类型

dict(str, str)

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

Blob 不需要已经存在。

get_blob_client(blob: str | BlobProperties, snapshot: str = None, *, version_id: str | None = None) -> BlobClient

参数

blob: str 或 BlobProperties

必需

要与之交互的 Blob。

snapshot: str

默认值: None

要在其上运行的可选 blob 快照。这可以是快照 ID 字符串，也可以是从 create_snapshot返回的响应。

version_id: str

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

返回

BlobClient。

返回类型

BlobClient

获取指定容器的权限。这些权限指示是否可以公开访问容器数据。

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

参数

lease: BlobLeaseClient 或 str

如果指定，get_container_access_policy仅当容器的租约处于活动状态且与此 ID 匹配时才会成功。

timeout: int

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

返回

访问 dict 中的策略信息。

返回类型

dict[str, Any]

返回指定容器的所有用户定义的元数据和系统属性。返回的数据不包含该容器的 Blob 列表。

get_container_properties(**kwargs: Any) -> ContainerProperties

参数

lease: BlobLeaseClient 或 str

如果指定，get_container_properties仅当容器的租约处于活动状态且与此 ID 匹配时才会成功。

timeout: int

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

返回

容器对象中指定容器的属性。

返回类型

ContainerProperties

返回一个生成器，用于列出指定容器下的 Blob 的名称。生成器将延迟跟踪服务返回的继续标记。

请注意，使用此 API 时不会返回任何其他属性或元数据。此外，此 API 无法包含其他 Blob，例如快照、版本、软删除的 blob 等。若要获取任何此数据，请使用 list_blobs。

list_blob_names(**kwargs: Any) -> ItemPaged[str]

参数

name_starts_with: str

筛选结果以便仅返回名称以指定前缀开头的 Blob。

timeout: int

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

返回

可迭代 (自动分页) blob 名称作为字符串的响应。

返回类型

ItemPaged[str]

返回一个生成器，用于列出指定容器下的 Blob。生成器将延迟跟踪服务返回的继续标记。

list_blobs(name_starts_with: str | None = None, include: str | List[str] | None = None, **kwargs: Any) -> ItemPaged[BlobProperties]

参数

name_starts_with: str

必需

筛选结果以便仅返回名称以指定前缀开头的 Blob。

include: list[str] 或 str

必需

指定要包含在响应中的一个或多个其他数据集。选项包括：“snapshots”、“metadata”、“uncommittedblobs”、“copy”、“deleted”、“deletedwithversions”、“tags”、“versions”、“不可变性policy”、“legalhold”。

timeout: int

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

返回

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

返回类型

ItemPaged[BlobProperties]

设置可能与共享访问签名一起使用的指定容器或存储访问策略的权限。这些权限指示是否可以公开访问容器中的 Blob。

set_container_access_policy(signed_identifiers: Dict[str, AccessPolicy], public_access: str | PublicAccess | None = None, **kwargs) -> Dict[str, str | datetime]

参数

signed_identifiers: dict[str, AccessPolicy]

必需

要与容器关联的访问策略字典。字典最多可以包含 5 个元素。空字典将清除在服务上设置的访问策略。

public_access: PublicAccess

必需

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

lease: BlobLeaseClient 或 str

如果容器具有活动租约，则为必需。值可以是 BlobLeaseClient 对象，也可以是作为字符串的租约 ID。

if_modified_since: datetime

日期/时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头以仅当资源自指定日期/时间以来已修改时才执行操作。

if_unmodified_since: datetime

日期/时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的日期/时间后未修改资源时才执行操作。

timeout: int

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

返回

容器更新的属性 dict (Etag 和上次修改) 。

返回类型

dict[str, str,

datetime]

为指定的容器设置一个或多个用户定义的名称-值对。每次调用此操作时，将替换与容器关联的所有现有的元数据。若要从容器中删除所有元数据，请调用此操作，不带元数据听写。

set_container_metadata(metadata: Dict[str, str] | None = None, **kwargs) -> Dict[str, str | datetime]

参数

metadata: dict[str, str]

必需

包含要作为元数据与容器关联的名称/值对的 dict。示例：{'category'：'test'}

lease: BlobLeaseClient 或 str

如果指定，set_container_metadata仅当容器的租约处于活动状态且与此 ID 匹配时才会成功。

if_modified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的时间后修改了资源时才执行操作。

if_unmodified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。指定此标头，以便仅在指定的日期/时间后未修改资源时才执行操作。

etag: str

ETag 值或通配符 (*)。用于检查资源是否已更改，并根据 match_condition 参数指定的条件进行操作。

timeout: int

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

返回

容器更新的属性 dict (Etag 和上次修改) 。

返回类型

dict[str, str,

datetime]

在所有 Blob 上设置页 Blob 层。仅高级帐户上的页 Blob 支持此 API。

单个请求中可更新的最大 Blob 数为 256。

set_premium_page_blob_tier_blobs(premium_page_blob_tier: str | PremiumPageBlobTier | None, *blobs: str | Dict[str, Any] | BlobProperties, **kwargs: Any) -> Iterator[HttpResponse]

参数

premium_page_blob_tier: PremiumPageBlobTier

必需

要将 Blob 设置为的页 Blob 层值。层与 Blob 的大小和允许的 IOPS 数相关联。这仅适用于高级存储帐户上的页 Blob。

注意

如果要在不同的 Blob 上设置不同的层，请将此位置参数设置为 None。

然后，将采用每个 BlobProperties 上的 Blob 层。

blobs: str 或 dict(str, Any) 或 BlobProperties

必需

要与之交互的 Blob。这可以是单个 Blob，也可以提供多个值，其中每个值都是 blob (str) 或 BlobProperties 的名称。

注意

当 blob 类型为 dict 时，下面是键、值规则的列表。

blob 名称：

key： 'name'， value type： str

高级 Blob 层：

键：“blob_tier”，值类型：PremiumPageBlobTier

租赁：

键：“lease_id”，值类型：Union[str， LeaseClient]

subrequest 的 timeout：

key： 'timeout'， value type： int

timeout: int

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

raise_on_any_failure: bool

这是一个布尔参数，默认为 True。设置此设置后，即使出现单个操作失败，也会引发异常。

返回

响应的迭代器，每个 Blob 按顺序对应一个

返回类型

<xref:iterator>[HttpResponse]

此操作在块 Blob 上设置层。

块 Blob 的层确定热/冷/存档存储类型。此操作不会更新 Blob 的 ETag。

单个请求中可更新的最大 Blob 数为 256。

set_standard_blob_tier_blobs(standard_blob_tier: str | StandardBlobTier | None, *blobs: str | Dict[str, Any] | BlobProperties, **kwargs: Any) -> Iterator[HttpResponse]

参数

standard_blob_tier: str 或 StandardBlobTier

必需

指示要在所有 Blob 上设置的层。选项包括“Hot”、“Cool”、“Archive”。热层经过优化，用于存储频繁访问的数据。冷存储层经过优化，用于存储不经常访问和存储至少一个月的数据。存档层经过优化，用于存储很少访问和存储至少六个月且延迟要求灵活的数据。

注意

如果要在不同的 Blob 上设置不同的层，请将此位置参数设置为 None。

然后，将采用每个 BlobProperties 上的 Blob 层。

blobs: str 或 dict(str, Any) 或 BlobProperties

必需

要与之交互的 Blob。这可以是单个 Blob，也可以提供多个值，其中每个值都是 blob (str) 或 BlobProperties 的名称。

注意

当 blob 类型为 dict 时，下面是键、值规则的列表。

blob 名称：

key： 'name'， value type： str

标准 Blob 层：

key： “blob_tier”，值类型： StandardBlobTier

解除冻结优先级：

键：“rehydrate_priority”，值类型：RehydratePriority

租赁：

键：“lease_id”，值类型：Union[str， LeaseClient]

快照：

key： “快照”，值类型： str

版本 ID：

key： “version_id”，值类型： str

标记匹配条件：

key： “if_tags_match_condition”，值类型： str

subrequest 的 timeout：

key： 'timeout'， value type： int

rehydrate_priority: RehydratePriority

指示解除存档 blob 冻结的优先级

if_tags_match_condition: str

指定 Blob 标记上的 SQL where 子句，以便仅在具有匹配值的 Blob 上运行。例如 "\"tagname\"='my tag'"

版本 12.4.0 中的新增功能。

timeout: int

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

raise_on_any_failure: bool

这是一个布尔参数，默认为 True。设置此设置后，即使出现单个操作失败，也会引发异常。

返回

响应的迭代器，每个 Blob 按顺序对应一个

返回类型

Iterator[HttpResponse]

使用自动分块从数据源创建新的 Blob。

upload_blob(name: str | BlobProperties, data: bytes | str | Iterable | IO, blob_type: str | BlobType = BlobType.BLOCKBLOB, length: int | None = None, metadata: Dict[str, str] | None = None, **kwargs) -> BlobClient

参数

name: str 或 BlobProperties

必需

要与之交互的 Blob。如果指定，此值将替代 Blob URL 中指定的 Blob 值。

data

必需

要上传的 Blob 数据。

blob_type: BlobType

必需

Blob 的类型。这可以是 BlockBlob、PageBlob 或 AppendBlob。默认值为 BlockBlob。

length: int

必需

要从流中读取的字节数。这是可选的，但为了获得最佳性能，应提供此选项。

metadata: dict(str, str)

必需

作为元数据、与 Blob 关联的名称-值对。

overwrite: bool

要上传的 Blob 是否应覆盖当前数据。如果为 True，upload_blob将覆盖现有数据。如果设置为 False，则操作将失败并出现 ResourceExistsError。上述的例外情况是追加 blob 类型：如果设置为 False 并且数据已存在，则不会引发错误，并且数据将追加到现有 Blob。如果设置为 overwrite=True，则将删除现有的追加 blob，并创建一个新追加 blob。默认为 False。

content_settings: ContentSettings

用于设置 Blob 属性的 ContentSettings 对象。用于设置内容类型、编码、语言、处置、md5 和缓存控制。

validate_content: bool

如果为 true，则计算 blob 的每个区块的 MD5 哈希。存储服务会检查已随发送的哈希一起到达的内容的哈希。如果使用 http 而不是 https，这主要适用于检测网络上的 bitflips，因为 https (默认) ，已得到验证。请注意，此 MD5 哈希值不与 Blob 一起存储。另请注意，如果启用，将不会使用内存高效上传算法，因为计算 MD5 哈希需要缓冲整个块，这样做会破坏内存高效算法的用途。

lease: BlobLeaseClient 或 str

如果容器具有活动租约，则为必需。值可以是 BlobLeaseClient 对象，也可以是作为字符串的租约 ID。

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 上使用的匹配条件。

if_tags_match_condition: str

指定 Blob 标记上的 SQL where 子句，以便仅在具有匹配值的 Blob 上运行。例如 "\"tagname\"='my tag'"

版本 12.4.0 中的新增功能。

timeout: int

设置操作的服务器端超时（以秒为单位）。有关详细信息，请参阅 https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。此方法可能会对服务进行多次调用，超时将单独应用于每个调用。

premium_page_blob_tier: PremiumPageBlobTier

要将 Blob 设置为的页 Blob 层值。层与 Blob 的大小和允许的 IOPS 数相关联。这仅适用于高级存储帐户上的页 Blob。

standard_blob_tier: StandardBlobTier

要将 Blob 设置为的标准 Blob 层值。对于此版本的库，这仅适用于标准存储帐户上的块 Blob。

maxsize_condition: int

可选条件标头。追加 blob 允许的最大长度（以字节为单位）。如果追加块操作会导致 Blob 超出该限制，或者 Blob 大小已大于此标头中指定的值，则请求将失败，并出现 MaxBlobSizeConditionNotMet 错误 (HTTP 状态代码 412 - 先决条件失败) 。

max_concurrency: int

Blob 大小超过 64MB 时要使用的最大并行连接数。

cpk: CustomerProvidedEncryptionKey

使用给定密钥加密服务端的数据。客户提供的密钥的使用必须通过 HTTPS 完成。由于加密密钥本身是在请求中提供的，因此必须建立安全连接才能传输密钥。

encryption_scope: str

用于加密服务上的数据的预定义加密范围。可以使用管理 API 创建加密范围，并在此处按名称引用。如果已在容器中定义了默认加密范围，则如果容器级范围配置为允许替代，则此值将覆盖它。否则将引发错误。

版本 12.2.0 中的新增功能。

encoding: str

默认为 UTF-8。

progress_hook: Callable[[int, Optional[int]], None]

用于跟踪长时间运行的上传进度的回调。签名是函数 (current： int， total： Optional[int]) 其中 current 是到目前为止传输的字节数，而 total 是 blob 的大小;如果大小未知，则为 None。

返回

用于与新上传的 Blob 交互的 BlobClient。

返回类型

BlobClient

返回一个生成器，用于列出指定容器下的 Blob。生成器将延迟跟踪服务返回的继续标记。此操作将根据层次结构列出 Blob，由指定的分隔符字符分隔。

walk_blobs(name_starts_with: str | None = None, include: str | List[str] | None = None, delimiter: str = '/', **kwargs: Any | None) -> ItemPaged[BlobProperties]

参数

name_starts_with: str

必需

筛选结果以便仅返回名称以指定前缀开头的 Blob。

include: list[str] 或 str

必需

指定要包含在响应中的一个或多个其他数据集。选项包括：“snapshots”、“metadata”、“uncommittedblobs”、“copy”、“deleted”、“deletedwithversions”、“tags”、“versions”、“不可变性policy”、“legalhold”。

delimiter: str

必需

当请求包含此参数时，操作在响应正文中返回一个 BlobPrefix 元素，该元素充当所有 Blob 的占位符，其名称以同一子字符串开头，一直为分隔符的外观。分隔符可以是单个字符或字符串。

timeout: int

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

返回

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

返回类型

ItemPaged[BlobProperties]

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

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

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

完整的主终结点 URL。

主终结点的主机名。

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

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

例外

ValueError

辅助终结点的主机名。

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

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

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

acquire_lease	请求新的租约。如果容器没有活动租约，则 BLOB 服务会在该容器上创建一个租约，并返回新的租约 ID。
close	此方法用于关闭客户端打开的套接字。与上下文管理器一起使用时，不需要使用它。
create_container	在指定的帐户下创建新容器。如果已存在同名的容器，操作将失败。
delete_blob	标记要删除的指定 blob 或快照。该 Blob 将在稍后的垃圾回收期间删除。请注意，要删除 Blob，必须删除其所有快照。可以使用delete_blob操作同时删除这两者。如果为服务启用了删除保留策略，则此操作将软删除 blob 或快照并将 blob 或快照保留指定的天数。在指定的天数后，Blob 的数据在垃圾回收期间会从服务中删除。可通过list_blobs指定 include=[“deleted”] 选项访问软删除的 blob 或快照。可以使用还原软删除的 blob 或快照<xref:azure.storage.blob.BlobClient.undelete>
delete_blobs	标记要删除的指定 blob 或快照。稍后在垃圾回收期间删除这些 Blob。请注意，若要删除 Blob，必须删除其所有快照。可以使用delete_blobs操作同时删除这两者。如果为服务启用了删除保留策略，则此操作将软删除 Blob 或快照，并将 Blob 或快照保留指定的天数。在指定的天数后，Blob 的数据在垃圾回收期间会从服务中删除。软 list_blobs 删除的 blob 或快照可通过指定 include=[“deleted”] 软删除的 blob 或快照进行还原 <xref:azure.storage.blob.BlobClient.undelete> 单个请求中可删除的最大 Blob 数为 256。
delete_container	标记要删除的指定容器。在稍后的垃圾回收期间，将删除该容器及其包含的任何 Blob。
download_blob	将 Blob 下载到 StorageStreamDownloader。 readall () 方法必须用于读取所有内容，或者必须使用 readinto () 将 Blob 下载到流中。使用区块 () 返回一个迭代器，该迭代器允许用户循环访问区块中的内容。
exists	如果容器存在，则返回 True，否则返回 False。
find_blobs_by_tags	返回一个生成器，用于列出指定容器下的 blob，其标记与给定的搜索表达式匹配。生成器将延迟跟踪服务返回的继续标记。
from_connection_string	从连接字符串创建 ContainerClient。
from_container_url	从容器 URL 创建 ContainerClient。
get_account_information	获取与存储帐户相关的信息。如果用户具有对容器或 Blob 的 SAS，也可以检索该信息。返回的字典中的键包括“sku_name”和“account_kind”。
get_blob_client	获取客户端以与指定的 Blob 交互。 Blob 不需要已经存在。
get_container_access_policy	获取指定容器的权限。这些权限指示是否可以公开访问容器数据。
get_container_properties	返回指定容器的所有用户定义的元数据和系统属性。返回的数据不包含该容器的 Blob 列表。
list_blob_names	返回一个生成器，用于列出指定容器下的 Blob 的名称。生成器将延迟跟踪服务返回的继续标记。请注意，使用此 API 时不会返回任何其他属性或元数据。此外，此 API 无法包含其他 Blob，例如快照、版本、软删除的 blob 等。若要获取任何此数据，请使用 list_blobs。
list_blobs	返回一个生成器，用于列出指定容器下的 Blob。生成器将延迟跟踪服务返回的继续标记。
set_container_access_policy	设置可能与共享访问签名一起使用的指定容器或存储访问策略的权限。这些权限指示是否可以公开访问容器中的 Blob。
set_container_metadata	为指定的容器设置一个或多个用户定义的名称-值对。每次调用此操作时，将替换与容器关联的所有现有的元数据。若要从容器中删除所有元数据，请调用此操作，不带元数据听写。
set_premium_page_blob_tier_blobs	在所有 Blob 上设置页 Blob 层。仅高级帐户上的页 Blob 支持此 API。单个请求中可更新的最大 Blob 数为 256。
set_standard_blob_tier_blobs	此操作在块 Blob 上设置层。块 Blob 的层确定热/冷/存档存储类型。此操作不会更新 Blob 的 ETag。单个请求中可更新的最大 Blob 数为 256。
upload_blob	使用自动分块从数据源创建新的 Blob。
walk_blobs	返回一个生成器，用于列出指定容器下的 Blob。生成器将延迟跟踪服务返回的继续标记。此操作将根据层次结构列出 Blob，由指定的分隔符字符分隔。

ContainerClient 类

构造函数

参数

方法

acquire_lease

参数

返回

返回类型

close

create_container

参数

返回

返回类型

delete_blob

参数

返回类型

delete_blobs

参数

返回

返回类型

delete_container

参数

返回类型

download_blob

参数

返回

返回类型

exists

参数

返回

返回类型

find_blobs_by_tags

参数

返回

返回类型

from_connection_string

参数

返回

返回类型

from_container_url

参数

返回

返回类型

get_account_information

返回

返回类型

get_blob_client

参数

返回

返回类型

get_container_access_policy

参数

返回

返回类型

get_container_properties

参数

返回

返回类型

list_blob_names

参数

返回

返回类型

list_blobs

参数

返回

返回类型

set_container_access_policy

参数

返回

返回类型

set_container_metadata

参数

返回

返回类型

set_premium_page_blob_tier_blobs

参数

返回

返回类型

set_standard_blob_tier_blobs

参数