Verwalten von Blobeigenschaften und Metadaten mit .NET

  • Artikel

Blobs unterstützen neben den darin enthaltenen Daten auch Systemeigenschaften und benutzerdefinierte Metadaten. In diesem Artikel erfahren Sie, wie Sie Systemeigenschaften und benutzerdefinierte Metadaten mithilfe der Azure Storage-Clientbibliothek für .NET verwalten.

Voraussetzungen

Erstellen Ihrer Umgebung

Wenn Sie nicht über ein vorhandenes Projekt verfügen, wird in diesem Abschnitt gezeigt, wie Sie ein Projekt für die Arbeit mit der Azure Blob Storage-Clientbibliothek für .NET einrichten. Die Schritte umfassen die Paketinstallation, das Hinzufügen von using-Anweisungen und das Erstellen eines autorisierten Clientobjekts. Ausführlichere Informationen finden Sie unter Erste Schritte mit Azure Blob Storage und .NET.

Installieren von Paketen

Installieren Sie in Ihrem Projektverzeichnis mithilfe des Befehls dotnet add package Pakete für die Azure Blob Storage- und Azure Identity-Clientbibliotheken. Für kennwortlose Verbindungen mit Azure-Diensten wird das Azure.Identity-Paket benötigt.

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

Fügen Sie Anweisungen vom Typ using hinzu.

Fügen Sie diese using-Anweisungen am Anfang der Codedatei hinzu:

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

Einige Codebeispiele in diesem Artikel erfordern möglicherweise zusätzliche using-Anweisungen.

Erstellen eines Clientobjekts

Um eine App mit Blob Storage zu verbinden, erstellen Sie eine Instanz von BlobServiceClient. Das folgende Beispiel zeigt, wie Sie ein Clientobjekt mithilfe von DefaultAzureCredential für die Autorisierung erstellen:

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

    return client;
}

Sie können einen Dienstclient für die Abhängigkeitsinjektion in einer .NET-App registrieren.

Sie können auch Clientobjekte für bestimmte Container oder Blobs erstellen. Weitere Informationen zum Erstellen und Verwalten von Clientobjekten finden Sie unter Erstellen und Verwalten von Clientobjekten, die mit Datenressourcen interagieren.

Autorisierung

Der Autorisierungsmechanismus muss über die erforderlichen Berechtigungen zum Arbeiten mit Containereigenschaften oder -metadaten verfügen. Für die Autorisierung mit Microsoft Entra ID (empfohlen) benötigen Sie mindestens die integrierte Azure RBAC-Rolle Storage-Blobdatenleser für die get-Vorgänge und mindestens Mitwirkender an Storage-Blobdaten für die set-Vorgänge. Weitere Informationen finden Sie in den Autorisierungsanleitungen für Festlegen von Blobeigenschaften (REST-API), Abrufen von Blobeigenschaften (REST-API), Festlegen von Blobmetadaten (REST-API)oder Abrufen von Blobmetadaten (REST-API).

Informationen zu Eigenschaften und Metadaten

  • Systemeigenschaften: Systemeigenschaften sind in jeder Blobspeicherressource vorhanden. Einige davon können gelesen oder festgelegt werden, während andere schreibgeschützt sind. Darüber hinaus entsprechen einige Systemeigenschaften bestimmten HTTP-Standardheadern. Die Azure Storage-Clientbibliothek für .NET verwaltet diese Eigenschaften für Sie.

  • Benutzerdefinierte Metadaten: Benutzerdefinierte Metadaten bestehen aus mindestens einem Name-Wert-Paar, das Sie für eine Blobspeicherressource angeben. Metadaten können verwendet werden, um zusätzliche Werte mit der Ressource zu speichern. Metadatenwerte sind nur für Ihre eigenen Zwecke bestimmt und wirken sich nicht auf das Verhalten der Ressource aus.

    Name/Wert-Paare für Metadaten sind gültige HTTP-Header und sollten allen Einschränkungen für HTTP-Header entsprechen. Weitere Informationen zu den Benennungsanforderungen für Metadaten finden Sie unter Metadatennamen.

Hinweis

Blobindextags bieten auch die Möglichkeit, beliebige benutzerdefinierte Schlüssel-Wert-Attribute zusammen mit einer Azure Blob Storage-Ressource zu speichern. Trotz der Ähnlichkeit mit Metadaten werden nur Blobindextags automatisch indiziert und durch den nativen Blob-Dienst suchbar gemacht. Metadaten können nicht indiziert und abgefragt werden, es sei denn, Sie verwenden einen separaten Dienst wie z. B. Azure Search.

Weitere Informationen zu dieser Funktion finden Sie unter Verwalten und Suchen von Daten in Azure Blob Storage mit dem Blobindex.

Festlegen und Abrufen von Eigenschaften

Im folgenden Codebeispiel werden die Systemeigenschaften ContentType und ContentLanguage für ein Blob festgelegt.

Um Eigenschaften für ein Blob festzulegen, rufen Sie SetHttpHeaders oder SetHttpHeadersAsync auf. Alle nicht explizit festgelegten Eigenschaften werden gelöscht. Im folgenden Codebeispiel werden zuerst die vorhandenen Eigenschaften für das Blob abgerufen und dann verwendet, um die Header aufzufüllen, die nicht aktualisiert werden.

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

Im folgenden Codebeispiel werden die Systemeigenschaften eines Blobs abgerufen und einige der Werte angezeigt.

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

Festlegen und Abrufen von Metadaten

Sie können Metadaten als ein oder mehrere Name-Wert-Paare für eine Blob- oder Containerressource angeben. Fügen Sie der Auflistung Metadata für die Ressource Name/Wert-Paare hinzu, um Metadaten festzulegen. Anschließend können Sie eine der folgenden Methoden zum Schreiben der Werte aufrufen:

Das folgende Codebeispiel legt die Metadaten für ein Blob fest. Mit der Methode Add der Sammlung wird ein Wert festgelegt. Der andere Wert wird mit der impliziten Schlüssel-Wert-Syntax festgelegt.

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

Das folgende Codebeispiel liest die Metadaten eines Blobs.

Zum Abrufen von Metadaten rufen Sie die GetProperties- oder GetPropertiesAsync-Methode für das Blob oder den Container auf, um die Metadaten-Sammlung zu füllen, und lesen anschließend die Werte wie im unten stehenden Beispiel gezeigt. Die GetProperties-Methode ruft Blobeigenschaften und Metadaten ab, indem sowohl der Vorgang Blobeigenschaften abrufen als auch der Vorgang Blobmetadaten abrufen aufgerufen wird.

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

Ressourcen

Weitere Informationen zum Verwalten von Systemeigenschaften und benutzerdefinierten Metadaten mithilfe der Azure Blob Storage-Clientbibliothek für .NET finden Sie in den folgenden Ressourcen.

REST-API-Vorgänge

Das Azure SDK für .NET enthält Bibliotheken, die auf der zugrunde liegenden Azure-REST-API basieren, und ermöglicht Ihnen dadurch die Interaktion mit REST-API-Vorgängen über vertraute .NET-Paradigmen. Die Methoden der Clientbibliothek zum Verwalten von Systemeigenschaften und benutzerdefinierten Metadaten verwenden die folgenden REST-API-Vorgänge:

Ressourcen zur Clientbibliothek

Zugehöriger Inhalt

  • Dieser Artikel ist Teil des Blob Storage-Entwicklerleitfadens für .NET. Weitere Informationen finden Sie in der vollständigen Liste der Entwicklerleitfadenartikel unter Erstellen Ihrer .NET-App.