Tworzenie obiektów klienta korzystających z zasobów danych i zarządzanie nimi

Artykuł
08/05/2024

Zestawy SDK platformy Azure to kolekcje bibliotek utworzonych w celu ułatwienia korzystania z usług platformy Azure z różnych języków. Zestawy SDK zostały zaprojektowane w celu uproszczenia interakcji między aplikacją a zasobami platformy Azure. Praca z zasobami platformy Azure przy użyciu zestawu SDK rozpoczyna się od utworzenia wystąpienia klienta. W tym artykule przedstawiono sposób tworzenia obiektów klienta w celu interakcji z zasobami danych w usłudze Azure Blob Storage i oferuje najlepsze rozwiązania dotyczące zarządzania klientami w aplikacji.

Informacje o obiektach klienta

Biblioteki klienta usługi Azure Blob Storage umożliwiają interakcję z trzema typami zasobów w usłudze magazynu:

Konta magazynu
Kontenery obiektów blob
Obiekty blob

W zależności od potrzeb aplikacji można tworzyć obiekty klienta na dowolnym z tych trzech poziomów.

W przypadku obiektów blob istnieje ogólny klient obiektów blob, który obejmuje typowe operacje obiektów blob we wszystkich typach i istnieją wyspecjalizowani klienci obiektów blob dla każdego typu (blokowy obiekt blob, uzupełnialne obiekty blob i stronicowy obiekt blob).

W poniższej tabeli wymieniono różne klasy klientów dla każdego języka:

Język	Pakiety	Klasa klienta usługi	Kontener client class (Klasa klienta kontenera)	Klasy klientów obiektów blob
.NET	Azure.Storage.Blobs Azure.Storage.Blobs.Models Azure.Storage.Blobs.Specialized	BlobServiceClient	BlobContainerClient	Obiekt 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	Obiekt blobClient BlobAsyncClient BlobClientBuilder BlockBlobClient AppendBlobClient PageBlobClient
JavaScript	@azure/storage-blob	BlobServiceClient	ContainerClient	Obiekt blobClient BlockBlobClient AppendBlobClient PageBlobClient
Python	azure.storage.blob	BlobServiceClient	ContainerClient	BlobClient¹

¹ W przypadku języka Python zawiera BlobClient metody wyspecjalizowanych typów obiektów blob.

Każdy typ klienta można utworzyć wystąpienie przez wywołanie prostego konstruktora lub przeciążenie, które przyjmuje różne opcje konfiguracji. W przypadku języka Java każdy typ klienta ma oddzielną klasę, która udostępnia interfejs API konstruktora, który ułatwia konfigurację i tworzenie wystąpień. W zależności od zestawu SDK języka te opcje konfiguracji klienta są przekazywane do konstruktora na różne sposoby. Aby uzyskać szczegółowe informacje, zobacz odwołanie do klasy z tabeli.

Autoryzowanie obiektu klienta

Aby aplikacja uzyskiwała dostęp do zasobów obiektów blob i wchodziła z nimi w interakcje, należy autoryzować obiekt klienta. Przykłady kodu w tym artykule używają elementu DefaultAzureCredential do uwierzytelniania na platformie Azure za pośrednictwem podmiotu zabezpieczeń firmy Microsoft Entra. Proces uwierzytelniania obejmuje uzyskanie tokenu dostępu do autoryzacji. Ten token dostępu jest przekazywany jako poświadczenie po utworzeniu wystąpienia klienta, a poświadczenie jest utrwalane przez cały okres istnienia klienta. Podmiot zabezpieczeń firmy Microsoft żądający tokenu musi mieć przypisaną odpowiednią rolę RBAC platformy Azure, która udziela dostępu do danych obiektów blob. Aby dowiedzieć się więcej, zobacz Przypisywanie roli platformy Azure w celu uzyskania dostępu do danych obiektów blob.

Następujące mechanizmy autoryzacji mogą służyć do udzielania odpowiedniego poziomu dostępu do obiektu klienta:

Microsoft Entra ID: zalecane w celu uzyskania optymalnego bezpieczeństwa
Sygnatura dostępu współdzielonego (SAS): obsługiwana i najbezpieczniejsza w przypadku korzystania z tokenu SAS delegowania użytkownika
Klucz dostępu do konta (klucz współużytkowany): obsługiwany, ale nie jest zalecany, ponieważ może być mniej bezpieczny

Aby dowiedzieć się więcej na temat autoryzacji, zobacz Autoryzowanie dostępu do danych w usłudze Azure Storage.

Tworzenie obiektu klienta

Praca z dowolnym zasobem platformy Azure przy użyciu zestawu SDK rozpoczyna się od utworzenia obiektu klienta. W tej sekcji dowiesz się, jak tworzyć obiekty klienta do interakcji z trzema typami zasobów w usłudze magazynu: kontami magazynu, kontenerami i obiektami blob.

Gdy aplikacja tworzy obiekt klienta, przekazujesz identyfikator URI odwołujący się do punktu końcowego do konstruktora klienta. Możesz utworzyć ciąg punktu końcowego ręcznie, jak pokazano w przykładach w tym artykule, lub wykonać zapytanie dotyczące punktu końcowego w czasie wykonywania przy użyciu biblioteki zarządzania usługi Azure Storage. Aby dowiedzieć się, jak wykonywać zapytania dotyczące punktu końcowego, zobacz Zapytanie dotyczące punktu końcowego usługi Blob Storage.

Tworzenie obiektu BlobServiceClient

Autoryzowany BlobServiceClient obiekt umożliwia aplikacji interakcję z zasobami na poziomie konta magazynu. BlobServiceClient Udostępnia metody pobierania i konfigurowania właściwości konta, a także listy, tworzenia i usuwania kontenerów na koncie magazynu. Ten obiekt klienta jest punktem wyjścia do interakcji z zasobami na koncie magazynu.

Typowym scenariuszem jest utworzenie wystąpienia pojedynczego klienta usługi, a następnie utworzenie klientów kontenera i klientów obiektów blob z poziomu klienta usługi zgodnie z potrzebami. Aby pracować z określonym kontenerem lub obiektem blob, możesz użyć BlobServiceClient obiektu do utworzenia klienta kontenera lub klienta obiektów blob. Klienci utworzeni na podstawie BlobServiceClient klasy dziedziczą konfigurację klienta, w tym opcje klienta i poświadczenia.

W poniższych przykładach pokazano, jak utworzyć BlobServiceClient obiekt:

Dodaj następujące using dyrektywy:

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

Dodaj następujący kod, aby utworzyć obiekt klienta:

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

    return client;
}

Dodaj następujące import dyrektywy:

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

Dodaj następujący kod, aby utworzyć obiekt klienta:

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

Dodaj następujące instrukcje require:

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

Dodaj następujący kod, aby utworzyć obiekt klienta:

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

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

Dodaj następujące instrukcje import:

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

Dodaj następujący kod, aby utworzyć obiekt klienta:

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

Tworzenie obiektu BlobContainerClient

Możesz użyć obiektu do utworzenia BlobServiceClient nowego BlobContainerClient obiektu (ContainerClient dla języków JavaScript i Python). Obiekt BlobContainerClient umożliwia interakcję z określonym zasobem kontenera. Ten zasób nie musi istnieć na koncie magazynu, aby utworzyć obiekt klienta. BlobContainerClient Udostępnia metody tworzenia, usuwania lub konfigurowania kontenera oraz zawiera metody wyświetlania, przekazywania i usuwania w nim obiektów blob. Aby wykonać operacje na określonym obiekcie blob w kontenerze, możesz utworzyć klienta obiektu blob.

W poniższych przykładach pokazano, jak utworzyć klienta kontenera na podstawie BlobServiceClient obiektu w celu interakcji z określonym zasobem kontenera:

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

Jeśli praca jest ograniczona do pojedynczego kontenera, możesz utworzyć BlobContainerClient obiekt bezpośrednio bez użycia polecenia BlobServiceClient. Nadal można ustawić opcje klienta na kliencie kontenera, tak jak w przypadku klienta usługi.

W poniższych przykładach pokazano, jak utworzyć klienta kontenera bezpośrednio bez użycia polecenia 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

Tworzenie obiektu BlobClient

Aby wchodzić w interakcje z określonym zasobem obiektów blob, utwórz BlobClient obiekt na podstawie klienta usługi lub klienta kontenera. Obiekt BlobClient umożliwia interakcję z określonym zasobem obiektu blob. Ten zasób nie musi istnieć na koncie magazynu, aby utworzyć obiekt klienta. BlobClient Udostępnia metody przekazywania, pobierania, usuwania i tworzenia migawek obiektu blob.

W poniższych przykładach pokazano, jak utworzyć klienta obiektów blob w celu interakcji z określonym zasobem obiektu 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

Zarządzanie obiektami klienta

Najlepszym rozwiązaniem do zarządzania klientami zestawu Azure SDK jest traktowanie klienta jako pojedynczego, co oznacza, że klasa będzie mieć tylko jeden obiekt naraz. Nie ma potrzeby przechowywania więcej niż jednego wystąpienia klienta dla danego zestawu parametrów konstruktora lub opcji klienta. Tę koncepcję można zaimplementować na wiele sposobów, w tym:

Tworzenie pojedynczego obiektu klienta i przekazywanie go jako parametru w całej aplikacji. To podejście jest pokazane w przykładach kodu w tym artykule.
Przechowywanie wystąpienia klienta w polu. Aby dowiedzieć się więcej o polach języka C#, zobacz Pola (Przewodnik programowania w języku C#).
Zarejestrowanie obiektu klienta jako pojedynczego w wybranym kontenerze iniekcji zależności. Aby uzyskać więcej informacji na temat wstrzykiwania zależności w aplikacjach ASP.NET Core, zobacz Wstrzykiwanie zależności za pomocą zestawu Azure SDK dla platformy .NET.

Takie podejście jest znacznie bardziej wydajne na dużą skalę niż wywoływanie konstruktora dla każdego potrzebnego klienta.

Niezmienność klienta i bezpieczeństwo wątków

Klienci zestawu Azure SDK są niezmienni po ich utworzeniu, co oznacza, że nie można zmienić punktu końcowego, z którym nawiązuje połączenie, poświadczeń używanych do autoryzacji lub innych wartości przekazywanych jako opcje klienta. Niezmienność klienta oznacza również, że klienci są bezpieczni do udostępniania i ponownego używania w całej aplikacji.

Jeśli aplikacja musi używać różnych konfiguracji lub poświadczeń dla klientów tego samego typu, możesz utworzyć wystąpienie klienta dla każdego zestawu opcji konfiguracji.

Zestaw Azure SDK gwarantuje, że wszystkie metody wystąpienia klienta są bezpieczne wątkowo i niezależne od siebie. Dzięki temu udostępnianie i ponowne korzystanie z wystąpień klientów jest zawsze bezpieczne, nawet w wątkach.

Następne kroki

Aby dowiedzieć się więcej o korzystaniu z bibliotek klienckich usługi Azure Storage do pracy z zasobami danych, zobacz następujące artykuły:

Udostępnij za pośrednictwem

Tworzenie obiektów klienta korzystających z zasobów danych i zarządzanie nimi

Informacje o obiektach klienta

Autoryzowanie obiektu klienta

Tworzenie obiektu klienta

Tworzenie obiektu BlobServiceClient

Tworzenie obiektu BlobContainerClient

Tworzenie obiektu BlobClient

Zarządzanie obiektami klienta

Niezmienność klienta i bezpieczeństwo wątków

Następne kroki

Opinia

Dodatkowe zasoby