你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
ContainerClient 类
用于与特定容器交互的客户端,尽管该容器可能尚不存在。
对于与此容器中的特定 Blob 相关的操作,可以使用 函数检索 get_blob_client Blob 客户端。
有关更多可选配置,请 单击此处。
- 继承
-
azure.storage.blob._shared.base_client.StorageAccountHostsMixinContainerClientazure.storage.blob._encryption.StorageEncryptionMixinContainerClient
构造函数
ContainerClient(account_url: str, container_name: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any)
参数
- credential
用于进行身份验证的凭据。 如果帐户 URL 已具有 SAS 令牌,则这是可选的。 该值可以是 SAS 令牌字符串、azure.core.credentials 中的 AzureSasCredential 或 AzureNamedKeyCredential 的实例、帐户共享访问密钥或 azure.identity 中的 TokenCredentials 类的实例。 如果资源 URI 已包含 SAS 令牌,则会忽略此令牌,转而使用显式凭据
- AzureSasCredential 的情况除外,其中冲突的 SAS 令牌将引发 ValueError。 如果使用 AzureNamedKeyCredential 的实例,“name”应为存储帐户名称,“key”应为存储帐户密钥。
- 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 (无限租用) 。
- 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]
参数
- container_encryption_scope
- dict 或 ContainerEncryptionScope
指定要在容器上设置的默认加密范围,并用于将来的所有写入操作。
版本 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
参数
- 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 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时,请参阅 此处。
返回类型
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
- 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
- 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
- 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 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时,请参阅 此处。
返回类型
download_blob
将 Blob 下载到 StorageStreamDownloader。 readall () 方法必须用于读取所有内容,或者必须使用 readinto () 将 Blob 下载到流中。 使用区块 () 返回一个迭代器,该迭代器允许用户循环访问区块中的内容。
download_blob(blob: str | BlobProperties, offset: int = None, length: int = None, *, encoding: str, **kwargs) -> StorageStreamDownloader[str]
参数
- 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 中的新增功能。
使用给定密钥加密服务端的数据。 客户提供的密钥的使用必须通过 HTTPS 完成。 由于加密密钥本身是在请求中提供的,因此必须建立安全连接才能传输密钥。
- max_concurrency
- int
要下载的并行连接数。
- encoding
- str
用于解码下载的字节的编码。 默认值为 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
参数
- credential
用于进行身份验证的凭据。 如果帐户 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
参数
- credential
用于进行身份验证的凭据。 如果帐户 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
参数
- version_id
- str
版本 ID 参数是一个不透明的 DateTime 值,如果存在,则指定运行 Blob 的版本。
返回
BlobClient。
返回类型
get_container_access_policy
获取指定容器的权限。 这些权限指示是否可以公开访问容器数据。
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 中的策略信息。
返回类型
get_container_properties
返回指定容器的所有用户定义的元数据和系统属性。 返回的数据不包含该容器的 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 。 不会在客户端上跟踪或验证此值。 若要配置客户端网络超时,请参阅 此处。
返回
容器对象中指定容器的属性。
返回类型
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]
参数
指定要包含在响应中的一个或多个其他数据集。 选项包括:“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]
参数
- 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 和上次修改) 。
返回类型
set_container_metadata
为指定的容器设置一个或多个用户定义的名称-值对。 每次调用此操作时,将替换与容器关联的所有现有的元数据。 若要从容器中删除所有元数据,请调用此操作,不带元数据听写。
set_container_metadata(metadata: Dict[str, str] | None = None, **kwargs) -> Dict[str, str | datetime]
参数
- 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 和上次修改) 。
返回类型
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
- 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 按顺序对应一个
返回类型
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
- 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 按顺序对应一个
返回类型
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
参数
- data
要上传的 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 时要使用的最大并行连接数。
使用给定密钥加密服务端的数据。 客户提供的密钥的使用必须通过 HTTPS 完成。 由于加密密钥本身是在请求中提供的,因此必须建立安全连接才能传输密钥。
- encryption_scope
- str
用于加密服务上的数据的预定义加密范围。 可以使用管理 API 创建加密范围,并在此处按名称引用。 如果已在容器中定义了默认加密范围,则如果容器级范围配置为允许替代,则此值将覆盖它。 否则将引发错误。
版本 12.2.0 中的新增功能。
- encoding
- str
默认为 UTF-8。
用于跟踪长时间运行的上传进度的回调。 签名是函数 (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]
参数
指定要包含在响应中的一个或多个其他数据集。 选项包括:“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