Inicio rápido: Biblioteca cliente de Azure Blob Storage para .NET
Introducción a la biblioteca cliente de Azure Blob Storage para .NET. 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. Blob Storage está optimizado para el almacenamiento de cantidades masivas de datos no estructurados.
Documentación de referencia de la API | Código fuente de la biblioteca | Paquete (NuGet) | Ejemplos
Prerrequisitos
- Una suscripción a Azure: cree una cuenta gratuita
- Una cuenta de Azure Storage: cree una cuenta de almacenamiento
- SDK de .NET actual para su sistema operativo. Asegúrese de obtener el SDK y no el entorno de ejecución.
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. NET.
Creación del proyecto
Para los pasos siguientes, deberá crear una aplicación de consola .NET mediante la CLI de .NET o Visual Studio 2022.
En la parte superior de Visual Studio, vaya a Archivo>Nuevo>proyecto....
En la ventana de diálogo, escriba aplicación de consola en el cuadro de búsqueda de la plantilla de proyecto y seleccione el primer resultado. Elija Siguiente en la parte inferior del cuadro de diálogo.
En Nombre del proyecto, escriba BlobQuickstart. Deje los valores predeterminados para el resto de los campos y seleccione Siguiente.
Para Marco, asegúrese de que .NET 6.0 esté seleccionado. Luego, elija Crear. El nuevo proyecto se abrirá dentro del entorno de Visual Studio.
Instalar el paquete
Para interactuar con Azure Blob Storage, instale la biblioteca cliente de Azure Blob Storage para .NET.
En Explorador de soluciones, haga clic con el botón derecho en el nodo Dependencias del proyecto. Seleccione Administrar paquetes NuGet.
En la ventana resultante, busque Azure.Storage.Blobs. Seleccione el resultado adecuado y haga clic en Instalar.
Configuración del código de la aplicación
Reemplace el código inicial del archivo Program.cs para que coincida con el ejemplo siguiente, que incluye las instrucciones necesarias using para este ejercicio.
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;
// See https://aka.ms/new-console-template for more information
Console.WriteLine("Hello, World!");
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.
DefaultAzureCredential es una clase que proporciona la biblioteca cliente de Azure Identity para .NET, de la que puede obtener más información en la introducción a DefaultAzureCredential. DefaultAzureCredential admite varios métodos de autenticación y determina el que se debe usar en tiempo de ejecución. Este enfoque permite que la aplicación use diferentes métodos de autenticación en distintos entornos (local frente a producción) sin implementar código específico del entorno.
El orden y las ubicaciones en las que DefaultAzureCredential busca credenciales se pueden encontrar en la información general de la biblioteca de Azure Identity.
Por ejemplo, la aplicación puede autenticarse con las credenciales de inicio de sesión de Visual Studio cuando se desarrolla localmente. A continuación, la aplicación puede usar una identidad administrada una vez se haya implementado en Azure. No se necesitan cambios de código para esta transición.
Asignación de roles a la cuenta de usuario de Azure AD
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.
En Azure Portal, busque la cuenta de almacenamiento mediante la barra de búsqueda principal o el panel de navegación de la izquierda.
En la página de información general de la cuenta de almacenamiento, seleccione Control de acceso (IAM) en el menú de la izquierda.
En la página Control de acceso (IAM), seleccione la pestaña Asignación de roles.
Seleccione + Agregar en el menú superior y, a continuación, Agregar asignación de roles en el menú desplegable resultante.
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.
En la pestaña Asignar acceso a, seleccione Usuario, grupo o entidad de servicio y, a continuación, elija + Seleccionar miembros.
En el cuadro de diálogo, busque el nombre de usuario de Azure AD (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.
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:
-
Asegúrese de que esté autenticado con la misma cuenta de Azure AD a la que asignó el rol. Puede autenticarse a través de la CLI de Azure, Visual Studio o Azure PowerShell.
Inicie sesión en Azure a través de la CLI de Azure mediante el siguiente comando:
az login -
Para usar
DefaultAzureCredential, agregue el paquete Azure.Identity a la aplicación.En Explorador de soluciones, haga clic con el botón derecho en el nodo Dependencias del proyecto. Seleccione Administrar paquetes NuGet.
En la ventana resultante, busque Azure.Identity. Seleccione el resultado adecuado y haga clic en Instalar.
Actualice el código Program.cs para que coincida con el ejemplo siguiente. Cuando el código se ejecute en la estación de trabajo local durante el desarrollo, usará las credenciales de desarrollador de la herramienta clasificada por orden de prioridad en la que ha iniciado sesión para autenticarse en Azure, como la CLI de Azure o Visual Studio.
using Azure.Storage.Blobs; using Azure.Storage.Blobs.Models; using System; using System.IO; using Azure.Identity; // TODO: Replace <storage-account-name> with your actual storage account name var blobServiceClient = new BlobServiceClient( new Uri("https://<storage-account-name>.blob.core.windows.net"), new DefaultAzureCredential());Asegúrese de actualizar el nombre de la cuenta de almacenamiento en el URI de
BlobServiceClient. El nombre de la cuenta de almacenamiento se puede encontrar en la página de información general de Azure Portal.
Nota
Cuando se implementa en Azure, se puede usar este mismo código para autorizar solicitudes a Azure Storage desde una aplicación que se ejecute en Azure. Sin embargo, deberá habilitar la identidad administrada en la aplicación en Azure. A continuación, configure la cuenta almacenamiento para permitir que esa identidad administrada se conecte. Para obtener instrucciones detalladas sobre la configuración de esta conexión entre los servicios de Azure, consulte el tutorial Autenticación desde aplicaciones hospedadas en Azure.
Modelo de objetos
Azure Blob Storage está optimizado para el almacenamiento de cantidades masivas de datos no estructurados. Los datos no estructurados 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 las siguientes clases de .NET para interactuar con estos recursos:
- BlobServiceClient: La clase
BlobServiceClientpermite manipular recursos de Azure Storage y contenedores de blobs. - BlobContainerClient: La clase
BlobContainerClientpermite manipular contenedores de Azure Storage y sus blobs. - BlobClient: La clase
BlobClientpermite manipular los blobs de Azure Storage.
Ejemplos de código
Los fragmentos de código de ejemplo de las secciones siguientes muestran cómo realizar operaciones de datos básicas con la biblioteca cliente de Azure Blob Storage para .NET.
Importante
Asegúrese de que ha instalado los paquetes NuGet correctos y de que ha agregado las instrucciones mediante instrucciones para que los códigos de ejemplo funcionen, tal y como se describe en la sección de configuración.
- Azure.Identity (si usa el enfoque sin contraseña)
- Azure.Storage.Blobs
Crear un contenedor
Decida un nombre para el nuevo contenedor. El código siguiente anexa un valor de GUID al nombre de contenedor para asegurarse de que sea único.
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).
Para crear un contenedor en la cuenta de almacenamiento, puede llamar al método CreateBlobContainerAsync en blobServiceClient.
Agregue este código al final de la claseProgram.cs:
// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
new Uri("https://<storage-account-name>.blob.core.windows.net"),
new DefaultAzureCredential());
//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();
// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);
Para obtener más información sobre cómo crear un contenedor y explorar más ejemplos de código, consulte Creación de un contenedor de blobs con .NET.
Carga de un blob en un contenedor
Agregue el siguiente código al final de la clase Program.cs:
// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);
// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");
// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);
Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);
// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);
El fragmento de código completa los pasos siguientes:
- Crea un archivo de texto en el directorio data local.
- Obtiene una referencia a un objeto BlobClient llamando al método GetBlobClient en el contenedor de la sección Crear un contenedor.
- Carga el archivo de texto local en el blob llamando al método UploadAsync. Esta operación crea el blob si no existe y lo sobrescribe, en caso de que ya exista.
Para obtener más información sobre cómo cargar blobs y explorar más ejemplos de código, consulte Carga de un blob con .NET.
Listado de blobs de un contenedor
Enumere los blobs en el contenedor llamando al método GetBlobsAsync. En este caso, solo se ha agregado un blob al contenedor, por lo que la operación de enumeración devuelve simplemente dicho blob.
Agregue el siguiente código al final de la clase Program.cs:
Console.WriteLine("Listing blobs...");
// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
Console.WriteLine("\t" + blobItem.Name);
}
Para obtener más información sobre cómo enumerar blobs y explorar más ejemplos de código, consulte Enumeración de blobs con .NET.
Descarga de un blob
Llame al método DownloadToAsync para descargar el blob creado previamente. El código de ejemplo agrega el sufijo "DOWNLOADED" al nombre de archivo para que pueda ver ambos archivos en el sistema de archivos local.
Agregue el siguiente código al final de la clase Program.cs:
// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");
Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);
// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);
Para obtener más información sobre cómo descargar blobs y explorar más ejemplos de código, consulte Descarga de un blob con .NET.
Eliminación de un contenedor
El código siguiente limpia los recursos que creó; para ello, elimina todo el contenedor con DeleteAsync. También elimina los archivos locales creados por la aplicación.
La aplicación se detiene para la entrada del usuario mediante una llamada a Console.ReadLine antes de eliminar el blob, el contenedor y los archivos locales. Esta es una buena oportunidad para verificar que los recursos se han creado correctamente antes de eliminarlos.
Agregue el siguiente código al final de la clase Program.cs:
// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();
Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();
Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);
Console.WriteLine("Done");
Para obtener más información sobre cómo eliminar un contenedor y explorar más ejemplos de código, consulte Eliminación y restauración de un contenedor de blobs con .NET.
Código completo
Después de completar estos pasos, el código del archivo Program.csahora debe ser similar al siguiente:
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Identity;
// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
new Uri("https://<storage-account-name>.blob.core.windows.net"),
new DefaultAzureCredential());
//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();
// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);
// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);
// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");
// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);
Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);
// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);
Console.WriteLine("Listing blobs...");
// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
Console.WriteLine("\t" + blobItem.Name);
}
// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");
Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);
// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);
// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();
Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();
Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);
Console.WriteLine("Done");
Ejecución del código
Esta aplicación crea un archivo de prueba en la carpeta data local y lo carga en Blob Storage. Después, en el ejemplo se enumeran los blobs del contenedor y se descarga el archivo con un nombre nuevo para que pueda comparar los archivos antiguo y nuevo.
Si usa Visual Studio, presione F5 para compilar y ejecutar el código e interactuar con la aplicación de consola. Si está usando la CLI de .NET, vaya hasta el directorio de la aplicación y, a continuación, compile y ejecute la aplicación.
dotnet build
dotnet run
La salida de la aplicación es similar a la del ejemplo siguiente:
Azure Blob Storage - .NET quickstart sample
Uploading to Blob storage as blob:
https://mystorageacct.blob.core.windows.net/quickstartblobs60c70d78-8d93-43ae-954d-8322058cfd64/quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31.txt
Listing blobs...
quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31.txt
Downloading blob to
./data/quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31DOWNLOADED.txt
Press any key to begin clean up
Deleting blob container...
Deleting the local source and downloaded files...
Done
Antes de comenzar a limpiar el proceso, compruebe la carpeta data para los dos archivos. Puede abrirlos y ver que son idénticos.
Después de haber comprobado los archivos, presione la tecla Entrar para eliminar los archivos de prueba y terminar la demostración.
Pasos siguientes
En esta guía de inicio rápido, ha aprendido a cargar, descargar y enumerar blobs mediante .NET.
Para ver las aplicaciones de ejemplo de Blob Storage, siga estos pasos:
- Para obtener más información, consulte Bibliotecas cliente de Azure Blob Storage para .NET.
- Para ver tutoriales, ejemplos, inicios rápido y otra documentación, visite Azure para desarrolladores de .NET.
- Para obtener más información sobre .NET, consulte Introducción a .NET en 10 minutos.