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

blob 包

aio

AccessPolicy

集使用的 Access Policy 类,并获取每个服务中的访问策略方法。

存储访问策略可以指定与其关联的共享访问签名的开始时间、到期时间和权限。 根据想要控制对资源的访问的方式,可以在存储访问策略中指定所有这些参数,并从共享访问签名的 URL 中省略这些参数。 这样一来,你可以随时修改关联的签名的行为以及撤消签名。 或者,还可在存储访问策略中指定一个或多个访问策略参数,并在 URL 上指定其他参数。 最后,可以在 URL 上指定所有参数。 在这种情况下,你可以使用存储访问策略来撤消签名,但不修改其行为。

共享访问签名和存储访问策略都必须包含对签名进行身份验证所需的所有字段。 如果缺少任何必需的字段,则请求将失败。 同样地,如果在共享访问签名 URL 和存储访问策略中指定了字段,则请求将失败,状态代码为 400(错误的请求)。

AccountSasPermissions

ResourceTypes 类与 generate_account_sas 函数一起使用,以及用于与 set_*_acl 一起使用的 AccessPolicies。 有两种类型的 SAS 可用于授予资源访问权限。 一种是授予对特定资源的访问权限 (特定于资源的) 。 另一种是授予对特定帐户整个服务的访问权限,并允许基于此处找到的权限执行某些操作。

ArrowDialect

箭头架构的字段。

必须填充所有必需的参数才能发送到 Azure。

BlobAnalyticsLogging

Azure Analytics 日志记录设置。

BlobBlock

BlockBlob Block 类。

BlobClient

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

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

BlobLeaseClient

创建新的 BlobLeaseClient。

此客户端在 BlobClient 或 ContainerClient 上提供租约操作。

BlobPrefix

Blob 属性的迭代。

使用分隔符时从walk_blobs返回。 可以视为虚拟 Blob 目录。

BlobProperties

Blob 属性。

BlobQueryError

错误发生在快速查询操作期间。

BlobQueryReader

用于读取查询结果的流式处理对象。

BlobSasPermissions

要与 函数一起使用的 generate_blob_sas BlobSasPermissions 类。

BlobServiceClient

在帐户级别与 Blob 服务交互的客户端。

此客户端提供用于检索和配置帐户属性以及列出、创建和删除帐户中的容器的操作。 对于与特定容器或 Blob 相关的操作,也可以使用 get_client 函数检索这些实体的客户端。

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

ContainerClient

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

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

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

ContainerEncryptionScope

容器的默认加密范围配置。

此范围隐式用于容器内的所有将来写入,但每个 Blob 操作都可以重写。

版本 12.2.0 中的新增功能。

ContainerProperties

Blob 容器的属性类。

返回的 ContainerProperties 实例通过字典接口公开这些值,例如: container_props["last_modified"]。 此外,容器名称可用作 container_props["name"]

ContainerSasPermissions

ContainerSasPermissions 类与 函数一起使用, generate_container_sas 以及用于与 一起使用 set_container_access_policy的 AccessPolicies。

ContentSettings

Blob 的内容设置。

CopyProperties

Blob 复制属性。

如果此 Blob 从未成为复制 Blob 操作中的目标,或者在完成复制 Blob 操作(例如,使用“设置 Blob 属性”、“上传 Blob”或“提交块列表”)后修改此 Blob,则这些属性将为 “无 ”。

CorsRule

CORS 是一项 HTTP 功能,使在一个域中运行的 Web 应用程序能够访问另一个域中的资源。 Web 浏览器实施一种称为同源策略的安全限制,以防止网页调用另一个域中的 API;CORS 提供了一种安全的方法来允许一个域(源域)调用另一个域中的 API。

CustomerProvidedEncryptionKey

Azure 存储中的所有数据都使用帐户级加密密钥进行静态加密。 在 2018-06-17 及更新版本中,可以通过在对存储服务的请求中提供 AES-256 加密密钥来管理用于加密每个 blob 的 Blob 内容和应用程序元数据的密钥。

使用客户提供的密钥时,Azure 存储不会管理或保留密钥。 将数据写入 Blob 时,在将数据写入磁盘之前,将使用提供的密钥对数据进行加密。 加密密钥的 SHA-256 哈希与 Blob 内容一起写入,用于验证针对 Blob 的所有后续操作是否使用相同的加密密钥。 此哈希不能用于检索加密密钥或解密 Blob 的内容。 读取 Blob 时,提供的密钥用于在从磁盘读取数据后解密数据。 在这两种情况下,一旦加密或解密过程完成,所提供的加密密钥就会被安全丢弃。

DelimitedJsonDialect

定义 Blob 数据查询的输入或输出 JSON 序列化。

keyword str 分隔符:行分隔符,默认值为 '

'

DelimitedTextDialect

定义 (CSV 分隔的输入或输出,) Blob 查询请求的序列化。

ExponentialRetry

指数重试。

FilteredBlob

来自筛选器 Blob API 调用的 Blob 信息。

ImmutabilityPolicy

用于设置 Blob、Blob 快照或 Blob 版本的不可变性策略的可选参数。

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

LeaseProperties

Blob 租约属性。

LinearRetry

线性重试。

LocationMode

指定请求应发送到的位置。 此模式仅适用于允许辅助读取访问的 RA-GRS 帐户。 所有其他帐户类型必须使用 PRIMARY。

Metrics

按 API 分组的请求统计信息的摘要,以小时或分钟聚合表示的 Blob。

ObjectReplicationPolicy

应用于 Blob 的策略 ID 和规则 ID。

ObjectReplicationRule

应用于 Blob 的策略 ID 和规则 ID。

PageRange

页 Blob 的页面范围。

PartialBatchErrorException

批处理操作中存在部分失败。

ResourceTypes

指定可通过帐户 SAS 访问的资源类型。

RetentionPolicy

确定关联数据应保留多长时间的保留策略。

StaticWebsite

使帐户能够托管静态网站的属性。

StorageStreamDownloader

要从 Azure 存储下载的流式处理对象。

UserDelegationKey

表示用户委派密钥,该密钥由 Azure 存储基于其 Azure Active Directory 访问令牌提供给用户。

字段保存为简单字符串,因为用户不必与此对象交互;若要生成标识 SAS,用户只需将其传递到正确的 API 即可。

枚举

ArrowType

枚举。

BlobImmutabilityPolicyMode

指定要在 Blob 上设置的不可变性策略模式。 “可变”只能由服务返回,不要设置为“可变”。

BlobType

枚举。

BlockState

块 Blob 块类型。

PremiumPageBlobTier

指定要将 Blob 设置为的页 Blob 层。 这仅适用于高级存储帐户上的页 Blob。 请查看: https://docs.microsoft.com/en-us/azure/storage/storage-premium-storage#scalability-and-performance-targets 有关每个 PageBlobTier 的相应 IOPS 和吞吐量的详细信息。

PublicAccess

指定是否可以公开访问容器中的数据以及访问级别。

QuickQueryDialect

指定快速查询输入/输出方言。

RehydratePriority

如果对象处于解除冻结挂起状态,则返回此标头的优先级为“解除冻结”。 有效值为“高”和“标准”。

SequenceNumberAction

序列号操作。

StandardBlobTier

指定要将 Blob 设置为的 Blob 层。 这仅适用于标准存储帐户上的块 Blob。

StorageErrorCode

枚举。

函数

download_blob_from_url

将 Blob 的内容下载到本地文件或流。

download_blob_from_url(blob_url: str, output: str, credential: Optional[Union[str, Dict[str, str], AzureNamedKeyCredential, AzureSasCredential, "TokenCredential"]] # pylint: disable=line-too-long = None, **kwargs) -> None

参数

blob_url
str
必需

Blob 的完整 URI。 这还可以包括 SAS 令牌。

output
str 或 <xref:<xref:writable stream.>>
必需

数据应下载到的位置。 这可以是要写入的文件路径,也可以是要写入的打开 IO 句柄。

credential
默认值: None

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

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

如果本地文件已存在,是否应覆盖该文件。 默认值为 False - 在这种情况下,如果文件已存在,将引发 ValueError。 如果设置为 True,则将尝试写入现有文件。 如果传入流句柄,则忽略此值。

max_concurrency
int

要下载的并行连接数。

offset
int

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

length
int

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

validate_content
bool

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

返回类型

generate_account_sas

为 Blob 服务生成共享访问签名。

将返回的签名与任何 BlobServiceClient、ContainerClient 或 BlobClient 的凭据参数一起使用。

generate_account_sas(account_name: str, account_key: str, resource_types: Union[ResourceTypes, str], permission: Union[AccountSasPermissions, str], expiry: Optional[Union[datetime, str]], start: Optional[Union[datetime, str]] = None, ip: Optional[str] = None, **kwargs: Any) -> str

参数

account_name
str
必需

用于生成共享访问签名的存储帐户名称。

account_key
str
必需

帐户密钥(也称为共享密钥或访问密钥)用于生成共享访问签名。

resource_types
strResourceTypes
必需

指定可通过帐户 SAS 访问的资源类型。

permission
strAccountSasPermissions
必需

与共享访问签名关联的权限。 用户只能执行权限允许的操作。 必需,除非提供了引用包含此字段的存储访问策略的 ID。 如果已在关联的存储访问策略中指定,则必须省略此字段。

expiry
datetimestr
必需

共享访问签名失效的时间。 必需,除非提供了引用包含此字段的存储访问策略的 ID。 如果已在关联的存储访问策略中指定,则必须省略此字段。 Azure 始终会将值转换为 UTC。 如果传入的日期没有时区信息,则假定该日期为 UTC。

start
datetimestr
默认值: None

共享访问签名生效的时间。 如果省略,将假定此调用的开始时间就是存储服务收到请求的时间。 Azure 始终会将值转换为 UTC。 如果传入的日期没有时区信息,则假定该日期为 UTC。

ip
str
默认值: None

指定要从中接受请求的 IP 地址或 IP 地址范围。 如果请求源自的 IP 地址与 SAS 令牌上指定的 IP 地址或地址范围不匹配,则不会对请求进行身份验证。 例如,在 SAS 上指定 ip=168.1.5.65 或 ip=168.1.5.60-168.1.5.70 会将请求限制为这些 IP 地址。

protocol
str

指定所发出请求所允许的协议。 默认值为 https。

encryption_scope
str

指定所发出的请求的加密范围,以便对所有写入操作进行服务加密。

返回

共享访问签名 (sas) 令牌。

返回类型

str

示例

生成共享访问签名。


   # Create a SAS token to use to authenticate a new client
   from datetime import datetime, timedelta
   from azure.storage.blob import ResourceTypes, AccountSasPermissions, generate_account_sas

   sas_token = generate_account_sas(
       blob_service_client.account_name,
       account_key=blob_service_client.credential.account_key,
       resource_types=ResourceTypes(object=True),
       permission=AccountSasPermissions(read=True),
       expiry=datetime.utcnow() + timedelta(hours=1)
   )

generate_blob_sas

生成 Blob 的共享访问签名。

将返回的签名与任何 BlobServiceClient、ContainerClient 或 BlobClient 的凭据参数一起使用。

generate_blob_sas(account_name: str, container_name: str, blob_name: str, snapshot: Optional[str] = None, account_key: Optional[str] = None, user_delegation_key: Optional[UserDelegationKey] = None, permission: Optional[Union[BlobSasPermissions, str]] = None, expiry: Optional[Union[datetime, str]] = None, start: Optional[Union[datetime, str]] = None, policy_id: Optional[str] = None, ip: Optional[str] = None, **kwargs: Any) -> Any

参数

account_name
str
必需

用于生成共享访问签名的存储帐户名称。

container_name
str
必需

容器的名称。

blob_name
str
必需

Blob 的名称。

snapshot
str
默认值: None

可选的 Blob 快照 ID。

account_key
str
默认值: None

帐户密钥(也称为共享密钥或访问密钥)用于生成共享访问签名。 必须指定 account_keyuser_delegation_key

user_delegation_key
UserDelegationKey
默认值: None

用户可以传入用户委托密钥,而不是帐户共享密钥。 可以通过使用 AAD 标识进行身份验证,从服务获取用户委托密钥;这可以通过调用 get_user_delegation_key来实现。 如果存在,则使用用户委托密钥对 SAS 进行签名。

permission
strBlobSasPermissions
默认值: None

与共享访问签名关联的权限。 用户只能执行权限允许的操作。 权限必须排序为 racwdxytmei。 必需,除非提供了引用包含此字段的存储访问策略的 ID。 如果已在关联的存储访问策略中指定,则必须省略此字段。

expiry
datetimestr
默认值: None

共享访问签名失效的时间。 必需,除非提供了引用包含此字段的存储访问策略的 ID。 如果已在关联的存储访问策略中指定,则必须省略此字段。 Azure 始终会将值转换为 UTC。 如果传入的日期没有时区信息,则假定该日期为 UTC。

start
datetimestr
默认值: None

共享访问签名生效的时间。 如果省略,将假定此调用的开始时间就是存储服务收到请求的时间。 Azure 始终会将值转换为 UTC。 如果传入的日期没有时区信息,则假定该日期为 UTC。

policy_id
str
默认值: None

与存储访问策略相关的最大长度为 64 个字符的唯一值。 若要创建存储访问策略,请使用 set_container_access_policy

ip
str
默认值: None

指定要从中接受请求的 IP 地址或 IP 地址范围。 如果请求源自的 IP 地址与 SAS 令牌上指定的 IP 地址或地址范围不匹配,则不会对请求进行身份验证。 例如,在 SAS 上指定 ip=168.1.5.65 或 ip=168.1.5.60-168.1.5.70 会将请求限制为这些 IP 地址。

version_id
str

可选的 Blob 版本 ID。 此参数仅适用于启用了版本控制功能的帐户

版本 12.4.0 中的新增功能:此关键字参数在 API 版本“2019-12-12”中引入。

protocol
str

指定所发出请求所允许的协议。 默认值为 https。

cache_control
str

使用此共享访问签名访问资源时Cache-Control的响应标头值。

content_disposition
str

使用此共享访问签名访问资源时 Content-Disposition 的响应标头值。

content_encoding
str

使用此共享访问签名访问资源时内容编码的响应标头值。

content_language
str

使用此共享访问签名访问资源时,Content-Language 的响应标头值。

content_type
str

使用此共享访问签名访问资源时,Content-Type 的响应标头值。

encryption_scope
str

指定所发出的请求的加密范围,以便对所有写入操作进行服务加密。

返回

共享访问签名 (sas) 令牌。

返回类型

str

generate_container_sas

为容器生成共享访问签名。

将返回的签名与任何 BlobServiceClient、ContainerClient 或 BlobClient 的凭据参数一起使用。

generate_container_sas(account_name: str, container_name: str, account_key: Optional[str] = None, user_delegation_key: Optional[UserDelegationKey] = None, permission: Optional[Union[ContainerSasPermissions, str]] = None, expiry: Optional[Union[datetime, str]] = None, start: Optional[Union[datetime, str]] = None, policy_id: Optional[str] = None, ip: Optional[str] = None, **kwargs: Any) -> Any

参数

account_name
str
必需

用于生成共享访问签名的存储帐户名称。

container_name
str
必需

容器的名称。

account_key
str
默认值: None

帐户密钥(也称为共享密钥或访问密钥)用于生成共享访问签名。 必须指定 account_keyuser_delegation_key

user_delegation_key
UserDelegationKey
默认值: None

用户可以传入用户委托密钥,而不是帐户共享密钥。 可以通过使用 AAD 标识进行身份验证,从服务获取用户委托密钥;这可以通过调用 get_user_delegation_key来实现。 如果存在,则使用用户委托密钥对 SAS 进行签名。

permission
strContainerSasPermissions
默认值: None

与共享访问签名关联的权限。 用户只能执行权限允许的操作。 权限必须排序为 racwdxyltfmei。 必需,除非提供了引用包含此字段的存储访问策略的 ID。 如果已在关联的存储访问策略中指定,则必须省略此字段。

expiry
datetimestr
默认值: None

共享访问签名变为无效的时间。 必需,除非提供了引用包含此字段的存储访问策略的 ID。 如果已在关联的存储访问策略中指定,则必须省略此字段。 Azure 将始终将值转换为 UTC。 如果传入的日期没有时区信息,则假定该日期为 UTC。

start
datetimestr
默认值: None

共享访问签名生效的时间。 如果省略,将假定此调用的开始时间就是存储服务收到请求的时间。 Azure 将始终将值转换为 UTC。 如果传入的日期没有时区信息,则假定该日期为 UTC。

policy_id
str
默认值: None

一个唯一值,长度最多为 64 个字符,与存储访问策略相关。 若要创建存储访问策略,请使用 set_container_access_policy

ip
str
默认值: None

指定从中接受请求的 IP 地址或 IP 地址范围。 如果请求源自的 IP 地址与 SAS 令牌上指定的 IP 地址或地址范围不匹配,则不会对请求进行身份验证。 例如,在 SAS 上指定 ip=168.1.5.65 或 ip=168.1.5.60-168.1.5.70 会将请求限制为这些 IP 地址。

protocol
str

指定允许发出的请求的协议。 默认值为 https。

cache_control
str

使用此共享访问签名访问资源时Cache-Control的响应标头值。

content_disposition
str

使用此共享访问签名访问资源时的内容处置的响应标头值。

content_encoding
str

使用此共享访问签名访问资源时的内容编码的响应标头值。

content_language
str

使用此共享访问签名访问资源时的内容语言的响应标头值。

content_type
str

使用此共享访问签名访问资源时 Content-Type 的响应标头值。

encryption_scope
str

指定所发出的请求的加密范围,以便对所有写入操作进行服务加密。

返回

共享访问签名 (sas) 令牌。

返回类型

str

示例

生成 sas 令牌。


   # Use access policy to generate a sas token
   from azure.storage.blob import generate_container_sas

   sas_token = generate_container_sas(
       container_client.account_name,
       container_client.container_name,
       account_key=container_client.credential.account_key,
       policy_id='my-access-policy-id'
   )

upload_blob_to_url

将数据上传到给定 URL

数据将作为块 Blob 上传。

upload_blob_to_url(blob_url: str, data: Union[Iterable[AnyStr], IO[AnyStr]], credential: Optional[Union[str, Dict[str, str], AzureNamedKeyCredential, AzureSasCredential, "TokenCredential"]] # pylint: disable=line-too-long = None, **kwargs) -> Dict[str, Any]

参数

blob_url
str
必需

Blob 的完整 URI。 这还可以包括 SAS 令牌。

data
bytesstr 或 <xref:Iterable>
必需

要上传的数据。 这可以是字节、文本、可迭代对象或类似文件的对象。

credential
默认值: None

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

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

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

max_concurrency
int

要下载的并行连接数。

length
int

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

metadata
dict(<xref:str,str>)

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

validate_content
bool

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

encoding
str

如果文本作为输入提供,则要使用的编码。 默认为 UTF-8。

返回

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

返回类型

dict(str, <xref:Any>)