Управление свойствами и метаданными BLOB-объектов с помощью .NET

Кроме данных, которые они содержат, BLOB-объекты поддерживают свойства системы и определяемые пользователем метаданные. В этой статье описывается управление свойствами системы и определяемыми пользователем метаданными с помощью клиентской библиотеки хранилища Azure для .NET.

Prerequisites

Подписка Azure — создайте бесплатную учетную запись.
Учетная запись хранения Azure — создайте такую учетную запись.
Последняя версия .NET SDK для вашей операционной системы. Обязательно получите пакет SDK, а не среду выполнения.

Настройка среды

Если у вас нет существующего проекта, в этом разделе показано, как настроить проект для работы с клиентской библиотекой Хранилище BLOB-объектов Azure для .NET. Ниже приведены шаги по установке пакета, добавлению using директив и созданию авторизованного клиентского объекта. Дополнительные сведения см. в статье «Начало работы с Azure Blob Storage и .NET».

Установка пакетов

В каталоге вашего проекта установите пакеты для клиентских библиотек Azure Blob Storage и Azure Identity с помощью команды dotnet add package. Пакет Azure.Identity необходим для подключений без пароля к службам Azure.

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

Добавьте директивы `using`.

Добавьте эти using директивы в начало файла кода:

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

Для некоторых примеров кода в этой статье могут потребоваться дополнительные using директивы.

Создание клиентского объекта

Чтобы подключить приложение к хранилищу BLOB-объектов, создайте экземпляр BLOBServiceClient. В следующем примере показано, как создать клиентский объект с помощью DefaultAzureCredential авторизации:

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

    return client;
}

Вы можете зарегистрировать клиент службы для внедрения зависимостей в приложении .NET.

Вы также можете создавать клиентские объекты для определенных контейнеров или блобов. Дополнительные сведения о создании клиентских объектов и управлении ими см. в статье "Создание клиентских объектов и управление ими", взаимодействующих с ресурсами данных.

Authorization

Механизм авторизации должен иметь необходимые разрешения для работы со свойствами контейнера или метаданными. Для авторизации с помощью Microsoft Entra ID (рекомендуется), вам потребуется встроенная роль Azure RBAC Storage Blob Data Reader или выше для операций get, и роль Storage Blob Data Contributor или выше для операций set. Дополнительные сведения см. в руководстве по авторизации для задания свойств BLOB-объектов (REST API), получения свойств BLOB-объектов (REST API), задания метаданных BLOB-объектов (REST API) или получения метаданных BLOB-объектов (REST API).

Сведения о свойствах и метаданных

Свойства системы: свойства системы есть у каждого ресурса хранилища BLOB-объектов. Некоторые из них можно читать или задавать, другие — только читать. На самом деле, некоторые свойства системы соответствуют определенным стандартным заголовкам HTTP. Клиентская библиотека службы хранилища Azure для .NET сохраняет эти свойства.
Определяемые пользователем метаданные: такие метаданные состоят из одной или нескольких пар "имя-значение", которые можно указать для ресурса хранилища BLOB-объектов. Вы можете использовать метаданные для хранения дополнительных значений вместе с ресурсом. Значения метаданных предназначены только для ваших собственных целей и не влияют на поведение ресурса.

Пары имен и значений метаданных являются допустимыми HTTP-заголовками, поэтому они должны соответствовать всем ограничениям для HTTP-заголовков. Дополнительные сведения о требованиях к именованию метаданных см. в разделе "Имена метаданных".

Note

Теги индекса BLOB-объектов также предоставляют возможность хранения произвольных пользовательских атрибутов ключа и значения наряду с ресурсом хранилища BLOB-объектов Azure. Аналогично метаданным только теги индекса BLOB-объектов автоматически индексируются и делаются доступными для поиска в собственной службе BLOB-объектов. Метаданные не могут индексироваться и запрашиваться, если не используется отдельная служба, например поиск Azure.

Дополнительные сведения об этой функции см. в статье "Управление и поиск данных в хранилище BLOB-объектов Azure" с помощью индекса BLOB-объектов.

Установка и получение свойств

В следующем примере кода задаются свойства системы ContentType и ContentLanguage на объекте BLOB.

Чтобы задать свойства блоба, вызовите SetHttpHeaders или SetHttpHeadersAsync. Все свойства, не заданные явно, очищаются. Пример кода сначала получает существующие свойства блоба, а затем использует их для заполнения неизменяемых заголовков.

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

Следующий пример кода получает системные свойства объекта BLOB и отображает некоторые из значений.

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

Настройка и извлечение метаданных

Метаданные можно указать в виде одной или нескольких пар "имя-значение" для объекта BLOB или контейнера. Чтобы задать метаданные, добавьте пары "имя-значение" в коллекцию Metadata ресурса. Затем вызовите один из следующих методов для записи значений:

Пример следующего кода устанавливает метаданные на BLOB. Одно значение задается с помощью метода коллекции Add . Другое значение задается с помощью синтаксиса неявного ключа или значения.

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

В следующем примере кода считываются метаданные большого двоичного объекта.

Чтобы получить метаданные, вызовите метод GetProperties или GetPropertiesAsync для вашего облака или контейнера, чтобы заполнить коллекцию Metadata, а затем прочитайте значения, как показано в приведенном ниже примере. Метод GetProperties извлекает свойства и метаданные большого двоичного объекта, вызывая операцию Get Blob Properties и операцию 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();
    }
}

Resources

Дополнительные сведения об управлении свойствами системы и пользовательскими метаданными с помощью клиентской библиотеки хранилища BLOB-объектов Azure для .NET см. в следующих ресурсах.

Операции REST API

Пакет SDK Azure для .NET содержит библиотеки, которые создаются на основе REST API Azure, что позволяет взаимодействовать с операциями REST API через знакомые парадигмы .NET. Методы клиентской библиотеки для управления системными свойствами и пользовательскими метаданными используют следующие операции REST API:

Установка свойств Blob (REST API)
Получение свойств BLOB-объектов (REST API)
Настройка метаданных BLOB-объектов (REST API)
Получение метаданных BLOB-объектов (REST API)

Ресурсы клиентской библиотеки

Эта статья является частью руководства разработчика хранилища BLOB-объектов для .NET. Дополнительные сведения см. в полном списке статей руководства разработчика по созданию приложения .NET.

Обратная связь

Была ли эта страница полезна?

Last updated on 2025-10-09