SalesBuy
1-855-856-7678
Technical SupportSupport
Put Blob (REST API)
Updated: June 12, 2012
The Put Blob operation creates a new block blob or page blob, or updates the content of an existing block blob.
Updating an existing block blob overwrites any existing metadata on the blob. Partial updates are not supported with Put Blob; the content of the existing blob is overwritten with the content of the new blob. To perform a partial update of the content of a block blob, use the Put Block List (REST API) operation.
Note that calling Put Blob to create a page blob only initializes the blob. To add content to a page blob, call the Put Page (REST API) operation.
The Put Blob request may be constructed as follows. HTTPS is recommended. Replace myaccount with the name of your storage account:
| PUT Method Request URI | HTTP Version |
|---|---|
|
|
HTTP/1.1 |
Emulated Storage Service URI
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 Method Request URI | HTTP Version |
|---|---|
|
|
HTTP/1.1 |
Note that the storage emulator only supports blob sizes up to 2 GB.
For more information, see About Development Storage and Differences between Development Storage and Cloud Storage Services.
URI Parameters
The following additional parameters may be specified on the request URI.
| Parameter | Description |
|---|---|
|
timeout |
Optional. The timeout parameter is expressed in seconds. For more information, see Setting Timeouts for Blob Service Operations. |
Request Headers (Block and Page Blobs)
The following table describes required and optional request headers for operations on both block blobs and page blobs.
| Request header | Description |
|---|---|
|
Authorization |
Required. Specifies the authentication scheme, account name, and signature. For more information, see Authentication for the Windows Azure Storage Services. |
|
Date or x-ms-date |
Required. Specifies the Coordinated Universal Time (UTC) for the request. For more information, see Authentication for the Windows Azure Storage Services. |
|
x-ms-version |
Required for all authenticated requests. Specifies the version of the operation to use for this request. For more information, see Versioning for the Blob, Queue, and Table services in Windows Azure. |
|
Content-Length |
Required. The length of the request. For a page blob, the value of this header must be set to zero, as Put Blob (REST API) is used only to initialize the page blob. The page blob's size is specified in the x-ms-blob-content-length header. All content must be written to a page blob by calling Put Page (REST API). |
|
Content-Type |
Optional. The MIME content type of the blob. The default type is application/octet-stream. |
|
Content-Encoding |
Optional. Specifies which content encodings have been applied to the blob. This value is returned to the client when the Get Blob (REST API) operation is performed on the blob resource. The client can use this value when returned to decode the blob content. |
|
Content-Language |
Optional. Specifies the natural languages used by this resource. |
|
Content-MD5 |
Optional. An MD5 hash of the blob content. This hash is used to verify the integrity of the blob during transport. When this header is specified, the storage service checks the hash that has arrived with the one that was sent. If the two hashes do not match, the operation will fail with error code 400 (Bad Request). When omitted in version 2012-02-12 and later, the Blob service generates an MD5 hash. Results from Get Blob (REST API), Get Blob Properties (REST API), and List Blobs (REST API) include the MD5 hash. |
|
Cache-Control |
Optional. The Blob service stores this value but does not use or modify it. |
|
x-ms-blob-content-type |
Optional. Set the blob’s content type. |
|
x-ms-blob-content-encoding |
Optional. Set the blob’s content encoding. |
|
x-ms-blob-content-language |
Optional. Set the blob's content language. |
|
x-ms-blob-content-md5 |
Optional. Set the blob’s MD5 hash. |
|
x-ms-blob-cache-control |
Optional. Sets the blob's cache control. |
|
x-ms-blob-type:<BlockBlob | PageBlob> |
Required. Specifies the type of blob to create: block blob or page blob. |
|
x-ms-meta-name:value |
Optional. Name-value pairs associated with the blob as metadata. Note that beginning with version 2009-09-19, metadata names must adhere to the naming rules for C# identifiers. |
|
x-ms-lease-id:<ID> |
Required if the blob has an active lease. To perform this operation on a blob with an active lease, specify the valid lease ID for this header. |
This operation also supports the use of conditional headers to write to the blob only if a specified condition is met. For more information, see Specifying Conditional Headers for Blob Service Operations.
Request Headers (Page Blobs Only)
The following table describes request headers applicable only for operations on page blobs.
| Request header | Description |
|---|---|
|
x-ms-blob-content-length: bytes |
Required for page blobs. This header specifies the maximum size for the page blob, up to 1 TB. The page blob size must be aligned to a 512-byte boundary. If this header is specified for a block blob, the Blob service returns status code 400 (Bad Request). |
|
x-ms-blob-sequence-number: <num> |
Optional. Set for page blobs only. The sequence number is a user-controlled value that you can use to track requests. The value of the sequence number must be between 0 and 2^63 - 1.The default value is 0. |
Request Body
For a block blob, the request body contains the content of the blob.
For a page blob, the request body is empty.
Sample Request
The following example shows a request to create a block blob:
Request Syntax: PUT https://myaccount.blob.core.windows.net/mycontainer/myblockblob HTTP/1.1 Request Headers: x-ms-version: 2011-08-18 x-ms-date: Sun, 25 Sep 2011 22:33:35 GMT Content-Type: text/plain; charset=UTF-8 x-ms-blob-type: BlockBlob x-ms-meta-m1: v1 x-ms-meta-m2: v2 Authorization: SharedKey myaccount:YhuFJjN4fAR8/AmBrqBz7MG2uFinQ4rkh4dscbj598g= Content-Length: 11 Request Body: hello world
This sample request creates a page blob and specifies its maximum size as 1024 bytes. Note that you must call Put Page (REST API) to add content to a page blob:
Request Syntax: PUT https://myaccount.blob.core.windows.net/mycontainer/mypageblob HTTP/1.1 Request Headers: x-ms-version: 2011-08-18 x-ms-date: Sun, 25 Sep 2011 22:41:55 GMT Content-Type: text/plain; charset=UTF-8 x-ms-blob-type: PageBlob x-ms-blob-content-length: 1024 x-ms-blob-sequence-number: 0 Authorization: SharedKey myaccount:YhuFJjN4fAR8/AmBrqBz7MG2uFinQ4rkh4dscbj598g= Content-Length: 0
The response includes an HTTP status code and a set of response headers.
Status Code
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. The response can also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.
| Response header | Description |
|---|---|
|
ETag |
The ETag contains a value that the client can use to perform conditional PUT operations by using the If-Match request header. If the request version is 2011-08-18 or newer, the ETag value will be in quotes. |
|
Last-Modified |
The date/time that the blob was last modified. The date format follows RFC 1123. For more information, see Representation of Date/Time Values in Headers. Any write operation on the blob (including updates on the blob's metadata or properties) changes the last modified time of the blob. |
|
Content-MD5 |
This header is returned for a block blob so the client can check the integrity of message content. The Content-MD5 value returned is computed by the Blob service. In version 2012-02-12 and later, this header is returned even when the request does not include Content-MD5 or x-ms-blob-content-md5 headers. |
|
x-ms-request-id |
This header uniquely identifies the request that was made and can be used for troubleshooting the request. For more information, see Troubleshooting API Operations. |
|
x-ms-version |
Indicates the version of the Blob service used to execute the request. This header is returned for requests made against version 2009-09-19 and later. |
|
Date |
A UTC date/time value generated by the service that indicates the time at which the response was initiated. |
Response Body
None.
Sample Response
Response Status: HTTP/1.1 201 Created Response Headers: Transfer-Encoding: chunked Content-MD5: sQqNsWTgdUEFt6mb5y4/5Q== Date: Sun, 25 Sep 2011 22:33:35 GMT ETag: "0x8CB171BA9E94B0B" Last-Modified: Sun, 25 Sep 2011 22:30:15 GMT Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
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.
When you create a blob, you must specify whether it is a block blob or a page blob. Once a blob has been created, the type of the blob cannot be changed unless it is deleted and re-created.
To create a new page blob, first initialize the blob by calling Put Blob and specify its maximum size, up to 1 TB. When creating a page blob, do not include content in the request body. Once the blob has been created, call Put Page (REST API) to add content to the blob or to modify it.
The maximum upload size for a block blob is 64 MB. If your blob is larger than 64 MB, you must upload it as a set of blocks. For more information, see the Put Block (REST API) and Put Block List (REST API) operations. It's not necessary to call Put Blob if you upload the blob as a set of blocks.
If you attempt to upload a block blob that is larger than 64 MB, or a page blob larger than 1 TB, the service returns status code 413 (Request Entity Too Large). The Blob service also returns additional information about the error in the response, including the maximum blob size permitted in bytes.
If you call Put Blob to overwrite an existing blob with the same name, any snapshots associated with the original blob are retained. To remove associated snapshots, call Delete Blob (REST API) first, then Put Blob to re-create the blob.
A blob has custom properties (set via headers) that you can use to store values associated with standard HTTP headers. These values can subsequently be read by calling Get Blob Properties (REST API), or modified by calling Set Blob Properties (REST API). The custom property headers and corresponding standard HTTP header are listed in the following table:
| HTTP header | Custom blob property header |
|---|---|
|
Content-Type |
x-ms-blob-content-type |
|
Content-Encoding |
x-ms-blob-content-encoding |
|
Content-Language |
x-ms-blob-content-language |
|
Content-MD5 |
x-ms-blob-content-md5 |
|
Cache-Control |
x-ms-blob-cache-control |
The semantics for setting persisting these property values with the blob as follows:
-
If the client specifies a custom property header, as indicated by the x-ms-blob prefix, this value is stored with the blob.
-
If the client specifies a standard HTTP header, but not the custom property header, the value is stored in the corresponding custom property associated with the blob, and is returned by a call to Get Blob Properties. For example, if the client sets the Content-Type header on the request, that value is stored in the blob's x-ms-blob-content-type property.
-
If the client sets both the standard HTTP header and the corresponding property header on the same request, the PUT request uses the value provided for the standard HTTP header, but the value specified for the custom property header is persisted with the blob and returned by subsequent GET requests.
If the blob has an active lease, the client must specify a valid lease ID on the request in order to overwrite the blob. If the client does not specify a lease ID, or specifies an invalid lease ID, the Blob service returns status code 412 (Precondition Failed). 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).
If an existing blob with an active lease is overwritten by a Put Blob operation, the lease persists on the updated blob, until it expires or is released.
A Put Blob operation is permitted 10 minutes per MB to complete. If the operation is taking longer than 10 minutes per MB on average, the operation will timeout.
