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 em 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++. Quer seja novo no Azure ou pretenda simplificar o seu processo de integração, esta documentação ajuda-o 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 no seu sistema.

Windows - PowerShell
MacOS/Linux - Bash

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

Para verificar se o git está instalado corretamente, execute o seguinte comando no seu terminal:
```
git --version
```
Você deve obter uma saída denotando a versão atualmente instalada para o git, assim:
```
git version <version>
```
Para verificar se o CMake está instalado corretamente, execute o seguinte comando no seu terminal:
```
cmake --version
```
Você deve obter uma saída denotando a versão atualmente instalada do CMake, assim:
```
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 manipulação 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 em seu diretório de projeto C++. Neste exemplo, vcpkg é clonado para o dir inicial.
```
cd ~
git clone https://github.com/microsoft/vcpkg.git
```
Depois que o repositório vcpkg for clonado, entre no novo diretório e execute o bootstrap-vcpkg.bat script.
```
cd .\vcpkg\
.\bootstrap-vcpkg.bat
```
Depois de inicializar o vcpkg, adicione-o ao seu caminho para que você possa acessar o executável vcpkg a partir do diretório do seu projeto. Lembre-se de substituir o <path\to\vcpkg> no exemplo de comando pelo caminho para o diretório vcpkg clonado 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ê deve obter a seguinte saída:

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 em seu diretório de projeto C++. Neste exemplo, vcpkg é clonado para o dir inicial.
```
cd ~
git clone https://github.com/microsoft/vcpkg.git
```
Depois que o repositório vcpkg for clonado, entre no novo diretório e execute o bootstrap-vcpkg.sh script.
```
cd vcpkg
./bootstrap-vcpkg.sh
```
Depois de inicializar o vcpkg, adicione-o ao seu caminho para que você possa acessar o executável vcpkg a partir do diretório do seu projeto. Lembre-se de substituir o <path\to\vcpkg> no exemplo de comando pelo caminho para o diretório vcpkg clonado 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ê deve obter a seguinte saída:

vcpkg package management program version <version>

Instalar as bibliotecas

Esta seção o orienta 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 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

A partir do 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 o Cofre da Chave do Azure e as bibliotecas de Identidade 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"
  ]
}

A partir do 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 o Cofre da Chave do Azure e as bibliotecas de Identidade 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"
  ]
}

Criar um recurso do Azure Key Vault

Esta seção discute como usar a CLI do Azure para criar um recurso do Azure Key Vault. Este recurso do Cofre de Chaves armazena e gerencia com segurança informações confidenciais, 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
```
Utilize as janelas de pop-up para iniciar sessão no Azure.
Depois de utilizar a janela pop-up do browser para iniciar sessão, selecione a subscrição do Azure que pretende utilizar no terminal.
Em seguida, use o seguinte comando para criar seu recurso 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, verá uma lista de propriedades 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
```
Utilize as janelas de pop-up para iniciar sessão no Azure.
Depois de utilizar a janela pop-up do browser para iniciar sessão, selecione a subscrição do Azure que pretende utilizar no terminal.
Em seguida, use o seguinte comando para criar seu recurso 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, verá uma lista de propriedades 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 os Segredos do Cofre da Chave. Você pode conceder a si mesmo as permissões adequadas atribuindo a si mesmo a função "Key Vault Secrets Officer" na página Controle de Acesso (IAM) do seu recurso Key Vault no portal do Azure. IAM significa gerenciamento de identidade e acesso.

Configure 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 . Este arquivo é usado para configurar nosso projeto 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 de compilação para os artefatos de compilação.

Compilar e executar

Esta seção discute como configurar e construir seu projeto usando comandos 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 seu projeto onde o diretório, buildCMakeLists.txt e main.cpp os arquivos estão localizados.

Windows - PowerShell
MacOS/Linux - Bash

Para configurar o CMake, digite o seguinte comando:
```
cmake -B ./build
```
Para criar o projeto, digite o seguinte comando:
```
cmake --build ./build
```
Para executar o programa, digite 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, digite o seguinte comando:
```
cmake -B ./build
```
Para criar o projeto, digite o seguinte comando:
```
cmake --build ./build
```
Para executar o programa, digite 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

Solução de problemas

Grupo de recursos não encontrado

Ao usar a AzureCLI para criar uma instância do Cofre da Chave, se você receber o seguinte erro, o grupo de recursos ao qual você está tentando adicionar a instância do Cofre da Chave 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 AzureCLI em Gerenciando Grupos de Recursos do Azure.

O CMake configure ou compile não consegue encontrar pacotes do Azure

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

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 que a linha set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") está acima de project(azure_sample VERSION 0.1.0 LANGUAGES C CXX).

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

Erro de sintaxe no código cmake

Ao executar os comandos de configuração ou compilação do CMake, se você receber o seguinte erro, o arquivo CMakeLists.txt pode conter caminhos usando \. Esse problema pode ser comum ao usar os caminhos do Windows.

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 só usa / em caminhos de arquivo. O problema pode ser resolvido substituindo tudo \ por / nos caminhos usados no arquivo CMakeLists.txt .

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

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

Ao executar o comando CMake configure, se você continuar a receber 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 compilação e, em seguida, executando novamente o comando CMake configure.

CMake 3.30 ou superior necessário

Ao executar o comando CMake configure, 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 indicada na mensagem de erro.

O chamador não está autorizado a executar uma 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 do Cofre de Chaves especificado.

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 adequadas podem ser dadas à 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 Controle de Acesso (IAM) do seu recurso Cofre de Chaves. Selecione a lista suspensa Adicionar e selecione Adicionar atribuição de função. Na página Função, selecione a função Key Vault Secrets Officer e, na parte inferior da página, selecione Seguinte. Na página Membros , deixe a opção Atribuir acesso a em Usuário, grupo ou entidade de serviço e selecione no link Selecionar membros . No pop-up à direita, procure e selecione o seu ID e, em seguida, selecione Selecionar na parte inferior do pop-up. O ID que selecionou deve agora aparecer na tabela da secção Membros . Selecione o botão Rever e atribuir na parte inferior. Em seguida, selecione o botão Rever + atribuir novamente.

Para atualizar suas permissões usando a CLI do Azure, digite o seguinte comando, substituindo <upn> pelo nome principal do 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 Cofre da Chave:

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 sob suas instruções include ao usar o VS Code (mostrado na imagem a seguir), o editor não sabe onde encontrar o diretório include.

{A captura de tela do C++ inclui instruções do VS Code que têm linhas onduladas de erro vermelhas por baixo.}

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

Para adicionar o diretório include à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 "Caminho de inclusão", você deve ver o caminho para o diretório de inclusão listado.

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

Ao executar o script bootstrap-vcpkg.sh no Linux, se você receber um erro como o seguinte, você não tem 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 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.

O Linux não conseguiu encontrar o arquivo toolchain

Ao executar o comando CMake configure, 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 ficheiro CMakeLists.txt, atualize a set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake") instrução com o caminho correto onde o vcpkg está instalado.

Falha na instalação do Linux vcpkg

Ao executar o comando CMake configure, se você receber um erro como o seguinte, as dependências do sistema para os pacotes precisam ser instaladas.

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

Para encontrar os pacotes de sistema necessários, procure na saída dos comandos de configuração do CMake por linhas que comecem com Could not find <system-package>, substituindo <system-package> pelo pacote de sistema ausente. Abaixo desta linha deve estar um comando para instalar o pacote de sistema ausente. Execute esse comando. Em seguida, execute novamente o comando de configuração do CMake. Pode ser necessário repetir esse processo algumas vezes, dependendo do número de pacotes de sistema ausentes.

Próximo passo

Comentários

Esta página foi útil?

Last updated on 2025-05-08