您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

放置块Put Block

Put Block 操作创建一个要作为 Blob 一部分提交的新块。The Put Block operation creates a new block to be committed as part of a blob.

请求Request

可以按如下方式构建Put Block请求。The Put Block request may be constructed as follows. 建议使用 HTTPS。HTTPS is recommended. 我的帐户替换为你的存储帐户的名称:Replace myaccount with the name of your storage account:

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

模拟的存储服务 URIEmulated Storage Service URI

在针对模拟的存储服务发出请求时,请将模拟器主机名和 BLOB 服务端口指定为 127.0.0.1:10000,后跟模拟的存储帐户名称:When making a request against the emulated storage service, specify the emulator hostname and Blob service port as 127.0.0.1:10000, followed by the emulated storage account name:

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

有关详细信息,请参阅使用 Azure 存储模拟器进行开发和测试For more information, see Using the Azure Storage Emulator for Development and Testing.

URI 参数URI Parameters

参数Parameter 描述Description
blockid 必需。Required. 一个用于对块进行标识的有效 Base64 字符串值。A valid Base64 string value that identifies the block. 在编码之前,该字符串的大小必须小于等于 64 字节。Prior to encoding, the string must be less than or equal to 64 bytes in size.

对于给定 Blob,为 blockid 参数指定的值的长度必须与每个块的大小相同。For a given blob, the length of the value specified for the blockid parameter must be the same size for each block.

请注意,Base64 字符串必须为 URL 编码字符串。Note that the Base64 string must be URL-encoded.
timeout 可选。Optional. timeout 参数以秒表示。The timeout parameter is expressed in seconds. 有关详细信息,请参阅为Blob 服务操作设置超时For more information, see Setting Timeouts for Blob Service Operations.

请求标头Request Headers

下表介绍必需的和可选的请求标头。The following table describes required and optional request headers.

请求头Request Header 说明Description
Authorization 必需。Required. 指定授权方案、帐户名和签名。Specifies the authorization scheme, account name, and signature. 有关详细信息,请参阅授权 Azure 存储的请求See Authorize requests to Azure Storage for more information.
Datex-ms-dateDate or x-ms-date 必需。Required. 指定请求的协调世界时 (UTC)。Specifies the Coordinated Universal Time (UTC) for the request. 有关详细信息,请参阅授权 Azure 存储的请求For more information, see Authorize requests to Azure Storage.
x-ms-version 所有授权的请求都需要此权限。Required for all authorized requests. 指定用于此请求的操作的版本。Specifies the version of the operation to use for this request. 有关详细信息,请参阅Azure 存储服务的版本控制For more information, see Versioning for the Azure Storage Services.
Content-Length 必需。Required. 块内容的长度(字节)。The length of the block content in bytes. 版本2019-12-12 和更高版本(预览版)的块必须小于或等于 4000 MiB 大小。The block must be less than or equal to 4000 MiB in size for version 2019-12-12 and later (Preview). 有关较旧版本中的限制,请参阅备注。See the Remarks for limits in older versions.

如果未提供长度,操作将失败并显示状态代码 411(需要长度)。When the length is not provided, the operation will fail with the status code 411 (Length Required).
Content-MD5 可选。Optional. 块内容的 MD5 哈希值。An MD5 hash of the block content. 此哈希值用于在传输期间验证块的完整性。This hash is used to verify the integrity of the block during transport. 指定此标头时,存储服务会对已到达内容的哈希值与此标头值进行比较。When this header is specified, the storage service compares the hash of the content that has arrived with this header value.

请注意,此 MD5 哈希值不与 Blob 一起存储。Note that this MD5 hash is not stored with the blob.

如果这两个哈希值不匹配,操作会失败,并显示错误代码 400(错误请求)。If the two hashes do not match, the operation will fail with error code 400 (Bad Request).
x-ms-content-crc64 可选。Optional. 块内容的 CRC64 哈希。A CRC64 hash of the block content. 此哈希值用于在传输期间验证块的完整性。This hash is used to verify the integrity of the block during transport. 指定此标头时,存储服务会对已到达内容的哈希值与此标头值进行比较。When this header is specified, the storage service compares the hash of the content that has arrived with this header value.

请注意,此 CRC64 哈希不与 blob 一起存储。Note that this CRC64 hash is not stored with the blob.

如果这两个哈希值不匹配,操作会失败,并显示错误代码 400(错误请求)。If the two hashes do not match, the operation will fail with error code 400 (Bad Request).

如果同时存在内容 MD5 和 crc64 标头,则请求将失败,并出现400(错误请求)。If both Content-MD5 and x-ms-content-crc64 headers are present, the request will fail with a 400 (Bad Request).

此标头在2019-02-02 版或更高版本中受支持。This header is supported in versions 2019-02-02 or later.
x-ms-encryption-scope 可选。Optional. 指示用于加密请求内容的加密范围。Indicates the encryption scope to use to encrypt the request contents. 此标头在2019-02-02 版或更高版本中受支持。This header is supported in versions 2019-02-02 or later.
x-ms-lease-id:<ID> 如果 Blob 具有活动租约,则是必需的。Required if the blob has an active lease. 要在具有活动租约的 Blob 上执行此操作,请为此标头指定有效的租约 ID。To perform this operation on a blob with an active lease, specify the valid lease ID for this header.
x-ms-client-request-id 可选。Optional. 提供客户端生成的、具有1个 KiB 字符限制的不透明值,当启用存储分析日志记录时,将记录在分析日志中。Provides a client-generated, opaque value with a 1 KiB character limit that is recorded in the analytics logs when storage analytics logging is enabled. 强烈建议使用此标头将客户端活动与服务器接收的请求相关联。Using this header is highly recommended for correlating client-side activities with requests received by the server. 有关详细信息,请参阅关于存储分析日志记录Azure 日志记录:使用日志跟踪存储请求For more information, see About Storage Analytics Logging and Azure Logging: Using Logs to Track Storage Requests.

请求标头(客户提供的加密密钥)Request Headers (Customer-provided encryption keys)

从版本2019-02-02 开始,可以在请求中指定以下标头,以使用客户提供的密钥来加密 blob。Beginning with version 2019-02-02, the following headers may be specified on the request to encrypt a blob with a customer-provided key. 使用客户提供的密钥(以及相应的标头集)进行加密是可选的。Encryption with a customer-provided key (and the corresponding set of headers) is optional.

请求标头Request header 说明Description
x-ms-encryption-key 必需。Required. Base64 编码的256加密密钥。The Base64-encoded AES-256 encryption key.
x-ms-encryption-key-sha256 必需。Required. 加密密钥的 Base64 编码的 SHA256 哈希。The Base64-encoded SHA256 hash of the encryption key.
x-ms-encryption-algorithm: AES256 必需。Required. 指定用于加密的算法。Specifies the algorithm to use for encryption. 此标头的值必须是 AES256The value of this header must be AES256.

请求正文Request Body

请求正文包含块的内容。The request body contains the content of the block.

示例请求Sample Request

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: 2011-08-18  
x-ms-date: Sun, 25 Sep 2011 14:37:35 GMT  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 1048576  

响应Response

响应包括 HTTP 状态代码和一组响应标头。The response includes an HTTP status code and a set of response headers.

状态代码Status Code

此操作成功后返回状态代码 201(已创建)。A successful operation returns status code 201 (Created).

有关状态代码的信息,请参阅状态和错误代码For information about status codes, see Status and Error Codes.

响应标头Response Headers

此操作的响应包括以下标头。The response for this operation includes the following headers. 该响应还可能包括其他标准 HTTP 标头。The response may also include additional standard HTTP headers. 所有标准标头都符合HTTP/1.1 协议规范All standard headers conform to the HTTP/1.1 protocol specification.

响应标头Response header 说明Description
Content-MD5 返回此标头是为了客户端可以检查消息内容完整性。This header is returned so that the client can check for message content integrity. 此标头的值由 BLOB 服务计算;它不一定是请求标头中指定的同一值。The value of this header is computed by the Blob service; it is not necessarily the same value specified in the request headers. 对于版本2019-02-02 或更高版本,仅当请求具有此标头时,才返回此标头。For versions 2019-02-02 or later, this header is only returned when the request has this header.
x-ms-content-crc64 对于版本2019-02-02 或更高版本,将返回此标头,以便客户端可以检查消息内容完整性。For versions 2019-02-02 or later, this header is returned so that the client can check for message content integrity. 此标头的值由 BLOB 服务计算;它不一定是请求标头中指定的同一值。The value of this header is computed by the Blob service; it is not necessarily the same value specified in the request headers.

Content-md5 请求中不存在标头时,将返回此标头。This header is returned when Content-md5 header is not present in the request.
x-ms-request-id 此标头唯一地标识发出的请求,并且可用于解决请求问题。This header uniquely identifies the request that was made and can be used for troubleshooting the request. 有关详细信息,请参阅API 操作故障排除For more information, see Troubleshooting API Operations.
x-ms-version 指示用于执行请求的 BLOB 服务的版本。Indicates the version of the Blob service used to execute the request. 针对 2009-09-19 和更高版本发出的请求将返回此标头。This header is returned for requests made against version 2009-09-19 and later.
Date 服务生成的 UTC 日期/时间值指示启动响应的时间。A UTC date/time value generated by the service that indicates the time at which the response was initiated.
x-ms-request-server-encrypted: true/false 版本2015-12-11 或更高版本。Version 2015-12-11 or newer. true如果使用指定的算法成功加密请求的内容,则将此标头的值设置为 false ; 否则设置为。The value of this header is set to true if the contents of the request are successfully encrypted using the specified algorithm, and false otherwise.
x-ms-encryption-key-sha256 版本2019-02-02 或更高版本。Version 2019-02-02 or newer. 如果请求使用客户提供的密钥进行加密,则返回此标头,以便客户端可以使用所提供的密钥来确保成功加密请求的内容。This header is returned if the request used a customer-provided key for encryption, so the client can ensure the contents of the request are successfully encrypted using the provided key.
x-ms-encryption-scope 版本2019-02-02 或更高版本。Version 2019-02-02 or newer. 如果请求使用加密范围,则返回此标头,以便客户端能够确保使用加密范围成功加密请求的内容。This header is returned if the request used an encryption scope, so the client can ensure the contents of the request are successfully encrypted using the encryption scope.
x-ms-client-request-id 此标头可用于排查请求和相应的响应。This header can be used to troubleshoot requests and corresponding responses. 如果此标头的值 x-ms-client-request-id 在请求中存在,并且其值最多为1024,则为该标头的值。The value of this header is equal to the value of the x-ms-client-request-id header if it is present in the request and the value is at most 1024 visible ASCII characters. 如果 x-ms-client-request-id 请求中不存在该标头,则此标头将不会出现在响应中。If the x-ms-client-request-id header is not present in the request, this header will not be present in the response.

示例响应Sample Response

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

授权Authorization

此操作可由帐户所有者调用执行,也可由有权向此 Blob 或其容器写入数据并具有共享访问签名的任何人执行。This operation can be called by the account owner and by anyone with a Shared Access Signature that has permission to write to this blob or its container.

注解Remarks

Put Block 上载一个块以供将来包含在块 Blob 中。Put Block uploads a block for future inclusion in a block blob. 块 blob 最多可包含50000块。A block blob can include a maximum of 50,000 blocks. 每个块可以有不同的大小,最大可为版本2019-12-12 和更高版本(预览版)使用 4000 MiB,为版本2016-05-31 和更高版本提供 100 MiB,为较早版本提供 4 MiB。Each block can be a different size, up to a maximum of 4000 MiB for version 2019-12-12 and later (Preview), 100 MiB for version 2016-05-31 and later, and 4 MiB for older versions. 因此,对于版本2019-12-12 和更高版本(预览版),块 blob 的最大大小为 190.7 TiB (4000 MiB X 50000 块),对于版本4.75 和更高版本,则为 100 TiB (50000 MiB X 2016-05-31 块),适用于所有旧版本。The maximum size of a block blob is therefore 190.7 TiB (4000 MiB X 50,000 blocks) for version 2019-12-12 and later (Preview), 4.75 TiB (100 MiB X 50,000 blocks) for version 2016-05-31 and later, and 195 GiB (4 MiB X 50,000 blocks) for all older versions.

在任意给定时间,一个 blob 最多可以有100000个未提交的块。A blob can have a maximum of 100,000 uncommitted blocks at any given time. 如果超过此最大值,则服务将返回状态代码409(RequestEntityTooLargeBlockCountExceedsLimit)。If this maximum is exceeded, the service returns status code 409 (RequestEntityTooLargeBlockCountExceedsLimit).

上传一组块后,可以通过调用Put 块列表操作,从此集创建或更新服务器上的 blob。After you have uploaded a set of blocks, you can create or update the blob on the server from this set by calling the Put Block List operation. 组中的每个块由该 Blob 中唯一的块 ID 进行标识。Each block in the set is identified by a block ID that is unique within that blob. 块 ID 的作用域为特定 Blob,因此不同 Blob 可具有 ID 相同的块。Block IDs are scoped to a particular blob, so different blobs can have blocks with same IDs.

如果对尚未存在的 Blob 调用 Put Block,则将使用内容长度 0 创建一个新的块 Blob。If you call Put Block on a blob that does not yet exist, a new block blob is created with a content length of 0. 如果指定了 include=uncommittedblobs 选项,此 Blob 将由 List Blobs 操作进行枚举。This blob is enumerated by the List Blobs operation if the include=uncommittedblobs option is specified. 在对新 Blob 调用 Put Block List 之前,不会提交已上载的块。The block or blocks that you uploaded are not committed until you call Put Block List on the new blob. 通过此方式创建的 Blob 将在服务器上保留一周的时间;如果该时间段内未向该 Blob 添加更多块也未提交块,则将对该 Blob 进行垃圾回收。A blob created this way is maintained on the server for a week; if you have not added more blocks or committed blocks to the blob within that time period, then the blob is garbage collected.

对于已使用 Put Block 操作成功上载的块,在使用 Put Block List 提交该块之前,它不会成为 Blob 的一部分。A block that has been successfully uploaded with the Put Block operation does not become part of a blob until it is committed with Put Block List. Put Block List 调用以提交新的或更新的 blob 之前,对获取 blob的任何调用都将返回 blob 内容,而不包含未提交的块。Before Put Block List is called to commit the new or updated blob, any calls to Get Blob return the blob contents without the inclusion of the uncommitted block.

如果上载的块与尚未提交的其他块具有相同块 ID,则将在下次成功执行 Put Block List 操作时提交上次上载的具有该 ID 的块。If you upload a block that has the same block ID as another block that has not yet been committed, the last uploaded block with that ID will be committed on the next successful Put Block List operation.

在调用 Put Block List 后,块列表中指定的所有未提交块都将作为新 Blob 的一部分提交。After Put Block List is called, all uncommitted blocks specified in the block list are committed as part of the new blob. 对于 Blob 的块列表中未指定的所有未提交块,都将对其进行垃圾回收并从 BLOB 服务中删除。Any uncommitted blocks that were not specified in the block list for the blob will be garbage collected and removed from the Blob service. 如果在上次成功执行 Put Block 操作后的一周内没有对同一 Blob 成功调用 Put Block ListPut Block,也将对所有未提交的块进行垃圾回收。Any uncommitted blocks will also be garbage collected if there are no successful calls to Put Block or Put Block List on the same blob within a week following the last successful Put Block operation. 如果对 Blob 调用Put Blob ,则将对所有未提交的块进行垃圾回收。If Put Blob is called on the blob, any uncommitted blocks will be garbage collected.

如果 Blob 具有活动租约,则客户端必须在请求中指定有效租约 ID 才能向 Blob 中写入块。If the blob has an active lease, the client must specify a valid lease ID on the request in order to write a block to the blob. 如果客户端不指定租约 ID,或指定无效的租约 ID,则 BLOB 服务将返回状态码 412(不满足前提条件)。If the client does not specify a lease ID, or specifies an invalid lease ID, the Blob service returns status code 412 (Precondition Failed). 如果客户端指定了一个租约 ID,但 Blob 没有活动租约,则 BLOB 服务也将返回状态码 412(不满足前提条件)。If the client specifies a lease ID but the blob does not have an active lease, the Blob service also returns status code 412 (Precondition Failed).

对于给定 Blob,所有块 ID 的长度必须相同。For a given blob, all block IDs must be the same length. 如果已上载块的块 ID 在长度上不同于任何现有未提交块的块 ID,服务将返回错误响应代码 400(错误请求)。If a block is uploaded with a block ID of a different length than the block IDs for any existing uncommitted blocks, the service returns error response code 400 (Bad Request).

如果尝试上传大于 4000 MiB 的版本2019-12-12 和更高版本(预览)、版本2016-05-31 和更高版本的 MiB 大于 100 MiB,并使用较旧版本的大于 4 MiB,则该服务将返回状态代码 "413 (请求实体太大)"。If you attempt to upload a block that is larger than 4000 MiB for version 2019-12-12 and later (Preview), larger than 100 MiB for version 2016-05-31 and later, and larger than 4 MiB for older versions, the service returns status code 413 (Request Entity Too Large). 服务还将在响应中返回有关错误的其他信息,包括允许的最大块大小(字节)。The service also returns additional information about the error in the response, including the maximum block size permitted in bytes.

调用 Put Block 不会更新现有 Blob 的上次修改时间。Calling Put Block does not update the last modified time of an existing blob.

对页 Blob 调用 Put Block 将返回错误。Calling Put Block on a page blob returns an error.

Put Block对已存档的 blob 调用将返回错误,在 Hot / Cool blob 上不会更改 blob 层。Calling Put Block on an archived blob will return an error and on Hot/Cool blob does not change the blob tier.

另请参阅See Also

向 Azure 存储授权请求 Authorize requests to Azure Storage
状态和错误代码 Status and Error Codes
Blob 服务错误代码 Blob Service Error Codes
为 Blob 服务操作设置超时Setting Timeouts for Blob Service Operations