Inicio rápido: Biblioteca cliente de Azure Blob Storage para C++

  • Artículo

Introducción a la biblioteca cliente de Azure Blob Storage para C++. Azure Blob Storage es la solución de almacenamiento de objetos de Microsoft para la nube. Siga estos pasos para instalar el paquete y probar el código de ejemplo para realizar tareas básicas.

| Documentación de referencia | Código fuente de la biblioteca | Ejemplo de código |

Requisitos previos

Instalación

En esta sección se explica cómo preparar un proyecto para que funcione con la biblioteca de cliente de Azure Blob Storage para C++. La manera más fácil de adquirir Azure SDK para C++ es usar el vcpkg administrador de paquetes.

Instalación de los paquetes

Use el comando vcpkg install para instalar la biblioteca de Azure Blob Storage para C++ y las dependencias necesarias:

vcpkg.exe install azure-storage-blobs-cpp

La biblioteca Azure.Identity es necesaria para las conexiones sin contraseña a los servicios de Azure:

vcpkg.exe install azure-identity-cpp

Para más información sobre la configuración del proyecto y cómo trabajar con Azure SDK para C++, consulte el archivo Léame de Azure SDK para C++.

Creación del proyecto

En Visual Studio, cree una nueva aplicación de consola de C++ para Windows llamada BlobQuickstart.

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

Modelo de objetos

Azure Blob Storage está optimizado para el almacenamiento de cantidades masivas de datos no estructurados. Los datos no estructurados son datos que no se ciñen a ningún un modelo de datos o definición concretos, como texto o datos binarios. Blob Storage ofrece tres tipos de recursos:

  • La cuenta de almacenamiento
  • Un contenedor en la cuenta de almacenamiento
  • Un blob en el contenedor

En el siguiente diagrama se muestra la relación entre estos recursos.

Diagram of Blob Storage architecture

Use estas clases de C++ para interactuar con estos recursos:

  • BlobServiceClient: La clase BlobServiceClient permite manipular recursos de Azure Storage y contenedores de blobs.
  • BlobContainerClient: La clase BlobContainerClient permite manipular contenedores de Azure Storage y sus blobs.
  • BlobClient: La clase BlobClient permite manipular los blobs de Azure Storage. Es la clase base para todas las clases de blob especializadas.
  • BlockBlobClient: La clase BlockBlobClient permite manipular los blobs en bloques de Azure Storage.

Ejemplos de código

Estos fragmentos de código de ejemplo muestran cómo realizar las siguientes tareas con la biblioteca cliente de Azure Blob Storage para C++:

Adición de archivos de inclusión

Desde el directorio del proyecto:

  1. Abra el archivo de soluciones BlobQuickstart.sln en Visual Studio
  2. En Visual Studio, abra el archivo de origen BlobQuickstart.cpp
  3. Quite todo el código incluido en main que se haya generado automáticamente
  4. Agregue las Instrucciones #include y using namespace
#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;

Autenticación en Azure y autorización del acceso a datos de blobs

Las solicitudes de aplicación a Azure Blob Storage deben estar autorizadas. El uso de la clase DefaultAzureCredential que proporciona la biblioteca cliente de Azure.Identity es el enfoque recomendado para implementar conexiones sin contraseña a los servicios de Azure en el código, incluido Blob Storage.

También puede autorizar las solicitudes a Azure Blob Storage mediante la clave de acceso de la cuenta. Sin embargo, este enfoque debe usarse con precaución. Los desarrolladores deben ser diligentes para no exponer nunca las claves de acceso en una ubicación que no sea segura. Cualquier persona que tenga la clave de acceso puede autorizar las solicitudes en la cuenta de almacenamiento y tiene acceso eficaz a todos los datos. DefaultAzureCredential ofrece ventajas de seguridad y administración mejoradas con respecto la clave de cuenta para permitir la autenticación sin contraseña. Ambas opciones se muestran en el ejemplo siguiente.

La biblioteca de identidades de Azure proporciona asistencia con la autenticación de tokens de Microsoft Entra a través de Azure SDK. Proporciona un conjunto de implementaciones de TokenCredential que se pueden usar para construir clientes del SDK de Azure que admitan la autenticación de tokens de Microsoft Entra. DefaultAzureCredential admite varios métodos de autenticación y determina el que se debe usar en tiempo de ejecución.

Asignación de roles a la cuenta de usuario de Microsoft Entra

Al desarrollar localmente, asegúrese de que la cuenta de usuario que accede a los datos de blob tenga los permisos correctos. Necesitará el Colaborador de datos de blobs de almacenamiento para leer y escribir datos de blob. Para asignarse este rol a sí mismo, necesitará que se le asigne el rol Administrador de acceso de usuario u otro rol que incluya la acción Microsoft.Authorization/roleAssignments/write. Puede asignar roles RBAC de Azure a un usuario mediante Azure Portal, la CLI de Azure o Azure PowerShell. Puede obtener más información sobre los ámbitos disponibles para las asignaciones de roles en la página de información general del ámbito.

En este escenario, asignará permisos a la cuenta de usuario, cuyo ámbito es la cuenta de almacenamiento, a fin de seguir el principio de privilegios mínimos. Esta práctica solo proporciona a los usuarios los permisos mínimos necesarios y crea entornos de producción más seguros.

En el ejemplo siguiente se asignará el rol Colaborador de datos de blobs de almacenamiento a la cuenta de usuario, que proporciona acceso de lectura y escritura a los datos de blobs de la cuenta de almacenamiento.

Importante

En la mayoría de los casos, la asignación de roles tardará un minuto o dos en propagarse en Azure, pero en casos excepcionales puede tardar hasta ocho minutos. Si recibe errores de autenticación al ejecutar por primera vez el código, espere unos instantes e inténtelo de nuevo.

  1. En Azure Portal, busque la cuenta de almacenamiento mediante la barra de búsqueda principal o el panel de navegación de la izquierda.

  2. En la página de información general de la cuenta de almacenamiento, seleccione Control de acceso (IAM) en el menú de la izquierda.

  3. En la página Control de acceso (IAM), seleccione la pestaña Asignación de roles.

  4. Seleccione + Agregar en el menú superior y, a continuación, Agregar asignación de roles en el menú desplegable resultante.

    A screenshot showing how to assign a role.

  5. Puede usar el cuadro de búsqueda para filtrar los resultados por el rol deseado. En este ejemplo, busque Colaborador de datos de blobs de almacenamiento y seleccione el resultado coincidente y, a continuación, elija Siguiente.

  6. En la pestaña Asignar acceso a, seleccione Usuario, grupo o entidad de servicio y, a continuación, elija + Seleccionar miembros.

  7. En el cuadro de diálogo, busque el nombre de usuario de Microsoft Entra (normalmente su dirección de correo electrónico de user@domain) y, a continuación, elija Seleccionar en la parte inferior del cuadro de diálogo.

  8. Seleccione Revisar y asignar para ir a la página final y, a continuación, de nuevo Revisar y asignar para completar el proceso.

Inicio de sesión y conexión del código de la aplicación a Azure mediante DefaultAzureCredential

Puede autorizar el acceso a los datos de la cuenta de almacenamiento mediante los siguientes pasos:

  1. Asegúrese de que esté autenticado con la misma cuenta de Microsoft Entra a la que asignó el rol en la cuenta almacenamiento. Puede autenticarse a través de la CLI de Azure. Inicie sesión en Azure a través de la CLI de Azure mediante el siguiente comando:

    az login

  2. Para usar DefaultAzureCredential, asegúrese de que el paquete azure-identity-cpp está instalado#include y se agrega lo siguiente:

    #include <azure/identity/default_azure_credential.hpp>

  3. Agregue este código al final de main(). Cuando el código se ejecuta en su estación de trabajo local, DefaultAzureCredential usa las credenciales de desarrollador para Azure CLI para autenticarse en 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. Asegúrese de actualizar el nombre de la cuenta de almacenamiento en el URI del objeto BlobServiceClient. El nombre de la cuenta de almacenamiento se puede encontrar en la página de información general de Azure Portal.

    A screenshot showing how to find the storage account name.

    Nota:

    Al usar el SDK de C++ en un entorno de producción, se recomienda que solo habilite las credenciales que sabe que usarán la aplicación. En lugar de usar DefaultAzureCredential, debe autorizar el uso de un tipo de credencial específico o mediante el uso de ChainedTokenCredential con las credenciales admitidas.

Crear un contenedor

Decida un nombre para el nuevo contenedor. A continuación, cree una instancia de BlobContainerClient y cree el contenedor.

Importante

Los nombres de contenedor deben estar en minúsculas. Para más información acerca de los contenedores de nomenclatura y los blobs, consulte Naming and Referencing Containers, Blobs, and Metadata (Asignación de nombres y realización de referencias a contenedores, blobs y metadatos).

Agregue este código al 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();

Carga de los blobs en un contenedor

El siguiente fragmento de código:

  1. Declara una cadena que contiene "Hello Azure!"
  2. Obtiene una referencia a un objeto BlockBlobClient llamando al contenedor GetBlockBlobClient de la sección Crear un contenedor.
  3. Carga la cadena en el blob mediante la llamada a la función UploadFrom. Esta función crea el blob, en caso de que no exista, o lo actualiza si existe.

Agregue este código al 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));

Enumeración de los blobs de un contenedor

Enumere los blobs en el contenedor llamando a la función ListBlobs. Se ha agregado un solo blob al contenedor, por lo que la operación devuelve simplemente dicho blob.

Agregue este código al 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;
}

Descargar blobs

Obtenga las propiedades del blob cargado. Luego, declare y cambie el tamaño de un nuevo objeto std::vector<uint8_t> mediante las propiedades del blob cargado. Descargue el blob que ha creado anteriormente en el objeto std::vector<uint8_t> nuevo, para lo que debe llamar a la función DownloadTo en la clase base BlobClient. Por último, muestre los datos del blob descargado.

Agregue este código al 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;

Eliminación de un blob

El código siguiente elimina el blob del contenedor de Azure Blob Storage, para lo que llama a la función BlobClient.Delete.

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

Eliminación de un contenedor

El código siguiente limpia los recursos que creó la aplicación; para ello, elimina todo el contenedor mediante BlobContainerClient.Delete.

Agregue este código al final de main():

std::cout << "Deleting container: " << containerName << std::endl;
containerClient.Delete();

Ejecución del código

Esta aplicación crea un contenedor y carga un archivo de texto en Azure Blob Storage. Luego, en el ejemplo se enumeran los blobs del contenedor, se descarga el archivo y se muestra su contenido. Por último, la aplicación elimina tanto el blob como el contenedor.

La salida de la aplicación es similar a la del ejemplo siguiente:

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

Pasos siguientes

En este inicio rápido, ha aprendido a cargar, descargar y enumerar blobs mediante C++. También ha aprendido a crear y eliminar un contenedor de Azure Blob Storage.

Para ver un ejemplo de Blob Storage para C++, siga estos pasos:

Muestras de la biblioteca cliente Azure Blob Storage para C++