通过

从 URL 放置块

  • 项目

该 Put Block From URL 作会创建一个新块，作为 blob 的一部分提交，其中的内容是从 URL 读取的。 此 API 从版本 2018-03-28 开始提供。

请求

可以按如下所示构造 Put Block From URL 请求。 建议使用 HTTPS。 将 myaccount 替换为存储帐户的名称：

PUT 方法请求 URI HTTP 版本
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=block&blockid=id HTTP/1.1

模拟存储服务请求

对模拟存储服务发出请求时，请将模拟器主机名和 Blob 服务端口指定为 127.0.0.1:10000，后跟模拟的存储帐户名称：

PUT 方法请求 URI HTTP 版本
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=block&blockid=id HTTP/1.1

有关详细信息，请参阅 使用 Azurite 模拟器进行本地 Azure 存储开发。

URI 参数

参数 DESCRIPTION
blockid 必填。 标识块的有效 Base64 字符串值。 在编码之前，字符串的大小必须小于或等于 64 字节。

对于指定的 blob，参数的 blockid 指定值的长度对于每个块的大小必须相同。

注意：Base64 字符串必须经过 URL 编码。
timeout 可选。 timeout 参数以秒为单位表示。 有关详细信息，请参阅 设置 Blob 服务操作的超时。

请求标头

下表描述了必需和可选的请求标头：

请求标头 DESCRIPTION
Authorization 必填。 指定授权方案、帐户名称和签名。 有关详细信息，请参阅 授权对 Azure 存储的请求。
Date 或 x-ms-date 必填。 指定请求的协调世界时（UTC）。 有关详细信息，请参阅 授权对 Azure 存储的请求。
x-ms-version 所有授权请求都是必需的。 指定要用于此请求的操作的版本。 有关详细信息，请参阅 Azure 存储服务的版本控制。 对于 Put Block From URL，版本必须为 2018-03-28 或更高版本。
Content-Length 必填。 指定在请求正文中传输的字节数。 此标头的值必须设置为 0。 当长度不为 0 时，作将失败，状态代码为 400 （Bad Request）。
x-ms-copy-source:name 必填。 指定源 blob 的 URL。 该值可以是长度最大为 2 KiB 的 URL，用于指定 blob。 该值应采用 URL 编码，因为它将显示在请求 URI 中。 源 blob 必须是公共的或通过共享访问签名授权的。 如果源 blob 是公共的，则无需授权即可执行该作。 下面是源对象 URL 的一些示例：

- https://myaccount.blob.core.windows.net/mycontainer/myblob
- https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>
- https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime>
x-ms-copy-source-authorization: <scheme> <signature> 可选。 指定复制源的授权方案和签名。 有关详细信息，请参阅 授权对 Azure 存储的请求。

注意：Microsoft Entra 仅支持不记名方案。

注意：如果您的源对象是可公开访问的，或者您的源对象位于存储帐户中，并且您使用的是传入 x-ms-copy-source:name的 SAS 令牌，则不需要此标头。

版本 2020-10-02 及更高版本支持此标头。
x-ms-source-range 可选。 仅上传指定范围内的源 URL 中 blob 的字节。 如果未指定此标头，则整个源 blob 内容将作为单个块上传。 有关详细信息，请参阅 指定 Blob 服务作的范围标头。
x-ms-source-content-md5 可选。 来自 URI 的区块内容的 MD5 哈希值。 此哈希用于在从 URI 传输数据期间验证块的完整性。 指定此标头后，存储服务会将从 copy-source 到达的内容的哈希值与此标头值进行比较。

注意：此 MD5 哈希值不与 blob 一起存储。

如果两个哈希不匹配，则作将失败，错误代码为 400 （Bad Request）。
x-ms-source-content-crc64 可选。 来自 URI 的区块内容的 CRC64 哈希值。 此哈希用于在从 URI 传输数据期间验证块的完整性。 指定此标头后，存储服务会将从 copy-source 到达的内容的哈希值与此标头值进行比较。

注意：此 CRC64 哈希值不与 blob 一起存储。

如果两个哈希不匹配，则作将失败，错误代码为 400 （Bad Request）。

如果同时 x-ms-source-content-md5 存在 和 x-ms-source-content-crc64 标头，则请求将失败，并显示 400 （Bad Request）。

版本 2019-02-02 及更高版本支持此标头。
x-ms-encryption-scope 可选。 指示用于加密源内容的加密范围。 版本 2019-02-02 及更高版本支持此标头。
x-ms-lease-id:<ID> 如果 Blob 具有活动租约，则为必需。 若要对具有活动租约的 blob 执行此作，请为此标头指定有效的租约 ID。
x-ms-client-request-id 可选。 提供客户端生成的不透明值，该值具有配置日志记录时日志中记录的 1-kibibyte （KiB） 字符限制。 强烈建议使用此标头将客户端活动与服务器接收的请求相关联。 有关详细信息，请参阅 监视 Azure Blob 存储。
x-ms-file-request-intent 如果 x-ms-copy-source header 是 Azure 文件 URL，则 x-ms-copy-source-authorization 为 Required，并且 header 指定 OAuth 令牌。 可接受的值为 backup。 此标头指定，如果 Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action 或 Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action 包含在分配给使用 x-ms-copy-source-authorization 标头授权的标识的 RBAC 策略中，则应授予 Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action。 适用于版本 2025-07-05 及更高版本。

请求标头（客户提供的加密密钥）

从版本 2019-02-02 开始，可以在请求中指定以下标头，以使用客户提供的密钥加密 blob。 使用客户提供的密钥（和相应的标头集）进行加密是可选的。

请求标头 DESCRIPTION
x-ms-encryption-key 必填。 Base64 编码的 AES-256 加密密钥。
x-ms-encryption-key-sha256 必填。 加密密钥的 Base64 编码 SHA256 哈希。
x-ms-encryption-algorithm: AES256 必填。 指定要用于加密的算法。 此标头的值必须为 AES256。

请求主体

没有。

示例请求

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=block&blockid=AAAAAA%3D%3D HTTP/1.1  
  
Request Headers:  
x-ms-version: 2018-03-28  
x-ms-date: Sat, 31 Mar 2018 14:37:35 GMT    
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 0
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-499

响应

响应包括 HTTP 状态代码和一组响应标头。

状态代码

成功的操作返回状态代码 201（已创建）。

有关状态代码的详细信息，请参阅 状态和错误代码。

响应标头

此操作的响应包括以下标头。 响应还可能包括其他标准 HTTP 标头。 所有标准标头都符合 HTTP/1.1 协议规范。

响应头 DESCRIPTION
Content-MD5 返回以便客户端可以检查消息内容完整性。 此标头的值由 Blob 存储计算。 它不一定与请求标头中指定的值相同。 对于版本 2019-02-02 及更高版本，仅当请求具有此标头时，才会返回此标头。
x-ms-content-crc64 对于版本 2019-02-02 及更高版本。 返回以便客户端可以检查消息内容完整性。 此标头的值由 Blob 存储计算。 它不一定与请求标头中指定的 value 相同。

当请求中不存在 header 时 x-ms-source-content-md5 返回。
x-ms-request-id 唯一标识已发出的请求，可以使用它对请求进行故障排除。 有关详细信息，请参阅 API 操作疑难解答。
x-ms-version 用于执行请求的 Blob 存储版本。
Date 由服务生成的 UTC 日期/时间值，该值指示启动响应的时间。
x-ms-request-server-encrypted: true/false 版本 2015-12-11 及更高版本。 此标头的值设置为 true 是否使用指定算法成功加密块的内容。 否则，该值设置为 false。
x-ms-encryption-key-sha256 版本 2019-02-02 及更高版本。 如果请求使用客户提供的密钥进行加密，则返回此密钥，以便客户端可以确保使用提供的密钥成功加密请求的内容。
x-ms-encryption-scope 版本 2019-02-02 及更高版本。 如果请求使用了加密范围，则返回 Token，因此客户端可以确保使用加密范围成功加密请求的内容。
x-ms-client-request-id 可用于对请求和相应的响应进行故障排除。 如果此标头存在于请求中，则此标头的值等于 x-ms-client-request-id 标头的值，并且该值包含不超过 1,024 个可见 ASCII 字符。 如果请求中不存在 x-ms-client-request-id 标头，则响应中不会显示该标头。

示例响应

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sat, 31 Mar 2018 23:47:09 GMT  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0

授权

在 Azure 存储中调用任何数据访问操作时，需要授权。 可以按如下所述授权 Put Block From URL 操作。

重要

Microsoft建议将 Microsoft Entra ID 与托管标识配合使用来授权对 Azure 存储的请求。 与共享密钥授权相比，Microsoft Entra ID 提供更高的安全性和易用性。

Azure 存储支持使用 Microsoft Entra ID 来授权请求 Blob 数据。 使用 Microsoft Entra ID，可以使用 Azure 基于角色的访问控制（Azure RBAC）向安全主体授予权限。 安全主体可以是用户、组、应用程序服务主体或 Azure 托管标识。 安全主体由 Microsoft Entra ID 进行身份验证，以返回 OAuth 2.0 令牌。 然后可以使用令牌来授权对 Blob 服务发出请求。

若要详细了解如何使用 Microsoft Entra ID 进行授权，请参阅 使用 Microsoft Entra ID授予对 blob 的访问权限。

权限

下面列出了Microsoft Entra 用户、组、托管标识或服务主体调用 Put Block From URL 操作所需的 RBAC 操作，以及包含此操作的最小特权内置 Azure RBAC 角色：

若要详细了解如何使用 Azure RBAC 分配角色，请参阅 分配 Azure 角色以访问 blob 数据。

注解

Put Block From URL 上传块以将来包含在块 blob 中。 块 blob 最多可以包含 50,000 个块。 每个块的大小可以不同。 上传的数据 Put Block From URL 块的最大大小为 100 兆字节 （MiB）。 要上传更大的数据块（最大 4000 MiB），请参阅 放置数据块。

在版本 2020-10-02 及更高版本中，复制作的源支持Microsoft Entra 授权。

一个 blob 在任何时候最多可以有 100,000 个未提交的块。 如果超过此最大值，服务将返回状态代码 409 （RequestEntityTooLargeBlockCountExceedsLimit）。

下表描述了按服务版本允许的最大块大小和 blob 大小：

服务版本 最大区块大小（通过 Put Block From URL） 最大 blob 大小（通过 Put Block List） 通过单个写入作（通过 Put Blob From URL） 实现的最大 blob 大小
版本 2020-04-08 及更高版本 4000 兆字节 大约 190.7 TiB（4000 MiB × 50000 个数据块） 5000 兆字节
2020-04-08 之前的版本 100 MiB 大约 4.75 TiB（100 MiB × 50000 个数据块） 256 MiB

上传一组块后，您可以通过调用 Put Block List 作从此集创建或更新 blob。 集中的每个块都由该 blob 中唯一的块 ID 标识。 块 ID 的范围限定为特定 blob，因此不同的 blob 可以具有具有相同 ID 的块。

如果调用 Put Block From URL 尚不存在的 blob，则会创建一个内容长度为 0 的新块 blob。 如果指定了选项，include=uncommittedblobs则作将枚举List Blobs此 blob。 在调用 Put Block List 新 blob 之前，不会提交上传的一个或多个块。 以这种方式创建的 blob 将在服务器上保留一周。 如果在该时间段内未向 blob 添加更多块或提交的块，则会对 blob 进行垃圾回收。

使用 Put Block From URL 作成功上传的块在使用 Put Block List. Before Put Block List 来提交新的或更新的 blob，则对 Get Blob 的任何调用都会返回 blob 内容，而不包含未提交的块。

如果您上传的块与另一个尚未提交的块具有相同的块 ID，则具有该 ID 的最后一个上传块将在下一次成功 Put Block List 作时提交。

之后 Put Block List ，块列表中指定的所有未提交的块都将作为新 blob 的一部分提交。 未在 blob 的块列表中指定的任何未提交块都会被垃圾回收并从 Blob 存储中删除。 如果在上次成功Put Block From URL作后的一周内没有成功调用Put Block From URL同一 blob 或Put Block List对同一 blob 进行垃圾回收，则也会对任何未提交的块进行垃圾回收。 如果在 blob 上调用 Put Blob ，则会对任何未提交的块进行垃圾回收。

如果 blob 具有活动租约，则客户端必须在请求中指定有效的租约 ID，才能将块写入 blob。 如果客户端未指定租约 ID 或指定了无效的租约 ID，则 Blob 存储将返回状态代码 412（前提条件失败）。 如果客户端指定了租约 ID，但 blob 没有活动租约，则 Blob 存储还会返回状态代码 412（前提条件失败）。

对于指定的 blob，所有块 ID 的长度必须相同。 如果上传数据块的块 ID 长度与任何现有未提交数据块的块 ID 长度不同，则服务将返回错误响应代码 400 （Bad Request）。

调用 Put Block From URL 不会更新现有 blob 的上次修改时间。

对页 blob 调用 Put Block From URL 将返回错误。

调用 Put Block From URL 'archive' blob 会返回错误，而在 或 cool blob 上hot调用它不会更改 blob 层。

账单管理

定价请求可能源自使用 Blob 存储 API 的客户端，可以直接通过 Blob 存储 REST API 或 Azure 存储客户端库。 这些请求按事务产生费用。 事务类型会影响帐户的计费方式。 例如，读取事务累算到与写入事务不同的计费类别。 下表显示了基于存储帐户类型的 Put Block From URL 请求的计费类别：

操作 存储帐户类型 计费类别
Put Block From URL（目标账户1） 高级块 blob
标准常规用途 v2
标准常规用途 v1		 写入操作
Put Block From URL（源账户2） 高级块 blob
标准常规用途 v2
标准常规用途 v1		 读取操作

1目标账户需要为启动写入的 1 个事务付费。
阿拉伯数字源账户对源对象的每个读取请求都会产生一个事务。

此外，如果源账户和目标账户位于不同的区域（例如，美国北部和美国南部），则用于传输请求的带宽将作为出口向源存储帐户收费。 同一区域中的帐户之间的出口是免费的。

若要了解指定计费类别的定价，请参阅 Azure Blob 存储定价。

另请参阅