Compartilhar via

Gerenciar contêineres de blob usando a CLI do Azure

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ê deve criar um contêiner de armazenamento antes de começar a carregar dados. Para saber mais sobre o armazenamento de blobs, leia a Introdução ao Armazenamento de Blobs do Azure.

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

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

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

  • É 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 Blob Storage

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 deste artigo usam exclusivamente a ID do Microsoft Entra.

Os comandos da CLI do Azure para operações de dados no Armazenamento de Blobs dão suporte ao parâmetro, o --auth-mode que permite especificar como autorizar uma determinada operação. Defina o parâmetro --auth-mode como login para 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 login comando para abrir um navegador e conectar-se à sua assinatura do Azure.

az login

Criar um contêiner

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êiner.

Para usar este exemplo, forneça valores para as variáveis e verifique se você fez logon. 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 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 para 5000. Esse limite garante que quantidades gerenciáveis de dados sejam recuperadas. Se o número de contêineres retornados exceder o --num-results valor 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 --query parâmetro para executar uma consulta JMESPath nos resultados dos comandos. JMESPath é uma linguagem de consulta para JSON que permite que você selecione e modifique os dados retornados da saída da CLI. As consultas são executadas na saída JSON antes de serem formatadas. Para obter mais informações, consulte Como consultar a saída do comando da CLI do Azure usando uma consulta JMESPath.

O exemplo a seguir primeiro lista 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 parâmetros --num-results e --prefix. Por fim, 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 do az storage.

#!/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 de 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 blobs. Algumas propriedades são somente de 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 especificados para um recurso de armazenamento de blobs. Você pode usar 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 az storage container show .

No exemplo a seguir, a primeira abordagem exibe as propriedades de um único contêiner nomeado. Posteriormente, ele recupera todos os contêineres com o prefixo de contêiner de demonstração e itera por meio 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 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 aceita apenas pares chave-valor 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 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

Excluir contêineres

Dependendo do 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.

Aviso

A execução dos exemplos a seguir pode excluir permanentemente contêineres e blobs. A Microsoft recomenda a habilitação da exclusão suave 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 reversível do 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 reversível da sua conta de armazenamento estiver habilitada, 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 lógica, consulte o artigo Exclusão lógica 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 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 habilitado, é 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 reversível e configurá-la em pelo menos uma de suas contas de armazenamento.

Os exemplos a seguir explicam como restaurar um contêiner excluído com o az storage container restore comando. 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 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 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 um contêiner

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

Uma SAS geralmente é usada para fornecer acesso temporário e seguro a um cliente que normalmente não teria permissões. Para gerar uma SAS de serviço ou conta, você precisará fornecer valores para os parâmetros --account-name e --account-key. Um exemplo desse cenário seria um serviço que permite que os usuários leiam e escrevam 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 o artigo de assinaturas de acesso compartilhado .

Cuidado

Qualquer cliente que possua uma SAS válida pode acessar dados em sua conta de armazenamento, conforme permitido por essa SAS. É importante proteger uma SAS contra uso mal-intencionado ou não intencional. Seja discreto na distribuição de SAS e tenha um plano para revogar uma SAS comprometida.

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 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 horários de início e expiração e um protocolo. Ele também especificará as permissões de exclusão, leitura, gravação e lista na SAS usando o --permissions parâmetro. Você pode referenciar a tabela completa de permissões no artigo Criar um serviço SAS .

Copie e cole o valor do token SAS do Blob em um local seguro. Ele só será exibido uma vez e não poderá ser recuperado quando 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

Observação

O token SAS retornado pela CLI do Azure não inclui o caractere delimitador ('?') para a cadeia de caracteres de consulta de URL. Se você 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 mais sobre como trabalhar com o armazenamento de blobs usando a CLI do Azure, selecione uma opção abaixo.

Gerenciar blobs de bloco com a CLI do Azure

Exemplos da CLI do Azure para Armazenamento de Blobs

  • Last updated on