azure.storage.blob.BlobClient class

中止正在进行的复制操作。

这将留下具有零长度和完整元数据的目标 Blob。如果复制操作已结束，则会引发错误。

abort_copy(copy_id: str | Dict[str, Any] | BlobProperties, **kwargs: Any) -> None

参数

copy_id: str 或 BlobProperties

必需

要中止的复制操作。这可以是 ID 字符串，也可以是 BlobProperties 的实例。

返回类型

None

请求新的租约。

如果 Blob 没有活动租约，则 Blob 服务将在 Blob 上创建租约并返回新租约。

acquire_lease(lease_duration: int = -1, lease_id: str | None = None, **kwargs: Any) -> 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 上使用的匹配条件。

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

返回

BlobLeaseClient 对象。

返回类型

BlobLeaseClient

将新的数据块提交到现有追加 blob 的末尾。

append_block(data: bytes | str | Iterable[AnyStr] | IO[AnyStr], length: int | None = None, **kwargs) -> Dict[str, str | datetime | int]

参数

data: bytes 或 str 或 Iterable

必需

块的内容。可以是字节、文本、可迭代对象或类似文件的对象。

length: int

必需

块的大小（以字节为单位）。

validate_content: bool

如果为 true，则计算块内容的 MD5 哈希。存储服务会检查已随发送的哈希一起到达的内容的哈希。如果使用 http 而不是 https，这主要适用于检测网络上的 bitflips，因为 https (默认) ，已得到验证。请注意，此 MD5 哈希值不与 Blob 一起存储。

maxsize_condition: int

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

appendpos_condition: int

可选条件标头，仅用于追加块操作。指示要比较的字节偏移量的数字。仅当追加位置等于此数字时，追加块才会成功。否则，请求将失败并出现 AppendPositionConditionNotMet 错误 (HTTP 状态代码 412 - 先决条件失败) 。

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 中的新增功能。

encoding: str

默认为 UTF-8。

cpk: CustomerProvidedEncryptionKey

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

encryption_scope: str

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

版本 12.2.0 中的新增功能。

timeout: int

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

返回

Blob 更新的属性 dict (Etag、上次修改、追加偏移量、提交块计数) 。

返回类型

dict(str, Any)

创建要作为 Blob 的一部分提交的新块，其中的内容从源 URL 读取。

append_block_from_url(copy_source_url: str, source_offset: int | None = None, source_length: int | None = None, **kwargs) -> Dict[str, str | datetime | int]

参数

copy_source_url: str

必需

源数据的 URL。它可以指向公共或附加共享访问签名的任何 Azure Blob 或文件。

source_offset: int

必需

这表示必须从复制源获取的字节范围 (非独占) 开始。

source_length: int

必需

这表示必须从复制源获取的字节范围的末尾。

source_content_md5: bytearray

如果给定，服务将计算块内容的 MD5 哈希，并将其与此值进行比较。

maxsize_condition: int

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

appendpos_condition: int

可选条件标头，仅用于追加块操作。指示要比较的字节偏移量的数字。仅当追加位置等于此数字时，追加块才会成功。否则，请求将失败并出现 AppendPositionConditionNotMet 错误 (HTTP 状态代码 412 - 先决条件失败) 。

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 中的新增功能。

source_if_modified_since: datetime

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

source_if_unmodified_since: datetime

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

source_etag: str

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

source_match_condition: MatchConditions

要用于 etag 的源匹配条件。

cpk: CustomerProvidedEncryptionKey

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

encryption_scope: str

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

版本 12.2.0 中的新增功能。

timeout: int

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

source_authorization: str

使用客户端密码作为服务主体进行身份验证，以访问源 Blob。确保“持有者”是source_authorization字符串的前缀。

清除一系列页面。

clear_page(offset: int, length: int, **kwargs: Any) -> Dict[str, str | datetime]

参数

offset: int

必需

用于写入 Blob 部分的字节范围的起始。页面必须与 512 字节边界对齐，起始偏移量必须为 512，长度必须为 512 的模数。

length: int

必需

用于写入 Blob 部分的字节数。页面必须与 512 字节边界对齐，起始偏移量必须为 512，长度必须为 512 的模数。

lease: BlobLeaseClient 或 str

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

if_sequence_number_lte: int

如果 blob 的序列号小于或等于指定的值，则请求继续;否则会失败。

if_sequence_number_lt: int

如果 blob 的序列号小于指定值，则请求将继续;否则会失败。

if_sequence_number_eq: int

如果 blob 的序列号等于指定值，则请求继续;否则会失败。

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 完成。由于加密密钥本身是在请求中提供的，因此必须建立安全连接才能传输密钥。

timeout: int

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

返回

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

返回类型

dict(str, Any)

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

close()

“提交阻止列表”操作通过指定构成 blob 的块 ID 列表来写入 Blob。

commit_block_list(block_list: List[BlobBlock], content_settings: ContentSettings | None = None, metadata: Dict[str, str] | None = None, **kwargs) -> Dict[str, str | datetime]

参数

block_list: list

必需

Blockblob 列表。

content_settings: ContentSettings

必需

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

metadata: dict[str, str]

必需

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

tags: dict(str, str)

与 Blob 关联的名称/值对作为标记。标记区分大小写。标记集最多可以包含 10 个标记。标记键必须介于 1 到 128 个字符之间，标记值必须介于 0 到 256 个字符之间。有效的标记键和值字符包括：小写字母和大写字母，数字 (0-9) ，空格 ( >><<) ，加上 (+) ，减去 (-) ，句点 (.) ，实心 (/) ，冒号 (：) ，等于 (=) ，下划线 (_)

版本 12.4.0 中的新增功能。

lease: BlobLeaseClient 或 str

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

immutability_policy: ImmutabilityPolicy

指定 Blob、blob 快照或 blob 版本的不可变性策略。

版本 12.10.0 中的新增功能：API 版本“2020-10-02”中引入了此功能。

legal_hold: bool

如果应在 Blob 上设置法定保留，则指定。

版本 12.10.0 中的新增功能：API 版本“2020-10-02”中引入了此功能。

validate_content: bool

如果为 true，则计算页面内容的 MD5 哈希。存储服务会检查已随发送的哈希一起到达的内容的哈希。如果使用 http 而不是 https，这主要适用于检测网络上的 bitflips，因为 https (默认) ，已得到验证。请注意，此 MD5 哈希值不与 Blob 一起存储。

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 上运行。

版本 12.4.0 中的新增功能。

standard_blob_tier: StandardBlobTier

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

cpk: CustomerProvidedEncryptionKey

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

encryption_scope: str

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

版本 12.2.0 中的新增功能。

timeout: int

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

返回

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

返回类型

dict(str, Any)

创建新的追加 Blob。此操作将创建新的 0 长度追加 blob。任何现有 Blob 的内容都将被新初始化的追加 blob 覆盖。若要将内容添加到追加 Blob，请调用 append_block 或 append_block_from_url 方法。

create_append_blob(content_settings: ContentSettings | None = None, metadata: Dict[str, str] | None = None, **kwargs: Any) -> Dict[str, str | datetime]

参数

content_settings: ContentSettings

必需

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

metadata: dict(str, str)

必需

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

tags: dict(str, str)

与 Blob 关联的名称/值对作为标记。标记区分大小写。标记集最多可以包含 10 个标记。标记键必须介于 1 到 128 个字符之间，标记值必须介于 0 到 256 个字符之间。有效的标记键和值字符包括：小写字母和大写字母，数字 (0-9) ，空格 ( >><<) ，加上 (+) ，减去 (-) ，句点 (.) ，实心 (/) ，冒号 (：) ，等于 (=) ，下划线 (_)

版本 12.4.0 中的新增功能。

lease: BlobLeaseClient 或 str

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

immutability_policy: ImmutabilityPolicy

指定 Blob、blob 快照或 blob 版本的不可变性策略。

版本 12.10.0 中的新增功能：API 版本“2020-10-02”中引入了此功能。

legal_hold: bool

如果应在 Blob 上设置法定保留，则指定。

版本 12.10.0 中的新增功能：API 版本“2020-10-02”中引入了此功能。

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

cpk: CustomerProvidedEncryptionKey

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

encryption_scope: str

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

版本 12.2.0 中的新增功能。

timeout: int

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

返回

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

返回类型

dict[str, Any]

创建指定大小的新页 Blob。

create_page_blob(size: int, content_settings: ContentSettings | None = None, metadata: Dict[str, str] | None = None, premium_page_blob_tier: str | PremiumPageBlobTier | None = None, **kwargs) -> Dict[str, str | datetime]

参数

size: int

必需

这指定页 Blob 的最大大小，最大为 1 TB。页 Blob 大小必须对齐 512 字节边界。

content_settings: ContentSettings

必需

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

metadata: dict(str, str)

必需

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

premium_page_blob_tier: PremiumPageBlobTier

必需

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

tags: dict(str, str)

与 Blob 关联的名称/值对作为标记。标记区分大小写。标记集最多可以包含 10 个标记。标记键必须介于 1 到 128 个字符之间，标记值必须介于 0 到 256 个字符之间。有效的标记键和值字符包括：小写字母和大写字母，数字 (0-9) ，空格 ( >><<) ，加上 (+) ，减去 (-) ，句点 (.) ，实心 (/) ，冒号 (：) ，等于 (=) ，下划线 (_)

版本 12.4.0 中的新增功能。

sequence_number: int

仅适用于页 blob。序列号是一个用户控制的值，可以用来跟踪请求。序列号的值必须介于 0 和 2^63 - 1 之间。默认值为 0。

lease: BlobLeaseClient 或 str

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

immutability_policy: ImmutabilityPolicy

指定 Blob、blob 快照或 blob 版本的不可变性策略。

版本 12.10.0 中的新增功能：API 版本“2020-10-02”中引入了此功能。

legal_hold: bool

如果应在 Blob 上设置法定保留，则指定。

版本 12.10.0 中的新增功能：API 版本“2020-10-02”中引入了此功能。

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

cpk: CustomerProvidedEncryptionKey

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

encryption_scope: str

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

版本 12.2.0 中的新增功能。

timeout: int

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

返回

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

返回类型

dict[str, Any]

创建 Blob 的快照。

快照是在某一时间点拍摄的只读版本的 Blob。它可以读取、复制或删除，但不能修改。利用快照，可以在某个时间点备份显示的 Blob。

Blob 的快照与从中创建快照的基本 Blob 具有相同的名称，但后面会追加一个 DateTime 值以指示创建快照的时间。

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

参数

metadata: dict(str, str)

必需

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

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 上运行。

版本 12.4.0 中的新增功能。

lease: BlobLeaseClient 或 str

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

cpk: CustomerProvidedEncryptionKey

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

encryption_scope: str

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

版本 12.2.0 中的新增功能。

timeout: int

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

返回

Blob 更新的属性 dict (快照 ID、Etag 和上次修改) 。

返回类型

dict[str, Any]

将指定的 Blob 标记为删除。

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

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

delete_blob(delete_snapshots: str = None, **kwargs: Any) -> None

参数

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 具有活动租约，则是必需的。如果指定，delete_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 中的新增功能。

timeout: int

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

返回类型

None

“删除不可变性策略”操作将删除 Blob 上的不可变性策略。

版本 12.10.0 中的新增功能：此操作是在 API 版本“2020-10-02”中引入的。

delete_immutability_policy(**kwargs: Any) -> None

参数

timeout: int

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

返回

Blob 标记的键值对。

返回类型

Dict[str, str]

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

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

参数

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

如果存在具有已定义参数的 Blob，则返回 True，否则返回 False。

exists(**kwargs: Any) -> bool

参数

version_id: str

version id 参数是一个不透明的 DateTime 值，如果存在，则指定要检查的 Blob 版本（如果存在）。

timeout: int

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

返回

boolean

返回类型

bool

从 Blob URL 创建 BlobClient。这不支持 Blob 名称中带有“/”的自定义 Blob URL。

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

参数

blob_url: str

必需

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

credential: Optional[Union[str, Dict[str, str], <xref:"AzureNamedKeyCredential">, <xref:"AzureSasCredential">, <xref:"TokenCredential">]] <xref:./>

默认值: None

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

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

snapshot: str

默认值: None

要对其操作的可选 blob 快照。这可以是快照 ID 字符串或从 create_snapshot返回的响应。如果指定，这将替代 url 中的快照。

version_id: str

version id 参数是一个不透明的 DateTime 值，如果存在，则指定要操作的 Blob 版本。

返回

Blob 客户端。

返回类型

BlobClient

从连接字符串创建 BlobClient。

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

参数

conn_str: str

必需

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

container_name: str

必需

Blob 的容器名称。

blob_name: str

必需

要与之交互的 Blob 的名称。

snapshot: str

默认值: None

要对其操作的可选 blob 快照。这可以是快照 ID 字符串或从 create_snapshot返回的响应。

credential: Optional[Union[str, Dict[str, str], <xref:"AzureNamedKeyCredential">, <xref:"AzureSasCredential">, <xref:"TokenCredential">]] <xref:./>

默认值: None

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

version_id: str

version id 参数是一个不透明的 DateTime 值，如果存在，则指定要操作的 Blob 版本。

返回

Blob 客户端。

返回类型

BlobClient

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

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

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

返回

帐户信息 (SKU 和帐户类型) 。

返回类型

dict(str, str)

返回 Blob 的所有用户定义的元数据、标准 HTTP 属性和系统属性。它不返回 Blob 的内容。

get_blob_properties(**kwargs: Any) -> BlobProperties

参数

lease: BlobLeaseClient 或 str

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

version_id: str

version id 参数是一个不透明的 DateTime 值，如果存在，则指定要获取属性的 Blob 版本。

版本 12.4.0 中的新增功能。

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

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 使用客户提供的密钥。由于加密密钥本身是在请求中提供的，因此必须建立安全连接才能传输密钥。

timeout: int

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

返回

BlobProperties

返回类型

BlobProperties

“获取标记”操作使用户能够获取 blob 或特定 blob 版本或快照上的标记。

版本 12.4.0 中的新增功能：此操作是在 API 版本“2019-12-12”中引入的。

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

参数

version_id: str

version id 参数是一个不透明的 DateTime 值，如果存在，则指定要向其添加标记的 Blob 版本。

if_tags_match_condition: str

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

lease: BlobLeaseClient 或 str

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

timeout: int

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

返回

Blob 标记的键值对。

返回类型

Dict[str, str]

“获取块列表”操作检索已作为块 Blob 的一部分上传的块列表。

get_block_list(block_list_type: str | None = 'committed', **kwargs: Any) -> Tuple[List[BlobBlock], List[BlobBlock]]

参数

block_list_type: str

必需

指定是返回已提交的块列表，返回未提交的块列表，还是同时返回这两个列表。可能的值包括：“committed”、“uncommitted”、“all”

lease: BlobLeaseClient 或 str

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

if_tags_match_condition: str

指定 Blob 标记上的 SQL where 子句，以便仅在具有匹配值的目标 Blob 上运行。

版本 12.4.0 中的新增功能。

timeout: int

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

返回

包含两个列表的元组 - 已提交和未提交的块

返回类型

tuple(list(BlobBlock), list(BlobBlock))

返回托管磁盘或快照的有效页范围列表。

注意

此操作仅适用于托管磁盘帐户。

版本 12.2.0 中的新增功能：此操作是在 API 版本“2019-07-07”中引入的。

get_page_range_diff_for_managed_disk(previous_snapshot_url: str, offset: int | None = None, length: int | None = None, **kwargs) -> Tuple[List[Dict[str, int]], List[Dict[str, int]]]

参数

previous_snapshot_url

必需

指定托管磁盘上一快照的 URL。响应将仅包含目标 blob 与其上一个快照之间已更改的页面。

offset: int

必需

要用于获取有效页面范围的字节范围的开头。如果未给定长度，则将搜索偏移量后的所有字节。页必须与 512 字节边界对齐，起始偏移量必须为 512，长度必须为 512 的模数。

length: int

必需

用于获取有效页面范围的字节数。如果给定长度，则必须提供偏移量。此范围将返回从偏移开始到指定长度的有效页面范围。页必须与 512 字节边界对齐，起始偏移量必须为 512，长度必须为 512 的模数。

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

timeout: int

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

返回

包含两个页面范围列表的元组，作为带有“start”和“end”键的字典。第一个元素是填充的页面范围，第二个元素是清除页面范围。

返回类型

tuple(list(dict(str, str), list(dict(str, str))

已弃用：返回页 Blob 的有效页范围列表或页 blob 的快照。

get_page_ranges(offset: int | None = None, length: int | None = None, previous_snapshot_diff: str | Dict[str, Any] | None = None, **kwargs) -> Tuple[List[Dict[str, int]], List[Dict[str, int]]]

参数

offset: int

必需

要用于获取有效页面范围的字节范围的开头。如果未给定长度，则将搜索偏移量后的所有字节。页必须与 512 字节边界对齐，起始偏移量必须为 512，长度必须为 512 的模数。

length: int

必需

用于获取有效页面范围的字节数。如果给定长度，则必须提供偏移量。此范围将返回从偏移开始到指定长度的有效页面范围。页必须与 512 字节边界对齐，起始偏移量必须为 512，长度必须为 512 的模数。

previous_snapshot_diff: str

必需

快照差异参数，该参数包含一个不透明的 DateTime 值，该值指定以前的 blob 快照与较新的快照或当前 blob 进行比较。

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

返回

包含两个页面范围列表的元组，作为带有“start”和“end”键的字典。第一个元素是填充的页面范围，第二个元素是清除页面范围。

返回类型

tuple(list(dict(str, str), list(dict(str, str))

返回页 Blob 或页 blob 快照的有效页范围列表。如果指定了previous_snapshot，则结果将是目标 blob 与上一个快照之间的更改差异。

list_page_ranges(*, offset: int | None = None, length: int | None = None, previous_snapshot: str | Dict[str, Any] | None = None, **kwargs: Any) -> ItemPaged[PageRange]

参数

offset: int

要用于获取有效页面范围的字节范围的开头。如果未给定长度，则将搜索偏移量后的所有字节。页必须与 512 字节边界对齐，起始偏移量必须为 512，长度必须为 512 的模数。

length: int

用于获取有效页面范围的字节数。如果给定长度，则必须提供偏移量。此范围将返回从偏移开始到指定长度的有效页面范围。页必须与 512 字节边界对齐，起始偏移量必须为 512，长度必须为 512 的模数。

previous_snapshot: str 或 Dict[str, Any]

一个快照值，该值指定响应将仅包含目标 blob 与上一个快照之间更改的页面。已更改的页面包括更新和清除的页面。目标 blob 可以是快照，只要 previous_snapshot 指定的快照是两者中较早的。

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 中的新增功能。

results_per_page: int

每个 API 调用要检索的最大页范围数。

timeout: int

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

返回

PageRange 的可迭代 (自动分页) 。

返回类型

ItemPaged[PageRange]

允许用户通过提供简单的查询表达式来选择/投影 blob/或 blob 快照数据。此操作返回 BlobQueryReader，用户需要使用 readall () 或 readinto () 获取查询数据。

query_blob(query_expression: str, **kwargs: Any) -> BlobQueryReader

参数

query_expression: str

必需

必需。查询语句。有关详细信息，请参阅 https://learn.microsoft.com/azure/storage/blobs/query-acceleration-sql-reference 。

on_error: Callable[BlobQueryError]

要针对服务返回的任何处理错误调用的函数。

blob_format: DelimitedTextDialect 或 DelimitedJsonDialect 或 QuickQueryDialect 或 str

可选。定义当前存储在 Blob 中的数据的序列化。默认设置是将 blob 数据视为采用默认方言格式的 CSV 数据。这可以使用自定义 DelimitedTextDialect、DelimitedJsonDialect 或“ParquetDialect” (作为字符串或枚举) 传递来重写。这些方言可以通过各自的类、QuickQueryDialect 枚举或作为字符串传递

output_format: DelimitedTextDialect 或 DelimitedJsonDialect 或 list[ArrowDialect] 或 QuickQueryDialect 或 str

可选。定义数据流的输出序列化。默认情况下，将返回数据，因为它在 blob 中表示， (Parquet 格式默认为 DelimitedTextDialect) 。通过提供输出格式，将根据该配置文件重新设置 Blob 数据的格式。此值可以是 DelimitedTextDialect、DelimitedJsonDialect 或 ArrowDialect。这些方言可以通过各自的类、QuickQueryDialect 枚举或作为字符串传递

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 中的新增功能。

cpk: CustomerProvidedEncryptionKey

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

timeout: int

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

返回

BlobQueryReader) (流式处理对象

返回类型

BlobQueryReader

将页 Blob 调整为指定大小。

如果指定的值小于当前的 Blob 大小，则会清除超过指定值的所有页面。

resize_blob(size: int, **kwargs: Any) -> Dict[str, str | datetime]

参数

size: int

必需

用于调整 Blob 大小的大小。页 Blob 的最大大小为 1 TB。页 Blob 大小必须对齐 512 字节边界。

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 中的新增功能。

premium_page_blob_tier: PremiumPageBlobTier

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

timeout: int

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

返回

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

返回类型

dict(str, Any)

密封操作会密封追加 Blob，使其成为只读的。

版本 12.4.0 中的新增功能。

seal_append_blob(**kwargs) -> Dict[str, str | datetime | int]

参数

appendpos_condition: int

可选条件标头，仅用于追加块操作。指示要比较的字节偏移量的数字。仅当追加位置等于此数字时，追加块才会成功。否则，请求将失败，并出现 AppendPositionConditionNotMet 错误 (HTTP 状态代码 412 - 先决条件失败) 。

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

timeout: int

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

返回

Blob 更新的属性 dict (Etag、上次修改时间、追加偏移量、提交的块计数) 。

返回类型

dict(str, Any)

将 Blob 的用户定义元数据设置为一个或多个名称/值对。

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

参数

metadata: dict(str, str)

必需

包含名称和值对的 Dict。每次调用此操作都会替换附加到该 Blob 的所有现有元数据。要从该 Blob 中删除所有元数据，请不带任何元数据头调用此操作。

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 中的新增功能。

cpk: CustomerProvidedEncryptionKey

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

encryption_scope: str

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

版本 12.2.0 中的新增功能。

timeout: int

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

返回

Blob 更新的属性 dict (Etag 和上次修改)

“设置标记”操作使用户能够在 blob 或特定 Blob 版本上设置标记，但不能快照。每次调用此操作都会替换附加到 Blob 的所有现有标记。若要从 Blob 中删除所有标记，请在未设置标记的情况下调用此操作。

版本 12.4.0 中的新增功能：此操作是在 API 版本“2019-12-12”中引入的。

set_blob_tags(tags: Dict[str, str] | None = None, **kwargs: Any) -> Dict[str, Any]

参数

tags: dict(str, str)

必需

与 Blob 关联的名称/值对作为标记。标记区分大小写。标记集最多可以包含 10 个标记。标记键必须介于 1 到 128 个字符之间，标记值必须介于 0 到 256 个字符之间。有效的标记键和值字符包括：小写字母和大写字母，数字 (0-9) ，空格 ( >><<) ，加上 (+) ，减去 (-) ，句点 (.) ，实心 (/) ，冒号 (：) ，等于 (=) ，下划线 (_)

version_id: str

版本 ID 参数是一个不透明的 DateTime 值，如果存在，则指定要向其添加标记的 Blob 版本。

validate_content: bool

如果为 true，则计算标记内容的 MD5 哈希。存储服务会检查已随发送的哈希一起到达的内容的哈希。如果使用 http 而不是 https，这主要适用于检测网络上的 bitflips，因为 https (默认) ，已得到验证。请注意，此 MD5 哈希值不与 Blob 一起存储。

if_tags_match_condition: str

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

lease: BlobLeaseClient 或 str

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

timeout: int

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

返回

Blob 更新的属性 dict (Etag 和上次修改)

返回类型

Dict[str, Any]

在 blob 上设置系统属性。

如果为content_settings设置了一个属性，则将重写所有属性。

set_http_headers(content_settings: ContentSettings | None = None, **kwargs: Any) -> None

参数

content_settings: ContentSettings

必需

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

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

返回

Blob 更新的属性 dict (Etag 和上次修改)

返回类型

Dict[str, Any]

“设置不可变性策略”操作在 Blob 上设置不可变性策略。

版本 12.10.0 中的新增功能：此操作是在 API 版本“2020-10-02”中引入的。

set_immutability_policy(immutability_policy: ImmutabilityPolicy, **kwargs: Any) -> Dict[str, str]

参数

immutability_policy: ImmutabilityPolicy

必需

指定 Blob、blob 快照或 blob 版本的不可变性策略。

版本 12.10.0 中的新增功能：API 版本“2020-10-02”中引入了此功能。

timeout: int

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

返回

Blob 标记的键值对。

返回类型

Dict[str, str]

“设置法定保留”操作在 Blob 上设置法定保留。

版本 12.10.0 中的新增功能：此操作是在 API 版本“2020-10-02”中引入的。

set_legal_hold(legal_hold: bool, **kwargs: Any) -> Dict[str, str | datetime | bool]

参数

legal_hold: bool

必需

如果应在 Blob 上设置法定保留，则指定。

timeout: int

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

返回

Blob 标记的键值对。

返回类型

Dict[str, Union[str, datetime, bool]]

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

set_premium_page_blob_tier(premium_page_blob_tier: str | PremiumPageBlobTier, **kwargs: Any) -> None

参数

premium_page_blob_tier: PremiumPageBlobTier

必需

要设置 Blob 的页 Blob 层值。层与 Blob 的大小和允许的 IOPS 数相关联。这仅适用于高级存储帐户上的页 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 。不会在客户端上跟踪或验证此值。若要配置客户端网络超时，请参阅此处。

lease: BlobLeaseClient 或 str

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

返回类型

None

设置 blob 序列号。

set_sequence_number(sequence_number_action: str | SequenceNumberAction, sequence_number: str | None = None, **kwargs: Any) -> Dict[str, str | datetime]

参数

sequence_number_action: str

必需

此属性指示服务应如何修改 Blob 的序列号。有关详细信息，请参阅SequenceNumberAction。

sequence_number: str

必需

此属性设置 Blob 的序列号。序列号是一个用户控制的属性，可用于跟踪请求和管理并发性问题。

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

返回

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

返回类型

dict(str, Any)

此操作设置块 Blob 上的层。

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

set_standard_blob_tier(standard_blob_tier: str | StandardBlobTier, **kwargs: Any) -> None

参数

standard_blob_tier: str 或 StandardBlobTier

必需

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

rehydrate_priority: RehydratePriority

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

version_id: str

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

版本 12.4.0 中的新增功能。

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

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

lease: BlobLeaseClient 或 str

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

返回类型

None

创建一个要作为 Blob 组成部分提交的新块。

stage_block(block_id: str, data: Iterable | IO, length: int | None = None, **kwargs) -> Dict[str, Any]

参数

block_id: str

必需

标识块的字符串值。字符串的大小应小于或等于 64 个字节。对于给定的 Blob，每个块的block_id大小必须相同。

data

必需

Blob 数据。

length: int

必需

块的大小。

validate_content: bool

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

lease: BlobLeaseClient 或 str

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

encoding: str

默认为 UTF-8。

cpk: CustomerProvidedEncryptionKey

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

encryption_scope: str

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

版本 12.2.0 中的新增功能。

timeout: int

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

返回

Blob 属性 dict。

返回类型

dict[str, Any]

创建要作为 Blob 的一部分提交的新块，其中的内容是从 URL 读取的。

stage_block_from_url(block_id: str | int, source_url: str, source_offset: int | None = None, source_length: int | None = None, source_content_md5: bytes | bytearray | None = None, **kwargs) -> Dict[str, Any]

参数

block_id: str

必需

标识块的字符串值。字符串的大小应小于或等于 64 个字节。对于给定的 Blob，每个块的block_id大小必须相同。

source_url: str

必需

URL。

source_offset: int

必需

要用于块的字节范围的开头。如果提供了源长度，则必须设置。

source_length: int

必需

块的大小（以字节为单位）。

source_content_md5: bytearray

必需

指定为必须从复制源读取的字节范围计算的 md5。

lease: BlobLeaseClient 或 str

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

cpk: CustomerProvidedEncryptionKey

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

encryption_scope: str

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

版本 12.2.0 中的新增功能。

timeout: int

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

source_authorization: str

使用客户端密码作为服务主体进行身份验证，以访问源 Blob。确保“持有者”是source_authorization字符串的前缀。

返回

Blob 属性 dict。

返回类型

dict[str, Any]

从给定 URL 复制 Blob。

此操作返回包含copy_status和copy_id的字典，可用于检查复制操作的状态或中止复制操作。如果复制同步完成，则copy_status为“成功”;如果复制已异步启动，则为“挂起”。对于异步副本，可以通过轮询 get_blob_properties 方法并检查复制状态来检查状态。 将requires_sync设置为 True 以强制复制为同步。 BLOB 服务尽量复制 Blob。

复制操作的源 Blob 可以是块 Blob、追加 Blob 或页 Blob。如果目标 Blob 已存在，该 Blob 的类型必须与源 Blob 的类型相同。将覆盖任何现有的目标 Blob。复制操作进行时不能修改目标 Blob。

从页 Blob 复制时，Blob 服务会创建源 Blob 长度的目标页 Blob，最初包含所有零。然后枚举页面范围，复制非空范围。

对于块 Blob 或追加 Blob，Blob 服务会在此操作返回之前创建长度为零的已提交 blob。从块 Blob 复制时，将复制所有已提交的块及其块 ID。不会复制未提交的块。在复制操作结束时，目标 Blob 将具有与源相同的已提交块计数。

从追加 Blob 复制时，将复制所有提交的块。在复制操作结束时，目标 Blob 将具有与源相同的已提交块计数。

start_copy_from_url(source_url: str, metadata: Dict[str, str] | None = None, incremental_copy: bool = False, **kwargs: Any) -> Dict[str, str | datetime]

参数

source_url: str

必需

长度为 2 KB 的 URL，用于指定文件或 Blob。此值应为 URL 编码，如同它显示在请求 URI 中那样。如果源位于另一个帐户中，则源必须是公共的，或者必须通过共享访问签名进行身份验证。如果源是公共的，则无需身份验证。示例：https://myaccount.blob.core.windows.net/mycontainer/myblob

https://myaccount.blob.core.windows.net/mycontainer/myblob?快照=

https://otheraccount.blob.core.windows.net/mycontainer/myblob?sastoken

metadata: dict(str, str)

必需

作为元数据、与 Blob 关联的名称-值对。如果未指定名称/值对，则操作会将元数据从源 Blob 或文件复制到目标 Blob。如果指定了一个或多个名称/值对，则使用指定的元数据创建目标 Blob，并且不会从源 Blob 或文件复制元数据。

incremental_copy: bool

必需

将源页 blob 的快照复制到目标页 Blob。复制快照，以便仅将以前复制快照之间的差异更改传输到目标。复制的快照是原始快照的完整副本，可以像往常一样从中读取或复制。默认为 False。

tags: dict(str, str) 或 Literal["COPY"]

与 Blob 关联的名称/值对作为标记。标记区分大小写。标记集最多可以包含 10 个标记。标记键必须介于 1 到 128 个字符之间，标记值必须介于 0 到 256 个字符之间。有效的标记键和值字符包括：小写字母和大写字母，数字 (0-9) ，空格 ( >><<) ，加上 (+) ，减去 (-) ，句点 (.) ，实体 (/) ，冒号 (：) ，等于 (=) ，下划线 (_) 。

可以传递 (区分大小写) 文本“COPY”，以从源 Blob 复制标记。仅当 incremental_copy=False 且 requires_sync=True 时，此选项才可用。

版本 12.4.0 中的新增功能。

immutability_policy: ImmutabilityPolicy

指定 Blob、blob 快照或 blob 版本的不可变性策略。

版本 12.10.0 中的新增功能：API 版本“2020-10-02”中引入了此功能。

legal_hold: bool

如果应在 Blob 上设置法定保留，则指定。

版本 12.10.0 中的新增功能：API 版本“2020-10-02”中引入了此功能。

source_if_modified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。如果指定此条件头，则仅当源 Blob 自指定日期/时间后发生了修改时才复制 Blob。

source_if_unmodified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。如果指定此条件头，则仅当源 Blob 自指定日期/时间后未修改时才复制 Blob。

source_etag: str

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

source_match_condition: MatchConditions

要用于 etag 的源匹配条件。

if_modified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。如果指定此条件头，则仅当目标 Blob 自指定日期/时间后发生了修改时才复制 Blob。如果目标 Blob 未修改，BLOB 服务将返回状态代码 412（不满足前提条件）。

if_unmodified_since: datetime

一个日期时间值。 Azure 预期传入的日期值为 UTC。如果包含时区，则任何非 UTC 日期时间都将转换为 UTC。如果传入的日期没有时区信息，则假定该日期为 UTC。如果指定此条件头，则仅当目标 Blob 自指定日期/时间后未修改时才复制 Blob。如果目标 Blob 已修改，BLOB 服务将返回状态代码 412（不满足前提条件）。

etag: str

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

match_condition: MatchConditions

要用于 etag 的目标匹配条件。

destination_lease: BlobLeaseClient 或 str

此标头的租约 ID 必须与目标 Blob 的租约 ID 匹配。如果请求中不包含租约 ID 或租约 ID 无效，则操作将失败，且显示状态码 412（不满足前提条件）。

source_lease: BlobLeaseClient 或 str

仅当给定的租约 ID 与源 Blob 的活动租约 ID 匹配时，指定此项才能执行复制 Blob 操作。

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。

rehydrate_priority: RehydratePriority

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

seal_destination_blob: bool

密封目标追加 blob。此操作仅适用于追加 blob。

版本 12.4.0 中的新增功能。

requires_sync: bool

强制服务在复制完成之前不会返回响应。

source_authorization: str

使用客户端密码作为服务主体进行身份验证，以访问源 Blob。确保“持有者”是source_authorization字符串的前缀。仅当 incremental_copy 设置为 False 且 requires_sync 设置为 True 时，此选项才可用。

版本 12.9.0 中的新增功能。

encryption_scope: str

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

版本 12.10.0 中的新增功能。

返回

etag、last_modified、copy_id、copy_status) (复制属性的字典。

返回类型

dict[str, Union[str, datetime]]

还原软删除的 Blob 或快照。

只有在删除保留策略中设置的指定天数内使用时，操作才会成功。

如果启用了 Blob 版本控制，则无法使用此方法还原基本 Blob。请改为将与要提升为当前版本的 Blob 版本的 URL 一起使用 start_copy_from_url 。

undelete_blob(**kwargs: Any) -> None

参数

timeout: int

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

返回类型

None

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

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

参数

data

必需

要上传的 Blob 数据。

blob_type: BlobType

必需

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

length: int

必需

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

metadata: dict(str, str)

必需

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

tags: dict(str, str)

与作为标记的 Blob 关联的名称/值对。标记区分大小写。标记集最多可以包含 10 个标记。标记键必须介于 1 到 128 个字符之间，标记值必须介于 0 到 256 个字符之间。有效的标记键和值字符包括：小写字母和大写字母、 digits (0-9) 、space ( >><<) 、plus (+) 、减 (-) 、句点 (.) 、solidus (/) 、冒号 (：) 、等于 (=) 、下划线 (_)

版本 12.4.0 中的新增功能。

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

如果 Blob 具有活动租约，则是必需的。如果指定，则仅当 blob 的租约处于活动状态且与此 ID 匹配时，upload_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 中的新增功能。

premium_page_blob_tier: PremiumPageBlobTier

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

standard_blob_tier: StandardBlobTier

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

immutability_policy: ImmutabilityPolicy

指定 Blob、blob 快照或 Blob 版本的不可变性策略。目前，upload_blob () API 的此参数仅适用于 BlockBlob。

版本 12.10.0 中的新增功能：这是在 API 版本“2020-10-02”中引入的。

legal_hold: bool

如果应在 Blob 上设置法定保留，则指定。目前，upload_blob () API 的此参数仅适用于 BlockBlob。

版本 12.10.0 中的新增功能：这是在 API 版本“2020-10-02”中引入的。

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。

timeout: int

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

返回

Blob 更新的属性 dict (Etag 和上次修改)

返回类型

dict[str, Any]

创建一个新的块 Blob，其中 Blob 的内容是从给定 URL 读取的。现有 Blob 的内容将被新 Blob 覆盖。

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

参数

source_url: str

必需

长度为 2 KB 的 URL，用于指定文件或 Blob。此值应为 URL 编码，如同它显示在请求 URI 中那样。如果源位于另一个帐户中，则源必须是公共的，或者必须通过共享访问签名进行身份验证。如果源是公共的，则无需身份验证。示例：https://myaccount.blob.core.windows.net/mycontainer/myblob

https://myaccount.blob.core.windows.net/mycontainer/myblob?快照=

https://otheraccount.blob.core.windows.net/mycontainer/myblob?sastoken

overwrite: bool

要上传的 Blob 是否应覆盖当前数据。如果为 True，upload_blob将覆盖现有数据。如果设置为 False，则操作将失败并出现 ResourceExistsError。

include_source_blob_properties: bool

指示是否应复制源 Blob 中的属性。默认为 True。

tags: dict(str, str)

与 Blob 关联的名称/值对作为标记。标记区分大小写。标记集最多可以包含 10 个标记。标记键必须介于 1 到 128 个字符之间，标记值必须介于 0 到 256 个字符之间。有效的标记键和值字符包括：小写字母和大写字母，数字 (0-9) ，空格 ( >><<) ，加上 (+) ，减去 (-) ，句点 (.) ，实心 (/) ，冒号 (：) ，等于 (=) ，下划线 (_)

source_content_md5: bytearray

指定用于验证源字节完整性的 md5。

source_if_modified_since: datetime

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

source_if_unmodified_since: datetime

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

source_etag: str

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

source_match_condition: MatchConditions

要用于 etag 的源匹配条件。

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 的目标匹配条件。

destination_lease: BlobLeaseClient 或 str

此标头的租约 ID 必须与目标 Blob 的租约 ID 匹配。如果请求中不包含租约 ID 或租约 ID 无效，则操作将失败，且显示状态码 412（不满足前提条件）。

timeout: int

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

content_settings: ContentSettings

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

cpk: CustomerProvidedEncryptionKey

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

encryption_scope: str

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

standard_blob_tier: StandardBlobTier

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

source_authorization: str

使用客户端密码作为服务主体进行身份验证，以访问源 Blob。确保“持有者”是source_authorization字符串的前缀。

“上传页面”操作将一系列页面写入页 Blob。

upload_page(page: bytes, offset: int, length: int, **kwargs) -> Dict[str, str | datetime]

参数

page: bytes

必需

页面的内容。

offset: int

必需

用于写入 Blob 部分的字节范围的起始。页面必须与 512 字节边界对齐，起始偏移量必须为 512，长度必须为 512 的模数。

length: int

必需

用于写入 Blob 部分的字节数。页面必须与 512 字节边界对齐，起始偏移量必须为 512，长度必须为 512 的模数。

lease: BlobLeaseClient 或 str

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

validate_content: bool

如果为 true，则计算页面内容的 MD5 哈希。存储服务会检查已随发送的哈希一起到达的内容的哈希。如果使用 http 而不是 https，这主要适用于检测网络上的 bitflips，因为 https (默认) ，已得到验证。请注意，此 MD5 哈希值不与 Blob 一起存储。

if_sequence_number_lte: int

如果 blob 的序列号小于或等于指定的值，则请求继续;否则会失败。

if_sequence_number_lt: int

如果 blob 的序列号小于指定值，则请求将继续;否则会失败。

if_sequence_number_eq: int

如果 blob 的序列号等于指定值，则请求继续;否则会失败。

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 完成。由于加密密钥本身是在请求中提供的，因此必须建立安全连接才能传输密钥。

encryption_scope: str

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

版本 12.2.0 中的新增功能。

encoding: str

默认为 UTF-8。

timeout: int

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

返回

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

返回类型

dict(str, Any)

“上传页面”操作将一系列页面写入页 Blob，其中的内容是从 URL 读取的。

upload_pages_from_url(source_url: str, offset: int, length: int, source_offset: int, **kwargs) -> Dict[str, Any]

参数

source_url: str

必需

源数据的 URL。它可以指向公共或附加共享访问签名的任何 Azure Blob 或文件。

offset: int

必需

用于写入 Blob 部分的字节范围的起始。页面必须与 512 字节边界对齐，起始偏移量必须为 512，长度必须为 512 的模数。

length: int

必需

用于写入 Blob 部分的字节数。页面必须与 512 字节边界对齐，起始偏移量必须为 512，长度必须为 512 的模数。

source_offset: int

必需

这表示必须从复制源获取的字节范围 (非独占) 的起始。该服务将读取与目标范围相同的字节数， (长度偏移) 。

source_content_md5: bytes

如果给定，服务将计算块内容的 MD5 哈希，并将其与此值进行比较。

source_if_modified_since: datetime

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

source_if_unmodified_since: datetime

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

source_etag: str

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

source_match_condition: MatchConditions

要用于 etag 的源匹配条件。

lease: BlobLeaseClient 或 str

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

if_sequence_number_lte: int

如果 blob 的序列号小于或等于指定的值，则请求继续;否则会失败。

if_sequence_number_lt: int

如果 blob 的序列号小于指定值，则请求将继续;否则会失败。

if_sequence_number_eq: int

如果 blob 的序列号等于指定值，则请求继续;否则会失败。

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 完成。由于加密密钥本身是在请求中提供的，因此必须建立安全连接才能传输密钥。

encryption_scope: str

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

版本 12.2.0 中的新增功能。

timeout: int

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

source_authorization: str

使用客户端密码作为服务主体进行身份验证，以访问源 Blob。确保“持有者”是source_authorization字符串的前缀。

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

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

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

完整的主终结点 URL。

主终结点的主机名。

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

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

例外

ValueError

辅助终结点的主机名。

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

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

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

abort_copy	中止正在进行的复制操作。这将留下具有零长度和完整元数据的目标 Blob。如果复制操作已结束，则会引发错误。
acquire_lease	请求新的租约。如果 Blob 没有活动租约，则 Blob 服务将在 Blob 上创建租约并返回新租约。
append_block	将新的数据块提交到现有追加 blob 的末尾。
append_block_from_url	创建要作为 Blob 的一部分提交的新块，其中的内容从源 URL 读取。
clear_page	清除一系列页面。
close	此方法用于关闭客户端打开的套接字。与上下文管理器一起使用时，不需要使用它。
commit_block_list	“提交阻止列表”操作通过指定构成 blob 的块 ID 列表来写入 Blob。
create_append_blob	创建新的追加 Blob。此操作将创建新的 0 长度追加 blob。任何现有 Blob 的内容都将被新初始化的追加 blob 覆盖。若要将内容添加到追加 Blob，请调用 append_block 或 append_block_from_url 方法。
create_page_blob	创建指定大小的新页 Blob。
create_snapshot	创建 Blob 的快照。快照是在某一时间点拍摄的只读版本的 Blob。它可以读取、复制或删除，但不能修改。利用快照，可以在某个时间点备份显示的 Blob。 Blob 的快照与从中创建快照的基本 Blob 具有相同的名称，但后面会追加一个 DateTime 值以指示创建快照的时间。
delete_blob	将指定的 Blob 标记为删除。该 Blob 将在稍后的垃圾回收期间删除。请注意，要删除 Blob，必须删除其所有快照。可以使用 delete_blob () 操作同时删除这两者。如果为服务启用了删除保留策略，则此操作将软删除 Blob 并将 Blob 保留指定的天数。在指定的天数之后，Blob 的数据在垃圾回收期间会从服务中删除。可以通过 list_blobs 指定 include=['deleted'] 选项访问软删除的 blob。可以使用操作还原软删除的 <xref:azure.storage.blob.undelete> Blob。
delete_immutability_policy	“删除不可变性策略”操作将删除 Blob 上的不可变性策略。版本 12.10.0 中的新增功能：此操作是在 API 版本“2020-10-02”中引入的。
download_blob	将 Blob 下载到 StorageStreamDownloader。 readall () 方法必须用于读取所有内容，或使用 readinto () 将 Blob 下载到流中。使用 chunks () 将返回一个迭代器，该迭代器允许用户循环访问区块中的内容。
exists	如果存在具有已定义参数的 Blob，则返回 True，否则返回 False。
from_blob_url	从 Blob URL 创建 BlobClient。这不支持 Blob 名称中带有“/”的自定义 Blob URL。
from_connection_string	从连接字符串创建 BlobClient。
get_account_information	获取与 Blob 所在的存储帐户相关的信息。如果用户具有对容器或 Blob 的 SAS，也可以检索该信息。返回的字典中的键包括“sku_name”和“account_kind”。
get_blob_properties	返回 Blob 的所有用户定义的元数据、标准 HTTP 属性和系统属性。它不返回 Blob 的内容。
get_blob_tags	“获取标记”操作使用户能够获取 blob 或特定 blob 版本或快照上的标记。版本 12.4.0 中的新增功能：此操作是在 API 版本“2019-12-12”中引入的。
get_block_list	“获取块列表”操作检索已作为块 Blob 的一部分上传的块列表。
get_page_range_diff_for_managed_disk	返回托管磁盘或快照的有效页范围列表。注意此操作仅适用于托管磁盘帐户。版本 12.2.0 中的新增功能：此操作是在 API 版本“2019-07-07”中引入的。
get_page_ranges	已弃用：返回页 Blob 的有效页范围列表或页 blob 的快照。
list_page_ranges	返回页 Blob 或页 blob 快照的有效页范围列表。如果指定了previous_snapshot，则结果将是目标 blob 与上一个快照之间的更改差异。
query_blob	允许用户通过提供简单的查询表达式来选择/投影 blob/或 blob 快照数据。此操作返回 BlobQueryReader，用户需要使用 readall () 或 readinto () 获取查询数据。
resize_blob	将页 Blob 调整为指定大小。如果指定的值小于当前的 Blob 大小，则会清除超过指定值的所有页面。
seal_append_blob	密封操作会密封追加 Blob，使其成为只读的。版本 12.4.0 中的新增功能。
set_blob_metadata	将 Blob 的用户定义元数据设置为一个或多个名称/值对。
set_blob_tags	“设置标记”操作使用户能够在 blob 或特定 Blob 版本上设置标记，但不能快照。每次调用此操作都会替换附加到 Blob 的所有现有标记。若要从 Blob 中删除所有标记，请在未设置标记的情况下调用此操作。版本 12.4.0 中的新增功能：此操作是在 API 版本“2019-12-12”中引入的。
set_http_headers	在 blob 上设置系统属性。如果为content_settings设置了一个属性，则将重写所有属性。
set_immutability_policy	“设置不可变性策略”操作在 Blob 上设置不可变性策略。版本 12.10.0 中的新增功能：此操作是在 API 版本“2020-10-02”中引入的。
set_legal_hold	“设置法定保留”操作在 Blob 上设置法定保留。版本 12.10.0 中的新增功能：此操作是在 API 版本“2020-10-02”中引入的。
set_premium_page_blob_tier	设置 Blob 上的页 Blob 层。仅高级帐户上的页 Blob 支持此 API。
set_sequence_number	设置 blob 序列号。
set_standard_blob_tier	此操作设置块 Blob 上的层。块 Blob 的层确定热/冷/存档存储类型。此操作不会更新 Blob 的 ETag。
stage_block	创建一个要作为 Blob 组成部分提交的新块。
stage_block_from_url	创建要作为 Blob 的一部分提交的新块，其中的内容是从 URL 读取的。
start_copy_from_url	从给定 URL 复制 Blob。此操作返回包含copy_status和copy_id的字典，可用于检查复制操作的状态或中止复制操作。如果复制同步完成，则copy_status为“成功”;如果复制已异步启动，则为“挂起”。对于异步副本，可以通过轮询 get_blob_properties 方法并检查复制状态来检查状态。将requires_sync设置为 True 以强制复制为同步。 BLOB 服务尽量复制 Blob。复制操作的源 Blob 可以是块 Blob、追加 Blob 或页 Blob。如果目标 Blob 已存在，该 Blob 的类型必须与源 Blob 的类型相同。将覆盖任何现有的目标 Blob。复制操作进行时不能修改目标 Blob。从页 Blob 复制时，Blob 服务会创建源 Blob 长度的目标页 Blob，最初包含所有零。然后枚举页面范围，复制非空范围。对于块 Blob 或追加 Blob，Blob 服务会在此操作返回之前创建长度为零的已提交 blob。从块 Blob 复制时，将复制所有已提交的块及其块 ID。不会复制未提交的块。在复制操作结束时，目标 Blob 将具有与源相同的已提交块计数。从追加 Blob 复制时，将复制所有提交的块。在复制操作结束时，目标 Blob 将具有与源相同的已提交块计数。
undelete_blob	还原软删除的 Blob 或快照。只有在删除保留策略中设置的指定天数内使用时，操作才会成功。如果启用了 Blob 版本控制，则无法使用此方法还原基本 Blob。请改为将与要提升为当前版本的 Blob 版本的 URL 一起使用 start_copy_from_url 。
upload_blob	使用自动分块从数据源创建新的 Blob。
upload_blob_from_url	创建一个新的块 Blob，其中 Blob 的内容是从给定 URL 读取的。现有 Blob 的内容将被新 Blob 覆盖。
upload_page	“上传页面”操作将一系列页面写入页 Blob。
upload_pages_from_url	“上传页面”操作将一系列页面写入页 Blob，其中的内容是从 URL 读取的。

BlobClient 类

构造函数

参数

方法

abort_copy

参数

返回类型

acquire_lease

参数

返回

返回类型

append_block

参数

返回

返回类型

append_block_from_url

参数

clear_page

参数

返回

返回类型

close

commit_block_list

参数

返回

返回类型

create_append_blob

参数

返回

返回类型

create_page_blob

参数

返回

返回类型

create_snapshot

参数

返回

返回类型

delete_blob

参数

返回类型

delete_immutability_policy

参数

返回

返回类型

download_blob

参数

返回

返回类型

exists

参数

返回

返回类型

from_blob_url

参数

返回

返回类型

from_connection_string

参数

返回

返回类型

get_account_information

返回

返回类型

get_blob_properties

参数

返回

返回类型

get_blob_tags

参数

返回

返回类型

get_block_list

参数

返回

返回类型

get_page_range_diff_for_managed_disk

参数

返回

返回类型