Vytváření a správa klientských objektů, které pracují s datovými prostředky

Sady Azure SDK jsou kolekce knihoven sestavené tak, aby se usnadnilo používání služeb Azure z různých jazyků. Sady SDK jsou navržené tak, aby zjednodušily interakce mezi vaší aplikací a prostředky Azure. Práce s prostředky Azure pomocí sady SDK začíná vytvořením instance klienta. Tento článek ukazuje, jak vytvořit klientské objekty pro interakci s datovými prostředky ve službě Azure Blob Storage a nabízí osvědčené postupy pro správu klientů ve vaší aplikaci.

O klientských objektech

Klientské knihovny Azure Blob Storage umožňují interakci se třemi typy prostředků ve službě úložiště:

• Účty úložiště
• Kontejnery objektů blob
• Objekty blob

V závislosti na potřebách vaší aplikace můžete vytvářet klientské objekty na kterékoli z těchto tří úrovní.

Pro objekty blob existuje obecný klient objektů blob, který pokrývá běžné operace objektů blob napříč všemi typy a pro každý typ existují specializovaní klienti objektů blob (objekt blob bloku, doplňovací objekt blob a objekt blob stránky).

Následující tabulka uvádí různé třídy klientů pro každý jazyk:

Jazyk	Balíčky	Klientská třída služby	Třída klienta kontejneru	Klientské třídy objektů 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

¹ Pro Python BlobClient zahrnuje metody pro specializované typy objektů blob.

Každý typ klienta lze vytvořit instancí voláním jednoduchého konstruktoru nebo přetížení, které přebírá různé možnosti konfigurace. Pro Javu má každý typ klienta samostatnou třídu, která poskytuje rozhraní API pro tvůrce, které pomáhá s konfigurací a vytvářením instancí. V závislosti na jazykové sadě SDK se tyto možnosti konfigurace klienta předávají konstruktoru různými způsoby. Podrobnosti najdete v odkazu na třídu z tabulky.

Autorizace klientského objektu

Aby aplikace přistupovala k prostředkům objektů blob a pracovala s nimi, musí být klientský objekt autorizovaný. Ukázky kódu v tomto článku používají k ověření v Azure pomocí objektu zabezpečení Microsoft Entra defaultAzureCredential . Proces ověřování zahrnuje získání přístupového tokenu pro autorizaci. Tento přístupový token se předává jako přihlašovací údaje při vytváření instance klienta a přihlašovací údaje se zachovají po celou dobu životnosti klienta. Objekt zabezpečení Microsoft Entra žádající o token musí mít přiřazenou odpovídající roli Azure RBAC, která uděluje přístup k datům objektů blob. Další informace najdete v tématu Přiřazení role Azure pro přístup k datům objektů blob.

Následující mechanismy autorizace lze použít k udělení odpovídající úrovně přístupu k objektu klienta:

• Microsoft Entra ID: doporučeno pro optimální zabezpečení
• Sdílený přístupový podpis (SAS): podporováno a nejbezpečnější při použití tokenu SAS delegování uživatele
• Přístupový klíč účtu (sdílený klíč): podporuje se, ale nedoporučuje se, protože může být méně zabezpečený.

Další informace o autorizaci najdete v tématu Autorizace přístupu k datům ve službě Azure Storage.

Vytvoření objektu klienta

Práce s libovolným prostředkem Azure pomocí sady SDK začíná vytvořením objektu klienta. V této části se dozvíte, jak vytvořit klientské objekty pro interakci se třemi typy prostředků ve službě úložiště: účty úložiště, kontejnery a objekty blob.

Když aplikace vytvoří objekt klienta, předáte identifikátor URI odkazující na koncový bod do konstruktoru klienta. Řetězec koncového bodu můžete sestavit ručně, jak je znázorněno v příkladech v tomto článku, nebo se můžete dotazovat na koncový bod za běhu pomocí knihovny pro správu Azure Storage. Informace o dotazování na koncový bod najdete v tématu Dotaz na koncový bod služby Blob Storage.

Vytvoření objektu BlobServiceClient

Autorizovaný BlobServiceClient objekt umožňuje aplikaci pracovat s prostředky na úrovni účtu úložiště. BlobServiceClient poskytuje metody pro načtení a konfiguraci vlastností účtu a také výpis, vytvoření a odstranění kontejnerů v rámci účtu úložiště. Tento klientský objekt je výchozím bodem pro interakci s prostředky v účtu úložiště.

Běžným scénářem je vytvoření instance jednoho klienta služby a následné vytvoření klientů kontejnerů a klientů objektů blob z klienta služby podle potřeby. Pokud chcete pracovat s konkrétním kontejnerem nebo objektem blob, můžete pomocí objektu BlobServiceClient vytvořit klienta kontejneru nebo klienta objektů blob. Klienti vytvořená z objektu BlobServiceClient zdědí konfiguraci klienta, včetně možností klienta a přihlašovacích údajů.

Následující příklady ukazují, jak vytvořit BlobServiceClient objekt:

.NET

Přidejte následující using direktivy:

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

Přidejte následující kód pro vytvoření objektu klienta:

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

    return client;
}

Java

Přidejte následující import direktivy:

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

Přidejte následující kód pro vytvoření objektu 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

Přidejte následující příkazy require:

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

Přidejte následující kód pro vytvoření objektu klienta:

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

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

Python

Přidejte následující příkazy import:

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

Přidejte následující kód pro vytvoření objektu 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

Vytvoření objektu BlobContainerClient

Objekt můžete použít BlobServiceClient k vytvoření nového BlobContainerClient objektu (ContainerClient pro JavaScript a Python). Objekt BlobContainerClient umožňuje interakci s konkrétním prostředkem kontejneru. Tento prostředek nemusí existovat v účtu úložiště, abyste mohli vytvořit objekt klienta. BlobContainerClient poskytuje metody pro vytvoření, odstranění nebo konfiguraci kontejneru a zahrnuje metody pro výpis, nahrání a odstranění objektů blob v něm. Pokud chcete provádět operace s konkrétním objektem blob v rámci kontejneru, můžete vytvořit klienta objektů blob.

Následující příklady ukazují, jak vytvořit klienta kontejneru z objektu BlobServiceClient pro interakci s konkrétním prostředkem kontejneru:

.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

Pokud je vaše práce úzce vymezena na jeden kontejner, můžete se rozhodnout vytvořit BlobContainerClient objekt přímo bez použití BlobServiceClient. U klienta kontejneru můžete nastavit možnosti klienta stejně jako u klienta služby.

Následující příklady ukazují, jak vytvořit klienta kontejneru přímo bez použití 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

Vytvoření objektu BlobClient

Pokud chcete pracovat s konkrétním prostředkem objektu blob, vytvořte BlobClient objekt z klienta služby nebo klienta kontejneru. Objekt BlobClient umožňuje interakci s konkrétním prostředkem objektu blob. Tento prostředek nemusí existovat v účtu úložiště, abyste mohli vytvořit objekt klienta. BlobClient poskytuje metody pro nahrávání, stahování, odstraňování a vytváření snímků objektu blob.

Následující příklady ukazují, jak vytvořit klienta objektů blob pro interakci s konkrétním prostředkem objektu blob:

.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

Správa klientských objektů

Osvědčeným postupem pro správu klientů Sady Azure SDK je považovat klienta za jednoúčelový, což znamená, že třída bude mít současně pouze jeden objekt. Není nutné uchovávat více než jednu instanci klienta pro danou sadu parametrů konstruktoru nebo možnosti klienta. Tento koncept lze implementovat mnoha způsoby, včetně:

• Vytvoření jednoho objektu klienta a jeho předání jako parametr v celé aplikaci Tento přístup je uvedený v příkladech kódu v tomto článku.
• Uložení instance klienta do pole Další informace o polích jazyka C# najdete v tématu Pole (Průvodce programováním v C#).
• Registrace klientského objektu jako jediného objektu v kontejneru injektáže závislostí podle vašeho výběru. Další informace o injektáži závislostí v aplikacích ASP.NET Core najdete v tématu Injektáž závislostí pomocí sady Azure SDK pro .NET.

Tento přístup je mnohem efektivnější ve velkém měřítku než volání konstruktoru pro každého klienta, kterého potřebujete.

Neměnnost klienta a zabezpečení vláken

Klienti Sady Azure SDK jsou po vytvoření neměnní, což znamená, že nemůžete změnit koncový bod, ke kterému se připojuje, přihlašovací údaje používané k autorizaci nebo jiné hodnoty předávané jako možnosti klienta. Neměnnost klienta také znamená, že klienti jsou v bezpečí sdílet a opakovaně používat v celé aplikaci.

Pokud vaše aplikace potřebuje pro klienty stejného typu používat různé konfigurace nebo přihlašovací údaje, můžete vytvořit instanci klienta pro každou sadu možností konfigurace.

Sada Azure SDK zaručuje, že všechny metody instance klienta jsou bezpečné pro přístup z více vláken a nezávisle na sobě. Tento návrh zajišťuje, že sdílení a opakované používání klientských instancí je vždy bezpečné, a to i napříč vlákny.

Další kroky

Další informace o používání klientských knihoven služby Azure Storage k práci s datovými prostředky najdete v následujících článcích:

• Začínáme se službou Azure Blob Storage a .NET
• Začínáme se službou Azure Blob Storage a Javou
• Začínáme se službou Azure Blob Storage a JavaScriptem
• Začínáme se službou Azure Blob Storage a Pythonem