Inicio rápido: Biblioteca cliente de Azure Blob Storage v12 para .NETQuickstart: Azure Blob storage client library v12 for .NET

Introducción a la biblioteca cliente de Azure Blob Storage v12 para .NET.Get started with the Azure Blob storage client library v12 for .NET. Azure Blob Storage es la solución de almacenamiento de objetos de Microsoft para la nube.Azure Blob storage is Microsoft's object storage solution for the cloud. Siga los pasos para instalar el paquete y probar el código de ejemplo para realizar tareas básicas.Follow steps to install the package and try out example code for basic tasks. Blob Storage está optimizado para el almacenamiento de cantidades masivas de datos no estructurados.Blob storage is optimized for storing massive amounts of unstructured data.

Use la biblioteca cliente de Azure Blob Storage v12 para .NET para:Use the Azure Blob storage client library v12 for .NET to:

  • Crear un contenedorCreate a container
  • Cargar un blob en Azure StorageUpload a blob to Azure Storage
  • Enumerar todos los blobs de un contenedorList all of the blobs in a container
  • Descargar el blob en el equipo localDownload the blob to your local computer
  • Eliminación de un contenedorDelete a container

Recursos adicionales:Additional resources:

Nota

Las características que se describen en este artículo ya están disponibles para las cuentas que tienen un espacio de nombres jerárquico.The features described in this article are now available to accounts that have a hierarchical namespace. Para revisar las limitaciones, consulte el artículo Características de Blob Storage disponibles en Azure Data Lake Storage Gen2.To review limitations, see the Blob storage features available in Azure Data Lake Storage Gen2 article.

Requisitos previosPrerequisites

InstalaciónSetting up

En esta sección se explica cómo preparar un proyecto para que funcione con la biblioteca cliente de Azure Blob Storage v12 para .NET.This section walks you through preparing a project to work with the Azure Blob storage client library v12 for .NET.

Creación del proyectoCreate the project

Cree una aplicación de .NET Core llamada BlobQuickstartV12.Create a .NET Core application named BlobQuickstartV12.

  1. En una ventana de consola (por ejemplo, cmd, PowerShell o Bash), use el comando dotnet new para crear una nueva aplicación de consola con el nombre BlobQuickstartV12.In a console window (such as cmd, PowerShell, or Bash), use the dotnet new command to create a new console app with the name BlobQuickstartV12. Este comando crea un sencillo proyecto "Hola mundo" de C# con un solo archivo de origen: Program.cs.This command creates a simple "Hello World" C# project with a single source file: Program.cs.

    dotnet new console -n BlobQuickstartV12
    
  2. Cambie al directorio BlobQuickstartV12 recién creado.Switch to the newly created BlobQuickstartV12 directory.

    cd BlobQuickstartV12
    
  3. En el directorio BlobQuickstartV12, cree otro directorio denominado data.In side the BlobQuickstartV12 directory, create another directory called data. Aquí es donde se crearán y almacenarán los archivos de datos de blobs.This is where the blob data files will be created and stored.

    mkdir data
    

Instalar el paqueteInstall the package

Mientras sigue en el directorio de aplicaciones, instale el paquete de la biblioteca de cliente de Azure Blob Storage para .NET con el comando dotnet add package.While still in the application directory, install the Azure Blob storage client library for .NET package by using the dotnet add package command.

dotnet add package Azure.Storage.Blobs

Instalación del marco de la aplicaciónSet up the app framework

Desde el directorio del proyecto:From the project directory:

  1. Abra el archivo Program.cs en el editor.Open the Program.cs file in your editor
  2. Quite la instrucción Console.WriteLine("Hello World!");.Remove the Console.WriteLine("Hello World!"); statement
  3. Agregue directivas using.Add using directives
  4. Actualice la declaración del método Main para admitir código asincrónico.Update the Main method declaration to support async code

Este es el código:Here's the code:

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;
using System.Threading.Tasks;

namespace BlobQuickstartV12
{
    class Program
    {
        static async Task Main()
        {
        }
    }
}

Copia de las credenciales desde Azure PortalCopy your credentials from the Azure portal

Cuando la aplicación de ejemplo realiza una solicitud a Azure Storage, debe estar autorizada.When the sample application makes a request to Azure Storage, it must be authorized. Para autorizar una solicitud, agregue a la aplicación las credenciales de la cuenta de almacenamiento en forma de cadena de conexión.To authorize a request, add your storage account credentials to the application as a connection string. Para ver las credenciales de la cuenta de almacenamiento, siga estos pasos:View your storage account credentials by following these steps:

  1. Inicie sesión en Azure Portal.Sign in to the Azure portal.

  2. Busque su cuenta de almacenamiento.Locate your storage account.

  3. En la sección Configuración de la información general de la cuenta de almacenamiento, seleccione Claves de acceso.In the Settings section of the storage account overview, select Access keys. Aquí puede ver las claves de acceso de la cuenta, así como la cadena de conexión completa de cada clave.Here, you can view your account access keys and the complete connection string for each key.

  4. Busque el valor de Cadena de conexión en key1 y seleccione el botón Copiar para copiar la cadena de conexión.Find the Connection string value under key1, and select the Copy button to copy the connection string. En el paso siguiente, agregará el valor de la cadena de conexión a una variable de entorno.You will add the connection string value to an environment variable in the next step.

    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.Configure your storage connection string

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.After you have copied your connection string, write it to a new environment variable on the local machine running the application. Para establecer la variable de entorno, abra una ventana de consola y siga las instrucciones de su sistema operativo.To set the environment variable, open a console window, and follow the instructions for your operating system. Reemplace <yourconnectionstring> por la cadena de conexión real.Replace <yourconnectionstring> with your actual connection string.

WindowsWindows

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.After you add the environment variable in Windows, you must start a new instance of the command window.

LinuxLinux

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

macOSmacOS

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Reiniciar programasRestart programs

Después de agregar la variable de entorno, reinicie todos los programas en ejecución que necesiten leer esta variable.After you add the environment variable, restart any running programs that will need to read the environment variable. Por ejemplo, reinicie el entorno de desarrollo o el editor antes de continuar.For example, restart your development environment or editor before continuing.

Modelo de objetosObject model

Azure Blob Storage está optimizado para el almacenamiento de cantidades masivas de datos no estructurados.Azure Blob storage is optimized for storing massive amounts of unstructured data. Los datos no estructurados son datos que no cumplen un modelo de datos o definición concreta, como texto o datos binarios.Unstructured data is data that does not adhere to a particular data model or definition, such as text or binary data. Blob Storage ofrece tres tipos de recursos:Blob storage offers three types of resources:

  • La cuenta de almacenamientoThe storage account
  • Un contenedor en la cuenta de almacenamientoA container in the storage account
  • Un blob en el contenedorA blob in the container

En el siguiente diagrama se muestra la relación entre estos recursos.The following diagram shows the relationship between these resources.

Diagrama de arquitectura de Blob Storage

Use las siguientes clases de .NET para interactuar con estos recursos:Use the following .NET classes to interact with these resources:

  • BlobServiceClient: La clase BlobServiceClient permite manipular recursos de Azure Storage y contenedores de blobs.BlobServiceClient: The BlobServiceClient class allows you to manipulate Azure Storage resources and blob containers.
  • BlobContainerClient: La clase BlobContainerClient permite manipular contenedores de Azure Storage y sus blobs.BlobContainerClient: The BlobContainerClient class allows you to manipulate Azure Storage containers and their blobs.
  • BlobClient: La clase BlobClient permite manipular los blobs de Azure Storage.BlobClient: The BlobClient class allows you to manipulate Azure Storage blobs.
  • BlobDownloadInfo: La clase BlobDownloadInfo representa las propiedades y el contenido devuelto por la descarga de un blob.BlobDownloadInfo: The BlobDownloadInfo class represents the properties and content returned from downloading a blob.

Ejemplos de códigoCode examples

Estos fragmentos de código de ejemplo muestran cómo realizar las siguientes acciones con la biblioteca de cliente de Azure Blob Storage para. NET:These example code snippets show you how to perform the following with the Azure Blob storage client library for .NET:

Obtención de la cadena de conexiónGet the connection string

El código siguiente recupera la cadena de conexión de la cuenta de almacenamiento de la variable de entorno creada en la sección Configuración de la cadena de conexión de almacenamiento.The code below retrieves the connection string for the storage account from the environment variable created in the Configure your storage connection string section.

Agregue este código dentro del método Main:Add this code inside the Main method:

Console.WriteLine("Azure Blob storage v12 - .NET quickstart sample\n");

// 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. If the
// environment variable is created after the application is launched in a
// console or with Visual Studio, the shell or application needs to be closed
// and reloaded to take the environment variable into account.
string connectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");

Crear un contenedorCreate a container

Decida un nombre para el nuevo contenedor.Decide on a name for the new container. El código siguiente anexa un valor de GUID al nombre de contenedor para asegurarse de que sea único.The code below appends a GUID value to the container name to ensure that it is unique.

Importante

Los nombres de contenedor deben estar en minúsculas.Container names must be lowercase. 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).For more information about naming containers and blobs, see Naming and Referencing Containers, Blobs, and Metadata.

Cree una instancia de la clase BlobServiceClient.Create an instance of the BlobServiceClient class. A continuación, llame al método CreateBlobContainerAsync para crear el contenedor en la cuenta de almacenamiento.Then, call the CreateBlobContainerAsync method to create the container in your storage account.

Agregue este código al final del método Main:Add this code to the end of the Main method:

// Create a BlobServiceClient object which will be used to create a container client
BlobServiceClient blobServiceClient = new BlobServiceClient(connectionString);

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

Carga de los blobs en un contenedorUpload blobs to a container

El siguiente fragmento de código:The following code snippet:

  1. Crea un archivo de texto en el directorio data local.Creates a text file in the local data directory.
  2. Obtiene una referencia a un objeto BlobClient llamando al método GetBlobClient en el contenedor de la sección Crear un contenedor.Gets a reference to a BlobClient object by calling the GetBlobClient method on the container from the Create a container section.
  3. Carga el archivo de texto local en el blob llamando al método UploadAsync.Uploads the local text file to the blob by calling the UploadAsync method. Esta operación crea el blob si no existe y lo sobrescribe, en caso de que ya exista.This method creates the blob if it doesn't already exist, and overwrites it if it does.

Agregue este código al final del método Main:Add this code to the end of the Main method:

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "./data/";
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);

// Open the file and upload its data
using FileStream uploadFileStream = File.OpenRead(localFilePath);
await blobClient.UploadAsync(uploadFileStream, true);
uploadFileStream.Close();

Enumerar los blobs de un contenedorList the blobs in a container

Enumere los blobs en el contenedor llamando al método GetBlobsAsync.List the blobs in the container by calling the GetBlobsAsync method. En este caso, solo se ha agregado un blob al contenedor, por lo que la operación de enumeración devuelve simplemente dicho blob.In this case, only one blob has been added to the container, so the listing operation returns just that one blob.

Agregue este código al final del método Main:Add this code to the end of the Main method:

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

Descargar blobsDownload blobs

Descargue el blob creado previamente llamando al método DownloadAsync.Download the previously created blob by calling the DownloadAsync method. 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.The example code adds a suffix of "DOWNLOADED" to the file name so that you can see both files in local file system.

Agregue este código al final del método Main:Add this code to the end of the Main method:

// 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
BlobDownloadInfo download = await blobClient.DownloadAsync();

using (FileStream downloadFileStream = File.OpenWrite(downloadFilePath))
{
    await download.Content.CopyToAsync(downloadFileStream);
    downloadFileStream.Close();
}

Eliminación de un contenedorDelete a container

El código siguiente limpia los recursos que creó; para ello, elimina todo el contenedor con DeleteAsync.The following code cleans up the resources the app created by deleting the entire container by using DeleteAsync. También elimina los archivos locales creados por la aplicación.It also deletes the local files created by the app.

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.The app pauses for user input by calling Console.ReadLine before it deletes the blob, container, and local files. Esta es una buena oportunidad para verificar que los recursos se han creado correctamente antes de eliminarlos.This is a good chance to verify that the resources were actually created correctly, before they are deleted.

Agregue este código al final del método Main:Add this code to the end of the Main method:

// 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ódigoRun the code

Esta aplicación crea un archivo de prueba en la carpeta data local y lo carga en Blob Storage.This app creates a test file in your local data folder and uploads it to 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.The example then lists the blobs in the container and downloads the file with a new name so that you can compare the old and new files.

Vaya al directorio de la aplicación y compile y ejecute la aplicación.Navigate to your application directory, then build and run the application.

dotnet build
dotnet run

La salida de la aplicación es similar a la del ejemplo siguiente:The output of the app is similar to the following example:

Azure Blob storage v12 - .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.Before you begin the clean up process, check your data folder for the two files. Puede abrirlos y ver que son idénticos.You can open them and observe that they are identical.

Después de haber comprobado los archivos, presione la tecla Entrar para eliminar los archivos de prueba y terminar la demostración.After you've verified the files, press the Enter key to delete the test files and finish the demo.

Pasos siguientesNext steps

En esta guía de inicio rápido, ha aprendido a cargar, descargar y enumerar blobs mediante .NET.In this quickstart, you learned how to upload, download, and list blobs using .NET.

Para ver las aplicaciones de ejemplo de Blob Storage, siga estos pasos:To see Blob storage sample apps, continue to: