從 URL 放置塊Put Block From URL

Put Block From URL操作將創建一個新塊,作為從 URL 讀取內容的 blob 的一部分提交。The Put Block From URL operation creates a new block to be committed as part of a blob where the contents are read from a URL. 此 API 可從版本2018-03-28開始。This API is available starting in version 2018-03-28.

要求Request

Put Block From URL 要求的建構如下。The Put Block From URL 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. 對於"從 URL 放置塊",版本必須為 2018-03-28 或更新。For Put Block From URL, the version has to be 2018-03-28 or newer.
Content-Length 必要。Required. 指定要求主體中所傳輸的位元組數目。Specifies the number of bytes being transmitted in the request body. 此標頭的值必須設置為零。The value of this header must be set to zero. 當長度不是零時,操作將失敗,狀態碼 400(錯誤請求)。When the length is not zero, the operation will fail with the status code 400 (Bad Request).
x-ms-copy-source:name 必要。Required. 指定源 Blob 的 URL。Specifies the URL of the source blob. 該值可以是指定 Blob 的長度高達 2 KB 的 URL。The value may be a URL of up to 2 KB in length that specifies a blob. 此值應該像出現在要求 URI 中一樣以 URL 編碼。The value should be URL-encoded as it would appear in a request URI. 源 blob 必須是公共的,或者必須通過共用訪問簽名進行授權。The source blob must either be public or must be authorized via a shared access signature. 如果源 Blob 是公共的,則無需授權即可執行該操作。If the source blob is public, no authorization is required to perform the operation. 下面是源物件 URL 的一些示例:Here are some examples of source object URLs:

- https://myaccount.blob.core.windows.net/mycontainer/myblob
- https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>
x-ms-source-range 選擇性。Optional. 僅上載指定範圍內源 URL 中 blob 的位元組。Uploads only the bytes of the blob in the source URL in the specified range. 如果未指定此選項,則整個源 blob 內容將作為單個塊上載。If this is not specified, the entire source blob contents are uploaded as a single block. 有關詳細資訊,請參閱為 Blob 服務操作指定範圍標頭See Specifying the Range Header for Blob Service Operations for more information.
x-ms-source-content-md5 選擇性。Optional. URI 塊內容的 MD5 雜湊。An MD5 hash of the block content from the URI. 此雜湊用於在從 URI 傳輸資料期間驗證塊的完整性。This hash is used to verify the integrity of the block during transport of the data from the URI. 指定此標頭時,存儲服務會將從複製源到達的內容的雜湊值與此標頭值進行比較。When this header is specified, the storage service compares the hash of the content that has arrived from the copy-source 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-source-content-crc64 選擇性。Optional. URI 塊內容的 CRC64 雜湊。A CRC64 hash of the block content from the URI. 此雜湊用於在從 URI 傳輸資料期間驗證塊的完整性。This hash is used to verify the integrity of the block during transport of the data from the URI. 指定此標頭時,存儲服務會將從複製源到達的內容的雜湊值與此標頭值進行比較。When this header is specified, the storage service compares the hash of the content that has arrived from the copy-source 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).

如果兩x-ms-source-content-md5x-ms-source-content-crc64標頭都存在,則請求將以 400(錯誤請求)失敗。If both x-ms-source-content-md5 and x-ms-source-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-lease-id:<ID> 如果 Blob 具有作用中租用,則為必要項目。Required if the blob has an active lease. 若要在具有作用中租用的 Blob 執行這項作業,請指定此標頭的有效租用識別碼。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 KB 的字元限制。Provides a client-generated, opaque value with a 1 KB 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 編碼的 AES-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

無請求正文。No request body.

範例要求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: 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

回應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.

當請求中不存在標頭x-ms-source-content-md5時,將返回此標頭。This header is returned when x-ms-source-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.
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 block 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-client-request-id 此標頭可用於對請求和相應的回應進行故障排除。This header can be used to troubleshoot requests and corresponding responses. 如果標頭存在於請求中且該值最多為 1024 個可見的 ASCII 字元,則此標頭的值等於x-ms-client-request-id標頭的值。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: Sat, 31 Mar 2018 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 From URL會上傳區塊,以供未來包含在區塊 Blob 中。Put Block From URL uploads a block for future inclusion in a block blob. 塊 Blob 最多可以包含 50,000 個塊。A block blob can include a maximum of 50,000 blocks. 每個塊的大小可能不同,最大為 100 MB。Each block can be a different size, up to a maximum of 100 MB. 因此,塊 Blob 的最大大小略高於 4.75 TB(100 MB X 50,000 塊)。The maximum size of a block blob is therefore slightly more than 4.75 TB (100 MB X 50,000 blocks).

在任意給定時間,blob 最多可以具有 100,000 個未提交的塊。A blob can have a maximum of 100,000 uncommitted blocks at any given time. 未提交的塊集的總大小不能超過 9.52 TB。The set of uncommitted blocks cannot exceed 9.52 TB in total size. 如果超過此最大值,服務將返回狀態碼 409(請求實體太大型塊計數超過限制)。If this maximum is exceeded, the service returns status code 409 (RequestEntityTooLargeBlockCountExceedsLimit).

上載一組塊後,可以通過調用Put Block List操作從該集創建或補救伺服器上的 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 中唯一的區塊識別碼進行識別。Each block in the set is identified by a block ID that is unique within that blob. 區塊識別碼的範圍僅限於特定 Blob,因此不同的 Blob 可以有相同識別碼的區塊。Block IDs are scoped to a particular blob, so different blobs can have blocks with same IDs.

如果您在不存在的 Blob 上呼叫 Put Block From URL,會建立內容長度為 0 的新區塊 Blob。If you call Put Block From URL on a blob that does not yet exist, a new block blob is created with a content length of 0. 如果指定 include=uncommittedblobs 選項,List Blobs 作業會列舉此 Blob。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 From URL 作業成功上傳的區塊,必須以 Put Block List 作業認可,才會成為 Blob 的一部分。A block that has been successfully uploaded with the Put Block From URL operation does not become part of a blob until it is committed with Put Block List. Put Block List調用提交新的或更新的 Blob 之前,對Get 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.

如果您上傳之區塊的區塊識別碼,與另一個未認可的區塊相同,在下一次成功的 Put Block List 作業中,會認可最後上傳且使用此識別碼的區塊。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 From URL 作業成功之後,如果一星期內沒有在相同的 Blob 上成功呼叫 Put Block ListPut Block From URL,任何未認可的區塊也都會進行記憶體回收。Any uncommitted blocks will also be garbage collected if there are no successful calls to Put Block From URL or Put Block List on the same blob within a week following the last successful Put Block From URL operation. 如果在 Blob 上調用Put Blob,則將回收任何未提交的塊。If Put Blob is called on the blob, any uncommitted blocks will be garbage collected.

如果 Blob 有作用中租用,用戶端必須在要求上指定有效的租用識別碼,才能將區塊寫入 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. 如果用戶端未指定租用識別碼,或是指定無效的租用識別碼,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). 如果用戶端指定租用識別碼,但是 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,所有區塊識別碼都必須是相同的長度。For a given blob, all block IDs must be the same length. 如果上傳之區塊的區塊識別碼長度,不同於任何現有未認可區塊的區塊識別碼,服務會傳回錯誤回應碼 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).

呼叫 Put Block From URL 並不會更新現有 Blob 的上次修改時間。Calling Put Block From URL does not update the last modified time of an existing blob.

在分頁 Blob 上呼叫 Put Block From URL 會傳回錯誤。Calling Put Block From URL on a page blob returns an error.

調用Put Block From URL存檔的 Blob 將返回錯誤,並且在Hot/CoolBlob 上不會更改 Blob 層。Calling Put Block From URL on an archived blob will return an error and on Hot/Cool blob does not change the blob tier.

另請參閱See Also