Condividi tramite

Gestire proprietà e 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 ha un progetto esistente, questa sezione spiega come configurare un progetto per l'uso con la libreria client di Archiviazione BLOB di Azure per .NET. I passaggi includono l'installazione del pacchetto, l'aggiunta di direttive using e la creazione di un oggetto client autorizzato. Per informazioni dettagliate, vedere Introduzione ad 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 direttive using all'inizio del file del 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 using aggiuntive.

Creare un oggetto client

Per connettere un'app ad 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;
}

È possibile registrare un client del servizio per l'inserimento delle dipendenze in un'app .NET.

È anche possibile creare oggetti client per contenitori o BLOB specifici. 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 utilizzare proprietà o metadati dei contenitori. Per l'autorizzazione con Microsoft Entra ID (scelta consigliata), è necessario disporre del ruolo predefinito di Controllo degli accessi in base al ruolo di Azure Lettore dei dati del BLOB di archiviazione o ruolo superiore per le operazioni get, e del ruolo Collaboratore ai dati del BLOB di archiviazione o ruolo superiore per le operazioni set. Per altre informazioni, vedere le indicazioni sulle autorizzazioni per Set Blob Properties (API REST), Get Blob Properties (API REST), Set Blob Metadata (API REST) o Get Blob Metadata (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 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 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 diverso, ad esempio Ricerca cognitiva di Azure.

Per altre informazioni su questa funzionalità, vedere Gestire e trovare i dati in Archiviazione BLOB di Azure con l'indice BLOB.

Impostare e recuperare le proprietà

Nell'esempio di codice seguente, vengono impostati ContentType e ContentLanguage le proprietà di sistema 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, le proprietà esistenti nel BLOB vengono prima recuperate e quindi usate 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, le proprietà di sistema di un BLOB vengono recuperate e ne vengono visualizzati alcuni 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 raccolta Metadata nella risorsa. Chiamare quindi uno dei metodi seguenti per scrivere i valori:

Nell’esempio di codice seguente, vengono impostati i metadati in un BLOB. Un valore viene impostato usando il metodo di raccoltaAdd. 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 Metadati, quindi leggere i valori, come nell'esempio mostrato di seguito. Il metodo GetProperties recupera le proprietà e i metadati del BLOB chiamando sia l'operazione Get Blob Properties, sia 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 di 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 gestire le proprietà di sistema e i metadati definiti dall'utente usano le operazioni API REST seguenti:

Risorse della libreria client

Contenuto correlato

  • Questo articolo fa parte della Guida per sviluppatori di Archiviazione BLOB per .NET. Per altre informazioni, vedere l’elenco completo degli articoli della Guida per sviluppatori inCreare la propria app .NET.