Inicio rápido: Versión 12 de la biblioteca cliente de Azure Blob Storage para C++

Introducción a la versión 12 de 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 los pasos para instalar el paquete y probar el código de ejemplo para realizar tareas básicas. Blob Storage está optimizado para el almacenamiento de cantidades masivas de datos no estructurados.

La versión 12 de la biblioteca cliente de Azure Blob Storage para C++ se puede usar para:

  • Crear un contenedor
  • Cargar un blob en Azure Storage
  • Enumerar todos los blobs de un contenedor
  • Descargar el blob en el equipo local
  • Eliminación de un contenedor

Recursos:

Prerrequisitos

Instalación

En esta sección se explica cómo preparar un proyecto para que funcione con la versión 12 de la biblioteca cliente de Azure Blob Storage para C++.

Instalación de los paquetes

El comando vcpkg install instalará el SDK de Azure Storage Blobs para C++ y las dependencias necesarias:

vcpkg.exe install azure-storage-blobs-cpp:x64-windows

Para más información, visite GitHub para adquirir y crear el SDK de Azure para C++.

Creación del proyecto

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

Cuadro de diálogo de Visual Studio para configurar una nueva aplicación de consola de Windows en C++

Copia de las credenciales desde Azure Portal

Cuando la aplicación de ejemplo realiza una solicitud a Azure Storage, debe estar autorizada. Para autorizar una solicitud, agregue a la aplicación las credenciales de la cuenta de almacenamiento en forma de cadena de conexión. Para ver las credenciales de la cuenta de almacenamiento, siga estos pasos:

  1. Inicie sesión en Azure Portal.

  2. Busque su cuenta de almacenamiento.

  3. En el panel del menú de la cuenta de almacenamiento, en Seguridad y redes, seleccione Claves de acceso. Aquí puede ver las claves de acceso de la cuenta, así como la cadena de conexión completa de cada clave.

    Captura de pantalla que muestra dónde se encuentra la configuración de las claves de acceso en Azure Portal

  4. En el panel Claves acceso, seleccione Mostrar claves.

  5. En la sección key1, busque el valor de Cadena de conexión. Seleccione el icono Copiar al portapapeles para copiar la cadena de conexión. En la siguiente sección, agregará el valor de la cadena de conexión a una variable de entorno.

    Captura de pantalla que muestra cómo copiar una cadena de conexión desde Azure Portal

Configuración de la cadena de conexión de almacenamiento.

Una vez que haya copiado la cadena de conexión, escríbala en una variable de entorno nueva en la máquina local que ejecuta la aplicación. Para establecer la variable de entorno, abra una ventana de consola y siga las instrucciones de su sistema operativo. Reemplace <yourconnectionstring> por la cadena de conexión real.

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Después de agregar la variable de entorno en Windows, debe iniciar una nueva instancia de la ventana de comandos.

Reiniciar programas

Después de agregar la variable de entorno, reinicie todos los programas en ejecución que necesiten leer esta variable. Por ejemplo, reinicie el entorno de desarrollo o el editor antes de continuar.

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.

Diagrama de la arquitectura de Blob Storage

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 BlobQuickstartV12.sln en Visual Studio.
  2. En Visual Studio, abra el archivo de origen BlobQuickstartV12.cpp
  3. Quite todo el código incluido en main que se haya generado automáticamente
  4. Agregue instrucciones #include.
#include <stdlib.h>
#include <iostream>
#include <azure/storage/blobs.hpp>

Obtención de la cadena de conexión

El código siguiente recupera la cadena de conexión de la cuenta de almacenamiento de la variable de entorno creada en Configuración de la cadena de conexión de almacenamiento.

Agregue este código a main():

        // Retrieve the connection string for use with the application. The storage
        // connection string is stored in an environment variable on the machine
        // running the application called AZURE_STORAGE_CONNECTION_STRING.
        // Note that _MSC_VER is set when using MSVC compiler.
        static const char* AZURE_STORAGE_CONNECTION_STRING = "AZURE_STORAGE_CONNECTION_STRING";
#if !defined(_MSC_VER)
        const char* connectionString = std::getenv(AZURE_STORAGE_CONNECTION_STRING);
#else
        // Use getenv_s for MSVC
        size_t requiredSize;
        getenv_s(&requiredSize, NULL, NULL, AZURE_STORAGE_CONNECTION_STRING);
        if (requiredSize == 0) {
            throw std::runtime_error("missing connection string from env.");
        }
        std::vector<char> value(requiredSize);
        getenv_s(&requiredSize, value.data(), value.size(), AZURE_STORAGE_CONNECTION_STRING);
        std::string connectionStringStr = std::string(value.begin(), value.end());
        const char* connectionString = connectionStringStr.c_str();
#endif

Crear un contenedor

Cree una instancia de la clase BlobContainerClient llamando a la función CreateFromConnectionString. Luego, llame a CreateIfNotExists para crear el contenedor real en la cuenta de almacenamiento.

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():

using namespace Azure::Storage::Blobs;

std::string containerName = "myblobcontainer";

// Initialize a new instance of BlobContainerClient
BlobContainerClient containerClient
    = BlobContainerClient::CreateFromConnectionString(connectionString, containerName);

// Create the container. This will do nothing if the container already exists.
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 v12 - 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: