Compartilhar via


Gerenciar contêineres de blob usando o PowerShell

O Armazenamento de Blobs do 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.

Este artigo de instruções explica como trabalhar com um ou vários objetos de contêiner de armazenamento.

Pré-requisitos

Você precisará obter autorização para uma assinatura do Azure antes de poder usar os exemplos neste artigo. A autorização pode ocorrer autenticando-se com uma conta do Microsoft Entra ou usando uma chave compartilhada. Os exemplos neste artigo usam a autenticação do Microsoft Entra em conjunto com objetos de contexto. Objetos de contexto encapsulam suas credenciais do Microsoft Entra e as transmitem em operações de dados subsequentes, eliminando a necessidade de autenticar novamente.

Para entrar em sua conta do Azure com uma conta do Microsoft Entra, abra o PowerShell e chame o cmdlet Connect-AzAccount.

# Connect to your Azure subscription
 Connect-AzAccount

Depois que a conexão tiver sido estabelecida, crie o contexto da conta de armazenamento chamando o cmdlet New-AzStorageContext. Inclua o parâmetro -UseConnectedAccount para que as operações de dados sejam executadas usando suas credenciais do Microsoft Entra.

# Create a context object using Azure AD credentials
 $ctx = New-AzStorageContext -StorageAccountName <storage account name> -UseConnectedAccount

Lembre-se de substituir os valores de espaço reservado entre colchetes pelos seus valores. Para obter mais informações sobre como entrar no Azure com o PowerShell, veja Conectar-se com o Azure PowerShell.

Criar um contêiner

Para criar contêineres com o PowerShell, chame o cmdlet New-AzStorageContainer. Não há limites para o número de blobs ou contêineres que podem ser criados em uma conta de armazenamento. Os contêineres não podem ser aninhados em outros contêineres.

O exemplo a seguir ilustra três opções para a criação de contêineres de blob com o cmdlet New-AzStorageContainer. A primeira abordagem cria apenas um contêiner, enquanto as duas abordagens restantes aproveitam as operações do PowerShell para automatizar a criação de contêineres.

Para usar este exemplo, forneça valores para as variáveis e verifique se você criou uma conexão com sua assinatura do Azure. Lembre-se de substituir os valores de espaço reservado entre colchetes pelos seus valores.

# Create variables
 $containerName  = "individual-container"
 $prefixName     = "loop"

# Approach 1: Create a container
 New-AzStorageContainer -Name $containerName -Context $ctx

# Approach 2: Create containers with a PowerShell loop
 for ($i = 1; $i -le 3; $i++) { 
     New-AzStorageContainer -Name (-join($prefixName, $i)) -Context $ctx
    } 

# Approach 3: Create containers using the PowerShell Split method
 "$($prefixName)4 $($prefixName)5 $($prefixName)6".split() | New-AzStorageContainer -Context $ctx

O resultado fornece o nome da conta de armazenamento e confirma a criação do contêiner.

Storage Account Name: demostorageaccount

Name                   PublicAccess   LastModified
----                   ------------   ------------
individual-container   Off            11/2/2021 4:09:05 AM +00:00
loop-container1        Off            11/2/2021 4:09:05 AM +00:00
loop-container2        Off            11/2/2021 4:09:05 AM +00:00
loop-container3        Off            11/2/2021 4:09:05 AM +00:00           
loop-container4        Off            11/2/2021 4:09:05 AM +00:00           
loop-container5        Off            11/2/2021 4:09:05 AM +00:00           
loop-container6        Off            11/2/2021 4:09:05 AM +00:00          

Listar contêineres

Use o cmdlet Get-AzStorageContainer para recuperar contêineres de armazenamento. Para recuperar apenas um único contêiner, inclua o parâmetro -Name. Para retornar uma lista de contêineres que começa com uma determinada cadeia de caracteres, especifique um valor para o parâmetro -Prefix.

O exemplo a seguir recupera um contêiner individual e uma lista de recursos de contêiner.

# Create variables
 $containerName  = "individual-container"
 $prefixName     = "loop-"

# Approach 1: Retrieve an individual container
 Get-AzStorageContainer -Name $containerName -Context $ctx
 Write-Host

# Approach 2: Retrieve a list of containers
 Get-AzStorageContainer -Prefix $prefixName -Context $ctx

O resultado fornece o URI do ponto de extremidade blob e lista os contêineres recuperados por nome e prefixo.

   Storage Account Name: demostorageaccount

Name                 PublicAccess         LastModified                   IsDeleted  VersionId        
----                 ------------         ------------                   ---------  ---------        
individual-container                      11/2/2021 5:52:08 PM +00:00                                

loop-container1                           11/2/2021 12:22:00 AM +00:00                               
loop-container2                           11/2/2021 12:22:00 AM +00:00                               

loop-container1                           11/2/2021 12:22:00 AM +00:00                               
loop-container2                           11/2/2021 12:22:00 AM +00:00
loop-container3                           11/2/2021 12:22:00 AM +00:00   True       01D7E7129FDBD7D4
loop-container4                           11/2/2021 12:22:00 AM +00:00   True       01D7E8A5EF01C787 

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

O exemplo a seguir recupera todos os contêineres com o prefixo demo e itera através deles, listando as respectivas propriedades.

# Create variable
 $prefix = "loop"

# Get containers
 $containers = Get-AzStorageContainer -Prefix $prefix -Context $ctx

# Iterate containers, display properties
 Foreach ($container in $containers) 
 {
    $containerProperties = $container.BlobContainerClient.GetProperties()
    Write-Host $container.Name "properties:"
    $containerProperties.Value
 }

Os resultados exibem todos os contêineres com o prefixo loop e listam as respectivas propriedades.

loop-container1 properties:

LastModified                      : 12/7/2021 7:47:17 PM +00:00
LeaseStatus                       : Unlocked
LeaseState                        : Available
LeaseDuration                     : Infinite
PublicAccess                      : 
HasImmutabilityPolicy             : False
HasLegalHold                      : False
DefaultEncryptionScope            : $account-encryption-key
PreventEncryptionScopeOverride    : False
DeletedOn                         : 
RemainingRetentionDays            : 
ETag                              : 0x8D9B9BA602806DA
Metadata                          : {}
HasImmutableStorageWithVersioning : False

loop-container2 properties:
LastModified                      : 12/7/2021 7:47:18 PM +00:00
LeaseStatus                       : Unlocked
LeaseState                        : Available
LeaseDuration                     : Infinite
PublicAccess                      : 
HasImmutabilityPolicy             : False
HasLegalHold                      : False
DefaultEncryptionScope            : $account-encryption-key
PreventEncryptionScopeOverride    : False
DeletedOn                         : 
RemainingRetentionDays            : 
ETag                              : 0x8D9B9BA605996AE
Metadata                          : {}
HasImmutableStorageWithVersioning : False

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 acessar os metadados, você usará o objeto BlobContainerClient. Este objeto permite que você acesse e manipule contêineres e os respectivos blobs. Para atualizar metadados, você precisará chamar o método SetMetadata(). O método aceita apenas pares de valores-chave armazenados em um objeto IDictionary genérico. Para obter mais informações, confira a classe BlobContainerClient

O exemplo abaixo primeiro atualiza os metadados de um contêiner e depois recupera-os. O exemplo libera o contêiner de exemplo da memória e recupera-o novamente para garantir que os metadados não estejam sendo lidos do objeto na memória.

# Create variable
  $containerName = "individual-container"

# Retrieve container
 $container = Get-AzStorageContainer -Name $containerName -Context $ctx

# Create IDictionary, add key-value metadata pairs to IDictionary
 $metadata = New-Object System.Collections.Generic.Dictionary"[String,String]"
 $metadata.Add("CustomerName","Anthony Bennedetto")
 $metadata.Add("CustomerDOB","08/03/1926")
 $metadata.Add("CustomerBirthplace","Long Island City")

# Update metadata
  $container.BlobContainerClient.SetMetadata($metadata, $null)

# Flush container from memory, retrieve updated container
 $container = $null
 $container = Get-AzStorageContainer -Name $containerName -Context $ctx
 
# Display metadata
 $properties = $container.BlobContainerClient.GetProperties()
 Write-Host $container.Name "metadata:" 
 Write-Host $properties.Value.Metadata

Os resultados exibem os metadados completos para um contêiner.

individual-container metadata:

[CustomerName, Anthony Bennedetto] [CustomerDOB, 08/03/1926] [CustomerBirthplace, Long Island City]

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 tempo para o qual as ações podem ser realizadas.

Uma SAS é comumente usada para fornecer acesso temporário e seguro a um cliente que normalmente não teria permissões. 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 obter mais informações sobre assinaturas de acesso compartilhado, confira o artigo Criar uma SAS de serviço para um contêiner ou blob.

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 cmdlet New-AzStorageContainerSASToken. 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 leitura, gravação e listagem na SAS usando o parâmetro -Permission. Você pode fazer referência à tabela completa de permissões no artigo Criar uma SAS de serviço.

# Create variables
 $accountName   = "<storage-account>"
 $containerName = "individual-container"
 $startTime     = Get-Date
 $expiryTime    = $startTime.AddDays(7)
 $permissions   = "rwl"
 $protocol      = "HttpsOnly"

# Create a context object using Azure AD credentials, retrieve container
 $ctx = New-AzStorageContext -StorageAccountName $accountName -UseConnectedAccount
 
# Approach 1: Generate SAS token for a specific container
 $sas = New-AzStorageContainerSASToken `
 -Context $ctx `
 -Name $containerName `
 -StartTime $startTime `
 -ExpiryTime $expiryTime `
 -Permission $permissions `
 -Protocol $protocol

# Approach 2: Generate SAS tokens for a container list using pipeline
  Get-AzStorageContainer -Container $filterName -Context $ctx | New-AzStorageContainerSASToken `
 -Context $ctx `
 -StartTime $startTime `
 -ExpiryTime $expiryTime `
 -Permission $permissions `
 -Protocol $protocol | Write-Output

Observação

O token SAS retornado pelo Armazenamento de Blobs 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 também acrescentar o caractere delimitador.

Excluir contêineres

Dependendo do caso de uso, você pode excluir um contêiner ou uma lista de contêineres com o cmdlet Remove-AzStorageContainer. Ao excluir uma lista de contêineres, você pode aproveitar operações condicionais, loops ou o pipeline do PowerShell, conforme mostrado nos exemplos abaixo.

# Create variables
 $accountName    = "<storage-account>"
 $containerName  = "individual-container"
 $prefixName     = "loop-"

# Delete a single named container
 Remove-AzStorageContainer -Name $containerName -Context $ctx

# Iterate a loop, deleting containers
 for ($i = 1; $i -le 2; $i++) { 
     Remove-AzStorageContainer -Name (-join($containerPrefix, $i)) -Context $ctx
    } 

# Retrieve container list, delete using a pipeline
 Get-AzStorageContainer -Prefix $prefixName -Context $ctx | Remove-AzStorageContainer

Em alguns casos, é 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 -IncludeDeleted retornará contêineres excluídos no período de retenção associado. O parâmetro -IncludeDeleted só pode ser usado em conjunto com o parâmetro -Prefix ao retornar uma lista de contêineres. 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.

# Retrieve a list of containers including those recently deleted
 Get-AzStorageContainer -Prefix $prefixName -Context $ctx -IncludeDeleted

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.

O exemplo a seguir explica como restaurar um contêiner excluído temporariamente com o cmdlet Restore-AzStorageContainer. 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.

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.

# Create variables
 $accountName = "<storage-account>"
 $prefixName  = "loop-"

# Create a context object using Azure AD credentials
 $ctx = New-AzStorageContext -StorageAccountName $accountName -UseConnectedAccount

# Retrieve all containers, filter deleted containers, restore deleted containers
 Get-AzStorageContainer -Prefix $prefixName -IncludeDeleted `
    -Context $ctx | ? { $_.IsDeleted } | Restore-AzStorageContainer

Os resultados exibem todos os contêineres com o prefixo demo que foram restaurados.

    Storage Account Name: demostorageaccount

Name                 PublicAccess         LastModified                   IsDeleted  VersionId        
----                 ------------         ------------                   ---------  ---------        
loop-container3                                                                                       
loop-container4               

Confira também