Instalación e integración de bibliotecas desde el SDK de Azure para C++

En esta guía se proporcionan a los desarrolladores los pasos necesarios para instalar bibliotecas del SDK de Azure para C++ mediante vcpkg e integrarlas en sus proyectos con CMake. Siguiendo las instrucciones, puede configurar el entorno de desarrollo y empezar a usar los servicios de Azure en las aplicaciones de C++. Tanto si no está familiarizado con Azure como si desea simplificar el proceso de integración, esta documentación le ayuda a empezar a trabajar de forma rápida y eficaz.

Prerrequisitos

• Cualquier editor de texto
• Un terminal
• Un compilador de C++
• Git
• CMake
• Una suscripción de Azure
• Azure CLI

Comprobación de la instalación de Git y CMake

Para garantizar un proceso de integración sin problemas, es importante comprobar que Git y CMake están instalados correctamente en el sistema.

Instalación de vcpkg

Para administrar e instalar el SDK de Azure para bibliotecas de C++, use vcpkg. vcpkg es un administrador de paquetes multiplataforma que simplifica el proceso de control de dependencias.

Instalación de las bibliotecas

Esta sección le guía por el proceso de instalación de las bibliotecas necesarias desde El SDK de Azure para C++ mediante vcpkg. En esta sección se muestra cómo usar vcpkg en modo de manifiesto que crea un par de archivos de proyecto vcpkg para ayudar a administrar las dependencias del proyecto incluso cuando se comparten con otros colaboradores.

Creación de un recurso de Azure Key Vault

En esta sección se describe cómo usar la CLI de Azure para crear un recurso de Azure Key Vault. Este recurso de Key Vault almacena y administra de forma segura información confidencial, como secretos y claves.

1. Por último, asegúrese de que la cuenta de Azure tiene los permisos adecuados para trabajar con secretos de Key Vault. Puede concederse los permisos adecuados asignándose el rol de "Oficial de secretos de Key Vault" en la página de Control de acceso (IAM) de su recurso de Key Vault en el portal de Azure. IAM significa administración de identidades y acceso.

Configurar su proyecto

En esta sección se describe el proceso de creación de las carpetas y archivos necesarios para configurar el proyecto de Azure C++.

1. En la raíz del directorio del proyecto, cree un archivo CMakeLists.txt . Este archivo se usa para configurar nuestro proyecto de CMake. Agregue el código siguiente al archivo 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
   )
   

2. En la raíz del directorio del proyecto, cree un archivo main.cpp . Agregue el código siguiente al archivo 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;
   }
   

3. Cree un directorio de compilación para los artefactos de compilación.

Compilación y ejecución

En esta sección se describe cómo configurar y compilar el proyecto mediante comandos de CMake y, a continuación, ejecutar el programa para asegurarse de que todo está configurado correctamente. Los comandos de esta sección deben ejecutarse desde la raíz del proyecto donde se encuentran el build directorio, CMakeLists.txtlos archivos y main.cpp .

Solución de problemas

Grupo de recursos no encontrado

Al usar AzureCLI para crear una instancia de Key Vault, si recibe el siguiente error, el grupo de recursos al que intenta agregar la instancia de Key Vault no 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 crear el grupo de recursos, puede usar el siguiente comando:

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

Para más información, consulte los documentos de AzureCLI sobre administración de grupos de recursos de Azure.

La configuración o compilación de CMake no puede encontrar paquetes de Azure

Al ejecutar los comandos de configuración o compilación de CMake, si recibe el siguiente error o algo similar, el archivo CMakeLists.txt no ejecuta el módulo vcpkg.cmake antes de que el proyecto de CMake se establezca o en ningún momento.

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.

Compruebe en el archivo CMakeLists.txt que la set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") línea está encima de project(azure_sample VERSION 0.1.0 LANGUAGES C CXX).

A continuación, verifique también que la línea /path/to/vcpkg-root/ en set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg-root/scripts/buildsystems/vcpkg.cmake") se actualice a la ubicación donde se instaló vcpkg.

Error de sintaxis en el código cmake

Al ejecutar los comandos de compilación o configuración de CMake, si recibe el siguiente error, el archivo CMakeLists.txt puede contener rutas de acceso mediante \. Este problema puede ser común al usar las rutas de acceso de 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'.

Aunque Windows usa \ en rutas de acceso de archivo, CMake solo usa / en rutas de acceso de archivo. El problema se puede resolver reemplazando todo \ por / en las rutas de acceso usadas en el archivo CMakeLists.txt .

Si el error persiste después de realizar el cambio, consulte la sección Errores de CMake después de realizar cambios para obtener información sobre cómo resolverlos.

Los errores de CMake persisten después de realizar cambios

Al ejecutar el comando de configuración de CMake, si sigue recibiendo el mismo error después de realizar cambios para corregirlo, intente borrar la caché de CMake. La caché de CMake se puede borrar eliminando el contenido del directorio de compilación y, a continuación, vuelve a ejecutar el comando de configuración de CMake.

Se requiere CMake 3.30 o superior

Al ejecutar el comando de configuración de CMake, si recibe un error similar al siguiente, es posible que tenga que actualizar la versión de 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 este error, actualice la instalación de CMake a la versión indicada en el mensaje de error.

La persona que llama no está autorizada para realizar acción en el recurso

Al ejecutar el programa de ejemplo de C++, si recibe un error similar al siguiente, no tiene los permisos adecuados para trabajar con secretos en el recurso de Key Vault 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>

Los permisos adecuados se pueden conceder a su cuenta mediante Azure Portal o la CLI de Azure.

Para actualizar los permisos mediante Azure Portal, vaya a la página Control de acceso (IAM) del recurso de Key Vault. Seleccione la lista desplegable Agregar y seleccione Agregar asignación de roles. En la página Rol , seleccione el rol Oficial de secretos de Key Vault y seleccione Siguiente en la parte inferior de la página. En la página Miembros , deje la opción Asignar acceso a en Usuario, grupo o entidad de servicio y seleccione en el vínculo Seleccionar miembros . En el menú emergente de la derecha, busque y seleccione el identificador y, a continuación, seleccione Seleccionar en la parte inferior del menú emergente. El identificador seleccionado ahora debería mostrarse en la tabla de la sección Miembros . Seleccione el botón Revisar y asignar en la parte inferior. A continuación, vuelva a seleccionar el botón Revisar y asignar .

Para actualizar los permisos mediante la CLI de Azure, escriba el comando siguiente, reemplazando <upn> por el nombre principal de usuario, <subscription-id> por el identificador de suscripción, <resource-group-name> por el nombre del grupo de recursos y <your-unique-keyvault-name> por el nombre de la instancia de 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 incluye errores

Si ve líneas de error en las instrucciones include al usar VS Code (que se muestra en la siguiente imagen), el editor no sabe dónde encontrar el directorio include.

vcpkg coloca los encabezados de inclusión en el build/vcpkg_installed/<vcpkg-platform-triplet>/include cuando está en "modo de manifiesto". Sustituya <vcpkg-platform-triplet> por el triplete vcpkg correspondiente a su plataforma.

Para agregar el directorio de inclusión a la configuración de VS Code, pase el puntero sobre la instrucción include con la línea de error. A continuación, seleccione el vínculo Corrección rápida... en la parte inferior del elemento emergente. En las opciones Corrección rápida, seleccione la opción Agregar a "includePath": ${workspaceFolder}/build/vcpkg_installed/<vcpkg-platform-triplet>/include . La pestaña Configuración de la extensión de C/C++ debe abrirse y, en la sección "Ruta de inclusión", debería ver la ruta al directorio de inclusión listada.

Linux bootstrap-vcpkg no encontró dependencias

Al ejecutar el script de bootstrap-vcpkg.sh en Linux, si recibe un error similar al siguiente, no tiene instaladas las herramientas necesarias para ejecutar el 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 las herramientas, use el comando proporcionado en el mensaje de error para la distribución de Linux. Por ejemplo, en Ubuntu sería el siguiente comando:

sudo apt-get install curl zip unzip tar

A continuación, vuelva a ejecutar el bootstrap-vcpkg.sh script.

Linux no pudo encontrar el archivo de cadena de herramientas

Al ejecutar el comando CMake configure, si recibe un error similar al siguiente, la ruta de acceso a los módulos vcpkg.cmake no se estableció correctamente.

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)

En el archivo CMakeLists.txt actualice la set(CMAKE_TOOLCHAIN_FILE "/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake") instrucción con la ruta de acceso correcta a donde se instaló vcpkg.

Error de instalación de vcpkg de Linux

Al ejecutar el comando de configuración de CMake, si recibe un error similar al siguiente, es necesario instalar las dependencias del sistema para los paquetes.

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

Para buscar los paquetes del sistema necesarios, busque la salida de los comandos de configuración de CMake para las líneas que comienzan por Could not find <system-package>, reemplazando <system-package> por el paquete del sistema que falta. Debajo de esta línea debe ser un comando para instalar ese paquete del sistema que falta. Ejecute ese comando. A continuación, vuelva a ejecutar el comando de configuración de CMake. Es posible que tenga que repetir este proceso varias veces en función del número de paquetes del sistema que faltan.

Paso siguiente