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
Uma assinatura do Azure. Consulte Obter a avaliação gratuita do Azure.
O módulo Az do Azure PowerShell é o módulo do PowerShell recomendado para interagir com o Azure. Para começar a usar o módulo do Az PowerShell, confira Instalar o Azure PowerShell.
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