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

Comece com a biblioteca cliente do Armazenamento de Blobs do Azure para C++. O Armazenamento de Blobs do Azure é a 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 | 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
• vcpkg – Gerenciador de pacotes 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 vcpkg gerenciador de pacotes.

Instalar os pacotes

Use o vcpkg install comando para instalar a biblioteca do 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 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 aderem a um modelo ou definição 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 estes recursos:

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

Exemplos de código

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

• Adicionar arquivos de inclusão
• Autenticar no Azure e autorizar o acesso aos dados em 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. Abrir o arquivo de solução BlobQuickstart.sln no Visual Studio
2. No Visual Studio, abra o arquivo de origem do BlobQuickstart.cpp
3. Remover qualquer código dentro main que tenha sido gerado automaticamente
4. Adicionar 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. Usar a DefaultAzureCredential classe fornecida pela biblioteca de clientes da Identidade do Azure é a abordagem recomendada para implementar conexões sem senha com os serviços do Azure em seu código, incluindo o Armazenamento de Blobs.

Você também pode autorizar solicitações ao Armazenamento de Blobs do Azure usando a chave de acesso da conta. No entanto, essa abordagem deve ser usada com cuidado. Os desenvolvedores devem ser diligentes para nunca expor a chave 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 da conta para permitir a autenticação sem senha. Ambas as opções são demonstradas no exemplo a seguir.

Login sem senha (Recomendado)

A biblioteca de Identidade do Azure fornece suporte à autenticação de token do Microsoft Entra no SDK do Azure. Ele fornece um conjunto de TokenCredential implementações 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 qual método deve ser usado em 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 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. Para obter mais informações sobre a função Colaborador de Dados do Blob de Armazenamento, consulte Colaborador de Dados do Blob de Armazenamento. Para obter mais informações sobre os escopos disponíveis para atribuições de função, consulte Noções básicas sobre o escopo do RBAC do Azure.

Nesse cenário, você atribuirá permissões à sua conta de usuário, com escopo para a 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.

Portal do Azure

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 usuário@domínio) 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.

Azure CLI

Para atribuir uma função no nível de recurso usando a CLI do Azure, primeiro você deve recuperar a ID do recurso usando o az storage account show comando. É 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ê deve 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>

Entre e conecte o código do aplicativo ao Azure usando DefaultAzureCredential

Você pode autorizar o acesso aos dados em sua conta de armazenamento usando as seguintes etapas:

1. Verifique se você está autenticado com a mesma conta do Microsoft Entra à qual atribuiu a função em 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 é adicionado:

   #include <azure/identity/default_azure_credential.hpp>
   

3. Adicione este código ao final de main(). Quando o código é executado em sua estação de trabalho local, DefaultAzureCredential usa 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 um tipo específico de credenciais ou usar ChainedTokenCredential com as credenciais suportadas.

String 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 rbac do Azure: Microsoft.Storage/storageAccounts/listkeys/action. A função interna menos privilegiada com permissões para essa ação é Leitor e Acesso a Dados, mas qualquer função que inclua essa ação funcionará.

Portal do Azure

1. Entre no portal do Azure.

2. Localize sua conta de armazenamento.

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

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

5. Na seção key1 , localize o valor da 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.

   

Azure CLI

Você pode ver a string de conexão para sua 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, escreva-a em uma nova variável de ambiente no computador local que executa o aplicativo. Para definir a variável de ambiente, abra uma janela do console e siga as instruções do sistema operacional. Substitua <yourconnectionstring> pela cadeia de conexão real.

Windows:

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Depois de adicionar a variável de ambiente no Windows, você deve 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 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

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

Importante

Os nomes de contêiner devem ser minúsculos. Para obter mais informações sobre como nomear contêineres e blobs, consulte 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 para um contêiner

O seguinte snippet de código:

1. Declara uma cadeia de caracteres que contém "Olá, Azure!"
2. Obtém uma referência a um objeto BlockBlobClient chamando GetBlockBlobClient no contêiner da seção Criar um contêiner .
3. Carrega a cadeia de caracteres no blob chamando a função UploadFrom . Essa função criará o blob se ele ainda não existir ou o atualizará se ele 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 std::vector<uint8_t> objeto usando as propriedades do blob carregado. Baixe o blob criado anteriormente no novo std::vector<uint8_t> objeto 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 do 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 excluindo todo o contêiner usando BlobContainerClient.Excluir.

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 no Armazenamento de Blobs do Azure. Em seguida, o exemplo 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 exemplo a seguir:

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

Para ver um exemplo de Armazenamento de Blobs do C++, continue a:

Biblioteca cliente do Armazenamento de Blobs do Azure para C++ - exemplos