Instalar e integrar bibliotecas do SDK do Azure para C++

Este guia fornece aos desenvolvedores as etapas necessárias para instalar bibliotecas do SDK do Azure para C++ usando vcpkg e integrá-las a seus projetos com o CMake. Seguindo as instruções, você pode configurar seu ambiente de desenvolvimento e começar a usar os serviços do Azure em seus aplicativos C++. Se você é novo no Azure ou deseja simplificar seu processo de integração, essa documentação ajuda você a começar de forma rápida e eficiente.

Pré-requisitos

Qualquer Editor de Texto
Um terminal
Um compilador C++
Git
CMake
Uma assinatura do Azure
Azure CLI

Verificar a instalação do Git e do CMake

Para garantir um processo de integração suave, é importante verificar se o Git e o CMake estão instalados corretamente em seu sistema.

Windows – PowerShell
MacOS/Linux – Bash

Para verificar se o Git está instalado corretamente, execute o seguinte comando em seu terminal:
```
git --version
```
Você deve obter uma saída denotando a versão instalada no momento para o Git, desta forma:
```
git version <version>
```
Para verificar se o CMake está instalado corretamente, execute o seguinte comando em seu terminal:
```
cmake --version
```
Você deve obter uma saída indicando a versão instalada no momento do CMake, desta forma:
```
cmake version <version>
```

Para verificar se o Git está instalado corretamente, execute o seguinte comando em seu terminal:
```
git --version
```
Você deve obter uma saída denotando a versão instalada no momento para o Git, desta forma:
```
git version <version>
```
Para verificar se o CMake está instalado corretamente, execute o seguinte comando em seu terminal:
```
cmake --version
```
Você deve obter uma saída indicando a versão instalada no momento do CMake, desta forma:
```
cmake version <version>
```

Instalar vcpkg

Para gerenciar e instalar o SDK do Azure para bibliotecas C++, use vcpkg. vcpkg é um gerenciador de pacotes multiplataforma que simplifica o processo de tratamento de dependências.

Windows – PowerShell
MacOS/Linux – Bash

Para instalar o vcpkg, primeiro clone o repositório vcpkg. A abordagem recomendada é clonar vcpkg para um local central em seu ambiente de desenvolvimento e não no diretório do projeto C++. Neste exemplo, vcpkg é clonado para o dir doméstico.
```
cd ~
git clone https://github.com/microsoft/vcpkg.git
```
Depois que o repositório vcpkg for clonado, percorra o novo diretório e execute o bootstrap-vcpkg.bat script.
```
cd .\vcpkg\
.\bootstrap-vcpkg.bat
```
Depois de inicializar vcpkg, adicione-o ao seu caminho para que você possa acessar o executável vcpkg do diretório do projeto. Lembre-se de substituir o <path\to\vcpkg> no exemplo de comando pelo caminho para o diretório vcpkg que você clonou anteriormente.
```
$env:Path = "$env:Path;<path\to\vcpkg>"
```
Para verificar se o diretório vcpkg foi adicionado ao seu caminho, volte para o diretório do projeto e execute o seguinte comando:
```
vcpkg --version
```

Você deverá obter o seguinte resultado:

vcpkg package management program version <version>

Para instalar o vcpkg, primeiro clone o repositório vcpkg. A abordagem recomendada é clonar vcpkg para um local central em seu ambiente de desenvolvimento e não no diretório do projeto C++. Neste exemplo, vcpkg é clonado para o dir doméstico.
```
cd ~
git clone https://github.com/microsoft/vcpkg.git
```
Depois que o repositório vcpkg for clonado, percorra o novo diretório e execute o bootstrap-vcpkg.sh script.
```
cd vcpkg
./bootstrap-vcpkg.sh
```
Depois de inicializar vcpkg, adicione-o ao seu caminho para que você possa acessar o executável vcpkg do diretório do projeto. Lembre-se de substituir o <path\to\vcpkg> no exemplo de comando pelo caminho para o diretório vcpkg que você clonou anteriormente.
```
export PATH=$PATH:/path/to/vcpkg
```
Para verificar se o diretório vcpkg foi adicionado ao seu caminho, volte para o diretório do projeto e execute o seguinte comando:
```
vcpkg --version
```

Você deverá obter o seguinte resultado:

vcpkg package management program version <version>

Instalar as bibliotecas

Esta seção orienta você pelo processo de instalação das bibliotecas necessárias do SDK do Azure para C++ usando vcpkg. Esta seção mostra como usar vcpkg no modo de manifesto, o que cria alguns arquivos de projeto vcpkg para ajudar a gerenciar as dependências do projeto mesmo quando compartilhado com outros colaboradores.

Windows – PowerShell
MacOS/Linux – Bash

No diretório raiz do seu projeto, execute o seguinte comando para iniciar um novo projeto vcpkg no modo de manifesto:
```
vcpkg new --application
```
Agora deve haver um arquivo vcpkg.json e um arquivo vcpkg-configuration.json no diretório do projeto.
Agora podemos adicionar as bibliotecas Azure Key Vault e Identity do SDK do Azure para C++ ao nosso projeto executando o seguinte comando:
```
vcpkg add port azure-identity-cpp azure-security-keyvault-secrets-cpp
```

O arquivo vcpkg.json agora deve ter o seguinte conteúdo:

{
  "dependencies": [
    "azure-identity-cpp",
    "azure-security-keyvault-secrets-cpp"
  ]
}

No diretório raiz do seu projeto, execute o seguinte comando para iniciar um novo projeto vcpkg no modo de manifesto:
```
vcpkg new --application
```
Agora deve haver um arquivo vcpkg.json e um arquivo vcpkg-configuration.json no diretório do projeto.
Agora podemos adicionar as bibliotecas Azure Key Vault e Identity do SDK do Azure para C++ ao nosso projeto executando o seguinte comando:
```
vcpkg add port azure-identity-cpp azure-security-keyvault-secrets-cpp
```

O arquivo vcpkg.json agora deve ter o seguinte conteúdo:

{
  "dependencies": [
    "azure-identity-cpp",
    "azure-security-keyvault-secrets-cpp"
  ]
}

Criamos um recurso do Azure Key Vault

Esta seção discute como usar a CLI do Azure para criar um recurso do Azure Key Vault. Esse recurso do Key Vault armazena e gerencia informações confidenciais com segurança, como segredos e chaves.

Windows – PowerShell
MacOS/Linux – Bash

Use a CLI do Azure para fazer logon inserindo o seguinte comando em seu terminal:
```
az login
```
Use as janelas pop-up para fazer logon no Azure.
Depois de usar a janela pop-up do navegador para fazer logon, selecione a assinatura do Azure que você deseja usar no terminal.
Em seguida, use o seguinte comando para criar seu recurso do Key Vault e lembre-se de substituir <your-resource-group-name> e <your-key-vault-name> por seus próprios nomes exclusivos:
```
az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>
```
Na saída, você deverá ver uma lista com uma propriedade vaultUri. Defina isso como uma variável de ambiente a ser usada em nosso programa com o seguinte comando:
```
$env:AZURE_KEYVAULT_URL = "https://<your-key-vault-name>.vault.azure.net/"
```

Use a CLI do Azure para fazer logon inserindo o seguinte comando em seu terminal:
```
az login
```
Use as janelas pop-up para fazer logon no Azure.
Depois de usar a janela pop-up do navegador para fazer logon, selecione a assinatura do Azure que você deseja usar no terminal.
Em seguida, use o seguinte comando para criar seu recurso do Key Vault e lembre-se de substituir <your-resource-group-name> e <your-key-vault-name> por seus próprios nomes exclusivos:
```
az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>
```
Na saída, você deverá ver uma lista com uma propriedade vaultUri. Defina isso como uma variável de ambiente a ser usada em nosso programa com o seguinte comando:
```
export AZURE_KEYVAULT_URL="https://<your-key-vault-name>.vault.azure.net/"
```

Por fim, verifique se sua conta do Azure tem as permissões adequadas para trabalhar com segredos do Key Vault. Você pode conceder a si mesmo as permissões adequadas atribuindo a si mesmo a função "Key Vault Secrets Officer" na página IAM (Controle de Acesso) do seu recurso do Key Vault no portal do Azure. O IAM significa gerenciamento de identidade e acesso.

Configurar o seu projeto

Esta seção descreve o processo de criação das pastas e arquivos necessários para configurar seu projeto do Azure C++.

Na raiz do diretório do projeto, crie um arquivo CMakeLists.txt . Esse arquivo é usado para configurar nosso projeto do CMake. Adicione o seguinte código ao arquivo CMakeLists.txt :

# Specify the minimum version of CMake required to build this project
cmake_minimum_required(VERSION 3.30.0)

# Set the path to the vcpkg toolchain file
# Remember to replace the path below with the path where you cloned vcpkg
set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake")

# Define the project name, version, and the languages used
project(azure_sample VERSION 0.1.0 LANGUAGES C CXX)

# Find and include the azure-identity-cpp package
find_package(azure-identity-cpp CONFIG REQUIRED)

# Find and include the azure-security-keyvault-secrets-cpp package
find_package(azure-security-keyvault-secrets-cpp CONFIG REQUIRED)

# Add an executable target named 'azure_sample' built from the main.cpp source file
add_executable(azure_sample main.cpp)

# Link the azure-identity and azure-security-keyvault-secrets 
# libraries to the azure_sample target
target_link_libraries(azure_sample PRIVATE
    Azure::azure-identity
    Azure::azure-security-keyvault-secrets
)

Na raiz do diretório do projeto, crie um arquivo main.cpp . Adicione o seguinte código ao arquivo main.cpp :

#include <azure/identity.hpp>
#include <azure/keyvault/secrets.hpp>
#include <iostream>

using namespace Azure::Security::KeyVault::Secrets;

int main()
{
    try
    {
        // Set Key Vault URL string
        auto const keyVaultUrl = std::getenv("AZURE_KEYVAULT_URL");

        // Create Default Azure Credential to Authenticate.
        // It will pick up on our AzureCLI login
        auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>();

        // Create Key Vault Secret Client
        SecretClient secretClient(keyVaultUrl, credential);

        // Create a Secret
        std::string secretName("MySampleSecret");
        std::string secretValue("My super secret value");
        secretClient.SetSecret(secretName, secretValue);

        // Get the Secret
        KeyVaultSecret secret = secretClient.GetSecret(secretName).Value;
        std::string valueString = secret.Value.HasValue()
                                      ? secret.Value.Value()
                                      : "NONE RETURNED";
        std::cout << "Secret is returned with name " << secret.Name
                  << " and value " << valueString << std::endl;
    }
    catch (Azure::Core::Credentials::AuthenticationException const &e)
    {
        std::cout << "Authentication Exception happened:" << std::endl
                  << e.what() << std::endl;
        return 1;
    }
    catch (Azure::Core::RequestFailedException const &e)
    {
        std::cout << "Key Vault Secret Client Exception happened:" << std::endl
                  << e.Message << std::endl;
        return 1;
    }

    return 0;
}

Crie um diretório build para os artefatos de compilação.

Criar e executar

Esta seção discute como configurar e criar seu projeto usando comandos do CMake e, em seguida, executar o programa para garantir que tudo esteja configurado corretamente. Os comandos nesta seção devem ser executados a partir da raiz do projeto onde o diretório build e os arquivos CMakeLists.txt e main.cpp estão localizados.

Windows – PowerShell
MacOS/Linux – Bash

Para configurar o CMake, insira o seguinte comando:
```
cmake -B ./build
```
Para criar o projeto, insira o seguinte comando:
```
cmake --build ./build
```
Para executar o programa, insira o seguinte comando:
```
.\build\Debug\azure_sample.exe
```

O programa deve ter a seguinte saída:

Secret is returned with name MySampleSecret and value My super secret value

Para configurar o CMake, insira o seguinte comando:
```
cmake -B ./build
```
Para criar o projeto, insira o seguinte comando:
```
cmake --build ./build
```
Para executar o programa, insira o seguinte comando:
```
./build/azure_sample
```

O programa deve ter a seguinte saída:

Secret is returned with name MySampleSecret and value My super secret value

Resolução de problemas

Grupo de recursos não encontrado

Ao usar a AzureCLI para criar uma instância do Key Vault, se você receber o seguinte erro, o grupo de recursos ao qual você está tentando adicionar a instância do Key Vault não existe.

(ResourceGroupNotFound) Resource group '<your-resource-group-name>' could not be found.
Code: ResourceGroupNotFound
Message: Resource group '<your-resource-group-name>' could not be found.

Para criar o grupo de recursos, você pode usar o seguinte comando:

az group create --name <your-resource-group-name> --___location <your-resource-group-___location>

Para obter mais informações, confira os documentos da AzureCLI sobre como gerenciar grupos de recursos do Azure.

A configuração ou compilação do CMake não pode localizar pacotes do Azure

Ao executar os comandos de configuração ou compilação do CMake, se você receber o seguinte erro ou algo semelhante, o arquivo CMakeLists.txt não está executando o módulo vcpkg.cmake antes que o projeto do CMake seja estabelecido ou acaba não sendo executado.

CMake Error at CMakeLists.txt:12 (find_package):
  Could not find a package configuration file provided by
  "azure-identity-cpp" with any of the following names:

    azure-identity-cppConfig.cmake
    azure-identity-cpp-config.cmake

  Add the installation prefix of "azure-identity-cpp" to CMAKE_PREFIX_PATH or
  set "azure-identity-cpp_DIR" to a directory containing one of the above
  files.  If "azure-identity-cpp" provides a separate development package or
  SDK, be sure it has been installed.

Verifique no arquivo CMakeLists.txt , se a set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") linha está acima do project(azure_sample VERSION 0.1.0 LANGUAGES C CXX).

Em seguida, verifique também se a /path/to/vcpkg-root/set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") linha está atualizada para o local em que o vcpkg foi instalado.

Erro de sintaxe no código cmake

Ao executar a configuração do CMake ou os comandos de build, se você receber o erro a seguir, o arquivo CMakeLists.txt poderá conter caminhos usando \. Esse problema pode ser comum ao usar os caminhos do Window.

Syntax error in cmake code at

    C:/Users/username/Desktop/CppProject/CMakeLists.txt:6

  when parsing string

    C:\Users\username\vcpkg\scripts\buildsystems\vcpkg.cmake

  Invalid character escape '\U'.

Embora o Windows use \ em caminhos de arquivo, o CMake usa apenas / em caminhos de arquivo. O problema pode ser resolvido substituindo todos os \ por / nos caminhos usados no arquivo CMakeLists.txt.

Se o erro persistir depois de fazer a alteração, consulte os erros do CMake que persistem depois de fazer a seção de alterações para saber como resolvê-los.

Os erros do CMake persistem após a alteração

Ao executar o comando de configuração do CMake, se você continuar recebendo o mesmo erro depois de fazer alterações para corrigi-lo, tente limpar o cache do CMake. O cache do CMake pode ser limpo excluindo o conteúdo do diretório de build e executando novamente o comando de configuração do CMake.

CMake 3.30 ou superior é necessário

Ao executar o comando de configuração do CMake, se você receber um erro como o seguinte, talvez seja necessário atualizar sua versão do CMake.

CMake Error at CMakeLists.txt:2 (cmake_minimum_required):
  CMake 3.30.0 or higher is required.  You are running version 3.25.0

Para resolver esse erro, atualize a instalação do CMake para a versão declarada na mensagem de erro.

A pessoa que está realizando a chamada não está autorizada a executar a ação no recurso

Ao executar o programa de exemplo C++, se você receber um erro como o seguinte, não terá as permissões adequadas para trabalhar com segredos no recurso especificado do Key Vault.

Key Vault Secret Client Exception happened:
Caller is not authorized to perform action on resource.
If role assignments, deny assignments or role definitions were changed recently, please observe propagation time.
Caller: <redacted-application-information>
Action: 'Microsoft.KeyVault/vaults/secrets/setSecret/action'
Resource: <redacted-resource-information>
Assignment: (not found)
DenyAssignmentId: null
DecisionReason: null 
Vault: <your-key-vault-name>;___location=<your-key-vault-___location>

As permissões apropriadas podem ser fornecidas à sua conta usando o portal do Azure ou a CLI do Azure.

Para atualizar suas permissões usando o portal do Azure, navegue até a página IAM (Controle de Acesso) do recurso do Key Vault. Selecione o menu Adicionar e selecione Adicionar atribuição de função. Na página Função , selecione a função Key Vault Secrets Officer e selecione Avançar na parte inferior da página. Na página Membros, deixe a opção Atribuir acesso àUsuário, grupo ou entidade de serviço e selecione o link Selecionar membros. No pop-up à direita, pesquise e selecione seu ID e clique em Selecionar na parte inferior do pop-up. A ID selecionada agora deve ser exibida na tabela da seção Membros . Selecione o botão Examinar + atribuir na parte inferior. Em seguida, selecione o botão Examinar + atribuir novamente.

Para atualizar suas permissões usando a CLI do Azure, insira o seguinte comando, substituindo <upn> pelo nome da entidade de usuário, <subscription-id> pela ID da assinatura, <resource-group-name> pelo nome do grupo de recursos e <your-unique-keyvault-name> pelo nome da instância do Key Vault:

az role assignment create --role "Key Vault Secrets Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

VS Code inclui erros

Se você vir linhas de erro em suas instruções de inclusão ao usar o VS Code (mostrado na imagem a seguir), o editor não saberá onde localizar o diretório de inclusão.

{Captura de tela das declarações de inclusão em C++ no VS Code que possuem sublinhados vermelhos de erro embaixo.}

vcpkg coloca os cabeçalhos de inclusão em build/vcpkg_installed/<vcpkg-platform-triplet>/include quando está no modo manifesto. Substitua <vcpkg-platform-triplet> pelo trigêmeo vcpkg para sua plataforma.

Para adicionar o diretório de inclusão às configurações do VS Code, passe o mouse sobre a instrução 'include' com a linha de erro. Em seguida, selecione o link Correção Rápida... na parte inferior do pop-up. Nas opções de Correção Rápida, selecione a opção Adicionar a "includePath": ${workspaceFolder}/build/vcpkg_installed/<vcpkg-platform-triplet>/include . A guia Configuração de Extensão C/C++ deve ser aberta e, na seção "Incluir caminho", você deverá ver o caminho para o diretório de inclusão listado.

O bootstrap-vcpkg do Linux não pôde encontrar dependências

Ao executar o script bootstrap-vcpkg.sh no Linux, se você receber um erro como o seguinte, não terá as ferramentas necessárias instaladas para executar o script.

Could not find zip. Please install it (and other dependencies) with:
On Debian and Ubuntu derivatives:
  sudo apt-get install curl zip unzip tar
On recent Red Hat and Fedora derivatives:
  sudo dnf install curl zip unzip tar
On older Red Hat and Fedora derivatives:
  sudo yum install curl zip unzip tar
On SUSE Linux and derivatives:
  sudo zypper install curl zip unzip tar
On Arch Linux and derivatives:
  sudo pacman -Syu base-devel git curl zip unzip tar cmake ninja
On Alpine:
  apk add build-base cmake ninja zip unzip curl git
  (and export VCPKG_FORCE_SYSTEM_BINARIES=1)

Para instalar as ferramentas, use o comando fornecido na mensagem de erro para sua distribuição do linux. Por exemplo, no Ubuntu, seria o seguinte comando:

sudo apt-get install curl zip unzip tar

Em seguida, execute novamente o bootstrap-vcpkg.sh script.

Não foi possível localizar o arquivo de cadeia de ferramentas do Linux

Ao executar o comando de configuração do CMake, se você receber um erro como o seguinte, o caminho para os módulos vcpkg.cmake não foi definido corretamente.

CMake Error at /usr/share/cmake-3.28/Modules/CMakeDetermineSystem.cmake:176 (message):
  Could not find toolchain file:
  /path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake
Call Stack (most recent call first):
  CMakeLists.txt:9 (project)

No arquivoCMakeLists.txt, atualize a set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake") declaração com o caminho correto para onde vcpkg foi instalado.

Falha na instalação do vcpkg do Linux

Ao executar o comando de configuração do CMake, se você receber um erro como o seguinte, as dependências do sistema para os pacotes precisarão ser instaladas.

CMake Error at /path/to/vcpkg/scripts/buildsystems/vcpkg.cmake:904 (message):
  vcpkg install failed.  See logs for more information:

Para localizar os pacotes de sistema necessários, pesquise a saída dos comandos de configuração do CMake em busca de linhas começando com Could not find <system-package>, substituindo <system-package> pelo pacote do sistema ausente. Abaixo dessa linha deve ser um comando para instalar esse pacote de sistema ausente. Execute esse comando. Em seguida, execute novamente o comando de configuração do CMake. Talvez seja necessário repetir esse processo algumas vezes, dependendo do número de pacotes do sistema ausentes.

Próxima etapa

Comentários

Esta página foi útil?

Last updated on 2025-05-08