Partilhar via


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

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.

Visual Studio dialog for configuring a new C++ Windows console app

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.

Diagram of Blob Storage architecture

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

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.

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.

  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.

    A screenshot showing how to assign a role.

  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.

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.

    A screenshot showing how to find the storage account name.

    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.

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: