Adaterőforrásokkal interakcióba lépő ügyfélobjektumok létrehozása és kezelése

Az Azure SDK-k kódtárak gyűjteményei, amelyek megkönnyítik a különböző nyelvekről származó Azure-szolgáltatások használatát. Az SDK-k célja az alkalmazás és az Azure-erőforrások közötti interakció egyszerűsítése. Az Azure-erőforrások SDK-val való használata egy ügyfélpéldány létrehozásával kezdődik. Ez a cikk bemutatja, hogyan hozhat létre ügyfélobjektumokat az Azure Blob Storage-beli adaterőforrásokkal való interakcióhoz, és ajánlott eljárásokat kínál az ügyfelek alkalmazásbeli kezelésével kapcsolatban.

Tudnivalók az ügyfélobjektumokról

Az Azure Blob Storage-ügyfélkódtárak három típusú erőforrás használatát teszik lehetővé a tárolási szolgáltatásban:

• Storage fiókok
• Blobtárolók
• Blobok

Az alkalmazás igényeitől függően ezen három szint bármelyikében létrehozhat ügyfélobjektumokat.

A blobok esetében létezik egy általános blobügyfél, amely minden típusra kiterjedő gyakori blobműveleteket fed le, és mindegyik típushoz (blokkblob, hozzáfűző blob és lapblob) speciális blobügyfelek tartoznak.

Az alábbi táblázat felsorolja az egyes nyelvekhez tartozó különböző ügyfélosztályokat:

Language	Csomagok	Szolgáltatásügyfél-osztály	Tárolóügyfél-osztály	Blob ügyfélosztályok
.NET	Azure.Storage.Blobs Azure.Storage.Blobs.Models Azure.Storage.Blobs.Special	BlobServiceClient	BlobContainerClient	BlobClient BlockBlobClient AppendBlobClient PageBlobClient
Java	com.azure.storage.blob com.azure.storage.blob.models com.azure.storage.blob.specializált	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

¹ Python BlobClient esetén a speciális blobtípusok módszereit tartalmazza.

Minden ügyféltípus példányosítható egy egyszerű konstruktor meghívásával, vagy egy olyan túlterheléssel, amely különböző konfigurációs beállításokat vesz igénybe. Java esetén minden ügyféltípus külön osztálysal rendelkezik, amely egy builder API-t biztosít a konfigurációhoz és a példányosításhoz. A nyelvi SDK-tól függően ezeket az ügyfélkonfigurációs beállításokat a rendszer különböző módokon továbbítja a konstruktornak. Részletekért tekintse meg a táblázat osztályhivatkozását.

Ügyfélobjektum engedélyezése

Ahhoz, hogy egy alkalmazás hozzáférhessen a bloberőforrásokhoz és kommunikáljon velük, engedélyezni kell egy ügyfélobjektumot. A cikkben szereplő kódminták a DefaultAzureCredential használatával hitelesíthetők az Azure-ban egy Microsoft Entra biztonsági tagon keresztül. A hitelesítési folyamat magában foglalja egy hozzáférési jogkivonat beszerzését az engedélyezéshez. Ez a hozzáférési jogkivonat hitelesítő adatként lesz átadva az ügyfél példányosításakor, és a hitelesítő adatok az ügyfél teljes élettartama alatt megmaradnak. A jogkivonatot kérő Microsoft Entra biztonsági taghoz hozzá kell rendelni egy megfelelő Azure RBAC-szerepkört, amely hozzáférést biztosít a blobadatokhoz. További információ: Azure-szerepkör hozzárendelése blobadatokhoz való hozzáféréshez.

Az alábbi engedélyezési mechanizmusokkal biztosíthatja az ügyfélobjektumok megfelelő szintű hozzáférését:

• Microsoft Entra ID: az optimális biztonság érdekében ajánlott
• Közös hozzáférésű jogosultságkód (SAS): támogatott és legbiztonságosabb felhasználói delegálási SAS-jogkivonat használatakor
• Fiókelérési kulcs (megosztott kulcs):: támogatott, de nem ajánlott, mivel kevésbé biztonságos

Az engedélyezéssel kapcsolatos további információkért lásd : Adatokhoz való hozzáférés engedélyezése az Azure Storage-ban.

Ügyfélobjektum létrehozása

Bármely Azure-erőforrás SDK-val való használata egy ügyfélobjektum létrehozásával kezdődik. Ebben a szakaszban megtudhatja, hogyan hozhat létre ügyfélobjektumokat a tárolási szolgáltatás három erőforrástípusával való interakcióhoz: tárfiókok, tárolók és blobok.

Amikor az alkalmazás létrehoz egy ügyfélobjektumot, átad egy URI-t, amely a végpontra hivatkozik az ügyfélkonstruktornak. A végponti sztringet manuálisan is létrehozhatja, ahogyan az ebben a cikkben látható példákban látható, vagy lekérdezheti a végpontot futtatókörnyezetben az Azure Storage felügyeleti kódtárával. A végpontok lekérdezéséről a Blob Storage-végpont lekérdezése című témakörben olvashat.

BlobServiceClient-objektum létrehozása

Egy engedélyezett BlobServiceClient objektum lehetővé teszi, hogy az alkalmazás a tárfiók szintjén kommunikáljon az erőforrásokkal. BlobServiceClient metódusokat biztosít a fióktulajdonságok lekéréséhez és konfigurálásához, valamint tárolók listázásához, létrehozásához és törléséhez a tárfiókban. Ez az ügyfélobjektum a tárfiók erőforrásaival való interakció kiindulópontja.

Gyakori forgatókönyv egyetlen szolgáltatásügyfél példányosítása, majd szükség szerint tárolóügyfelek és blobügyfelek létrehozása a szolgáltatásügyfélből. Ha egy adott tárolóval vagy blobgal szeretne dolgozni, az BlobServiceClient objektummal létrehozhat egy tárolóügyfélt vagy blobügyfélt. Az egyből BlobServiceClient létrehozott ügyfelek öröklik az ügyfélkonfigurációt, beleértve az ügyfélbeállításokat és a hitelesítő adatokat.

Az alábbi példák azt mutatják be, hogyan hozhat létre objektumot BlobServiceClient :

.NET

Adja hozzá a következő using irányelveket:

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

Adja hozzá a következő kódot az ügyfélobjektum létrehozásához:

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

    return client;
}

Java

Adja hozzá a következő import irányelveket:

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

Adja hozzá a következő kódot az ügyfélobjektum létrehozásához:

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

Adja hozzá a következő require-utasításokat:

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

Adja hozzá a következő kódot az ügyfélobjektum létrehozásához:

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

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

Python

Adja hozzá a következő import-utasításokat:

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

Adja hozzá a következő kódot az ügyfélobjektum létrehozásához:

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

BlobContainerClient-objektum létrehozása

Egy objektum használatával BlobServiceClient új BlobContainerClient objektumot hozhat létre (ContainerClient JavaScripthez és Pythonhoz). Az BlobContainerClient objektumok lehetővé teszik egy adott tárolóerőforrás használatát. Ennek az erőforrásnak nem kell léteznie a tárfiókban az ügyfélobjektum létrehozásához. BlobContainerClient metódusokat biztosít a tárolók létrehozásához, törléséhez vagy konfigurálásához, valamint a benne lévő blobok listázására, feltöltésére és törlésére szolgáló metódusokat tartalmaz. Ha egy adott blobon szeretne műveleteket végrehajtani a tárolón belül, létrehozhat egy blobügyfélt.

Az alábbi példák azt mutatják be, hogyan hozhat létre tárolóügyfélt egy BlobServiceClient objektumból egy adott tárolóerőforrás használatához:

.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

Ha a munka hatóköre szűken egyetlen tárolóra van korlátozva, akkor dönthet úgy, hogy közvetlenül a használata BlobServiceClientnélkül hoz létre objektumotBlobContainerClient. A tárolóügyfél ügyfélbeállításai továbbra is ugyanúgy beállíthatók, mint egy szolgáltatásügyfélben.

Az alábbi példák bemutatják, hogyan hozhat létre közvetlenül tárolóügyfélt anélkül, hogy a következőt használtákBlobServiceClient:

.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

BlobClient-objektum létrehozása

Ha egy adott bloberőforrást szeretne használni, hozzon létre egy BlobClient objektumot egy szolgáltatásügyfélből vagy egy tárolóügyfélből. Az BlobClient objektumok lehetővé teszik egy adott bloberőforrás használatát. Ennek az erőforrásnak nem kell léteznie a tárfiókban az ügyfélobjektum létrehozásához. BlobClient metódusokat biztosít a blobok feltöltéséhez, letöltéséhez, törléséhez és pillanatképek létrehozásához.

Az alábbi példák bemutatják, hogyan hozhat létre blobügyfélt egy adott bloberőforrással való interakcióhoz:

.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

Ügyfélobjektumok kezelése

Az Azure SDK-ügyfélkezelés ajánlott eljárása az ügyfél egyszeri kezelése, ami azt jelenti, hogy egy osztálynak egyszerre csak egy objektuma lesz. Egy adott konstruktorparaméterhez vagy ügyfélbeállításokhoz nem kell egynél több ügyfélpéldányt tartania. Ez a koncepció számos módon implementálható, többek között:

• Egyetlen ügyfélobjektum létrehozása és paraméterként való átadása az egész alkalmazásban. Ez a megközelítés a jelen cikkben szereplő kód példákban látható.
• Ügyfélpéldány tárolása egy mezőben. A C# mezőkkel kapcsolatos további információkért lásd a Mezők (C# programozási útmutató) című témakört.
• Az ügyfélobjektum egyszeri regisztrálása egy tetszőleges függőséginjektálási tárolóban. Az ASP.NET Core-alkalmazások függőséginjektálásával kapcsolatos további információkért lásd : Függőséginjektálás az Azure SDK for .NET-hez.

Ez a megközelítés sokkal hatékonyabb, mint konstruktort hívni minden szükséges ügyfélhez.

Ügyfél nem módosítható és menetbiztonság

Az Azure SDK-ügyfelek a létrehozásuk után nem módosíthatók, ami azt jelenti, hogy nem módosítható a végpont, amelyhez csatlakozik, az engedélyezéshez használt hitelesítő adatokat vagy az ügyfélbeállításokként átadott egyéb értékeket. Az ügyfél nem módosíthatósága azt is jelenti, hogy az ügyfelek biztonságosan megoszthatják és újra felhasználhatják az alkalmazást.

Ha az alkalmazásnak különböző konfigurációkat vagy hitelesítő adatokat kell használnia az azonos típusú ügyfelekhez, minden konfigurációs beállításhoz létrehozhat egy ügyfelet.

Az Azure SDK garantálja, hogy minden ügyfélpéldány-metódus szálbiztos és független egymástól. Ez a kialakítás biztosítja, hogy az ügyfélpéldányok megosztása és újrafelhasználása mindig biztonságos legyen, akár több szálon is.

Következő lépések

Az Azure Storage-ügyfélkódtárak adaterőforrásokkal való használatáról az alábbi cikkekben olvashat bővebben:

• Az Azure Blob Storage és a .NET használatának első lépései
• Az Azure Blob Storage és a Java használatának első lépései
• Az Azure Blob Storage és a JavaScript használatának első lépései
• Az Azure Blob Storage és a Python használatának első lépései