Gestire le proprietà e i metadati dei BLOB con .NET
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
- Sottoscrizione di Azure: creare un account gratuito
- Account di archiviazione di Azure: creare un account di archiviazione
- Versione più recente di .NET SDK per il sistema operativo. Assicurarsi di ottenere l'SDK e non il runtime.
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 le operazioni 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:
- Impostare le proprietà del BLOB (API REST)
- Ottenere le proprietà del BLOB (API REST)
- Impostare i metadati blob (API REST)
- Ottenere metadati BLOB (API REST)