Quickstart: Create, download, and list blobs with Azure CLI

The Azure CLI is Azure's command-line experience for managing Azure resources. You can install it on macOS, Linux, or Windows and run it from the command line. In this quickstart, you learn to use the Azure CLI to upload and download data to and from Azure Blob storage.

Prerequisites

To access Azure Storage, you'll need an Azure subscription. If you don't already have a subscription, create a Trial Subscription before you begin.

All access to Azure Storage takes place through a storage account. For this quickstart, create a storage account using the Azure portal, Azure PowerShell, or Azure CLI. For help creating a storage account, see Create a storage account.

• If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.

  • If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.

  • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.

  • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

• This article requires version 2.0.46 or later of the Azure CLI.

Authorize access to Blob storage

You can authorize access to Blob storage from the Azure CLI either with Microsoft Entra credentials or by using the storage account access key. Using Microsoft Entra credentials is recommended. This article shows how to authorize Blob storage operations using Microsoft Entra ID.

Azure CLI commands for data operations against Blob storage support the --auth-mode parameter, which enables you to specify how to authorize a given operation. Set the --auth-mode parameter to login to authorize with Microsoft Entra credentials. For more information, see Authorize access to blob or queue data with Azure CLI.

Only Blob storage data operations support the --auth-mode parameter. Management operations, such as creating a resource group or storage account, automatically use Microsoft Entra credentials for authorization.

To begin, sign-in to to your Azure account with the az login.

az cloud set --name AzureChinaCloud
az login

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.

Remember to replace placeholder values in angle brackets with your own values:

az group create \
    --name <resource-group> \
    --location <location>

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.

Remember to replace placeholder values in angle brackets with your own values:

az storage account create \
    --name <storage-account> \
    --resource-group <resource-group> \
    --location <location> \
    --sku Standard_ZRS \
    --encryption-services blob

Create a container

Blobs are always uploaded into a container. You can organize groups of blobs in containers similar to the way you organize your files on your computer in folders. Create a container for storing blobs with the az storage container create command.

The following example uses your Microsoft Entra account to authorize the operation to create the container. Before you create the container, assign the Storage Blob Data Contributor role to yourself. Even if you are the account owner, you need explicit permissions to perform data operations against the storage account. For more information about assigning Azure roles, see Assign an Azure role for access to blob data.

Remember to replace placeholder values in angle brackets with your own values:

az ad signed-in-user show --query id -o tsv | az role assignment create \
    --role "Storage Blob Data Contributor" \
    --assignee @- \
    --scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>"

az storage container create \
    --account-name <storage-account> \
    --name <container> \
    --auth-mode login

You can also use the storage account key to authorize the operation to create the container. For more information about authorizing data operations with Azure CLI, see Authorize access to blob or queue data with Azure CLI.

Upload a blob

Blob storage supports block blobs, append blobs, and page blobs. The examples in this quickstart show how to work with block blobs.

First, create a file to upload to a block blob.

In this example, you upload a blob to the container you created in the last step using the az storage blob upload command.

az storage blob upload \
    --account-name <storage-account> \
    --container-name <container> \
    --name helloworld \
    --file ~/path/to/local/file \
    --auth-mode login

This operation creates the blob if it doesn't already exist, and overwrites it if it does. Upload as many files as you like before continuing.

When you upload a blob using the Azure CLI, it issues respective REST API calls via http and https protocols.

To upload multiple files at the same time, you can use the az storage blob upload-batch command.

List the blobs in a container

List the blobs in the container with the az storage blob list command. Remember to replace placeholder values in angle brackets with your own values:

az storage blob list \
    --account-name <storage-account> \
    --container-name <container> \
    --output table \
    --auth-mode login

Download a blob

Use the az storage blob download command to download the blob you uploaded earlier. Remember to replace placeholder values in angle brackets with your own values:

az storage blob download \
    --account-name <storage-account> \
    --container-name <container> \
    --name helloworld \
    --file <~/destination/path/for/file> \
    --auth-mode login

Data transfer with AzCopy

The AzCopy command-line utility offers high-performance, scriptable data transfer for Azure Storage. You can use AzCopy to transfer data to and from Blob storage and Azure Files. For more information about AzCopy v10, the latest version of AzCopy, see Get started with AzCopy. To learn about using AzCopy v10 with Blob storage, see Transfer data with AzCopy and Blob storage.

The following example uses AzCopy to upload a local file to a blob. Remember to replace the sample values with your own values:

azcopy login --aad-endpoint https://login.partner.microsoftonline.cn
azcopy copy 'C:\myDirectory\myFile.txt' 'https://mystorageaccount.blob.core.chinacloudapi.cn/mycontainer/myFile.txt'

Clean up resources

If you want to delete the resources you created as part of this quickstart, including the storage account, delete the resource group by using the az group delete command. Remember to replace placeholder values in angle brackets with your own values:

az group delete \
    --name <resource-group> \
    --no-wait

Next steps

In this quickstart, you learned how to transfer files between a local file system and a container in Azure Blob storage. To learn more about working with Blob storage by using Azure CLI, select an option below.