Condividi tramite

Gestire le proprietà e i metadati dei BLOB con .NET

  • Articolo

Oltre ai dati che contengono, i BLOB supportano le proprietà di sistema e i metadati definiti dall'utente. Questo articolo illustra come gestire le proprietà di sistema e i metadati definiti dall'utente con la libreria client di Archiviazione di Azure per .NET.

Prerequisiti

Configurazione dell'ambiente

Se non si dispone di un progetto esistente, questa sezione illustra come configurare un progetto per l'uso con la libreria client Archiviazione BLOB di Azure per .NET. I passaggi includono l'installazione dei pacchetti, l'aggiunta using di direttive e la creazione di un oggetto client autorizzato. Per informazioni dettagliate, vedere Introduzione a Archiviazione BLOB di Azure e .NET.

Installare i pacchetti

Nella directory del progetto installare i pacchetti per le librerie client di Archiviazione BLOB di Azure e Azure Identity usando il comando dotnet add package. Il pacchetto Azure.Identity è necessario per le connessioni senza password ai servizi di Azure.

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

Aggiungere le direttive using

Aggiungere queste using direttive all'inizio del file di codice:

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

Alcuni esempi di codice in questo articolo potrebbero richiedere direttive aggiuntive using .

Creare un oggetto client

Per connettere un'app all'archiviazione BLOB, creare un'istanza di BlobServiceClient. Nell'esempio seguente viene illustrato come creare un oggetto client usando DefaultAzureCredential per l'autorizzazione:

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

    return client;
}

È anche possibile registrare un client del servizio per l'inserimento delle dipendenze in un'app .NET. Per altre informazioni sulla creazione e la gestione di oggetti client, vedere Creare e gestire oggetti client che interagiscono con le risorse dati.

Autorizzazione

Il meccanismo di autorizzazione deve disporre delle autorizzazioni necessarie per lavorare con le proprietà o i metadati del contenitore. Per l'autorizzazione con Microsoft Entra ID (scelta consigliata), per le operazioni get è necessario disporre del ruolo predefinito controllo degli accessi in base al ruolo di Azure per l'utilità di lettura dei dati dei BLOB di archiviazione o versione successiva per leoperazioni get. Per altre informazioni, vedere le linee guida per l'autorizzazione per l'impostazione delle proprietà BLOB (API REST), Get Blob Properties (API REST), Set Blob Metadata (REST API) (Imposta metadati BLOB (API REST) o Recupera metadati BLOB (API REST).

Informazioni su proprietà e metadati

  • Proprietà di sistema: le proprietà di sistema esistono in ogni risorsa di archiviazione BLOB. Alcune di esse possono essere lette o impostate, mentre altre sono di sola lettura. Anche se in modo non esplicito, alcune proprietà di sistema corrispondono a specifiche intestazioni HTTP standard. La libreria client di Archiviazione di Azure per .NET mantiene queste proprietà per l'utente.

  • Metadati definiti dall'utente: i metadati definiti dall'utente sono costituiti da una o più coppie nome-valore specificate per una risorsa di archiviazione BLOB. È possibile usare i metadati per archiviare valori aggiuntivi con la risorsa. I valori di metadati sono solo per le proprie esigenze e non influiscono sul comportamento della risorsa.

    Le coppie nome/valore di metadati sono intestazioni HTTP valide e devono essere conformi alle restrizioni imposte sulle intestazioni HTTP. Per ulteriori informazioni sui requisiti di denominazione dei metadati, consultare Nomi dei metadati.

Nota

I tag di indice BLOB offrono anche la possibilità di archiviare attributi chiave/valore arbitrari definiti dall'utente insieme a una risorsa di archiviazione BLOB di Azure. Analogamente ai metadati, solo i tag di indice BLOB vengono indicizzati automaticamente e resi ricercabili dal servizio BLOB nativo. I metadati non possono essere indicizzati e sottoposti a query a meno che non si usi un servizio separato, ad esempio Ricerca di Azure.

Per altre informazioni su questa funzionalità, vedere Gestire e trovare dati nell'archivio BLOB di Azure con indice BLOB.

Impostare e recuperare le proprietà

Nell'esempio di codice seguente vengono impostate le proprietà di ContentType sistema e ContentLanguage in un BLOB.

Per impostare le proprietà in un BLOB, chiamare SetHttpHeaders o SetHttpHeadersAsync. Tutte le proprietà non impostate in modo esplicito vengono cancellate. Nell'esempio di codice seguente vengono prima recuperate le proprietà esistenti nel BLOB, quindi le usa per popolare le intestazioni che non vengono aggiornate.

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

Nell'esempio di codice seguente vengono recuperate le proprietà di sistema di un BLOB e vengono visualizzati alcuni dei valori.

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

Impostare e recuperare i metadati

È possibile specificare i metadati come uno o più coppie nome-valore in una risorsa BLOB o contenitore. Per impostare i metadati, aggiungere coppie nome-valore alla Metadata raccolta nella risorsa. Chiamare quindi uno dei metodi seguenti per scrivere i valori:

L'esempio di codice seguente imposta i metadati in un BLOB. Un valore viene impostato usando il metodo della Add raccolta. L'altro valore è impostato utilizzando la sintassi implicita chiave/valore.

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

Nell'esempio di codice seguente vengono letti i metadati in un BLOB.

Per recuperare i metadati, chiamare il metodo GetProperties o GetPropertiesAsync nel BLOB o nel contenitore per popolare la raccolta Metadata, quindi leggere i valori, come illustrato nell'esempio seguente. Il GetProperties metodo recupera le proprietà e i metadati del BLOB chiamando sia l'operazione Get Blob Properties che l'operazione 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();
    }
}

Risorse

Per altre informazioni su come gestire le proprietà di sistema e i metadati definiti dall'utente usando la libreria client Archiviazione BLOB di Azure per .NET, vedere le risorse seguenti.

Operazioni dell'API REST

Azure SDK per .NET contiene librerie basate sull'API REST di Azure che consentono di interagire con le operazioni dell'API REST tramite paradigmi .NET noti. I metodi della libreria client per la gestione delle proprietà di sistema e dei metadati definiti dall'utente usano le operazioni API REST seguenti:

Risorse della libreria client