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

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

• Una suscripción a Azure: cree una cuenta gratuita
• Una cuenta de Azure Storage: cree una cuenta de almacenamiento
• Compilador de C++
• CMake
• Vcpkg: administrador de paquetes de C y C++

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.

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.

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
• Autenticación en Azure y autorización del acceso a datos de blobs
• Creación de un contenedor
• Carga de los blobs en un contenedor
• Enumeración de los blobs de un contenedor
• Descarga de los blobs
• Eliminación de un contenedor

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.

Sin contraseña (recomendado)

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.

Azure Portal

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.

   

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.

CLI de Azure

Para asignar un rol en el nivel de recurso mediante la CLI de Azure, primero debe recuperar el id. de recurso mediante el comando az storage account show. Puede filtrar las propiedades de salida mediante el parámetro --query.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

Copie la salida Id del comando anterior. A continuación, puede asignar roles mediante el comando az role de la CLI de Azure.

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

PowerShell

Para asignar un rol en el nivel de recurso mediante Azure PowerShell, primero debe recuperar el Id. de recurso mediante el comando Get-AzResource.

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

Copie el valor Id de la salida del comando anterior. A continuación, puede asignar roles mediante el comando New-AzRoleAssignment en PowerShell.

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

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.

   

   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.

Cadena de conexión

Una cadena de conexión incluye la clave de acceso de la cuenta de almacenamiento y la usa para autorizar solicitudes. Tenga siempre cuidado de no exponer nunca las claves en una ubicación no segura.

Nota

Para autorizar el acceso a datos con la clave de acceso de la cuenta de almacenamiento, necesitará permisos para la siguiente acción de Azure RBAC: Microsoft.Storage/storageAccounts/listkeys/action. El rol integrado con privilegios mínimos con permisos para esta acción es Lector y acceso a los datos, pero cualquier rol que incluya esta acción funcionará.

Azure Portal

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.

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.

   

CLI de Azure

Puede ver la cadena de conexión de la cuenta de almacenamiento mediante el comando az storage account show-connection-string.

az storage account show-connection-string --name "<your-storage-account-name>"

PowerShell

Puede ensamblar una cadena de conexión con PowerShell mediante los comandos Get-AzStorageAccount y Get-AzStorageAccountKey.

$saName = "yourStorageAccountName"
$rgName = "yourResourceGroupName"
$sa = Get-AzStorageAccount -StorageAccountName $saName -ResourceGroupName $rgName

$saKey = (Get-AzStorageAccountKey -ResourceGroupName $rgName -Name $saName)[0].Value

'DefaultEndpointsProtocol=https;AccountName=' + $saName + ';AccountKey=' + $saKey + ';EndpointSuffix=core.windows.net'

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.

Windows:

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.

Linux:

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

El siguiente ejemplo de código recupera la cadena de conexión para la cuenta de almacenamiento de la variable de entorno creada anteriormente, y usa la cadena de conexión para construir un objeto cliente de servicio.

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

	auto blobServiceClient = BlobServiceClient::CreateFromConnectionString(connectionString);

Importante

La clave de acceso de la cuenta debe usarse con precaución. Si la clave de acceso de la cuenta se pierde o se coloca por accidente en una ubicación no segura, el servicio puede volverse vulnerable. 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 proporciona características y ventajas de seguridad mejoradas y es el enfoque recomendado para administrar la autorización en los servicios de Azure.

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++