Compartir vía

Administración de propiedades y metadatos de blobs con .NET

  • Artículo

Además de los datos que contienen, los blobs admiten propiedades del sistema y metadatos definidos por el usuario. En este artículo se muestra cómo administrar propiedades del sistema y metadatos definidos por el usuario con la biblioteca cliente de Azure Storage para .NET.

Requisitos previos

Configurar el entorno

Si no tiene un proyecto existente, en esta sección se muestra cómo configurar un proyecto para que funcione con la biblioteca cliente de Azure Blob Storage para .NET. Los pasos incluyen la instalación del paquete, la adición de directivas using, y la creación de un objeto de cliente autorizado. Para más información, consulte Introducción a Azure Blob Storage y .NET.

Instalar paquetes

En el directorio del proyecto, instale los paquetes para las bibliotecas cliente de Azure Blob Storage y Azure Identity mediante el comando dotnet add package. El paquete Azure.Identity es necesario para las conexiones sin contraseña a los servicios de Azure.

dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Identity

Agregue directivas using.

Agregue estas directivas using al principio del archivo de código:

using Azure.Identity;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;

Algunos ejemplos de código de este artículo pueden requerir using directivas adicionales.

Creación de un objeto de cliente

Para conectar una aplicación a Blob Storage, cree una instancia de BlobServiceClient. En el ejemplo siguiente se muestra cómo crear un objeto de cliente mediante DefaultAzureCredential para la autorización:

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net"),
        new DefaultAzureCredential());

    return client;
}

También puede registrar un cliente de servicio para la inserción de dependencias en una aplicación .NET. Para obtener más información sobre cómo crear y administrar objetos de cliente, consulte Crear y administrar objetos de cliente que interactúan con los recursos de datos.

Authorization

El mecanismo de autorización debe tener los permisos necesarios para trabajar con propiedades o metadatos del contenedor. Para la autorización con Microsoft Entra ID (recomendada), necesita el rol integrado de RBAC de Azure Lector de datos de Storage Blob o superior para las operaciones get, y el rol Colaborador de datos de blobs de Almacenamiento o superior para las operaciones set. Para obtener más información, consulte la guía de autorización de Establecer propiedades de blobs (API de REST), Obtener propiedades de blobs (API de REST), Establecer metadatos de blobs (API de REST) u Obtener metadatos de blobs (API de REST).

Acerca de las propiedades y los metadatos

  • Propiedades del sistema: en cada recurso de almacenamiento de blobs existen propiedades del sistema. Algunas se pueden leer o establecer, mientras que otras son de solo lectura. En segundo plano, algunas propiedades del sistema corresponden a ciertos encabezados HTTP estándar. La biblioteca cliente de Azure Storage para .NET mantiene estas propiedades automáticamente.

  • Metadatos definidos por el usuario: los metadatos definidos por el usuario se componen de uno o más pares nombre-valor que especifica para un recurso de almacenamiento de blobs. Puede usar metadatos para almacenar valores adicionales con el recurso. Los valores de metadatos se proporcionan para uso personal y no afectan a cómo se comporta el recurso.

    Los pares de nombre/valor de metadatos son encabezados HTTP válidos y deben cumplir todas las restricciones que gobiernan los encabezados HTTP. Para obtener más información sobre los requisitos de nomenclatura de metadatos, consulte Nombres de metadatos.

Nota:

Las etiquetas del índice de blobs ofrecen la capacidad de almacenar atributos arbitrarios de clave-valor definidas por el usuario junto con un recurso de Azure Blob Storage. De manera similar a los metadatos, solo las etiquetas del índice de blobs se indexan automáticamente y son objeto de búsquedda mediante el Blob service nativo. Los metadatos no se pueden indexar ni consultar, a menos que se use un servicio independiente, como Azure Search.

Para obtener más información sobre esta característica, consulte Administración y búsqueda de datos de Azure Blob con etiquetas de índice de blobs.

Establecimiento y recuperación de propiedades

En el ejemplo de código siguiente se establecen las propiedades del sistema ContentType y ContentLanguage en un blob.

Para establecer las propiedades de un blob, llame a SetHttpHeaders o SetHttpHeadersAsync. Se borran todas las propiedades no establecidas explícitamente. En el siguiente ejemplo de código se obtienen primero las propiedades existentes en el blob y, a continuación, se usan para rellenar los encabezados que no se están actualizando.

public static async Task SetBlobPropertiesAsync(BlobClient blob)
{
    Console.WriteLine("Setting blob properties...");

    try
    {
        // Get the existing properties
        BlobProperties properties = await blob.GetPropertiesAsync();

        BlobHttpHeaders headers = new BlobHttpHeaders
        {
            // Set the MIME ContentType every time the properties 
            // are updated or the field will be cleared
            ContentType = "text/plain",
            ContentLanguage = "en-us",

            // Populate remaining headers with 
            // the pre-existing properties
            CacheControl = properties.CacheControl,
            ContentDisposition = properties.ContentDisposition,
            ContentEncoding = properties.ContentEncoding,
            ContentHash = properties.ContentHash
        };

        // Set the blob's properties.
        await blob.SetHttpHeadersAsync(headers);
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"HTTP error code {e.Status}: {e.ErrorCode}");
        Console.WriteLine(e.Message);
        Console.ReadLine();
    }
}

En el ejemplo de código siguiente se obtienen las propiedades del sistema de un blob y se muestran algunos de los valores.

private static async Task GetBlobPropertiesAsync(BlobClient blob)
{
    try
    {
        // Get the blob properties
        BlobProperties properties = await blob.GetPropertiesAsync();

        // Display some of the blob's property values
        Console.WriteLine($" ContentLanguage: {properties.ContentLanguage}");
        Console.WriteLine($" ContentType: {properties.ContentType}");
        Console.WriteLine($" CreatedOn: {properties.CreatedOn}");
        Console.WriteLine($" LastModified: {properties.LastModified}");
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"HTTP error code {e.Status}: {e.ErrorCode}");
        Console.WriteLine(e.Message);
        Console.ReadLine();
    }
}

Establecimiento y recuperación de metadatos

Puede especificar metadatos como uno o más pares nombre-valor en un recurso de blob o contenedor. Para establecer los metadatos, agregue pares nombre-valor a la colección Metadata del recurso. A continuación, llame a uno de los métodos siguientes para escribir los valores:

El ejemplo de código siguiente establece los metadatos en un blob. Un valor se establece mediante el método Add de la colección. El otro valor se establece mediante la sintaxis implícita de clave/valor.

public static async Task AddBlobMetadataAsync(BlobClient blob)
{
    Console.WriteLine("Adding blob metadata...");

    try
    {
        IDictionary<string, string> metadata =
           new Dictionary<string, string>();

        // Add metadata to the dictionary by calling the Add method
        metadata.Add("docType", "textDocuments");

        // Add metadata to the dictionary by using key/value syntax
        metadata["category"] = "guidance";

        // Set the blob's metadata.
        await blob.SetMetadataAsync(metadata);
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"HTTP error code {e.Status}: {e.ErrorCode}");
        Console.WriteLine(e.Message);
        Console.ReadLine();
    }
}

El ejemplo de código siguiente lee los metadatos en un blob.

Para recuperar metadatos, llame al método GetProperties o GetPropertiesAsync en el blob o contenedor para rellenar la colección Metadata y después lea los valores tal como se muestra en el ejemplo siguiente. El método GetProperties recupera las propiedades del blob y los metadatos llamando a la operación Get Blob Properties y a la operación Get Blob Metadata.

public static async Task ReadBlobMetadataAsync(BlobClient blob)
{
    try
    {
        // Get the blob's properties and metadata.
        BlobProperties properties = await blob.GetPropertiesAsync();

        Console.WriteLine("Blob metadata:");

        // Enumerate the blob's metadata.
        foreach (var metadataItem in properties.Metadata)
        {
            Console.WriteLine($"\tKey: {metadataItem.Key}");
            Console.WriteLine($"\tValue: {metadataItem.Value}");
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"HTTP error code {e.Status}: {e.ErrorCode}");
        Console.WriteLine(e.Message);
        Console.ReadLine();
    }
}

Recursos

Para obtener más información sobre cómo administrar las propiedades del sistema y los metadatos definidos por el usuario usando la biblioteca cliente de Azure Blob Storage para .NET, consulte los siguientes recursos.

Operaciones de API REST

El SDK de Azure para .NET contiene bibliotecas que se crean a partir de la API REST de Azure, lo que le permite interactuar con las operaciones de API REST a través de paradigmas conocidos de .NET. Los métodos de la biblioteca cliente para administrar las propiedades del sistema y los metadatos definidos por el usuario usan las siguientes operaciones de la API de REST:

Recursos de la biblioteca cliente