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

Статья
08/05/2024

Пакеты 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	BlobClient¹

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

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

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

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

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

Идентификатор Microsoft Entra: рекомендуется для оптимальной безопасности
Подписанный URL-адрес (SAS): поддерживается и наиболее безопасна при использовании маркера SAS делегирования пользователей.
Ключ доступа к учетной записи (общий ключ): поддерживается, но не рекомендуется, так как это может быть менее безопасным.

Дополнительные сведения о авторизации см. в статье "Авторизация доступа к данным" в служба хранилища 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;
}

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

import com.azure.identity.*;
import com.azure.storage.blob.*;

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

public BlobServiceClient GetBlobServiceClient(String accountName) {
    String endpointString = String.format("https://%s.blob.core.windows.net", accountName);
    BlobServiceClient client = new BlobServiceClientBuilder()
            .endpoint(endpointString)
            .credential(new DefaultAzureCredentialBuilder().build())
            .buildClient();

    return client;
}

Добавьте следующие операторы require :

const { BlobServiceClient } = require('@azure/storage-blob');
const { DefaultAzureCredential } = require('@azure/identity');

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

const accountName = "<storage-account-name>";

const blobServiceClient = new BlobServiceClient(
    `https://${accountName}.blob.core.windows.net`,
    new DefaultAzureCredential()
);

Добавьте следующие операторы import :

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

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

def get_blob_service_client(self, account_name):
    account_url = f"https://{account_name}.blob.core.windows.net"
    credential = DefaultAzureCredential()

    # Create the BlobServiceClient object
    blob_service_client = BlobServiceClient(account_url, credential=credential)

    return blob_service_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;
}

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

const containerName = "sample-container";
let containerClient = blobServiceClient.getContainerClient(containerName);

def get_blob_container_client(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)
    return container_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;
}

public BlobContainerClient getBlobContainerClient(
        String accountName,
        String containerName) {
    // Append the container name to the URI
    String endpointString = String.format("https://%s.blob.core.windows.net/%s",
            accountName, containerName);

    BlobContainerClient client = new BlobContainerClientBuilder()
            .endpoint(endpointString)
            .credential(new DefaultAzureCredentialBuilder().build())
            .buildClient();

    return client;
}

const accountName = "<storage-account-name>";
const containerName = "sample-container";

// Append the container name to the URI
const containerClient = new ContainerClient(
    `https://${accountName}.blob.core.windows.net/${containerName}`,
    new DefaultAzureCredential()

def get_blob_container_client(self, account_name, container_name):
    # Append the container name to the URI
    account_url = f"https://{account_name}.blob.core.windows.net/{container_name}"
    credential = DefaultAzureCredential()

    # Create the client object
    container_client = ContainerClient(account_url, credential=credential)

    return container_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;
}

public BlobClient getBlobClient(
        BlobServiceClient blobServiceClient,
        String containerName,
        String blobName) {
    // Create a blob client using the service client object
    BlobClient client = blobServiceClient.getBlobContainerClient(containerName).getBlobClient(blobName);
    return client;
}

const containerName = "sample-container";
const blobName = "sample-blob";
let blobClient = blobServiceClient.getContainerClient(containerName).getBlobClient(blobName);

def get_blob_client(self, blob_service_client: BlobServiceClient, container_name, blob_name):
    # Create a blob client using the service client object
    blob_client = blob_service_client.get_blob_client(container=container_name, blob=blob_name)
    return blob_client

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Дополнительные ресурсы