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

ContainerClient 类

用于与特定容器交互的客户端,尽管该容器可能尚不存在。

对于与此容器中的特定 Blob 相关的操作,可以使用 函数检索 get_blob_client Blob 客户端。

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

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

构造函数

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

参数

account_url
str
必需

存储帐户的 URI。 若要创建给定容器的完整 URI 的客户端,请使用 from_container_url 类方法。

container_name
str
必需

Blob 的容器的名称。

credential
默认值: None

用于进行身份验证的凭据。 如果帐户 URL 已具有 SAS 令牌,则这是可选的。 该值可以是 SAS 令牌字符串、azure.core.credentials 中的 AzureSasCredential 或 AzureNamedKeyCredential 的实例、帐户共享访问密钥或 azure.identity 中的 TokenCredentials 类的实例。 如果资源 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 或 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。

方法

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,由指定的分隔符字符分隔。

acquire_lease

请求新的租约。 如果容器没有活动租约,则 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 对象,可在上下文管理器中运行。

返回类型

close

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

close()

create_container

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

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
dictContainerEncryptionScope

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

版本 12.2.0 中的新增功能。

timeout
int

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

返回

响应标头的字典。

返回类型

delete_blob

标记要删除的指定 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
strBlobProperties
必需

要与之交互的 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
BlobLeaseClientstr

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

返回类型

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_blobs(*blobs: str | Dict[str, Any] | BlobProperties, **kwargs: Any) -> Iterator[HttpResponse]

参数

blobs
strdict(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 按顺序对应一个

返回类型

delete_container

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

delete_container(**kwargs: Any) -> None

参数

lease
BlobLeaseClientstr

如果指定,则仅当容器的租约处于活动状态且与此 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 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时,请参阅 此处

返回类型

download_blob

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

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

参数

blob
strBlobProperties
必需

要与之交互的 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
BlobLeaseClientstr

如果 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) 流式处理对象

返回类型

exists

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

exists(**kwargs: Any) -> bool

参数

timeout
int

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

返回

boolean

返回类型

find_blobs_by_tags

返回一个生成器,用于列出指定容器下的 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 的可迭代 (自动分页) 响应。

返回类型

from_connection_string

从连接字符串创建 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”应为存储帐户密钥。

返回

容器客户端。

返回类型

from_container_url

从容器 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”应为存储帐户密钥。

返回

容器客户端。

返回类型

get_account_information

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

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

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

返回

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

返回类型

get_blob_client

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

Blob 不需要已经存在。

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

参数

blob
strBlobProperties
必需

要与之交互的 Blob。

snapshot
str
默认值: None

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

version_id
str

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

返回

BlobClient。

返回类型

get_container_access_policy

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

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

参数

lease
BlobLeaseClientstr

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

timeout
int

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

返回

访问 dict 中的策略信息。

返回类型

get_container_properties

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

get_container_properties(**kwargs: Any) -> ContainerProperties

参数

lease
BlobLeaseClientstr

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

timeout
int

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

返回

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

返回类型

list_blob_names

返回一个生成器,用于列出指定容器下的 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 名称作为字符串的响应。

返回类型

list_blobs

返回一个生成器,用于列出指定容器下的 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 的可迭代 (自动分页) 响应。

返回类型

set_container_access_policy

设置可能与共享访问签名一起使用的指定容器或存储访问策略的权限。 这些权限指示是否可以公开访问容器中的 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
BlobLeaseClientstr

如果容器具有活动租约,则为必需。 值可以是 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 和上次修改) 。

返回类型

set_container_metadata

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

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

参数

metadata
dict[str, str]
必需

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

lease
BlobLeaseClientstr

如果指定,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 和上次修改) 。

返回类型

set_premium_page_blob_tier_blobs

在所有 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
strdict(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]

set_standard_blob_tier_blobs

此操作在块 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
strStandardBlobTier
必需

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

注意

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

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

blobs
strdict(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 按顺序对应一个

返回类型

upload_blob

使用自动分块从数据源创建新的 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
strBlobProperties
必需

要与之交互的 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
BlobLeaseClientstr

如果容器具有活动租约,则为必需。 值可以是 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。

返回类型

walk_blobs

返回一个生成器,用于列出指定容器下的 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 的可迭代 (自动分页) 响应。

返回类型

属性

api_version

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

location_mode

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

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

primary_endpoint

完整的主终结点 URL。

primary_hostname

主终结点的主机名。

secondary_endpoint

完整的辅助终结点 URL(如果已配置)。

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

例外

secondary_hostname

辅助终结点的主机名。

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

url

此实体的完整终结点 URL,包括 SAS 令牌(如果使用)。

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