Gerenciar contêineres de blob usando a CLI do Azure

Artigo
06/01/2023

O Armazenamento de Blobs do Microsoft Azure permite armazenar grandes quantidades de dados de objeto não estruturados. Você pode usar o armazenamento de blobs para coletar ou expor dados de mídia, conteúdo ou aplicativo aos usuários. Como todos os dados de blob são armazenados em contêineres, você precisa criar um contêiner de armazenamento antes de começar a carregar dados. Para saber mais sobre o armazenamento de blobs, confira Introdução ao Armazenamento de Blobs do Azure.

A CLI do Azure é a experiência da linha de comando de plataforma cruzada do Azure para gerenciar os recursos do Azure. Você pode usá-la em seu navegador com o Azure Cloud Shell. Você também pode instalá-lo no Windows, no Linux ou no macOS e executá-lo localmente a partir da linha de comando.

Neste artigo de instruções, você aprenderá a usar a CLI do Azure com Bash para trabalhar com objetos contêineres.

Pré-requisitos

Para acessar o Armazenamento do Azure, você precisará de uma assinatura do Azure. Se você ainda não tiver uma assinatura, crie uma conta gratuita antes de começar.

Todo o acesso ao Armazenamento do Azure ocorre por meio de uma conta de armazenamento. Para este Início Rápido, crie uma conta de armazenamento usando o portal do Azure, o Azure PowerShell ou a CLI do Azure. Para obter ajuda sobre como criar uma conta de armazenamento, confira Criar uma conta de armazenamento.

Preparar o ambiente para a CLI do Azure

Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.
Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.
- Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.
- Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.
- Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

É sempre uma boa ideia instalar a versão mais recente da CLI do Azure. Se você está usando o Azure Cloud Shell, a versão mais recente já está instalada.

Autorizar o acesso ao Armazenamento de Blobs

Você pode autorizar o acesso ao Armazenamento de Blobs por meio da CLI do Azure com as credenciais do Microsoft Entra ou usando a chave de acesso da conta de armazenamento. É recomendável usar as credenciais do Microsoft Entra e os exemplos desse artigo usam exclusivamente o Microsoft Entra ID.

Os comandos da CLI do Azure para operações de dados no Armazenamento de Blobs dão suporte ao parâmetro --auth-mode, que permite especificar como autorizar determinada operação. Defina o parâmetro --auth-mode para login autorizar com as credenciais do Microsoft Entra. Para obter mais informações, confira Autorizar o acesso a dados de blob ou de filas com a CLI do Azure.

Execute o comando login para abrir um navegador e se conectar à sua assinatura do Azure.

az login

Criar um contêiner

Para criar um contêiner com a CLI do Azure, chame o comando criar o contêiner de armazenamento do az. O exemplo a seguir ilustra três opções para a criação de contêineres blob com o comando az storage container create. A primeira abordagem cria apenas um contêiner, enquanto as duas abordagens restantes usam operações de script Bash para automatizar a criação de contêineres.

Para usar este exemplo, fornece valores para as variáveis e certifique-se de que você fez logo on. Lembre-se de substituir os valores de espaço reservado entre colchetes pelos seus valores.

#!/bin/bash
storageAccount="<storage-account>"
containerName="demo-container-1"
containerPrefix="demo-container-"

# Approach 1: Create a container
az storage container create \
    --name $containerName \
    --account-name $storageAccount \
    --auth-mode login

# Approach 2: Create containers with a loop
for value in {2..5}
do
    az storage container create \
        --name $containerPrefix$value \
        --account-name $storageAccount \
        --auth-mode login
done

# Approach 3: Create containers by splitting multiple values
containerList="${containerPrefix}6 ${containerPrefix}7 ${containerPrefix}8"
for container in $containerList
do
    az storage container create \
        --name $container \
        --account-name $storageAccount \
        --auth-mode login
done

Listar contêineres

Use o comando az storage container list para recuperar uma lista de contêineres de armazenamento. Para retornar uma lista de contêineres cujos nomes começam com uma determinada cadeia de caracteres, passe a cadeia de caracteres como o valor do parâmetro --prefix.

O parâmetro --num-results pode ser usado para limitar o número de contêineres retornados pela solicitação. O Armazenamento do Microsoft Azure limita o número de contêineres retornados por uma única operação de listagem para 5.000. Esse limite garante que quantidades gerenciáveis de dados sejam recuperadas. Se o número de contêineres retornados exceder o valor --num-results ou o limite de serviço, um token de continuação será retornado. Esse token permite que você use várias solicitações para recuperar qualquer número de contêineres.

Você também pode usar o parâmetro --query para executar uma consulta JMESPath nos resultados dos comandos. O JMESPath é um idioma de consulta para JSON que permite selecionar e modificar dados retornados da saída da CLI. As consultas são executadas na saída do JSON antes que ela possa ser formatada. Para obter mais informações, consulte Como consultar a saída de comandos da CLI do Azure usando uma consulta do JMESPath.

O exemplo a seguir lista primeiro o número máximo de contêineres (sujeito ao limite de serviço). Em seguida, ele lista três contêineres cujos nomes começam com o prefixo container-, fornecendo valores para os --num-results e parâmetros --prefix. Por fim, um único contêiner é listado fornecendo um nome de contêiner conhecido para o parâmetro --prefix.

Leia mais sobre a lista de contêineres de armazenamento do az.

#!/bin/bash
storageAccount="<storage-account>"
containerPrefix="demo-container-"
containerName="demo-container-1"
numResults="3"

# Approach 1: List maximum containers
az storage container list \
    --account-name $storageAccount \
    --auth-mode login

# Approach 2: List a defined number of named containers
az storage container list \
    --prefix $containerPrefix \
    --num-results $numResults \
    --account-name $storageAccount \
    --auth-mode login

# Approach 3: List an individual container
az storage container list \
    --prefix $containerPrefix \
    --query "[?name=='$containerName']" \
    --account-name $storageAccount \
    --auth-mode login

Ler metadados e propriedades do contêiner

Um contêiner expõe as propriedades do sistema e os metadados definidos pelo usuário. Existem propriedades do sistema em cada recurso de armazenamento de blobs. Algumas propriedades são somente leitura, enquanto outras podem ser lidas ou definidas. Internamente, algumas propriedades do sistema correspondem a certos cabeçalhos HTTP padrão.

Os metadados definidos pelo usuário consistem em um ou mais pares nome/valor que você especifica para um recurso de armazenamento de blobs. É possível usar os metadados para armazenar valores adicionais com o recurso. Os valores de metadados são apenas para serem usados para os objetivos que você desejar e não afetam o comportamento do recurso.

Propriedades do contêiner

Para exibir as propriedades de um contêiner com a CLI do Azure, chame o comando show do contêiner de armazenamento do az.

No exemplo a seguir, a primeira abordagem exibe as propriedades de um único contêiner nomeado. Depois, ele recupera todos os contêineres com o prefixo demo-container- e itera através deles, listando as respectivas propriedades. Lembre-se de substituir os valores de espaço reservado por seus próprios valores.

#!/bin/bash
storageAccount="<storage-account>"
containerPrefix="demo-container-"
containerName="demo-container-1"

# Show a named container's properties
az storage container show \
    --name $containerName \
    --account-name $storageAccount \
    --auth-mode login

# List several containers and show their properties
containerList=$(az storage container list \
    --query "[].name" \
    --prefix $containerPrefix \
    --account-name $storageAccount \
    --auth-mode login \
    --output tsv)

for row in $containerList
do
  tmpRow=$(echo $row | sed -e 's/\r//g')
  az storage container show --name $tmpRow --account-name $storageAccount --auth-mode login
done

Ler e gravar metadados de contêiner

Os usuários que têm muitos milhares de objetos nas próprias contas de armazenamento podem localizar rapidamente contêineres específicos com base nos respectivos metadados. Para ler os metadados, você usará o comando az storage container metadata show. Para atualizar metadados, você precisará chamar o método az storage container metadata update. O método aceita apenas pares de valores de chave separados por espaço. Para obter mais informações, consulte a documentação de metadados do contêiner de armazenamento do az.

O primeiro exemplo abaixo atualiza e recupera os metadados de um contêiner nomeado. O segundo exemplo itera a lista de contêineres correspondentes ao valor -prefix. Contêineres com nomes que contêm números mesmo têm seus metadados definidos com valores contidos na variável de metadados.

#!/bin/bash
storageAccount="<storage-account>"
containerName="demo-container-1"
containerPrefix="demo-container-"

# Create metadata string
metadata="key=value pie=delicious"

# Update named container metadata
az storage container metadata update \
    --name $containerName \
    --metadata $metadata \
    --account-name $storageAccount \
    --auth-mode login

# Display metadata
az storage container metadata show \
    --name $containerName \
    --account-name $storageAccount \
    --auth-mode login

# Get list of containers
containerList=$(az storage container list \
    --query "[].name" \
    --prefix $containerPrefix \
    --account-name $storageAccount \
    --auth-mode login \
    --output tsv)

# Update and display metadata
for row in $containerList
do
  #Get the container's number
  tmpName=$(echo $row | sed -e 's/\r//g')
  if [ `expr ${tmpName: ${#containerPrefix}} % 2` == 0 ]
  then
    az storage container metadata update \
        --name $tmpName \
        --metadata $metadata \
        --account-name $storageAccount \
        --auth-mode login
    
    echo $tmpName

    az storage container metadata show \
    --name $tmpName \
    --account-name $storageAccount \
    --auth-mode login    
  fi
done

Excluir contêineres

Dependendo do caso de uso, você pode excluir um único contêiner ou um grupo de contêineres com o comando az storage container delete. Ao excluir uma lista de contêineres, você precisará usar operações condicionais, conforme mostrado nos exemplos abaixo.

Aviso

Executar os exemplos a seguir pode excluir permanentemente contêineres e blobs. A Microsoft recomenda habiltar a exclusão temporária do contêiner para proteger contêineres e blobs contra exclusão acidental. Para obter mais informações, consulte Exclusão temporária para contêineres.

#!/bin/bash
storageAccount="<storage-account>"
containerName="demo-container-1"
containerPrefix="demo-container-"

# Delete a single named container
az storage container delete \
    --name $containerName \
    --account-name $storageAccount \
    --auth-mode login

# Delete containers by iterating a loop
list=$(az storage container list \
    --query "[].name" \
    --prefix $containerPrefix \
    --account-name $storageAccount \
    --auth-mode login \
    --output tsv)
for row in $list
do
    tmpName=$(echo $row | sed -e 's/\r//g')
    az storage container delete \
    --name $tmpName \
    --account-name $storageAccount \
    --auth-mode login
done

Se você tiver a exclusão temporária do contêiner habilitada para sua conta de armazenamento, é possível recuperar contêineres que foram excluídos. Se a opção de proteção de dados de exclusão temporária da sua conta de armazenamento estiver habilitada, o parâmetro --include-deleted retornará contêineres excluídos no período de retenção associado. O parâmetro --include-deleted só pode ser usado para retornar contêineres quando usado com o parâmetro --prefix. Para saber mais sobre a exclusão temporária, confira o artigo Exclusão temporária para contêineres.

Use o exemplo a seguir para recuperar uma lista de contêineres excluídos no período de retenção associado da conta de armazenamento.

#!/bin/bash
storageAccount="<storage-account>"
containerPrefix="demo-container-"

# Retrieve a list of containers including those recently deleted
az storage container list \
    --prefix $containerPrefix \
    --include-deleted \
    --account-name $storageAccount\
    --auth-mode login

Restaurar um contêiner excluído de forma reversível

Conforme mencionado na seção Contêineres de lista, você pode configurar a opção de proteção de dados de exclusão temporária em sua conta de armazenamento. Quando habilitada, é possível restaurar contêineres excluídos dentro do período de retenção associado. Antes de seguir este exemplo, você precisará habilitar a exclusão temporária e configurá-la em pelo menos uma de suas contas de armazenamento.

Os exemplos a seguir explicam como restaurar um contêiner excluído temporariamente com o comando az storage container restore. Você precisará fornecer valores para os parâmetros --name e --version para garantir que a versão correta do contêiner seja restaurada. Se você não sabe o número da versão, pode usar o comando az storage container list para recuperá-lo, conforme mostrado no primeiro exemplo. O segundo exemplo localiza e restaura todos os contêineres excluídos em uma conta de armazenamento específica.

Para saber mais sobre a opção de proteção de dados de exclusão temporária, confira o artigo Exclusão temporária para contêineres.

#!/bin/bash
storageAccount="<storage-account>"
containerName="demo-container-1"

# Restore an individual named container
containerVersion=$(az storage container list \
    --account-name $storageAccount \
    --query "[?name=='$containerName'].[version]" \
    --auth-mode login \
    --output tsv \
    --include-deleted | sed -e 's/\r//g')

az storage container restore \
    --name $containerName \
    --deleted-version $containerVersion \
    --account-name $storageAccount \
    --auth-mode login

# Restore a list of deleted containers
containerList=$(az storage container list \
    --account-name $storageAccount \
    --include-deleted \
    --auth-mode login \
    --query "[?deleted].{name:name,version:version}" \
    -o json)

for row in $(echo "${containerList}" | jq -c '.[]' )
do
    tmpName=$(echo $row | jq -r '.name')
    tmpVersion=$(echo $row | jq -r '.version')
    az storage container restore \
        --account-name $storageAccount \
        --name $tmpName \
        --deleted-version $tmpVersion \
        --auth-mode login
done

Obter uma assinatura de acesso compartilhado para o contêiner

A SAS (Assinatura de Acesso Compartilhado) fornece acesso delegado aos recursos do Azure. Com uma SAS, você tem controle granular sobre como um cliente pode acessar seus dados. Por exemplo, você pode especificar quais recursos estão disponíveis para o cliente. Você também pode limitar os tipos de operações que o cliente pode executar e especificar o intervalo sobre o qual o SAS é válido.

Uma SAS é comumente usada para fornecer acesso temporário e seguro a um cliente que normalmente não teria permissões. Para gerar um SAS de serviço ou conta, você precisará fornecer valores para os --account-name e parâmetros --account-key. Um exemplo desse cenário seria um serviço que permite que os usuários leiam e escrevam os próprios dados em sua conta de armazenamento.

O Armazenamento do Azure dá suporte a três tipos de assinaturas de acesso compartilhado: SAS de serviço, de conta e de delegação de usuário. Para mais informações sobre assinaturas de acesso compartilhado, confira o artigo Conceder acesso limitado a recursos de Armazenamento do Microsoft Azure usando assinaturas de acesso compartilhado.

Cuidado

Qualquer cliente que possua um SAS válido pode acessar os dados em sua conta de armazenamento conforme permitido por esse SAS. É importante proteger um SAS contra uso malicioso ou não intencional. Use discrição ao distribuir um SAS e tenha um plano em vigor para revogar um SAS comprometido.

O exemplo a seguir ilustra o processo de configuração de uma SAS de serviço para um contêiner específico usando o comando az storage container generate-sas. Como ele está gerando um SAS de serviço, o exemplo primeiro recupera a chave da conta de armazenamento para passar como o valor --account-key.

O exemplo configurará a SAS com tempos de início e de expiração e um protocolo. Ele também especificará as permissões de excluir, leitura, gravação e listagem na SAS usando o parâmetro --permissions. Você pode fazer referência à tabela completa de permissões no artigo Criar uma SAS de serviço.

Copie e cole o valor do token SAS do blob em um local seguro. Ele será exibido apenas uma vez e não poderá ser recuperado depois que o Bash for fechado. Para criar a URL de SAS, acrescente o token SAS (URI) à URL do serviço de armazenamento.

#!/bin/bash
storageAccount="<storage-account>"
containerName="demo-container-1"
permissions="drwl"
expiry=`date -u -d "30 minutes" '+%Y-%m-%dT%H:%MZ'`

accountKey=$(az storage account keys list \
    --account-name $storageAccount \
    --query "[?permissions == 'FULL'].[value]" \
    --output tsv)

accountKey=$( echo $accountKey | cut -d' ' -f1 )
 
az storage container generate-sas \
    --name $containerName \
    --https-only \
    --permissions dlrw \
    --expiry $expiry \
    --account-key $accountKey \
    --account-name $storageAccount

Observação

O token SAS retornado pela CLI do Azure não inclui o caractere delimitador (‘?’) para a cadeia de caracteres de consulta da URL. Se estiver acrescentando o token SAS a uma URL de recurso, lembre-se de acrescentar o caractere delimitador à URL do recurso antes de acrescentar o token SAS.

Próximas etapas

Neste artigo de instruções, você aprendeu a gerenciar contêineres no Armazenamento de Blobs. Para saber como trabalhar com o armazenamento de blobs usando a CLI do Azure, selecione uma opção abaixo.

Gerenciar blob de blocos com CLI do Azure

Exemplos da CLI do Azure para o Armazenamento de Blobs

Compartilhar via