Créer et gérer des objets clients qui interagissent avec les ressources de données

Les Kits de développement logiciel (SDK) Azure sont des collections de bibliothèques conçues pour faciliter l’utilisation des services Azure à partir de différents langages. Les Kits de développement logiciel (SDK) sont conçus pour simplifier les interactions entre votre application et les ressources Azure. L’utilisation des ressources Azure à l’aide du Kit de développement logiciel (SDK) commence par la création d’une instance cliente. Cet article explique comment créer des objets clients pour interagir avec les ressources de données dans Stockage Blob Azure et propose les meilleures pratiques sur la gestion des clients dans votre application.

À propos des objets clients

Les bibliothèques clientes Stockage Blob Azure vous permettent d’interagir avec trois types de ressources dans le service de stockage :

• Comptes de stockage
• Conteneurs d’objets blob
• Objets blob

Selon les besoins de votre application, vous pouvez créer des objets clients à l’un de ces trois niveaux.

Pour les objets blob, il existe un client d’objet blob général qui couvre les opérations d’objet blob courantes sur tous les types, et il existe des clients d’objets blob spécialisés pour chaque type (objet blob de blocs, objet blob d’ajout et objet blob de pages).

Le tableau suivant répertorie les différentes classes de client pour chaque langage :

¹ Pour Python, BlobClient inclut des méthodes pour les types d’objets blob spécialisés.

Chaque type de client peut être instancié en appelant un constructeur simple ou une surcharge qui accepte différentes options de configuration. Pour Java, chaque type de client a une classe distincte qui fournit une API de générateur pour faciliter la configuration et l’instanciation. Selon le Kit de développement logiciel (SDK) de langage, ces options de configuration client sont passées au constructeur de différentes manières. Pour plus d’informations, consultez la référence de classe dans le tableau.

Autoriser un objet client

Pour qu’une application accède aux ressources blob et interagisse avec celles-ci, un objet client doit être autorisé. Les exemples de code de cet article utilisent DefaultAzureCredential pour s’authentifier auprès d’Azure via un principal de sécurité Microsoft Entra. Le processus d’authentification comprend l’obtention d’un jeton d’accès pour l’autorisation. Ce jeton d’accès est passé en tant qu’informations d’identification lorsque le client est instancié et que les informations d’identification sont conservées tout au long de la durée de vie du client. Le principal de sécurité Microsoft Entra qui demande le jeton doit se voir attribuer un rôle RBAC Azure approprié qui accorde l’accès aux données d’objet blob. Pour plus d’informations, consultez Attribuer un rôle Azure pour l’accès aux données d’objet blob.

Les mécanismes d’autorisation suivants peuvent être utilisés pour accorder le niveau d’accès approprié à un objet client :

• Microsoft Entra ID : recommandé pour une sécurité optimale
• Signature d’accès partagé (SAP) : prise en charge et plus sécurisée lors de l’utilisation d’un jeton SAP de délégation d’utilisateur
• Clé d’accès au compte (clé partagée) : prise en charge, mais non recommandée, car elle peut être moins sécurisée

Pour en savoir plus sur l’autorisation, consultez Autoriser l’accès aux données dans Stockage Azure.

Créer un objet client

L’utilisation des ressources Azure à l’aide du Kit de développement logiciel (SDK) commence par la création d’un objet client. Dans cette section, vous allez apprendre à créer des objets clients pour interagir avec les trois types de ressources du service de stockage : comptes de stockage, conteneurs et objets blob.

Lorsque votre application crée un objet client, vous transmettez un URI référençant le point de terminaison au constructeur client. Vous pouvez construire la chaîne de point de terminaison manuellement, comme illustré dans les exemples de cet article, ou vous pouvez interroger le point de terminaison au moment de l’exécution à l’aide de la bibliothèque de gestion Stockage Azure. Pour savoir comment interroger un point de terminaison, consultez Requête pour un point de terminaison Stockage Blob.

Créer un objet BlobServiceClient

Un objet BlobServiceClient autorisé permet à votre application d’interagir avec les ressources au niveau du compte de stockage. BlobServiceClient fournit des méthodes pour récupérer et configurer les propriétés du compte, ainsi que répertorier, créer et supprimer des conteneurs dans le compte de stockage. Cet objet client est le point de départ pour interagir avec les ressources du compte de stockage.

Un scénario courant consiste à instancier un client de service unique, puis à créer des clients de conteneur et des clients d’objet blob à partir du client de service, si nécessaire. Pour utiliser un conteneur ou un objet blob spécifique, vous pouvez utiliser l’objet BlobServiceClient pour créer un client de conteneur ou un client d’objet blob. Les clients créés à partir d’un BlobServiceClient héritent de sa configuration client, y compris les options et les informations d’identification du client.

Les exemples suivants montrent comment créer un objet 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

Créer un objet BlobContainerClient

Vous pouvez utiliser un objet BlobServiceClient pour créer un objet BlobContainerClient (ContainerClient pour JavaScript et Python). Un objet BlobContainerClient vous permet d’interagir avec une ressource de conteneur spécifique. Cette ressource n’a pas besoin d’exister dans le compte de stockage pour que vous créiez l’objet client. BlobContainerClient fournit des méthodes pour créer, supprimer ou configurer un conteneur, et inclut des méthodes pour répertorier, charger et supprimer les objets blob qu’il contient. Pour effectuer des opérations sur un objet blob spécifique dans le conteneur, vous pouvez créer un client d’objet blob.

Les exemples suivants montrent comment créer un client de conteneur à partir d’un objet BlobServiceClient pour interagir avec une ressource de conteneur spécifique :

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

Si votre travail est limité à un seul conteneur, vous pouvez choisir de créer un objet BlobContainerClient directement sans utiliser BlobServiceClient. Vous pouvez toujours définir des options client sur un client de conteneur comme vous le feriez sur un client de service.

Les exemples suivants montrent comment créer un client de conteneur directement sans utiliser 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

Créer un objet BlobClient

Pour interagir avec une ressource d’objet blob spécifique, créez un objet BlobClient à partir d’un client de service ou d’un client de conteneur. Un objet BlobClient vous permet d’interagir avec une ressource d’objet blob spécifique. Cette ressource n’a pas besoin d’exister dans le compte de stockage pour que vous créiez l’objet client. BlobClient fournit des méthodes pour charger, télécharger, supprimer et créer des instantanés d’un objet blob.

Les exemples suivants montrent comment créer un client d’objet blob pour interagir avec une ressource d’objet blob spécifique :

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

Créer des objets clients

Une bonne pratique pour la gestion des clients du Kit de développement logiciel (SDK) Azure consiste à traiter un client comme un singleton, ce qui signifie qu’une classe n’aura qu’un seul objet à la fois. Il n’est pas nécessaire de conserver plusieurs instances d’un client pour un ensemble donné de paramètres de constructeur ou d’options client. Ce concept peut être implémenté de plusieurs façons, notamment :

• Création d’un objet client unique et transmission de celui-ci en tant que paramètre dans l’application. Cette approche est illustrée dans les exemples de code de cet article.
• Stockage d’une instance cliente dans un champ. Pour en savoir plus sur les champs C#, consultez Champs (Guide de programmation C#).
• Inscription de l’objet client en tant que singleton dans un conteneur d’injection de dépendances de votre choix. Pour plus d’informations sur l’injection de dépendances dans les applications ASP.NET Core, consultez Injection de dépendances avec le Kit de développement logiciel (SDK) Azure pour .NET.

Cette approche est beaucoup plus efficace à grande échelle que l’appel d’un constructeur pour chaque client dont vous avez besoin.

Immuabilité du client et cohérence de thread

Les clients du Kit de développement logiciel (SDK) Azure sont immuables après leur création, ce qui signifie que vous ne pouvez pas modifier le point de terminaison auquel il se connecte, les informations d’identification utilisées pour l’autorisation ou d’autres valeurs passées en tant qu’options client. L’immuabilité des clients signifie également que les clients peuvent être partagés et réutilisés en toute sécurité dans l’ensemble de l’application.

Si votre application doit utiliser différentes configurations ou informations d’identification pour les clients du même type, vous pouvez instancier un client pour chaque ensemble d’options de configuration.

Le Kit de développement logiciel (SDK) Azure garantit que toutes les méthodes d’instance clientes sont thread-safe et indépendantes les unes des autres. Cette conception garantit que le partage et la réutilisation des instances clientes sont toujours sécurisés, même entre les threads.

Étapes suivantes

Pour en savoir plus sur l’utilisation des bibliothèques clientes Stockage Azure pour utiliser des ressources de données, consultez les articles suivants :

• Prise en main de Stockage Blob Azure et .NET
• Bien démarrer avec le Stockage Blob Azure et Java
• Prise en main de Stockage Blob Azure et JavaScript
• Bien démarrer avec le service Stockage Blob Azure et Python