Skip to content

Commit 3dc0a57

Browse files
LJSpillerLJSpiller
authored
Merge pull request #184908 from stevenmatthew/containersCLI
Manage containers using Azure CLI
2 parents 98cd06c + e68f83f commit 3dc0a57

File tree

3 files changed

+304
-3
lines changed

3 files changed

+304
-3
lines changed

‎articles/storage/blobs/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -320,6 +320,8 @@ items:
320320
href: ../common/storage-account-get-info.md?toc=%2fazure%2fstorage%2fblobs%2ftoc.json
321321
- name: Create and manage containers
322322
items:
323+
- name: Manage containers (CLI)
324+
href: blob-containers-cli.md
323325
- name: Manage containers (PowerShell)
324326
href: blob-containers-powershell.md
325327
- name: Create or delete a container (.NET)

‎articles/storage/blobs/blob-containers-cli.md

Lines changed: 299 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,299 @@
1+
---
2+
title: Manage blob containers using Azure CLI
3+
titleSuffix: Azure Storage
4+
description: Learn how to manage Azure storage containers using Azure CLI
5+
services: storage
6+
author: stevenmatthew
7+
8+
ms.service: storage
9+
ms.topic: how-to
10+
ms.date: 01/19/2022
11+
ms.author: shaas
12+
ms.subservice: blobs
13+
---
14+
15+
# Manage blob containers using Azure CLI
16+
17+
Azure blob storage allows you to store large amounts of unstructured object data. You can use blob storage to gather or expose media, content, or application data to users. Because all blob data is stored within containers, you must create a storage container before you can begin to upload data. To learn more about blob storage, read the [Introduction to Azure Blob storage](storage-blobs-introduction.md).
18+
19+
The Azure CLI is Azure's cross-platform command-line experience for managing Azure resources. You can use it in your browser with Azure Cloud Shell. You can also install it on macOS, Linux, or Windows and run it locally from the command line.
20+
21+
In this how-to article, you learn to use the Azure CLI to work with container objects.
22+
23+
## Prerequisites
24+
25+
[!INCLUDE [storage-quickstart-prereq-include](../../../includes/storage-quickstart-prereq-include.md)]
26+
27+
[!INCLUDE [azure-cli-prepare-your-environment.md](../../../includes/azure-cli-prepare-your-environment-h3.md)]
28+
29+
- It's always a good idea to install the latest version of the Azure CLI. If using Azure Cloud Shell, the latest version is already installed.
30+
31+
### Authorize access to Blob storage
32+
33+
You can authorize access to Blob storage from the Azure CLI either with Azure AD credentials or by using the storage account access key. Using Azure AD credentials is recommended, and this article's examples use Azure AD exclusively.
34+
35+
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 Azure AD credentials. For more information, see [Authorize access to blob or queue data with Azure CLI](./authorize-data-operations-cli.md?toc=%2fazure%2fstorage%2fblobs%2ftoc.json).
36+
37+
Run the `login` command to open a browser and connect to your Azure subscription.
38+
39+
```azurecli-interactive
40+
az login
41+
```
42+
43+
## Create a container
44+
45+
To create a container with Azure CLI, call the [az storage container create](/cli/azure/storage/container#az_storage_container_create) command.The following example illustrates three options for the creation of blob containers with the `az storage container create` command. The first approach creates a single container, while the remaining two approaches use Bash scripting operations to automate container creation.
46+
47+
To use this example, supply values for the variables and ensure that you've logged in. Remember to replace the placeholder values in brackets with your own values.
48+
49+
```azurecli
50+
#!/bin/bash
51+
export AZURE_STORAGE_ACCOUNT="<storage-account>"
52+
containerName="demo-container-1"
53+
containerPrefix="demo-container-"
54+
55+
# Approach 1: Create a container
56+
az storage container create \
57+
--name $containerName \
58+
--auth-mode login
59+
60+
# Approach 2: Create containers with a loop
61+
for value in {2..4}
62+
do
63+
az storage container create \
64+
--name $containerPrefix$value \
65+
--auth-mode login
66+
done
67+
68+
# Approach 3: Create containers by splitting multiple values
69+
containerList="${containerPrefix}5 ${containerPrefix}6 ${containerPrefix}7"
70+
for container in $containerList
71+
do
72+
az storage container create \
73+
--name $container \
74+
--auth-mode login
75+
done
76+
```
77+
78+
## List containers
79+
80+
Use the `az storage container list` command to retrieve a list of storage containers. To return a list of containers whose names begin with a given character string, pass the string as the `--prefix` parameter value.
81+
82+
The `--num-results` parameter can be used to limit the number of containers returned by the request. Azure Storage limits the number of containers returned by a single listing operation to 5000. This limit ensures that manageable amounts of data are retrieved. If the number of containers returned exceeds either the `--num-results` value or the service limit, a continuation token is returned. This token allows you to use multiple requests to retrieve any number of containers.
83+
84+
You can also use the `--query` parameter to execute a [JMESPath query](https://jmespath.org/) on the results of commands. JMESPath is a query language for JSON that allows you to select and modify data returned from CLI output. Queries are executed on the JSON output before it can be formatted. For more information, see [How to query Azure CLI command output using a JMESPath query](/cli/azure/query-azure-cli).
85+
86+
The following example first lists the maximum number of containers (subject to the service limit). Next, it lists three containers whose names begin with the prefix *container-* by supplying values for the `--num-results` and `--prefix` parameters. Finally, a single container is listed by supplying a known container name to the `--prefix` parameter.
87+
88+
Read more about the [az storage container list](/cli/azure/storage/container#az_storage_container_list).
89+
90+
```azurecli-interactive
91+
#!/bin/bash
92+
export AZURE_STORAGE_ACCOUNT="<storage-account>"
93+
numResults="3"
94+
containerPrefix="demo-container-"
95+
containerName="demo-container-1"
96+
97+
# Approach 1: List maximum containers
98+
az storage container list \
99+
--auth-mode login
100+
101+
# Approach 2: List a defined number of named containers
102+
az storage container list \
103+
--prefix $containerPrefix \
104+
--num-results $numResults \
105+
--auth-mode login
106+
107+
# Approach 3: List an individual container
108+
az storage container list \
109+
--prefix $containerPrefix \
110+
--query "[?name=='$containerName']" \
111+
--auth-mode login
112+
```
113+
114+
## Read container properties and metadata
115+
116+
A container exposes both system properties and user-defined metadata. System properties exist on each blob storage resource. Some properties are read-only, while others can be read or set. Under the covers, some system properties map to certain standard HTTP headers.
117+
118+
User-defined metadata consists of one or more name-value pairs that you specify for a blob storage resource. You can use metadata to store additional values with the resource. Metadata values are for your own purposes only, and don't affect how the resource behaves.
119+
120+
### Container properties
121+
122+
To display the properties of a container with Azure CLI, call the [az storage container show](/cli/azure/storage/container#az_storage_container_show) command.
123+
124+
In the following example, the first approach displays the properties of a single named container. Afterward, it retrieves all containers with the **demo-container-** prefix and iterates through them, listing their properties. Remember to replace the placeholder values with your own values.
125+
126+
```azurecli-interactive
127+
#!/bin/bash
128+
export AZURE_STORAGE_ACCOUNT="<storage-account>"
129+
containerPrefix="demo-container-"
130+
containerName="demo-container-1"
131+
132+
# Show a named container's properties
133+
az storage container show \
134+
--name $containerName \
135+
--auth-mode login
136+
137+
# List several containers and show their properties
138+
containerList=$(az storage container list \
139+
--query "[].name" \
140+
--prefix $containerPrefix \
141+
--auth-mode login \
142+
--output tsv)
143+
for item in $containerList
144+
do
145+
az storage container show \
146+
--name $item \
147+
--auth-mode login
148+
done
149+
```
150+
151+
### Read and write container metadata
152+
153+
Users that have many thousands of objects within their storage account can quickly locate specific containers based on their metadata. To read the metadata, you'll use the `az storage container metadata show` command. To update metadata, you'll need to call the `az storage container metadata update` command. The method only accepts space-separated key-value pairs. For more information, see the [az storage container metadata](/cli/azure/storage/container/metadata) documentation.
154+
155+
The example below first updates a container's metadata and afterward retrieves the container's metadata.
156+
157+
```azurecli-interactive
158+
#!/bin/bash
159+
export AZURE_STORAGE_ACCOUNT="<storage-account>"
160+
containerName = "demo-container-1"
161+
162+
# Create metadata string
163+
metadata="key=value pie=delicious"
164+
165+
# Update metadata
166+
az storage container metadata update \
167+
--name $containerName \
168+
--metadata $metadata \
169+
--auth-mode login
170+
171+
# Display metadata
172+
az storage container metadata show \
173+
--name $containerName \
174+
--auth-mode login
175+
```
176+
177+
## Delete containers
178+
179+
Depending on your use case, you can delete a single container or a group of containers with the `az storage container delete` command. When deleting a list of containers, you'll need to use conditional operations as shown in the examples below.
180+
181+
> [!WARNING]
182+
> Running the following examples may permanently delete containers and blobs. Microsoft recommends enabling container soft delete to protect containers and blobs from accidental deletion. For more info, see [Soft delete for containers](soft-delete-container-overview.md).
183+
184+
```azurecli-interactive
185+
#!/bin/bash
186+
export AZURE_STORAGE_ACCOUNT="<storage-account>"
187+
containerName="demo-container-1"
188+
containerPrefix="demo-container-"
189+
190+
# Delete a single named container
191+
az storage container delete \
192+
--name $containerName \
193+
--auth-mode login
194+
195+
# Delete containers by iterating a loop
196+
list=$(az storage container list \
197+
--query "[].name" \
198+
--auth-mode login \
199+
--prefix $containerPrefix \
200+
--output tsv)
201+
for item in $list
202+
do
203+
az storage container delete \
204+
--name $item \
205+
--auth-mode login
206+
done
207+
```
208+
209+
If you have container soft delete enabled for your storage account, then it's possible to retrieve containers that have been deleted. If your storage account's soft delete data protection option is enabled, the `--include-deleted` parameter will return containers deleted within the associated retention period. The `--include-deleted` parameter can only be used in conjunction with the `--prefix` parameter when returning a list of containers. To learn more about soft delete, refer to the [Soft delete for containers](soft-delete-container-overview.md) article.
210+
211+
Use the following example to retrieve a list of containers deleted within the storage account's associated retention period.
212+
213+
```azurecli-interactive
214+
# Retrieve a list of containers including those recently deleted
215+
az storage container list \
216+
--prefix $prefix \
217+
--include-deleted \
218+
--auth-mode login
219+
```
220+
221+
## Restore a soft-deleted container
222+
223+
As mentioned in the [List containers](#list-containers) section, you can configure the soft delete data protection option on your storage account. When enabled, it's possible to restore containers deleted within the associated retention period. Before you can follow this example, you'll need to enable soft delete and configure it on at least one of your storage accounts.
224+
225+
The following example explains how to restore a soft-deleted container with the `az storage container restore` command. You'll need to supply values for the `--name` and `--version` parameters to ensure that the correct version of the container is restored. If you don't know the version number, you can use the `az storage container list` command to retrieve it as shown in the following example.
226+
227+
To learn more about the soft delete data protection option, refer to the [Soft delete for containers](soft-delete-container-overview.md) article.
228+
229+
```azurecli-interactive
230+
#!/bin/bash
231+
export AZURE_STORAGE_ACCOUNT="<storage-account>"
232+
containerName="demo-container-1"
233+
234+
# Restore an individual named container
235+
containerVersion=$(az storage container list \
236+
--query "[?name=='$containerName'].[version]" \
237+
--auth-mode login \
238+
--output tsv \
239+
--include-deleted)
240+
241+
az storage container restore \
242+
--name $containerName \
243+
--deleted-version $containerVersion \
244+
--auth-mode login
245+
```
246+
247+
## Get a shared access signature for a container
248+
249+
A shared access signature (SAS) provides delegated access to Azure resources. A SAS gives you granular control over how a client can access your data. For example, you can specify which resources are available to the client. You can also limit the types of operations that the client can perform, and specify the interval over which the SAS is valid.
250+
251+
A SAS is commonly used to provide temporary and secure access to a client who wouldn't normally have permissions. To generate either a service or account SAS, you'll need to supply values for the `–-account-name` and `-–account-key` parameters. An example of this scenario would be a service that allows users read and write their own data to your storage account.
252+
253+
Azure Storage supports three types of shared access signatures: user delegation, service, and account SAS. For more information on shared access signatures, see the [Grant limited access to Azure Storage resources using shared access signatures](../common/storage-sas-overview.md) article.
254+
255+
> [!CAUTION]
256+
> Any client that possesses a valid SAS can access data in your storage account as permitted by that SAS. It's important to protect a SAS from malicious or unintended use. Use discretion in distributing a SAS, and have a plan in place for revoking a compromised SAS.
257+
258+
The following example illustrates the process of configuring a service SAS for a specific container using the `az storage container generate-sas` command. Because it is generating a service SAS, the example first retrieves the storage account key to pass as the `--account-key` value.
259+
260+
The example will configure the SAS with start and expiry times and a protocol. It will also specify the **delete**, **read**, **write**, and **list** permissions in the SAS using the `--permissions` parameter. You can reference the full table of permissions in the [Create a service SAS](/rest/api/storageservices/create-service-sas) article.
261+
262+
```azurecli-interactive
263+
#!/bin/bash
264+
storageAccount="<storage-account-name>"
265+
export AZURE_STORAGE_ACCOUNT=$storageAccount
266+
containerName="demo-container-1"
267+
permissions="drwl"
268+
expiry=`date -u -d "30 minutes" '+%Y-%m-%dT%H:%MZ'`
269+
270+
accountKey=$(az storage account keys list \
271+
--account-name $storageAccount \
272+
--query "[?permissions == 'FULL'].[value]" \
273+
--output tsv)
274+
275+
accountKey=$( echo $accountKey | cut -d' ' -f1 )
276+
277+
az storage container generate-sas \
278+
--name $containerName \
279+
--https-only \
280+
--permissions dlrw \
281+
--expiry $expiry \
282+
--account-key $accountKey
283+
```
284+
285+
## Clean up resources
286+
287+
If you want to delete the environment variables as part of this how-to article, run the following script.
288+
289+
```azurecli
290+
# Remove environment variables
291+
unset AZURE_STORAGE_ACCOUNT
292+
```
293+
294+
## Next steps
295+
296+
In this how-to article, you learned how to manage containers in Azure blob storage. To learn more about working with blob storage by using Azure CLI, explore Azure CLI samples for Blob storage.
297+
298+
> [!div class="nextstepaction"]
299+
> [Azure CLI samples for Blob storage](storage-samples-blobs-cli.md?toc=%2fazure%2fstorage%2fblobs%2ftoc.json)

‎articles/storage/blobs/blob-containers-powershell.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ ms.custom: template-how-to
1515

1616
# Manage blob containers using PowerShell
1717

18-
Azure blob storage allows you to store large amounts of unstructured object data. You can use Blob Storage to gather or expose media, content, or application data to users. Because all blob data is stored within containers, you must create a storage container before you can begin to upload data. To learn more about Blob Storage, read the [Introduction to Azure Blob storage](storage-blobs-introduction.md).
18+
Azure blob storage allows you to store large amounts of unstructured object data. You can use blob storage to gather or expose media, content, or application data to users. Because all blob data is stored within containers, you must create a storage container before you can begin to upload data. To learn more about blob storage, read the [Introduction to Azure Blob storage](storage-blobs-introduction.md).
1919

2020
This how-to article explains how to work with both individual and multiple storage container objects.
2121

@@ -123,9 +123,9 @@ loop-container4 11/2/2021 12:22:00 AM +00:00 True
123123

124124
## Read container properties and metadata
125125

126-
A container exposes both system properties and user-defined metadata. System properties exist on each Blob Storage resource. Some properties are read-only, while others can be read or set. Under the covers, some system properties map to certain standard HTTP headers.
126+
A container exposes both system properties and user-defined metadata. System properties exist on each blob storage resource. Some properties are read-only, while others can be read or set. Under the covers, some system properties map to certain standard HTTP headers.
127127

128-
User-defined metadata consists of one or more name-value pairs that you specify for a Blob Storage resource. You can use metadata to store additional values with the resource. Metadata values are for your own purposes only, and don't affect how the resource behaves.
128+
User-defined metadata consists of one or more name-value pairs that you specify for a blob storage resource. You can use metadata to store additional values with the resource. Metadata values are for your own purposes only, and don't affect how the resource behaves.
129129

130130
### Container properties
131131

0 commit comments

Comments
 (0)