Skapa och hantera klientobjekt som interagerar med dataresurser

Azure SDK:er är bibliotekssamlingar som skapats för att göra det enklare att använda Azure-tjänster från olika språk. SDK:erna är utformade för att förenkla interaktioner mellan ditt program och Azure-resurser. Att arbeta med Azure-resurser med hjälp av SDK börjar med att skapa en klientinstans. Den här artikeln visar hur du skapar klientobjekt för att interagera med dataresurser i Azure Blob Storage och erbjuder metodtips för hur du hanterar klienter i ditt program.

Om klientobjekt

Med Azure Blob Storage-klientbiblioteken kan du interagera med tre typer av resurser i lagringstjänsten:

• Lagringskonton
• Blobcontainrar
• Blobar

Beroende på programmets behov kan du skapa klientobjekt på någon av dessa tre nivåer.

För blobar finns det en allmän blobklient som omfattar vanliga blobåtgärder för alla typer, och det finns specialiserade blobklienter för varje typ (blockblob, tilläggsblob och sidblob).

I följande tabell visas de olika klientklasserna för varje språk:

Språk	Paket	Tjänstklientklass	Containerklientklass	Blob-klientklasser
.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

¹ För Python BlobClient innehåller metoder för specialiserade blobtyper.

Varje klienttyp kan instansieras genom att anropa en enkel konstruktor eller en överlagring som tar olika konfigurationsalternativ. För Java har varje klienttyp en separat klass som tillhandahåller ett builder-API för att hjälpa till med konfiguration och instansiering. Beroende på språk-SDK skickas dessa klientkonfigurationsalternativ till konstruktorn på olika sätt. Mer information finns i klassreferensen från tabellen.

Auktorisera ett klientobjekt

För att en app ska få åtkomst till blobresurser och interagera med dem måste ett klientobjekt auktoriseras. Kodexemplen i den här artikeln använder DefaultAzureCredential för att autentisera till Azure via ett Microsoft Entra-säkerhetsobjekt. Autentiseringsprocessen omfattar att hämta en åtkomsttoken för auktorisering. Den här åtkomsttoken skickas som en autentiseringsuppgift när klienten instansieras och autentiseringsuppgifterna bevaras under hela klientlivslängden. Microsoft Entra-säkerhetsobjektet som begär token måste tilldelas en lämplig Azure RBAC-roll som ger åtkomst till blobdata. Mer information finns i Tilldela en Azure-roll för åtkomst till blobdata.

Följande auktoriseringsmekanismer kan användas för att bevilja lämplig åtkomstnivå till ett klientobjekt:

• Microsoft Entra-ID: rekommenderas för optimal säkerhet
• Signatur för delad åtkomst (SAS): stöds och är säkrast när du använder en SAS-token för användardelegering
• Kontoåtkomstnyckel (delad nyckel): stöds, men rekommenderas inte eftersom den kan vara mindre säker

Mer information om auktorisering finns i Auktorisera åtkomst till data i Azure Storage.

Skapa ett klientobjekt

Att arbeta med en Azure-resurs med hjälp av SDK börjar med att skapa ett klientobjekt. I det här avsnittet får du lära dig hur du skapar klientobjekt för att interagera med de tre typerna av resurser i lagringstjänsten: lagringskonton, containrar och blobar.

När programmet skapar ett klientobjekt skickar du en URI som refererar till slutpunkten till klientkonstruktorn. Du kan konstruera slutpunktssträngen manuellt, som du ser i exemplen i den här artikeln, eller så kan du fråga efter slutpunkten vid körning med hjälp av Azure Storage-hanteringsbiblioteket. Information om hur du frågar efter en slutpunkt finns i Fråga efter en Blob Storage-slutpunkt.

Skapa ett BlobServiceClient-objekt

Med ett auktoriserat BlobServiceClient objekt kan din app interagera med resurser på lagringskontonivå. BlobServiceClient innehåller metoder för att hämta och konfigurera kontoegenskaper samt lista, skapa och ta bort containrar i lagringskontot. Det här klientobjektet är startpunkten för att interagera med resurser i lagringskontot.

Ett vanligt scenario är att instansiera en enskild tjänstklient och sedan skapa containerklienter och blobklienter från tjänstklienten efter behov. Om du vill arbeta med en specifik container eller blob kan du använda BlobServiceClient objektet för att skapa en containerklient eller blobklient. Klienter som skapas från en BlobServiceClient ärver klientkonfigurationen, inklusive klientalternativ och autentiseringsuppgifter.

Följande exempel visar hur du skapar ett BlobServiceClient objekt:

.NET

Lägg till följande using direktiv:

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

Lägg till följande kod för att skapa klientobjektet:

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

    return client;
}

Java

Lägg till följande import direktiv:

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

Lägg till följande kod för att skapa klientobjektet:

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

Lägg till följande require-uttryck:

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

Lägg till följande kod för att skapa klientobjektet:

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

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

Python

Lägg till följande import-uttryck:

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

Lägg till följande kod för att skapa klientobjektet:

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

Skapa ett BlobContainerClient-objekt

Du kan använda ett BlobServiceClient objekt för att skapa ett nytt BlobContainerClient objekt (ContainerClient för JavaScript och Python). Med BlobContainerClient ett objekt kan du interagera med en specifik containerresurs. Den här resursen behöver inte finnas i lagringskontot för att du ska kunna skapa klientobjektet. BlobContainerClient innehåller metoder för att skapa, ta bort eller konfigurera en container och innehåller metoder för att lista, ladda upp och ta bort blobarna i den. Om du vill utföra åtgärder på en specifik blob i containern kan du skapa en blobklient.

I följande exempel visas hur du skapar en containerklient från ett BlobServiceClient objekt för att interagera med en specifik containerresurs:

.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

Om ditt arbete är begränsat till en enda container kan du välja att skapa ett BlobContainerClient objekt direkt utan att använda BlobServiceClient. Du kan fortfarande ange klientalternativ på en containerklient precis som på en tjänstklient.

Följande exempel visar hur du skapar en containerklient direkt utan att använda 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

Skapa ett BlobClient-objekt

Om du vill interagera med en specifik blobresurs skapar du ett BlobClient objekt från en tjänstklient eller containerklient. Med BlobClient ett objekt kan du interagera med en specifik blobresurs. Den här resursen behöver inte finnas i lagringskontot för att du ska kunna skapa klientobjektet. BlobClient innehåller metoder för att ladda upp, ladda ned, ta bort och skapa ögonblicksbilder av en blob.

I följande exempel visas hur du skapar en blobklient för att interagera med en specifik blobresurs:

.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

Hantera klientobjekt

Bästa praxis för Azure SDK-klienthantering är att behandla en klient som en singleton, vilket innebär att en klass bara har ett objekt i taget. Du behöver inte behålla mer än en instans av en klient för en viss uppsättning konstruktorparametrar eller klientalternativ. Det här konceptet kan implementeras på många sätt, bland annat:

• Skapa ett enda klientobjekt och skicka det som en parameter i hela programmet. Den här metoden visas i kodexemplen i den här artikeln.
• Lagra en klientinstans i ett fält. Mer information om C#-fält finns i Fält (C#-programmeringsguide).
• Registrera klientobjektet som en singleton i valfri container för beroendeinmatning. Mer information om beroendeinmatning i ASP.NET Core-appar finns i Beroendeinmatning med Azure SDK för .NET.

Den här metoden är mycket effektivare i stor skala än att anropa en konstruktor för varje klient som du behöver.

Klientens oföränderlighet och trådsäkerhet

Azure SDK-klienter är oföränderliga när de har skapats, vilket innebär att du inte kan ändra slutpunkten som den ansluter till, de autentiseringsuppgifter som används för auktorisering eller andra värden som skickas som klientalternativ. Klientens oföränderlighet innebär också att klienter är säkra att dela och återanvända i hela programmet.

Om din app behöver använda olika konfigurationer eller autentiseringsuppgifter för klienter av samma typ kan du instansiera en klient för varje uppsättning konfigurationsalternativ.

Azure SDK garanterar att alla klientinstansmetoder är trådsäkra och oberoende av varandra. Den här designen säkerställer att delning och återanvändning av klientinstanser alltid är säker, även mellan trådar.

Nästa steg

Mer information om hur du använder Azure Storage-klientbiblioteken för att arbeta med dataresurser finns i följande artiklar:

• Kom igång med Azure Blob Storage och .NET
• Kom igång med Azure Blob Storage och Java
• Kom igång med Azure Blob Storage och JavaScript
• Kom igång med Azure Blob Storage och Python