Create Container operation creates a new container under the specified account. If the container with the same name already exists, the operation fails.
The container resource includes metadata and properties for that container. It doesn't include a list of the blobs in the container.
You can construct the
Create Container request as shown here. We recommend that you use HTTPS. The name of your container can include only lowercase characters and needs to follow these naming rules. In the URL, replace myaccount with the name of your storage account.
|Method||Request URI||HTTP version|
Emulated storage service request
When you make a request against the emulated storage service, specify the emulator hostname and Blob Storage port as
127.0.0.1:10000, followed by the emulated storage account name.
|Method||Request URI||HTTP version|
For more information, see Use the Azurite emulator for local Azure Storage development.
You can specify the following additional parameters on the request URI.
The required and optional request headers are described in the following table:
||Required. Specifies the authorization scheme, account name, and signature. For more information, see Authorize requests to Azure Storage.|
||Required. Specifies the Coordinated Universal Time (UTC) time for the request. For more information, see Authorize requests to Azure Storage.|
||Required for all authorized requests. Specifies the version of the operation to use for this request. For more information, see Versioning for the Azure Storage services.|
||Optional. A name-value pair to associate with the container as metadata. Note: As of version 2009-09-19, metadata names must adhere to the naming rules for C# identifiers.|
||Optional. Specifies whether data in the container can be accessed publicly and the level of access. Possible values include:
If this header isn't included in the request, container data is private to the account owner.
||Optional. Provides a client-generated, opaque value with a 1-kibibyte (KiB) character limit that's recorded in the logs when logging is configured. We highly recommend that you use this header to correlate client-side activities with requests that the server receives. For more information, see Monitor Azure Blob Storage.|
Request headers (encryption scopes)
As of version 2019-02-02, you can specify the following headers on a request to set a default encryption scope on a container. If you set an encryption scope, it is automatically used to encrypt all blobs that are uploaded to the container.
||Required. The encryption scope to set as the default on the container.|
||Required. Values are
Request Syntax: PUT https://myaccount.blob.core.windows.net/mycontainer?restype=container HTTP/1.1 Request Headers: x-ms-version: 2011-08-18 x-ms-date: Sun, 25 Sep 2011 22:50:32 GMT x-ms-meta-Name: StorageSample Authorization: SharedKey myaccount:Z5043vY9MesKNh0PNtksNc9nbXSSqGHueE00JdjidOQ=
The response includes an HTTP status code and a set of response headers.
A successful operation returns status code 201 (Created).
For information about status codes, see Status and error codes.
The response for this operation includes the headers that are described in the following table. The response can also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.
||The ETag for the container. If the request version is 2011-08-18 or later, the ETag value is enclosed in quotation marks.|
||Returns the date and time when the container was last modified. The date format follows RFC 1123. For more information, see Representation of date/time values in headers.
Any operation that modifies the container or its properties or metadata updates the last modified time. Operations on blobs do not affect the last modified time of the container.
||Uniquely identifies the request that was made. You can use it to troubleshoot the request. For more information, see Troubleshoot API operations|
||Indicates the Blob Storage version that's used to execute the request. This header is returned for requests made against version 2009-09-19 or later.|
||The UTC date/time value generated by the service, which indicates the time at which the response was initiated.|
||Can be used to troubleshoot requests and corresponding responses. The value of this header is equal to the value of the
Response status: HTTP/1.1 201 Created Response headers: Transfer-Encoding: chunked Date: Sun, 25 Sep 2011 23:00:12 GMT ETag: “0x8CB14C3E29B7E82” Last-Modified: Sun, 25 Sep 2011 23:00:06 GMT x-ms-version: 2011-08-18 Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
Authorization is required when calling any data access operation in Azure Storage. You can authorize the
Create Container operation as described below.
Azure Storage supports using Microsoft Entra ID to authorize requests to blob data. With Microsoft Entra ID, you can use Azure role-based access control (Azure RBAC) to grant permissions to a security principal. The security principal may be a user, group, application service principal, or Azure managed identity. The security principal is authenticated by Microsoft Entra ID to return an OAuth 2.0 token. The token can then be used to authorize a request against the Blob service.
To learn more about authorization using Microsoft Entra ID, see Authorize access to blobs using Microsoft Entra ID.
Listed below are the RBAC action necessary for a Microsoft Entra user, group, or service principal to call the
Create Container operation, and the least privileged built-in Azure RBAC role that includes this action:
- Azure RBAC action: Microsoft.Storage/storageAccounts/blobServices/containers/write
- Least privileged built-in role: Storage Blob Data Contributor
To learn more about assigning roles using Azure RBAC, see Assign an Azure role for access to blob data.
Containers are created immediately within the storage account. It isn't possible to nest one container within another.
You can optionally create a default or root container for your storage account. The root container makes it possible to reference a blob from the top level of the storage account hierarchy, without referencing the container name.
To add the root container to your storage account, create a container named
$root. Construct the request as follows:
Request Syntax: PUT https://myaccount.blob.core.windows.net/$root?restype=container HTTP/1.1 Request Headers: x-ms-version: 2011-08-18 x-ms-date: Sun, 25 Sep 2011 22:50:32 GMT x-ms-meta-Name: StorageSample Authorization: SharedKey myaccount:Z5043vY9MesKNh0PNtksNc9nbXSSqGHueE00JdjidOQ=
You can specify metadata for a container when you're creating it by including one or more metadata headers on the request. The format for the metadata header is
If a container by the same name is being deleted when
Create Container is called, the server returns status code 409 (Conflict), and it provides additional error information that indicates that the container is being deleted.
Pricing requests can originate from clients that use Blob Storage APIs, either directly through the Blob Storage REST API, or from an Azure Storage client library. These requests accrue charges per transaction. The type of transaction affects how the account is charged. For example, read transactions accrue to a different billing category than write transactions. The following table shows the billing category for
Create Container requests based on the storage account type:
|Operation||Storage account type||Billing category|
|Create Container||Premium block blob
Standard general-purpose v2
Standard general-purpose v1
|List and Create Container operations|
To learn about pricing for the specified billing category, see Azure Blob Storage Pricing.
Authorize requests to Azure Storage
Status and error codes
Blob Storage error codes
Name and reference containers, blobs, and metadata
Set and retrieve properties and metadata for blob resources
Set Container ACL