Guia de Início Rápido: biblioteca de clientes do Armazenamento de Blobs do Azure para C++

Introdução à biblioteca de clientes do Armazenamento de Blobs do Azure para C++. O Armazenamento de Blobs do Azure é uma solução de armazenamento de objetos da Microsoft para a nuvem. Siga estas etapas para instalar o pacote e experimentar o código de exemplo para tarefas básicas.

| Documentação de referência da API | Código-fonte da biblioteca | Amostras |

Pré-requisitos

• Assinatura do Azure - criar uma gratuitamente
• Conta de armazenamento do Azure – criar uma conta de armazenamento
• Compilador C++
• CMake
• Gerenciador de pacotes vcpkg - C e C++

Configurando

Esta seção orienta você na preparação de um projeto para trabalhar com a biblioteca de clientes do Armazenamento de Blobs do Azure para C++. A maneira mais fácil de adquirir o SDK do Azure para C++ é usar o gerenciador de pacotes vcpkg.

Instalar os pacotes

Use o comando vcpkg install para instalar a biblioteca de Armazenamento de Blobs do Azure para C++ e as dependências necessárias:

vcpkg.exe install azure-storage-blobs-cpp

A biblioteca de Identidade do Azure é necessária para conexões sem senha com os serviços do Azure:

vcpkg.exe install azure-identity-cpp

Para obter mais informações sobre a configuração do projeto e como trabalhar com o SDK do Azure para C++, consulte o Readme do SDK do Azure para C++.

Criar o projeto

No Visual Studio, crie um novo aplicativo de console C++ para o Windows chamado BlobQuickstart.

Modelo de objeto

O Armazenamento de Blobs do Azure é otimizado para armazenar grandes quantidades de dados não estruturados. Dados não estruturados são dados que não estão de acordo com uma definição ou um modelo de dados específico, como texto ou dados binários. O Armazenamento de Blobs oferece três tipos de recursos:

• A conta de armazenamento
• Um contêiner na conta de armazenamento
• Um blob no contêiner

O diagrama a seguir mostra a relação entre esses recursos.

Use estas classes C++ para interagir com esses recursos:

• BlobServiceClient: a classe BlobServiceClient permite manipular os recursos do Armazenamento do Azure e os contêineres do blob.
• BlobContainerClient: a classe BlobContainerClient permite manipular os contêineres do Armazenamento do Azure e seus blobs.
• BlobClient: a classe BlobClient permite manipular os blobs do Armazenamento do Azure. É a classe base para todas as classes de blob especializadas.
• BlockBlobClient: A classe BlockBlobClient permite manipular os blobs de blocos de Armazenamento do Azure.

Exemplos de código

Esses snippets de código de exemplo mostram como fazer as seguintes tarefas com a biblioteca de clientes do Armazenamento de Blobs do Azure para C++:

• Adicionar arquivos de inclusão
• Autenticar-se no Azure e autorizar o acesso a dados de blob
• Criar um contêiner
• Carregar blobs em um contêiner
• Listar os blobs em um contêiner
• Baixar blobs
• Excluir um contêiner

Adicionar arquivos de inclusão

No diretório do projeto:

1. Abra o arquivo da solução BlobQuickstart.sln no Visual Studio
2. Dentro do Visual Studio, abra o arquivo de origem do BlobQuickstart.cpp
3. Remova qualquer código dentro de main que foi gerado automaticamente
4. Adicione as instruções #include e using namespace

#include <iostream>
#include <azure/core.hpp>
#include <azure/identity/default_azure_credential.hpp>
#include <azure/storage/blobs.hpp>

using namespace Azure::Identity;
using namespace Azure::Storage::Blobs;

Autenticar-se no Azure e autorizar o acesso a dados de blob

As solicitações de aplicativo para o Armazenamento de Blobs do Azure devem ser autorizadas. O uso da classe DefaultAzureCredential fornecida pela biblioteca de clientes de identidade do Azure é a abordagem recomendada para implementar conexões sem senha com os serviços do Azure no código, incluindo o Armazenamento de Blobs.

Você também pode autorizar solicitações para o Armazenamento de Blobs do Azure usando a chave de acesso da conta. No entanto, essa abordagem deve ser usada com cautela. Os desenvolvedores devem ser diligentes para nunca expor as chaves de acesso em um local não seguro. Qualquer pessoa que tenha a chave de acesso pode autorizar solicitações na conta de armazenamento e efetivamente tem acesso a todos os dados. DefaultAzureCredential oferece benefícios aprimorados de gerenciamento e segurança sobre a chave de conta para permitir a autenticação sem senha. Ambas as opções são demonstradas no exemplo a seguir.

Sem senha (recomendado)

A biblioteca de Identidade do Azure dá suporte à autenticação de token do Microsoft Entra no SDK do Azure. Ela fornece um conjunto de implementações de TokenCredential que podem ser usadas para construir clientes do SDK do Azure que dão suporte à autenticação de token do Microsoft Entra. DefaultAzureCredential dá suporte a vários métodos de autenticação e determina quais métodos devem ser usados no runtime.

Atribuir funções à sua conta de usuário do Microsoft Entra

Ao desenvolver localmente, verifique se a conta de usuário que está acessando os dados de blob tem as permissões corretas. Você precisará do Colaborador de Dados do Blob de Armazenamento para ler e gravar os dados de blob. Para atribuir essa função a si mesmo, você precisará receber a atribuição da função Administrador de Acesso do Usuário ou de outra função que inclua a ação Microsoft.Authorization/roleAssignments/write. É possível atribuir funções RBAC do Azure a um usuário usando o portal do Azure, a CLI do Azure ou o Azure PowerShell. Você pode saber mais sobre os escopos disponíveis para atribuições de função na página de visão geral do escopo.

Nesse cenário, você atribuirá permissões à sua conta de usuário, no escopo da conta de armazenamento, para seguir o Princípio do Privilégio Mínimo. Essa prática fornece aos usuários apenas as permissões mínimas necessárias e cria ambientes de produção mais seguros.

O exemplo a seguir atribuirá a função de Colaborador de Dados do Blob de Armazenamento à sua conta de usuário, que fornece acesso de leitura e gravação aos dados de blob na sua conta de armazenamento.

Importante

Na maioria dos casos, levará um ou dois minutos para a atribuição de função se propagar no Azure, mas em casos raros pode levar até oito minutos. Se você receber erros de autenticação ao executar o código pela primeira vez, aguarde alguns instantes e tente novamente.

Azure portal

1. No portal do Azure, localize sua conta de armazenamento usando a barra de pesquisa principal ou a navegação à esquerda.

2. Na página de visão geral da conta de armazenamento, selecione Controle de acesso (IAM) no menu à esquerda.

3. Na página Controle de acesso (IAM), selecione a guia Atribuições de função.

4. Selecione + Adicionar no menu superior e, em seguida, Adicionar atribuição de função no menu suspenso resultante.

   

5. Use a caixa de pesquisa para filtrar os resultados para a função desejada. Para este exemplo, pesquise o Colaborador de Dados do Blob de Armazenamento e selecione o resultado correspondente e, em seguida, escolha Avançar.

6. Em Atribuir acesso a, selecione Usuário, grupo ou entidade de serviço e, em seguida, selecione + Selecionar membros.

7. No diálogo, pesquise seu nome de usuário do Microsoft Entra (geralmente seu endereço de email user@domain) e escolha Selecionar na parte inferior do diálogo.

8. Selecione Revisar + atribuir para ir para a página final e, em seguida, Revisar + atribuir novamente para concluir o processo.

CLI do Azure

Para atribuir uma função no nível do recurso usando a CLI do Azure, primeiro você deve recuperar a ID do recurso usando o comando az storage account show. É possível filtrar as propriedades de saída usando o parâmetro --query.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

Copie a saída Id do comando anterior. Em seguida, você pode atribuir funções usando o comando az role da CLI do Azure.

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

PowerShell

Para atribuir uma função no nível do recurso usando o Azure PowerShell, primeiro você precisa recuperar a ID do recurso usando o comando Get-AzResource.

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

Copie o valor Id da saída do comando anterior. Em seguida, é possível atribuir funções usando o comando New-AzRoleAssignment no PowerShell.

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

Entrar e conectar o código do aplicativo ao Azure usando DefaultAzureCredential

É possível autorizar o acesso aos dados pela conta de armazenamento usando as seguintes etapas:

1. Verifique se você está autenticado com a mesma conta do Microsoft Entra à qual a função foi atribuída na sua conta de armazenamento. Você pode autenticar por meio da CLI do Azure. Entre no Azure por meio da CLI do Azure usando o seguinte comando:

   az login
   

2. Para usar DefaultAzureCredential, verifique se o pacote azure-identity-cpp está instalado e se o seguinte #include está adicionado:

   #include <azure/identity/default_azure_credential.hpp>
   

3. Adicione este código ao final de main(). Quando o código for executado em sua estação de trabalho local, DefaultAzureCredential usará as credenciais de desenvolvedor da CLI do Azure para autenticar no Azure.

   // Initialize an instance of DefaultAzureCredential
    auto defaultAzureCredential = std::make_shared<DefaultAzureCredential>();
   
    auto accountURL = "https://<storage-account-name>.blob.core.windows.net";
    BlobServiceClient blobServiceClient(accountURL, defaultAzureCredential);
   

4. Atualize o nome da conta de armazenamento no URI do objeto BlobServiceClient. O nome da conta de armazenamento pode ser encontrado na página de visão geral do portal do Azure.

   

   Observação

   Ao usar o SDK do C++ em um ambiente de produção, é recomendável habilitar apenas as credenciais que você sabe que seu aplicativo usará. Em vez de usar DefaultAzureCredential, você deve autorizar o uso de um tipo de credencial específico ou usar ChainedTokenCredential com as credenciais com suporte.

Cadeia de Conexão

Uma cadeia de conexão inclui a chave de acesso da conta de armazenamento e a utiliza para autorizar solicitações. Sempre tenha cuidado para nunca expor as chaves em um local não seguro.

Observação

Para autorizar o acesso a dados com a chave de acesso da conta de armazenamento, você precisará de permissões para a seguinte ação do RBAC do Azure: Microsoft.Storage/storageAccounts/listkeys/action. A função interna de privilégio mínimo com permissões para essa ação é a função de Leitor e Acesso a Dados, mas qualquer função que inclua essa ação funcionará.

Azure portal

1. Entre no portal do Azure.

2. Localize sua cadeia de conexão.

3. No painel do menu da conta de armazenamento, em Segurança + rede, selecione Chaves de acesso. Aqui, você pode ver as chaves de acesso da conta, bem como a cadeia de conexão completa para cada chave.

4. No painel Chaves de acesso, selecione Mostrar chaves.

5. Na seção key1, localize o valor Cadeia de conexão. Selecione o ícone Copiar para a área de transferência para copiar a cadeia de conexão. Você adicionará o valor da cadeia de conexão a uma variável de ambiente na próxima seção.

   

CLI do Azure

É possível ver a cadeia de conexão da conta de armazenamento usando o comando az storage account show-connection-string.

az storage account show-connection-string --name "<your-storage-account-name>"

PowerShell

Você pode montar uma cadeia de conexão com o PowerShell usando os comandos Get-AzStorageAccount e Get-AzStorageAccountKey.

$saName = "yourStorageAccountName"
$rgName = "yourResourceGroupName"
$sa = Get-AzStorageAccount -StorageAccountName $saName -ResourceGroupName $rgName

$saKey = (Get-AzStorageAccountKey -ResourceGroupName $rgName -Name $saName)[0].Value

'DefaultEndpointsProtocol=https;AccountName=' + $saName + ';AccountKey=' + $saKey + ';EndpointSuffix=core.windows.net'

Configurar a cadeia de conexão de armazenamento

Depois de copiar a cadeia de conexão, grave em uma nova variável de ambiente no computador local que executa o aplicativo. Para definir a variável de ambiente, abra uma janela de console e siga as instruções do seu sistema operacional. Substitua <yourconnectionstring> pela cadeia de conexão real.

Windows:

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Após adicionar a variável de ambiente no Windows, é necessário iniciar uma nova instância da janela de comando.

Linux:

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

O exemplo de código a seguir recupera a cadeia de conexão da conta de armazenamento da variável de ambiente criada anteriormente e usa a cadeia de conexão para construir um objeto de cliente de serviço.

Adicione este código ao final de main():

    // Retrieve the connection string for use with the application. The storage
    // connection string is stored in an environment variable on the machine
    // running the application called AZURE_STORAGE_CONNECTION_STRING.
    // Note that _MSC_VER is set when using MSVC compiler.
    static const char* AZURE_STORAGE_CONNECTION_STRING = "AZURE_STORAGE_CONNECTION_STRING";

#if !defined(_MSC_VER)
    const char* connectionString = std::getenv(AZURE_STORAGE_CONNECTION_STRING);
#else
	// Use getenv_s for MSVC
	size_t requiredSize;
	getenv_s(&requiredSize, NULL, NULL, AZURE_STORAGE_CONNECTION_STRING);
	if (requiredSize == 0) {
		throw std::runtime_error("missing connection string from env.");
	}
	std::vector<char> value(requiredSize);
	getenv_s(&requiredSize, value.data(), value.size(), AZURE_STORAGE_CONNECTION_STRING);
	std::string connectionStringStr = std::string(value.begin(), value.end());
	const char* connectionString = connectionStringStr.c_str();
#endif

	auto blobServiceClient = BlobServiceClient::CreateFromConnectionString(connectionString);

Importante

A chave de acesso da conta deve ser usada com cautela. Se a chave de acesso da conta for perdida ou colocada acidentalmente em um local inseguro, o serviço poderá ficar vulnerável. Qualquer pessoa que tenha a chave de acesso pode autorizar solicitações na conta de armazenamento e efetivamente tem acesso a todos os dados. DefaultAzureCredential fornece recursos e benefícios de segurança avançados e é a abordagem recomendada para gerenciar a autorização para os serviços do Azure.

Criar um contêiner

Escolha um nome para o novo contêiner. Em seguida, crie uma instância de BlobContainerClient e crie o contêiner.

Importante

Os nomes de contêiner devem estar em minúsculas. Para saber mais sobre como nomear contêineres e blobs, veja Nomenclatura e referência de contêineres, blobs e metadados.

Adicione este código ao final de main():

std::string containerName = "myblobcontainer";
auto containerClient = blobServiceClient.GetBlobContainerClient("myblobcontainer");

// Create the container if it does not exist
std::cout << "Creating container: " << containerName << std::endl;
containerClient.CreateIfNotExists();

Carregar blobs em um contêiner

O trecho de código a seguir:

1. Declara uma cadeia de caracteres contendo "Olá, Azure!"
2. Obtém uma referência para um objeto BlockBlobClient chamando o método GetBlockBlobClient no contêiner da seção Criar um contêiner.
3. Carrega a cadeia de caracteres para o blob chamando a função UploadFrom. Essa operação criará o blob se ele ainda não existir e o substituirá, se já existir.

Adicione este código ao final de main():

std::string blobName = "blob.txt";
uint8_t blobContent[] = "Hello Azure!";
// Create the block blob client
BlockBlobClient blobClient = containerClient.GetBlockBlobClient(blobName);

// Upload the blob
std::cout << "Uploading blob: " << blobName << std::endl;
blobClient.UploadFrom(blobContent, sizeof(blobContent));

Listar os blobs em um contêiner

Liste os blobs no contêiner chamando a função ListBlobs. Apenas um blob foi adicionado ao contêiner, portanto, a operação retorna apenas esse blob.

Adicione este código ao final de main():

std::cout << "Listing blobs..." << std::endl;
auto listBlobsResponse = containerClient.ListBlobs();
for (auto blobItem : listBlobsResponse.Blobs)
{
    std::cout << "Blob name: " << blobItem.Name << std::endl;
}

Baixar blobs

Obtenha as propriedades do blob carregado. Em seguida, declare e redimensione um novo objeto std::vector<uint8_t> usando as propriedades do blob carregado. Baixe o blob criado anteriormente no novo objeto std::vector<uint8_t> chamando a função Downloadto na classe base BlobClient. Por fim, exiba os dados de blob baixados.

Adicione este código ao final de main():

auto properties = blobClient.GetProperties().Value;
std::vector<uint8_t> downloadedBlob(properties.BlobSize);

blobClient.DownloadTo(downloadedBlob.data(), downloadedBlob.size());
std::cout << "Downloaded blob contents: " << std::string(downloadedBlob.begin(), downloadedBlob.end()) << std::endl;

Excluir um blob

O código a seguir exclui o blob do contêiner de Armazenamento de Blobs do Azure chamando a função BlobClient.Delete.

std::cout << "Deleting blob: " << blobName << std::endl;
blobClient.Delete();

Excluir um contêiner

O código a seguir limpa os recursos que o aplicativo criou ao excluir todo o contêiner usando BlobContainerClient.Delete.

Adicione este código ao final de main():

std::cout << "Deleting container: " << containerName << std::endl;
containerClient.Delete();

Executar o código

Esse aplicativo cria um contêiner e carrega um arquivo de texto para o armazenamento de Blob do Azure. Em seguida, lista os blobs no contêiner, baixa o arquivo e exibe o conteúdo do arquivo. Por fim, o aplicativo exclui o blob e o contêiner.

A saída do aplicativo é semelhante ao seguinte exemplo:

Azure Blob Storage - C++ quickstart sample
Creating container: myblobcontainer
Uploading blob: blob.txt
Listing blobs...
Blob name: blob.txt
Downloaded blob contents: Hello Azure!
Deleting blob: blob.txt
Deleting container: myblobcontainer

Próximas etapas

Neste início rápido você aprendeu a carregar, baixar e listar blobs usando C++. Você também aprendeu a criar e excluir um contêiner de Armazenamento de Blob do Azure.

Para ver o exemplo de armazenamento de blob C++, prossiga para:

Biblioteca de clientes do Armazenamento de Blobs do Azure para amostras do C++