Perform Blob storage operations with Azure CLI

Azure Blob storage is a service for storing large amounts of unstructured object data, such as text or binary data, that can be accessed from anywhere in the world via HTTP or HTTPS. This tutorial covers basic operations in Azure Blob storage such as uploading, downloading, and deleting blobs. You learn how to:

  • Create a container
  • Upload a file (blob) to a container
  • List the blobs in a container
  • Download a blob from a container
  • Copy a blob between storage accounts
  • Delete a blob
  • Display and modify blob properties and metadata
  • Manage security with a shared access signature (SAS)

This tutorial requires Azure CLI version 2.0.4 or later. Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI 2.0.

Launch Azure Cloud Shell

The Azure Cloud Shell is a free interactive shell that you can use to run the steps in this article. It has common Azure tools preinstalled and configured to use with your account. Just click the Copy to copy the code, paste it into the Cloud Shell, and then press enter to run it. There are a few ways to launch the Cloud Shell:

Click Try It in the upper right corner of a code block. Cloud Shell in this article
Open Cloud Shell in your browser. https://shell.azure.com/bash
Click the Cloud Shell button on the menu in the upper right of the Azure portal. Cloud Shell in the portal

Create a resource group

Create an Azure resource group with the az group create command. A resource group is a logical container into which Azure resources are deployed and managed.

az group create \
    --name myResourceGroup \
    --location eastus

Create a storage account

Create a general-purpose storage account with the az storage account create command. The general-purpose storage account can be used for all four services: blobs, files, tables, and queues.

az storage account create \
    --name mystorageaccount \
    --resource-group myResourceGroup \
    --location eastus \
    --sku Standard_LRS \
    --encryption blob

Specify storage account credentials

The Azure CLI needs your storage account credentials for most of the commands in this tutorial. While there are several options for doing so, one of the easiest ways to provide them is to set AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_ACCESS_KEY environment variables.

First, display your storage account keys by using the az storage account keys list command:

az storage account keys list \
    --account-name mystorageaccount \
    --resource-group myResourceGroup \
    --output table

Now, set the AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_ACCESS_KEY environment variables. You can do this in the Bash shell by using the export command:

export AZURE_STORAGE_ACCOUNT="mystorageaccountname"
export AZURE_STORAGE_ACCESS_KEY="myStorageAccountKey"

Create a container

Containers are similar to directories on your computer, allowing you to organize groups of blobs in a container like you organize files in a directory. A storage account can have any number of containers. You can store up to 500 TB of blob data in a container, which is the maximum amount of data in a storage account.

Create a container for storing blobs with the az storage container create command.

az storage container create --name mystoragecontainer

Container names must start with a letter or number, and can contain only letters, numbers, and the hyphen character (-). For more rules about naming blobs and containers, see Naming and referencing containers, blobs, and metadata.

Enable public read access for a container

A newly created container is private by default. That is, nobody can access the container without a shared access signature or the access keys for the storage account. Using Azure CLI, you can modify this behavior by setting container permissions to one of three levels:

--public-access off (Default) No public read access
--public-access blob Public read access to blobs only
--public-access container Public read access to blobs, can list blobs in container

When you set public access to blob or container, you enable read-only access for anyone on the Internet. For example, if you want to display images stored as blobs on your website, you need to enable public read access. If you want to enable read/write access, you must instead use a shared access signature (SAS).

Enable public read access for your container with the az storage container set-permission command.

az storage container set-permission \
    --name mystoragecontainer \
    --public-access container

Upload a blob to a container

Blob storage supports block blobs, append blobs, and page blobs. Block blobs are the most common type of blob stored in Azure Storage. Append blobs are used when data must be added to an existing blob without modifying its existing content, such as for logging. Page blobs back the VHD files of IaaS virtual machines.

In this example, we upload a blob into the container we created in the last step with the az storage blob upload command.

az storage blob upload \
    --container-name mystoragecontainer \
    --name blobName \
    --file ~/path/to/local/file

This operation creates the blob if it doesn't already exist, and overwrites it if it does. Upload several files so you can see multiple entries when you list the blobs in the next step.

List the blobs in a container

List the blobs in the container with the az storage blob list command.

az storage blob list \
    --container-name mystoragecontainer \
    --output table

Sample output:

Name            Blob Type      Length  Content Type              Last Modified
--------------  -----------  --------  ------------------------  -------------------------
ISSUE_TEMPLATE  BlockBlob         761  application/octet-stream  2017-04-21T18:29:50+00:00
LICENSE         BlockBlob       18653  application/octet-stream  2017-04-21T18:28:50+00:00
LICENSE-CODE    BlockBlob        1090  application/octet-stream  2017-04-21T18:29:02+00:00
README.md       BlockBlob        6700  application/octet-stream  2017-04-21T18:27:33+00:00
dir1/file1.txt  BlockBlob        6700  application/octet-stream  2017-04-21T18:32:51+00:00

Download a blob

Download the blob you uploaded in a previous step using the az storage blob download command.

az storage blob download \
    --container-name mystoragecontainer \
    --name blobName \
    --file ~/destination/path/for/file

Copy a blob between storage accounts

You can copy blobs within or across storage accounts and regions asynchronously.

The following example demonstrates how to copy blobs from one storage account to another. We first create a container in the source storage account, specifying public read-access for its blobs. Next, we upload a file to the container, and finally, copy the blob from that container into a container in the destination storage account.

In this example, the destination container must already exist in the destination storage account for the copy operation to succeed. Additionally, the source blob specified in the --source-uri argument must either include a shared access signature (SAS) token, or be publicly accessible, as in this example.

# Create container in source account
az storage container create \
    --account-name sourceaccountname \
    --account-key sourceaccountkey \
    --name sourcecontainer \
    --public-access blob

# Upload blob to container in source account
az storage blob upload \
    --account-name sourceaccountname \
    --account-key sourceaccountkey \
    --container-name sourcecontainer \
    --file ~/path/to/sourcefile \
    --name sourcefile

# Copy blob from source account to destination account (destcontainer must exist)
az storage blob copy start \
    --account-name destaccountname \
    --account-key destaccountkey \
    --destination-blob destfile.png \
    --destination-container destcontainer \
    --source-uri https://sourceaccountname.blob.core.windows.net/sourcecontainer/sourcefile.png

Delete a blob

Delete the blob from the container using the az storage blob delete command.

az storage blob delete \
    --container-name mystoragecontainer \
    --name blobName

Set the content type

The content type, also known as the MIME type, identifies the format of the data in the blob. Browsers and other software use the content type to determine how to process the data. The following example sets the content type to image/png.

# Set the content type
az storage blob update
    --container-name mystoragecontainer 
    --name blobName 
    --content-type image/png

Display and modify blob properties and metadata

Each blob has several service-defined properties you can display with the az storage blob show command, including its name, type, length, and others. You can also configure a blob with your own properties and their values by using the az storage blob metadata update command.

In this example, we first display the service-defined properties of a blob, then update the blob with two of our own metadata properties. Finally, we display the blob's metadata properties and their values with the az storage blob metadata show command.

# Show properties of a blob
az storage blob show \
    --container-name mystoragecontainer \
    --name blobName \
    --output table

# Set metadata properties of a blob (replaces all existing metadata)
az storage blob metadata update \
    --container-name mystoragecontainer \
    --name blobName \
    --metadata "key1=value1" "key2=value2"

# Show metadata properties of a blob
az storage blob metadata show \
    --container-name mystoragecontainer \
    --name blobName

Create a shared access signature (SAS)

Shared access signatures (SAS) provide you with a way to grant limited access to objects in your storage account without exposing your storage account access keys. To produce a URI that permits access to a private resource, you create SAS token with the desired permissions and validity window (its effective duration), and append it as a query string to a resource's URL, thus forming its full SAS URI. Anyone with this SAS URI (the resource's URL plus the SAS token) can then access it during the SAS token's validity window. For example, you might want to permit read access to a private blob for two minutes so someone can view it.

In the following steps, you'll disable public access to your container, test the private-only access, then generate and test a SAS URI.

Disable container public access

First, set the access level of the container to off. This designates that there is no access to the container or its blobs without either a shared access signature or a storage account access key.

az storage container set-permission \
    --name mystoragecontainer \
    --public-access off

Verify private access

To verify that there is no public read access to the blobs in that container, get the URL for one of its blobs with the az storage blob url command.

az storage blob url \
    --container-name mystoragecontainer \
    --name blobName \
    --output tsv

Navigate to the blob's URL in a private browser window. You're presented with a ResourceNotFound error because the blob is private, and you have not included a shared access signature.

Create a SAS URI

Now we'll create a SAS URI that permits access to the blob. In the following example, we first populate a variable with the URL for the blob with az storage blob url, then populate another variable with a SAS token generated with the az storage blob generate-sas command. Finally, we output the full SAS URI for blob by concatenating the two, separated by the ? query string separator.

# Get UTC datetimes for SAS start and expiry (Example: 1994-11-05T13:15:30Z)
sas_start=`date -u +'%Y-%m-%dT%H:%M:%SZ'`
sas_expiry=`date -u +'%Y-%m-%dT%H:%M:%SZ' -d '+2 minute'`

# Get the URL for the blob
blob_url=`az storage blob url \
    --container-name mystoragecontainer \
    --name blobName \
    --output tsv`

# Obtain a SAS token granting read (r) access between the
# SAS start and expiry times
sas_token=`az storage blob generate-sas \
    --container-name mystoragecontainer \
    --name blobName \
    --start $sas_start \
    --expiry $sas_expiry \
    --permissions r \
    --output tsv`

# Display the full SAS URI for the blob
echo $blob_url?$sas_token

Test the SAS URI

In a private browser window, navigate to the full SAS URI that you displayed with the echo command in the preceding code snippet. This time, you aren't presented with an error and you can view or download the blob.

Wait long enough for the URL to expire (two minutes in this example), then navigate to the URI in another private browser window. You now see an AuthenticationFailed error because the SAS token has expired.

Clean up resources

If you no longer need any of the resources in your resource group, including the storage account you created and any blobs you've uploaded in this tutorial, delete the resource group with the az group delete command.

az group delete --name myResourceGroup

Next steps

In this tutorial, you learned the basics of working with blobs in Azure Storage:

  • Create a container
  • Upload a file (blob) to a container
  • List the blobs in a container
  • Download a blob from a container
  • Copy a blob between storage accounts
  • Delete a blob
  • Display and modify blob properties and metadata
  • Manage security with a shared access signature (SAS)

The following resources provide additional information about working with Azure CLI, as well as working with the resources in your storage account.