Guia de início rápido: biblioteca de cliente do Armazenamento de Blobs do Azure para 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 Exemplos de código-fonte | da biblioteca |

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++

Configuraçã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. Os dados não estruturados são dados que não seguem uma definição ou um modelo de dados particular, como texto ou dados binários. O Armazenamento de Blob 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 no Azure e autorizar o acesso a dados de blob
• 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 #include e using namespace instruções

#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 a dados de blob

As solicitações de aplicativo para o Armazenamento de Blobs do Azure devem ser autorizadas. Usar a classe fornecida pela biblioteca de cliente do Azure Identity é a DefaultAzureCredential abordagem recomendada para implementar conexões sem senha para 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 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 implementações que podem ser usadas para construir clientes do SDK do Azure que oferecem suporte à autenticação de TokenCredential token 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 tenha as permissões corretas. Você precisará do Storage Blob Data Contributor para ler e gravar dados de blob. Para atribuir essa função a si mesmo, você precisará receber a função de Administrador de Acesso de Usuário 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. 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, com escopo para a 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 Colaborador de Dados de Blob de Armazenamento à sua conta de usuário, que fornece acesso de leitura e gravação aos dados de blob em sua conta de armazenamento.

Importante

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 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, 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.

CLI do Azure

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 Id valor 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 DefaultAzureCredentialo , 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.

   

   Nota

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

Cadeia de Ligaçã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.

Nota

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 do 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 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

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);

Importante

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 contentor

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

Importante

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();

Carregar blobs para um contêiner

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 num contentor

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 exclui o blob do contêiner Armazenamento de Blob do Azure chamando a função BlobClient.Delete .

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

Eliminar um contentor

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();

Executar 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 Armazenamento de Blob C++, continue para:

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