Поделиться через


Создание клиентских объектов, взаимодействующих с ресурсами данных, и управление ими

Пакеты SDK Azure — это коллекции библиотек, созданные для упрощения использования служб Azure на разных языках. Пакеты SDK предназначены для упрощения взаимодействия между приложением и ресурсами Azure. Работа с ресурсами Azure с помощью пакета SDK начинается с создания экземпляра клиента. В этой статье показано, как создавать клиентские объекты для взаимодействия с ресурсами данных в Хранилище BLOB-объектов Azure и предлагает рекомендации по управлению клиентами в приложении.

Сведения о клиентских объектах

Клиентские библиотеки Хранилище BLOB-объектов Azure позволяют взаимодействовать с тремя типами ресурсов в службе хранилища:

  • Учетные записи хранения
  • контейнеров BLOB-объектов;
  • BLOB-объекты

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

Для больших двоичных объектов существует общий клиент BLOB-объектов, охватывающий общие операции больших двоичных объектов для всех типов, а также специализированные клиенты больших двоичных объектов для каждого типа (блочный большой двоичный объект, добавление большого двоичного объекта и страничный большой двоичный объект).

В следующей таблице перечислены различные клиентские классы для каждого языка:

Язык Пакеты Класс клиента службы Класс клиента контейнера Клиентские классы BLOB-объектов
.NET Azure.Storage.Blobs
Azure. служба хранилища. Blobs.Models
Azure. служба хранилища. Blbs.Specialized
BlobServiceClient BlobContainerClient BlobClient
BlockBlobClient
AppendBlobClient
PageBlobClient
Java com.azure.storage.blob
com.azure.storage.blob.models
com.azure.storage.blob.specialized
BlobServiceClient
BlobServiceAsyncClient
BlobServiceClientBuilder
BlobContainerClient
BlobContainerAsyncClient
BlobContainerClientBuilder
BlobClient
BlobAsyncClient
BlobClientBuilder
BlockBlobClient
AppendBlobClient
PageBlobClient
JavaScript @azure/storage-blob BlobServiceClient ContainerClient BlobClient
BlockBlobClient
AppendBlobClient
PageBlobClient
Python azure.storage.blob BlobServiceClient ContainerClient BlobClient1

1 Для Python BlobClient включает методы для специализированных типов BLOB-объектов.

Каждый тип клиента можно создать экземпляр, вызвав простой конструктор или перегрузку, которая принимает различные параметры конфигурации. Для Java каждый тип клиента имеет отдельный класс, который предоставляет API построителя для поддержки конфигурации и создания экземпляров. В зависимости от языкового пакета SDK эти параметры конфигурации клиента передаются конструктору разными способами. Дополнительные сведения см. в справочнике по классу из таблицы.

Авторизация клиентского объекта

Чтобы приложение получите доступ к ресурсам BLOB-объектов и взаимодействовать с ними, клиентский объект должен быть авторизован. Примеры кода в этой статье используют DefaultAzureCredential для проверки подлинности в Azure с помощью субъекта безопасности Microsoft Entra. Процесс проверки подлинности включает получение маркера доступа для авторизации. Этот маркер доступа передается в качестве учетных данных при создании экземпляра клиента, а учетные данные сохраняются в течение всего времени существования клиента. Субъект безопасности Microsoft Entra, запрашивающий маркер, должен быть назначен соответствующая роль Azure RBAC, которая предоставляет доступ к данным BLOB-объектов. Дополнительные сведения см. в статье "Назначение роли Azure для доступа к данным BLOB-объектов".

Для предоставления соответствующего уровня доступа к объекту клиента можно использовать следующие механизмы авторизации:

Дополнительные сведения о авторизации см. в статье "Авторизация доступа к данным" в служба хранилища Azure.

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

Работа с любым ресурсом Azure с помощью пакета SDK начинается с создания клиентского объекта. В этом разделе описано, как создать клиентские объекты для взаимодействия с тремя типами ресурсов в службе хранения: учетными записями хранения, контейнерами и большими двоичными объектами.

При создании клиентского объекта приложение передает универсальный код ресурса (URI), ссылающийся на конечную точку конструктору клиента. Строку конечной точки можно создать вручную, как показано в примерах в этой статье, или запросить конечную точку во время выполнения с помощью библиотеки управления служба хранилища Azure. Сведения о том, как запрашивать конечную точку, см. в статье "Запрос для конечной точки служба хранилища BLOB-объекта".

Создание объекта BlobServiceClient

Авторизованный BlobServiceClient объект позволяет приложению взаимодействовать с ресурсами на уровне учетной записи хранения. BlobServiceClient предоставляет методы для получения и настройки свойств учетной записи, а также списка, создания и удаления контейнеров в учетной записи хранения. Этот клиентский объект является отправной точкой для взаимодействия с ресурсами в учетной записи хранения.

Типичным сценарием является создание экземпляра одного клиента службы, а затем создание клиентов контейнеров и клиентов БОЛЬШИХ двоичных объектов из клиента службы по мере необходимости. Для работы с определенным контейнером или большим двоичным объектом можно использовать BlobServiceClient объект для создания клиента контейнера или клиента BLOB-объектов. Клиенты, созданные BlobServiceClient из конфигурации клиента, наследуют ее конфигурацию, включая параметры клиента и учетные данные.

В следующих примерах показано, как создать BlobServiceClient объект:

Затем добавьте следующие using директивы:

using Azure.Identity;
using Azure.Storage.Blobs;

Добавьте следующий код для создания клиентского объекта:

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

    return client;
}

Создание объекта BlobContainerClient

Объект можно использовать BlobServiceClient для создания нового BlobContainerClient объекта (ContainerClient для JavaScript и Python). Объект BlobContainerClient позволяет взаимодействовать с определенным ресурсом контейнера. Этот ресурс не должен существовать в учетной записи хранения для создания клиентского объекта. BlobContainerClient предоставляет методы для создания, удаления или настройки контейнера и включает методы для перечисления, отправки и удаления больших двоичных объектов в нем. Для выполнения операций с определенным большим двоичным объектом в контейнере можно создать клиент БОЛЬШОго двоичного объекта.

В следующих примерах показано, как создать клиент контейнера из BlobServiceClient объекта для взаимодействия с определенным ресурсом контейнера:

public BlobContainerClient GetBlobContainerClient(
    BlobServiceClient blobServiceClient,
    string containerName)
{
    // Create the container client using the service client object
    BlobContainerClient client = blobServiceClient.GetBlobContainerClient(containerName);
    return client;
}

Если работа узко область в один контейнер, вы можете создать BlobContainerClient объект непосредственно без использованияBlobServiceClient. Параметры клиента по-прежнему можно задать на клиенте контейнера так же, как и в клиенте службы.

В следующих примерах показано, как создать клиент контейнера напрямую без использования BlobServiceClient:

public BlobContainerClient GetBlobContainerClient(
    string accountName,
    string containerName,
    BlobClientOptions clientOptions)
{
    // Append the container name to the end of the URI
    BlobContainerClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net/{containerName}"),
        new DefaultAzureCredential(),
        clientOptions);

    return client;
}

Создание объекта BLOBClient

Чтобы взаимодействовать с определенным ресурсом BLOB-объектов, создайте BlobClient объект из клиента службы или клиента контейнера. Объект BlobClient позволяет взаимодействовать с определенным ресурсом BLOB-объектов. Этот ресурс не должен существовать в учетной записи хранения для создания клиентского объекта. BlobClient предоставляет методы для отправки, скачивания, удаления и создания моментальных снимков большого двоичного объекта.

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

public BlobClient GetBlobClient(
    BlobServiceClient blobServiceClient,
    string containerName,
    string blobName)
{
    BlobClient client =
        blobServiceClient.GetBlobContainerClient(containerName).GetBlobClient(blobName);
    return client;
}

Управление клиентскими объектами

Рекомендуется управлять клиентами Пакета SDK Azure для обработки клиента как однотонного, что означает, что класс будет одновременно иметь только один объект. Нет необходимости хранить несколько экземпляров клиента для заданного набора параметров конструктора или параметров клиента. Эта концепция может быть реализована различными способами, в том числе:

  • Создание одного клиентского объекта и передача его в качестве параметра во всем приложении. Этот подход показан в примерах кода в этой статье.
  • Хранение экземпляра клиента в поле. Дополнительные сведения о полях C# см. в разделе "Поля" (руководство по программированию на C#).
  • Регистрация клиентского объекта в качестве единого в контейнере внедрения зависимостей по вашему выбору. Дополнительные сведения о внедрении зависимостей в приложениях ASP.NET Core см. в статье об внедрении зависимостей с помощью пакета SDK Azure для .NET.

Этот подход гораздо эффективнее, чем вызов конструктора для каждого необходимого клиента.

Неизменяемость клиента и безопасность потоков

Клиенты пакета SDK Azure неизменяемы после их создания, что означает, что вы не можете изменить конечную точку, к которой он подключается, учетные данные, используемые для авторизации, или другие значения, передаваемые в качестве параметров клиента. Неизменяемость клиента также означает, что клиенты безопасны для совместного использования и повторного использования в приложении.

Если приложение должно использовать разные конфигурации или учетные данные для клиентов одного типа, можно создать экземпляр клиента для каждого набора параметров конфигурации.

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

Следующие шаги

Дополнительные сведения об использовании клиентских библиотек служба хранилища Azure для работы с ресурсами данных см. в следующих статьях: