Gerenciar contêineres de blob usando a CLI do Azure

O Armazenamento de Blobs do Microsoft Azure permite armazenar grandes quantidades de dados de objetos não estruturados. Você pode usar o armazenamento de blob 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ê deve criar um contêiner de armazenamento antes de começar a carregar dados. Para saber mais sobre o armazenamento de blob, leia a Introdução ao armazenamento de Blob do Azure.

A CLI do Azure é a experiência de linha de comando entre plataformas do Azure para gerenciar recursos do Azure. Pode utilizá-la no seu browser com o Azure Cloud Shell. Você também pode instalá-lo no macOS, Linux ou Windows 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 de contêiner.

Pré-requisitos

Para acessar o Armazenamento do Azure, você precisará de uma assinatura do Azure. Se ainda não tiver uma subscrição, 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 para criar uma conta de armazenamento, consulte Criar uma conta de armazenamento.

Prepare o seu ambiente para o CLI do Azure

• Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.

  

• Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.

  • Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.

  • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.

  • Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

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

Autorizar o acesso ao armazenamento de Blob

Você pode autorizar o acesso ao armazenamento de Blob a partir da CLI do Azure com credenciais do Microsoft Entra ou usando a chave de acesso da conta de armazenamento. O uso de credenciais do Microsoft Entra é recomendado, e os exemplos deste artigo usam exclusivamente o Microsoft Entra ID.

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

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

az login

Criar um contentor

Para criar um contêiner com a CLI do Azure, chame o comando az storage container create . O exemplo a seguir ilustra três opções para a criação de contêineres de blob com o az storage container create comando. A primeira abordagem cria um único 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, forneça valores para as variáveis e verifique se você fez login. Lembre-se de substituir os valores de espaço reservado entre colchetes pelos seus próprios 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 contentores

Use o az storage container list comando 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 --prefix parâmetro.

O --num-results parâmetro pode ser usado para limitar o número de contêineres retornados pela solicitação. O Armazenamento do Azure limita o número de contêineres retornados por uma única operação de listagem a 5000. Esse limite garante que quantidades gerenciáveis de dados sejam recuperadas. Se o número de contêineres retornados exceder o valor ou o --num-results 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 --query parâmetro para executar uma consulta JMESPath nos resultados dos comandos. JMESPath é uma linguagem de consulta para JSON que permite selecionar e modificar dados retornados da saída da CLI. As consultas são executadas na saída JSON antes que ela possa ser formatada. Para obter mais informações, consulte Como consultar a saída do comando CLI do Azure usando uma consulta 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 contêiner de prefixo - fornecendo valores para os --num-results parâmetros e --prefix . Finalmente, um único contêiner é listado fornecendo um nome de contêiner conhecido para o --prefix parâmetro.

Leia mais sobre a lista de contêineres de armazenamento 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 propriedades e metadados do contêiner

Um contêiner expõe as propriedades do sistema e os metadados definidos pelo usuário. As propriedades do sistema existem em cada recurso de armazenamento de blob. Algumas propriedades são somente leitura, enquanto outras podem ser lidas ou definidas. Sob as capas, algumas propriedades do sistema são mapeadas para determinados 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 blob. Você pode usar metadados para armazenar valores adicionais com o recurso. Os valores de metadados são apenas para seus próprios fins e não afetam como o recurso se comporta.

Propriedades do contentor

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

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 suas 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 em sua conta de armazenamento podem localizar rapidamente contêineres específicos com base em seus metadados. Para ler os metadados, você usará o az storage container metadata show comando. Para atualizar metadados, você precisará chamar o az storage container metadata update comando. O método só aceita pares chave-valor separados por espaço. Para obter mais informações, consulte a documentação de metadados do contêiner de armazenamento 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 -prefix valor. Contêineres com nomes contendo números pares 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

Eliminar contentores

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

#!/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 suave de contêiner habilitada para sua conta de armazenamento, será possível recuperar contêineres que foram excluídos. Se a opção de proteção de dados de exclusão suave da sua conta de armazenamento estiver ativada, o --include-deleted parâmetro retornará contêineres excluídos dentro do período de retenção associado. O --include-deleted parâmetro só pode ser usado para retornar contêineres quando usado com o --prefix parâmetro. Para saber mais sobre a exclusão suave, consulte o artigo Exclusão suave para contêineres .

Use o exemplo a seguir para recuperar uma lista de contêineres excluídos dentro do 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 suavemente

Conforme mencionado na seção Listar contêineres , você pode configurar a opção de proteção de dados de exclusão suave em sua conta de armazenamento. Quando ativado, é 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 virtual e configurá-la em pelo menos uma de suas contas de armazenamento.

Os exemplos a seguir explicam como restaurar um contêiner excluído por software com o az storage container restore comando. Você precisará fornecer valores para os --name parâmetros e --version para garantir que a versão correta do contêiner seja restaurada. Se você não souber o número da versão, poderá usar o az storage container list comando 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 suave, consulte o artigo Exclusão suave 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 um contêiner

Uma assinatura de acesso compartilhado (SAS) fornece acesso delegado aos recursos do Azure. Uma SAS oferece 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 durante o qual a SAS é válida.

Um SAS é comumente usado 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 de conta, você precisará fornecer valores para os --account-name parâmetros e --account-key . Um exemplo desse cenário seria um serviço que permite que os usuários leiam e gravem seus próprios dados em sua conta de armazenamento.

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

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

O exemplo configurará o SAS com tempos de início e expiração e um protocolo. Ele também especificará as permissões de exclusão, leitura, gravação e lista no SAS usando o --permissions parâmetro. 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 Blob SAS em um local seguro. Ele só será exibido uma vez e não poderá ser recuperado quando o Bash for fechado. Para construir a URL 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

Próximos passos

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