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 de API | Código fuente de la biblioteca | Ejemplos |

Prerrequisitos

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

Configuración

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

Instalación de los paquetes

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

vcpkg.exe install azure-storage-blobs-cpp

La biblioteca de identidades de Azure 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 denominada 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 adhieren a un modelo o definición de datos 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 blobs especializadas.
• BlockBlobClient: la BlockBlobClient clase permite manipular 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++:

• Incluir archivos
• 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 solución BlobQuickstart.sln en Visual Studio.
2. Dentro de Visual Studio, abra el archivo fuente BlobQuickstart.cpp
3. Quitar cualquier código dentro de main que fue 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 Azure Identity ofrece compatibilidad con la autenticación de tokens de Microsoft Entra en el SDK de Azure. Proporciona un conjunto de TokenCredential implementaciones que se pueden usar para construir clientes del SDK de Azure que admiten 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. Para obtener más información sobre el rol, consulte Colaborador de datos de Storage Blob. Para obtener más información sobre los ámbitos disponibles para las asignaciones de roles, consulte Descripción del ámbito de RBAC de Azure.

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.

Azure CLI

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

Inicie sesión y conecte el 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 comando siguiente:

   az login
   

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

   #include <azure/identity/default_azure_credential.hpp>
   

3. Agregue este código al final de main(). Cuando el código se ejecuta en la estación de trabajo local, DefaultAzureCredential usa las credenciales de desarrollador de la CLI de Azure 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 BlobServiceClient objeto. 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á la aplicación. En lugar de usar DefaultAzureCredential, debe autorizar mediante un tipo de credencial específico o usando 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.

   

Azure CLI

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

En el ejemplo de código siguiente se recupera la cadena de conexión de la cuenta de almacenamiento de la variable de entorno creada anteriormente y se usa la cadena de conexión para construir un objeto de 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.

Creación de 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

Fragmento de código siguiente:

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

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));

Enumerar los blobs de un contenedor

Enumere los blobs del contenedor llamando a la función ListBlobs . Solo se ha agregado un blob al contenedor, por lo que la operación solo devuelve ese 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. A continuación, declare y cambie el tamaño de un nuevo std::vector<uint8_t> objeto mediante las propiedades del blob cargado. Descargue el blob creado anteriormente en el nuevo std::vector<uint8_t> objeto llamando a la función DownloadTo en la clase base BlobClient . Por último, muestre los datos de blobs descargados.

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 mediante una llamada 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 mediante la eliminación del contenedor completo mediante BlobContainerClient.Eliminar.

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. A continuación, en el ejemplo se enumeran los blobs del contenedor, se descarga el archivo y se muestra el contenido del archivo. Por último, la aplicación elimina el blob y 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 C++ Blob Storage, continúe:

Biblioteca cliente de Azure Blob Storage para ejemplos de C++