Clientobjecten maken en beheren die communiceren met gegevensbronnen

De Azure SDK's zijn verzamelingen bibliotheken die zijn gebouwd om het gebruik van Azure-services uit verschillende talen eenvoudiger te maken. De SDK's zijn ontworpen om interacties tussen uw toepassing en Azure-resources te vereenvoudigen. Het werken met Azure-resources met behulp van de SDK begint met het maken van een clientexemplaren. In dit artikel wordt beschreven hoe u clientobjecten maakt om te communiceren met gegevensbronnen in Azure Blob Storage en aanbevolen procedures biedt voor het beheren van clients in uw toepassing.

Over clientobjecten

Met de Azure Blob Storage-clientbibliotheken kunt u communiceren met drie typen resources in de opslagservice:

• Opslagaccounts
• Blobcontainers
• Blobs

Afhankelijk van de behoeften van uw toepassing kunt u clientobjecten maken op een van deze drie niveaus.

Voor blobs is er een algemene blobclient die algemene blobbewerkingen voor alle typen omvat, en er zijn speciale blobclients voor elk type (blok-blob, toevoeg-blob en pagina-blob).

De volgende tabel bevat de verschillende clientklassen voor elke taal:

Taal	Pakketten	Serviceclientklasse	Containerclientklasse	Blob-clientklassen
.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

¹ Voor Python BlobClient bevat methoden voor gespecialiseerde blobtypen.

Elk clienttype kan worden geïnstantieerd door een eenvoudige constructor aan te roepen of een overbelasting waarvoor verschillende configuratieopties nodig zijn. Voor Java heeft elk clienttype een afzonderlijke klasse die een opbouw-API biedt om u te helpen bij de configuratie en instantiëring. Afhankelijk van de taal-SDK worden deze clientconfiguratieopties op verschillende manieren doorgegeven aan de constructor. Zie de klassereferentie uit de tabel voor meer informatie.

Een clientobject autoriseren

Een app kan alleen toegang krijgen tot blob-resources en ermee communiceren als een clientobject is geautoriseerd. De codevoorbeelden in dit artikel gebruiken DefaultAzureCredential om te verifiëren bij Azure via een Microsoft Entra-beveiligingsprincipaal. Het verificatieproces omvat het verkrijgen van een toegangstoken voor autorisatie. Dit toegangstoken wordt doorgegeven als referentie wanneer de client wordt geïnstantieerd en de referenties blijven behouden gedurende de levensduur van de client. Aan de Microsoft Entra-beveiligingsprincipaal die het token aanvraagt, moet een geschikte Azure RBAC-rol worden toegewezen die toegang verleent tot blobgegevens. Zie Een Azure-rol toewijzen voor toegang tot blobgegevens voor meer informatie.

De volgende autorisatiemechanismen kunnen worden gebruikt om het juiste toegangsniveau tot een clientobject te verlenen:

• Microsoft Entra ID: aanbevolen voor optimale beveiliging
• Shared Access Signature (SAS): ondersteund en het veiligst bij het gebruik van een SAS-token voor gebruikersdelegering
• Accounttoegangssleutel (gedeelde sleutel): ondersteund, maar niet aanbevolen omdat deze minder veilig kan zijn

Zie Toegang tot gegevens in Azure Storage autoriseren voor meer informatie over autorisatie.

Een clientobject maken

Werken met een Azure-resource met behulp van de SDK begint met het maken van een clientobject. In deze sectie leert u hoe u clientobjecten maakt om te communiceren met de drie typen resources in de opslagservice: opslagaccounts, containers en blobs.

Wanneer uw toepassing een clientobject maakt, geeft u een URI door die naar het eindpunt verwijst naar de clientconstructor. U kunt de eindpunttekenreeks handmatig samenstellen, zoals wordt weergegeven in de voorbeelden in dit artikel, of u kunt tijdens runtime een query uitvoeren op het eindpunt met behulp van de Azure Storage-beheerbibliotheek. Zie Query voor een Blob Storage-eindpunt voor meer informatie over het uitvoeren van query's voor een eindpunt.

Een BlobServiceClient-object maken

Met een geautoriseerd BlobServiceClient object kan uw app communiceren met resources op het niveau van het opslagaccount. BlobServiceClient biedt methoden voor het ophalen en configureren van accounteigenschappen, evenals het weergeven, maken en verwijderen van containers binnen het opslagaccount. Dit clientobject is het startpunt voor interactie met resources in het opslagaccount.

Een veelvoorkomend scenario is het instantiëren van één serviceclient en vervolgens indien nodig containerclients en blobclients maken van de serviceclient. Als u wilt werken met een specifieke container of blob, kunt u het BlobServiceClient object gebruiken om een containerclient of blobclient te maken. Clients die zijn gemaakt op basis van een BlobServiceClient client, nemen de clientconfiguratie over, inclusief clientopties en referenties.

In de volgende voorbeelden ziet u hoe u een BlobServiceClient object maakt:

.NET

Voeg de volgende using-instructies toe:

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

Voeg de volgende code toe om het clientobject te maken:

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

    return client;
}

Java

Voeg de volgende import-instructies toe:

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

Voeg de volgende code toe om het clientobject te maken:

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

Voeg de volgende require instructies toe:

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

Voeg de volgende code toe om het clientobject te maken:

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

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

Python

Voeg de volgende import instructies toe:

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

Voeg de volgende code toe om het clientobject te maken:

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

Een BlobContainerClient-object maken

U kunt een BlobServiceClient object gebruiken om een nieuw BlobContainerClient object te maken (ContainerClient voor JavaScript en Python). Met BlobContainerClient een object kunt u communiceren met een specifieke containerresource. Deze resource hoeft niet te bestaan in het opslagaccount om het clientobject te maken. BlobContainerClient biedt methoden voor het maken, verwijderen of configureren van een container en bevat methoden voor het weergeven, uploaden en verwijderen van de blobs erin. Als u bewerkingen wilt uitvoeren op een specifieke blob in de container, kunt u een blobclient maken.

In de volgende voorbeelden ziet u hoe u een containerclient maakt op basis van een BlobServiceClient object om te communiceren met een specifieke containerresource:

.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

Als uw werk beperkt is tot één container, kunt u ervoor kiezen om rechtstreeks een BlobContainerClient object te maken zonder dat u dit hoeft te gebruiken BlobServiceClient. U kunt nog steeds clientopties instellen op een containerclient, net zoals u dat zou doen op een serviceclient.

In de volgende voorbeelden ziet u hoe u rechtstreeks een containerclient maakt zonder gebruik te maken BlobServiceClientvan:

.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

Een BlobClient-object maken

Als u wilt communiceren met een specifieke blobresource, maakt u een BlobClient object op basis van een serviceclient of containerclient. Met BlobClient een object kunt u communiceren met een specifieke blobresource. Deze resource hoeft niet te bestaan in het opslagaccount om het clientobject te maken. BlobClient biedt methoden voor het uploaden, downloaden, verwijderen en maken van momentopnamen van een blob.

In de volgende voorbeelden ziet u hoe u een blobclient maakt om te communiceren met een specifieke blobresource:

.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

Clientobjecten beheren

Een best practice voor Azure SDK-clientbeheer is om een client als singleton te behandelen, wat betekent dat een klasse slechts één object tegelijk heeft. Het is niet nodig om meer dan één exemplaar van een client te bewaren voor een bepaalde set constructorparameters of clientopties. Dit concept kan op veel manieren worden geïmplementeerd, waaronder:

• Eén clientobject maken en doorgeven als een parameter in de toepassing. Deze benadering wordt weergegeven in de codevoorbeelden in dit artikel.
• Een clientexemplaren opslaan in een veld. Zie Velden (C#-programmeerhandleiding) voor meer informatie over C#-velden.
• Het clientobject registreren als een singleton in een container voor afhankelijkheidsinjectie van uw keuze. Zie Afhankelijkheidsinjectie met de Azure SDK voor .NET voor meer informatie over afhankelijkheidsinjectie in ASP.NET Core-apps.

Deze benadering is veel efficiënter op schaal dan het aanroepen van een constructor voor elke client die u nodig hebt.

Onveranderbaarheid van clients en threadveiligheid

Azure SDK-clients kunnen onveranderbaar zijn nadat ze zijn gemaakt, wat betekent dat u het eindpunt waarmee het verbinding maakt, de referenties die worden gebruikt voor autorisatie of andere waarden die als clientopties worden doorgegeven, niet kunt wijzigen. Onveranderbaarheid van clients betekent ook dat clients veilig zijn om te delen en opnieuw te gebruiken in de hele toepassing.

Als uw app verschillende configuraties of referenties moet gebruiken voor clients van hetzelfde type, kunt u een client instantiëren voor elke set configuratieopties.

De Azure SDK garandeert dat alle methoden voor clientexemplaren thread-veilig en onafhankelijk van elkaar zijn. Dit ontwerp zorgt ervoor dat het delen en hergebruiken van clientexemplaren altijd veilig is, zelfs tussen threads.

Volgende stappen

Zie de volgende artikelen voor meer informatie over het gebruik van de Azure Storage-clientbibliotheken om met gegevensresources te werken:

• Aan de slag met Azure Blob Storage en .NET
• Aan de slag met Azure Blob Storage en Java
• Aan de slag met Azure Blob Storage en JavaScript
• Aan de slag met Azure Blob Storage en Python