Introdução Rápida: Biblioteca Cliente para Armazenamento de Blobs do Azure em C++

Introdução à biblioteca de 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 de referência da API | Código fonte da biblioteca | Amostras |

Pré-requisitos

• Subscrição do Azure - crie uma gratuitamente
• Conta de armazenamento do Azure - criar uma conta de armazenamento
• Compilador C++
• CMake
• vcpkg - Gerenciador de pacotes C e C++

Preparação

Esta seção orienta você na preparação de um projeto para trabalhar com a biblioteca de cliente 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 vcpkg pacotes.

Instalar os pacotes

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

vcpkg.exe install azure-storage-blobs-cpp

A biblioteca de Identidades 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 o trabalho com o SDK do Azure para C++, consulte o Leiame 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 determinado modelo ou definição de dados, 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
• Uma bolha no recipiente

O diagrama seguinte mostra a relação entre estes recursos.

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

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

Exemplos de código

Estes trechos de código de exemplo mostram como executar as seguintes tarefas com a biblioteca de cliente do Armazenamento de Blobs do Azure para C++:

• Adicionar arquivos de inclusão
• Autenticar-se no Azure e autorizar o acesso aos dados de blobs
• Criar um contêiner
• Carregar blobs para um contêiner
• Listar os blobs em um contêiner
• Baixar blobs
• Eliminar um contentor

Adicionar arquivos de inclusão

No diretório do projeto:

1. Abra o arquivo de solução BlobQuickstart.sln no Visual Studio
2. Dentro do Visual Studio, abra o arquivo de origem BlobQuickstart.cpp
3. Remova qualquer código dentro main que tenha sido gerado automaticamente
4. Adicionar as expressõ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 no Azure e autorizar o acesso aos dados BLOB

As solicitações de aplicativo para o Armazenamento de Blobs do Azure devem ser autorizadas. Usar a DefaultAzureCredential classe fornecida pela biblioteca de cliente do Azure Identity é a abordagem recomendada para implementar conexões sem senha aos serviços do Azure em seu código, incluindo o Armazenamento de Blob.

Você também pode autorizar solicitações para o Armazenamento de Blobs do Azure usando a chave de acesso da conta. No entanto, esta abordagem deve ser utilizada com precaução. 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 é capaz de autorizar solicitações contra a 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 autenticação sem senha. Ambas as opções são demonstradas no exemplo a seguir.

Sem Palavra-passe (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 implementações que podem ser usadas para construir clientes do SDK do Azure que oferecem suporte à autenticação de token do Microsoft Entra. DefaultAzureCredential suporta vários métodos de autenticação e determina qual método deve ser usado em tempo de execução.

Atribuir funções à sua conta de utilizador do Microsoft Entra

Ao desenvolver localmente, certifique-se de que a conta de usuário que está acessando dados de blob tem as permissões corretas. Você precisará do Storage Blob Data Contributor para ler e gravar dados de blobs. Para atribuir esta função a si próprio, terá de receber a função de Administrador de Acesso do Utilizador ou outra função que inclua a ação Microsoft.Authorization/roleAssignments/write. Você pode atribuir funções do 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 de Colaborador de Dados de Blob de Armazenamento , consulte Colaborador de Dados de Blob de Armazenamento. Para obter mais informações sobre os escopos disponíveis para atribuições de função, consulte Entender o escopo do Azure RBAC.

Neste cenário, atribuirás permissões à tua conta de utilizador, limitado à conta de armazenamento, para seguir o Princípio do Menor Privilégio. Essa prática oferece 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 Storage Blob Data Contributor à sua conta de utilizador, que fornece acesso de leitura e gravação aos dados de blob na sua conta de armazenamento.

Important

Na maioria dos casos, levará um ou dois minutos para que a atribuição de função se propague no Azure, mas, em casos raros, pode levar até oito minutos. Se você receber erros de autenticação quando executar o código pela primeira vez, aguarde alguns momentos 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 Controlo de acesso (IAM), selecione o separador Atribuição de funções.

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, procure por Storage Blob Data Contributor e selecione o resultado correspondente e, em seguida, escolha Next.

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

7. Na caixa de diálogo, procure seu nome de usuário do Microsoft Entra (geralmente seu endereço de e-mail user@domain ) e escolha Selecionar na parte inferior da caixa de diálogo.

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

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. Você pode filtrar as propriedades de saída usando o --query parâmetro.

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 de recurso usando o Azure PowerShell, primeiro você deve recuperar a ID do recurso usando o Get-AzResource comando.

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

Copie o valor Id da saída do comando anterior. Em seguida, você pode 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 seu aplicativo ao Azure usando DefaultAzureCredential

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

1. Certifique-se de que está autenticado com a mesma conta Microsoft Entra à qual atribuiu a função 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 foi adicionado:

   #include <azure/identity/default_azure_credential.hpp>
   

3. Adicione este código ao final do main(). Quando o código é executado em sua estação de trabalho local, DefaultAzureCredential usa as credenciais do desenvolvedor para a 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. Certifique-se de atualizar o nome da conta de armazenamento no URI do seu BlobServiceClient objeto. 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, deve autorizar usando um tipo de credencial específico ou usando 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 usa para autorizar solicitações. Tenha sempre cuidado para nunca expor as chaves num local inseguro.

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 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. Inicie sessão no portal Azure.

2. Localize a sua conta de armazenamento.

3. No painel de menu da conta de armazenamento, em Segurança + rede, selecione Chaves de acesso. Aqui, você pode visualizar 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 string de conexão. Você adicionará o valor da cadeia de conexão a uma variável de ambiente na próxima seção.

   

Você pode ver a cadeia 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 ligação de armazenamento

Depois de copiar a cadeia de conexão, escreva-a em uma nova variável de ambiente na máquina local que executa o aplicativo. Para definir a variável de ambiente, abra uma janela da consola e siga as instruções relevantes para o seu sistema operativo. 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 para a 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);

Important

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

Criar um contêiner

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

Important

Os nomes dos contentores têm de estar em minúscula. Para obter mais informações sobre a atribuição de nomes de contentores e blobs, veja Nomenclatura e Referenciação de Contentores, 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();

Fazer upload de blobs para um contentor

O seguinte trecho de código:

1. Declara uma cadeia de caracteres contendo "Hello 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 para o blob chamando a função UploadFrom . Esta função cria o blob, se ainda não existir, ou atualiza-o, se 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;
}

Transferir 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 . Finalmente, 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 elimina o blob do contentor do Azure Blob Storage 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.Suprimir.

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

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

Execute o código

Este aplicativo cria um contêiner e carrega um arquivo de texto no Armazenamento de Blobs do Azure. O exemplo lista os blobs no contêiner, baixa o arquivo e exibe o conteúdo do arquivo. Finalmente, 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óximos passos

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

Para ver um exemplo de Blob Storage em C++, continue para a seguinte ligação:

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