Creare e gestire oggetti client che interagiscono con risorse dati

Gli SDK di Azure sono raccolte di librerie create per semplificare l'uso dei servizi di Azure da linguaggi diversi. Gli SDK sono progettati per semplificare le interazioni tra l'applicazione e le risorse di Azure. L'uso delle risorse di Azure con l'SDK inizia con la creazione di un'istanza del client. Questo articolo illustra come creare oggetti client per interagire con le risorse dati in Archiviazione BLOB di Azure e offre le procedure consigliate su come gestire i client nell'applicazione.

Informazioni sugli oggetti client

Le librerie client di Archiviazione BLOB di Azure consentono di interagire con tre tipi di risorse nel servizio di archiviazione:

• Account di archiviazione
• Contenitori BLOB
• BLOB

A seconda delle esigenze dell'applicazione, è possibile creare oggetti client a uno di questi tre livelli.

Per i BLOB, è disponibile un client BLOB generale che copre le operazioni BLOB comuni in tutti i tipi e sono disponibili client BLOB specialistici per ogni tipo (BLOB in blocchi, BLOB di accodamento e BLOB di pagine).

La tabella seguente elenca le diverse classi client per ogni linguaggio:

¹ Per Python, BlobClient include i metodi per i tipi di BLOB specialistici.

È possibile creare un'istanza per ogni tipo di client chiamando un costruttore semplice o un overload che accetta varie opzioni di configurazione. Per Java, ogni tipo di client ha una classe separata che fornisce un'API del generatore per facilitare la configurazione e la creazione di istanze. A seconda dell'SDK del linguaggio, queste opzioni di configurazione client vengono passate al costruttore in modi diversi. Per informazioni dettagliate, vedere le informazioni di riferimento sulla classe dalla tabella.

Autorizzare un oggetto client

Per consentire a un'app di accedere alle risorse BLOB e interagirvi, è necessario autorizzare un oggetto client. Gli esempi di codice in questo articolo usano DefaultAzureCredential per l'autenticazione in Azure tramite un'entità di sicurezza di Microsoft Entra. Il processo di autenticazione include l'acquisizione di un token di accesso per l'autorizzazione. Questo token di accesso viene passato come credenziale quando viene creata un'istanza del client e le credenziali vengono mantenute per tutta la durata del client. All'entità di sicurezza di Microsoft Entra che richiede il token deve essere assegnato un ruolo di Controllo degli accessi in base al ruolo di Azure appropriato che concede l'accesso ai dati BLOB. Per altre informazioni, vedere Assegnare un ruolo di Azure per l'accesso ai dati BLOB.

È possibile usare i meccanismi di autorizzazione seguenti per concedere il livello di accesso appropriato a un oggetto client:

• Microsoft Entra ID: consigliato per una sicurezza ottimale
• Firma di accesso condiviso (SAS): supportata e più sicura quando si usa un token di firma di accesso condiviso di delega utente
• Chiave di accesso dell'account (chiave condivisa): supportata, ma non consigliata perché può essere meno sicura

Per altre informazioni sull'autorizzazione, vedere Autorizzare l'accesso ai dati in Archiviazione di Azure.

Creare un oggetto client

L'uso di qualsiasi risorsa di Azure con l'SDK inizia con la creazione di un oggetto client. In questa sezione viene illustrato come creare oggetti client per interagire con i tre tipi di risorse nel servizio di archiviazione: account di archiviazione, contenitori e BLOB.

Quando l'applicazione crea un oggetto client, si passa un URI che fa riferimento all'endpoint al costruttore client. È possibile costruire manualmente la stringa dell'endpoint, come illustrato negli esempi di questo articolo oppure eseguire query sull'endpoint in fase di esecuzione usando la libreria di gestione di Archiviazione di Azure. Per informazioni su come eseguire query per un endpoint, vedere Query per un endpoint di Archiviazione BLOB.

Creare un oggetto BlobServiceClient

Un oggetto autorizzato BlobServiceClient consente all'app di interagire con le risorse a livello di account di archiviazione. BlobServiceClient fornisce metodi per recuperare e configurare le proprietà dell'account, nonché elencare, creare ed eliminare contenitori all'interno dell'account di archiviazione. Questo oggetto client è il punto di partenza per interagire con le risorse nell'account di archiviazione.

Uno scenario comune consiste nel creare un'istanza di un singolo client del servizio, quindi creare client contenitore e client BLOB dal client del servizio in base alle esigenze. Per usare un contenitore o un BLOB specifico, è possibile usare l'oggetto BlobServiceClient per creare un client contenitore o un client BLOB. I client creati da un oggetto BlobServiceClient erediteranno la relativa configurazione del client, incluse le opzioni e le credenziali del client.

Gli esempi seguenti illustrano come creare un oggetto BlobServiceClient:

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

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

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

Creare un oggetto BlobContainerClient

È possibile usare un oggetto BlobServiceClient per creare un nuovo oggetto BlobContainerClient (ContainerClient per JavaScript e Python). Un oggetto BlobContainerClient consente di interagire con una risorsa contenitore specifica. Non è necessario che questa risorsa esista nell'account di archiviazione per creare l'oggetto client. BlobContainerClient fornisce metodi per creare, eliminare o configurare un contenitore e include metodi per elencare, caricare ed eliminare i BLOB al suo interno. Per eseguire operazioni su un BLOB specifico all'interno del contenitore, è possibile creare un client BLOB.

Gli esempi seguenti illustrano come creare un client contenitore da un oggetto BlobServiceClient per interagire con una risorsa contenitore specifica:

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

Se l'ambito del lavoro è limitato a un singolo contenitore, è possibile scegliere di creare un oggetto BlobContainerClient direttamente senza usare BlobServiceClient. È comunque possibile impostare le opzioni del client in un client contenitore esattamente come in un client del servizio.

Gli esempi seguenti illustrano come creare un client contenitore direttamente senza usare 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

Creare un oggetto BlobClient

Per interagire con una risorsa BLOB specifica, creare un oggetto BlobClient da un client del servizio o da un client contenitore. Un oggetto BlobClient consente di interagire con una risorsa BLOB specifica. Non è necessario che questa risorsa esista nell'account di archiviazione per creare l'oggetto client. BlobClient fornisce metodi per caricare, scaricare, eliminare e creare snapshot di un BLOB.

Gli esempi seguenti illustrano come creare un client BLOB per interagire con una risorsa BLOB specifica:

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

Gestire gli oggetti client

Una procedura consigliata per la gestione dei client di Azure SDK consiste nel considerare un client come un oggetto singleton, ovvero una classe avrà un solo oggetto alla volta. Non è necessario mantenere più di un'istanza di un client per un determinato set di parametri del costruttore o di opzioni del client. Questo concetto può essere implementato in molti modi, tra cui:

• Creando un singolo oggetto client e passandolo come parametro in tutta l'applicazione. Questo approccio è illustrato negli esempi di codice di questo articolo.
• Archiviando un'istanza del client in un campo. Per altre informazioni sui campi C#, vedere Campi (Guida per programmatori C#).
• Registrando l'oggetto client come singleton in un contenitore di inserimento delle dipendenze preferito. Per altre informazioni sull'inserimento delle dipendenze nelle app ASP.NET Core, vedere Inserimento delle dipendenze con Azure SDK per .NET.

Questo approccio è molto più efficiente su larga scala rispetto alla chiamata di un costruttore per ogni client necessario.

Immutabilità dei client e thread safety

I client di Azure SDK non sono modificabili dopo la creazione, il che significa che non è possibile modificare l'endpoint a cui si connette, le credenziali usate per l'autorizzazione o altri valori passati come opzioni del client. L'immutabilità del client significa anche che i client sono sicuri da condividere e riutilizzare in tutta l'applicazione.

Se l'app deve usare configurazioni o credenziali diverse per i client dello stesso tipo, è possibile creare un'istanza di un client per ogni set di opzioni di configurazione.

Azure SDK garantisce che tutti i metodi di istanza del client siano thread-safe e indipendenti l'uno dall'altro. Questa progettazione garantisce che la condivisione e il riutilizzo delle istanze del client sia sempre sicura, anche tra thread.

Passaggi successivi

Per altre informazioni sull'uso delle librerie client di Archiviazione di Azure per usare le risorse dati, vedere gli articoli seguenti:

• Introduzione ad Archiviazione BLOB di Azure e a .NET
• Introduzione ad Archiviazione BLOB di Azure e Java
• Introduzione ad Archiviazione BLOB di Azure e JavaScript
• Introduzione ad Archiviazione BLOB di Azure e Python