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

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 dużej objętości danych

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 uniwersalny klient obiektów blob, który obsługuje typowe operacje dla wszystkich rodzajów, a także istnieją specjalizowani klienci obiektów blob dla każdego rodzaju (obiekty blob blokowe, obiekty blob dołączalne i obiekty blob stronicowane).

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

Język	Pakiety	Klasa klienta usługi	Klasa klienta kontenera	Klasy klientów obiektów blob
.NET	Azure.Storage.Blobs Azure.Storage.Blobs.Models Azure.Storage.Blobs.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
Idź	azblob	azblob. Klient	container.Client	Blob Client blockblob.Client appendblob.Klient pageblob.Client

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

Każdy typ klienta można zainicjować za pomocą prostego konstruktora lub przeciążonego konstruktora, który 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. Zobacz odniesienie do klasy w tabeli, aby uzyskać szczegółowe informacje.

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 podczas inicjalizacji klienta, a poświadczenie pozostaje ważne przez cały czas trwania jego istnienia. Podmiot zabezpieczeń Microsoft Entra żądający tokenu musi mieć przypisaną odpowiednią rolę RBAC platformy Azure, zapewniającą dostęp do danych 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 magazynowego. BlobServiceClient zapewnia metody pobierania i konfigurowania właściwości konta, a także umożliwia wyświetlanie listy, tworzenie i usuwanie kontenerów w koncie magazynowym. Ten obiekt klienta jest punktem wyjścia do interakcji z zasobami na koncie magazynowym.

Typowym scenariuszem jest utworzenie pojedynczego klienta serwisowego, a następnie, w razie potrzeby, utworzenie klientów dla kontenerów i obiektów blob na bazie klienta serwisowego. 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 z BlobServiceClient odziedziczą jego konfigurację klienta, w tym opcje klienta i dane uwierzytelniające.

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

.NET

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

Java

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

JavaScript

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

Python

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

Przejdź

Dodaj następujące instrukcje import:

import (
    "context"
    "fmt"

    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
)

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

func getClient(accountName string) *azblob.Client {
    accountURL := fmt.Printf("https://%s.blob.core.windows.net", accountName)

	// Create a new service client with token credential
	credential, err := azidentity.NewDefaultAzureCredential(nil)
	handleError(err)

	client, err := azblob.NewClient(accountURL, credential, nil)
	handleError(err)

	return client
}

Wystąpienia azblob.Client zapewniają metody do pracy z kontenerami i obiektami blob w koncie magazynowym. Określ punkt końcowy konta przechowywania podczas konstruowania obiektu klienta.

Tworzenie obiektu BlobContainerClient

Możesz użyć obiektu BlobServiceClient do utworzenia nowego obiektu BlobContainerClient (ContainerClient dla JavaScript i Python). Obiekt BlobContainerClient umożliwia interakcję z określonym zasobem kontenera. Ten zasób nie musi istnieć na koncie przechowywania, żeby 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:

.NET

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

Java

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

JavaScript

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

Python

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

Przejdź

Dodaj następujące instrukcje import:

import (
    "context"
    "fmt"

    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob/container"
)

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

func getBlobContainerClient(client *azblob.Client, containerName string) *container.Client {
	// Create the container client using the azblob client object
	containerClient := client.ServiceClient().NewContainerClient(containerName)
	return containerClient
}

Wystąpienia azblob.Client zapewniają metody pracy z kontenerami i obiektami blob na koncie magazynowym. W przypadku większości operacji można użyć azblob.Client wystąpienia zamiast tworzyć oddzielne container.Client wystąpienie.

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:

.NET

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

Java

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

JavaScript

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

Python

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

Przejdź

Dodaj następujące instrukcje import:

import (
    "context"
    "fmt"

    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob/container"
)

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

func getBlobContainerClient(accountName string, containerName string) *container.Client {
	// Create a new container client with token credential
	credential, err := azidentity.NewDefaultAzureCredential(nil)
	handleError(err)

	containerURL := fmt.Sprintf("https://%s.blob.core.windows.net/%s", accountName, containerName)
	containerClient, err := container.NewClient(containerURL, credential, nil)
	handleError(err)

	return containerClient
}

Tworzenie obiektu BlobClient

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

W poniższych przykładach pokazano, jak utworzyć klienta blobu w celu interakcji z określonym zasobem blobu.

.NET

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

Java

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

JavaScript

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

Python

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

Przejdź

Dodaj następujące instrukcje import:

import (
    "context"
    "fmt"

    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob/blob"
)

Dodaj poniższy kod, aby utworzyć obiekt klienta blob.

func getBlobClient(client *azblob.Client, containerName string, blobName string) *blob.Client {
	// Create the blob client using the azblob client object
	blobClient := client.ServiceClient().NewContainerClient(containerName).NewBlobClient(blobName)
	return blobClient
}

Wystąpienia azblob.Client zapewniają metody pracy z kontenerami i obiektami blob w koncie magazynowym. W przypadku większości operacji można użyć instancji azblob.Client zamiast tworzenia oddzielnej instancji 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 pracy z wątkami

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 klienty można bezpiecznie udostępniać i ponownie używać 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ć instancję klienta dla każdego zestawu opcji konfiguracji.

Azure SDK gwarantuje, że wszystkie metody instancji klienta są wątkowo bezpieczne i niezależne od siebie. Projekt ten zapewnia, że udostępnianie i ponowne korzystanie z wystąpień klientów jest zawsze bezpieczne, nawet między wątkami.

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:

• Rozpoczynanie pracy z usługami Azure Blob Storage i .NET
• Rozpoczynanie pracy z usługą Azure Blob Storage i językiem Java
• Rozpoczynanie pracy z usługami Azure Blob Storage i JavaScript
• Wprowadzenie do usługi Azure Blob Storage i języka Python