Membuat dan mengelola objek klien yang berinteraksi dengan sumber daya data

Azure SDK adalah kumpulan pustaka yang dibuat untuk memudahkan penggunaan layanan Azure dari berbagai bahasa. SDK dirancang untuk menyederhanakan interaksi antara aplikasi Anda dan sumber daya Azure. Bekerja dengan sumber daya Azure menggunakan SDK dimulai dengan membuat instans klien. Artikel ini memperlihatkan cara membuat objek klien untuk berinteraksi dengan sumber daya data di Azure Blob Storage, dan menawarkan praktik terbaik tentang cara mengelola klien di aplikasi Anda.

Tentang objek klien

Pustaka klien Azure Blob Storage memungkinkan Anda berinteraksi dengan tiga jenis sumber daya dalam layanan penyimpanan:

• Akun penyimpanan
• Kontainer blob
• Blobs

Tergantung pada kebutuhan aplikasi Anda, Anda dapat membuat objek klien di salah satu dari tiga tingkat ini.

Untuk blob, ada klien blob umum yang mencakup operasi blob umum di semua jenis, dan ada klien blob khusus untuk setiap jenis (blob blok, blob penambahan, dan blob halaman).

Tabel berikut mencantumkan kelas klien yang berbeda untuk setiap bahasa:

Language	Paket	Kelas klien layanan	Kelas klien kontainer	Kelas klien blob
.NET	Azure.Storage.Blobs Azure.Storage.Blobs.Models Azure.Storage.Blobs.Specialized	KlienLayananBlob	BlobContainerClient	BlobClient BlockBlobClient AppendBlobClient PageBlobClient
Java	com.azure.storage.blob com.azure.storage.blob.models com.azure.storage.blob.specialized	KlienLayananBlob BlobServiceAsyncClient BlobServiceClientBuilder	BlobContainerClient BlobContainerAsyncClient BlobContainerClientBuilder	BlobClient BlobAsyncClient BlobClientBuilder BlockBlobClient AppendBlobClient PageBlobClient
JavaScript	@azure/storage-blob	KlienLayananBlob	ContainerClient	BlobClient BlockBlobClient AppendBlobClient PageBlobClient
Python	azure.storage.blob	KlienLayananBlob	ContainerClient	BlobClient1

¹ Untuk Python, BlobClient termasuk metode untuk jenis blob khusus.

Setiap jenis klien dapat dibuat dengan memanggil konstruktor sederhana, atau kelebihan beban yang mengambil berbagai opsi konfigurasi. Untuk Java, setiap jenis klien memiliki kelas terpisah yang menyediakan API penyusun untuk membantu konfigurasi dan instansiasi. Bergantung pada bahasa SDK, opsi konfigurasi klien ini diteruskan ke konstruktor dengan cara yang berbeda. Lihat referensi kelas dari tabel untuk detailnya.

Mengotorisasi objek klien

Agar aplikasi dapat mengakses sumber daya blob dan berinteraksi dengannya, objek klien harus diotorisasi. Sampel kode dalam artikel ini menggunakan DefaultAzureCredential untuk mengautentikasi ke Azure melalui perwakilan keamanan Microsoft Entra. Proses autentikasi termasuk mendapatkan token akses untuk otorisasi. Token akses ini diteruskan sebagai kredensial ketika klien dibuat, dan kredensial tetap ada sepanjang masa pakai klien. Perwakilan keamanan Microsoft Entra yang meminta token harus diberi peran Azure RBAC yang sesuai yang memberikan akses ke data blob. Untuk mempelajari selengkapnya, lihat Menetapkan peran Azure untuk akses ke data blob.

Mekanisme otorisasi berikut dapat digunakan untuk memberikan tingkat akses yang sesuai ke objek klien:

• ID Microsoft Entra: direkomendasikan untuk keamanan yang optimal
• Tanda tangan akses bersama (SAS): didukung, dan paling aman saat menggunakan token SAS delegasi pengguna
• Kunci akses akun (Kunci Bersama): didukung, tetapi tidak disarankan karena dapat kurang aman

Untuk mempelajari selengkapnya tentang otorisasi, lihat Mengotorisasi akses ke data di Azure Storage.

Membuat objek klien

Bekerja dengan sumber daya Azure apa pun menggunakan SDK dimulai dengan membuat objek klien. Di bagian ini, Anda mempelajari cara membuat objek klien untuk berinteraksi dengan tiga jenis sumber daya dalam layanan penyimpanan: akun penyimpanan, kontainer, dan blob.

Saat aplikasi Anda membuat objek klien, Anda meneruskan URI yang mereferensikan titik akhir ke konstruktor klien. Anda dapat membuat string titik akhir secara manual, seperti yang diperlihatkan dalam contoh dalam artikel ini, atau Anda dapat mengkueri titik akhir saat runtime menggunakan pustaka manajemen Azure Storage. Untuk mempelajari cara mengkueri titik akhir, lihat Kueri untuk titik akhir Blob Storage.

Membuat objek BlobServiceClient

Objek resmi BlobServiceClient memungkinkan aplikasi Anda berinteraksi dengan sumber daya di tingkat akun penyimpanan. BlobServiceClient menyediakan metode untuk mengambil dan mengonfigurasi properti akun, serta mencantumkan, membuat, dan menghapus kontainer dalam akun penyimpanan. Objek klien ini adalah titik awal untuk berinteraksi dengan sumber daya di akun penyimpanan.

Skenario umum adalah membuat instans klien layanan tunggal, lalu membuat klien kontainer dan klien blob dari klien layanan, sesuai kebutuhan. Untuk bekerja dengan kontainer atau blob tertentu, Anda dapat menggunakan BlobServiceClient objek untuk membuat klien kontainer atau klien blob. Klien yang BlobServiceClient dibuat dari akan mewarisi konfigurasi kliennya, termasuk opsi klien dan kredensial.

Contoh berikut menunjukkan cara membuat BlobServiceClient objek:

.NET

Tambahkan instruksi using berikut:

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

Tambahkan kode berikut untuk membuat objek klien:

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

    return client;
}

Java

Tambahkan instruksi import berikut:

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

Tambahkan kode berikut untuk membuat objek klien:

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

Tambahkan pernyataan require berikut:

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

Tambahkan kode berikut untuk membuat objek klien:

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

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

Python

Tambahkan pernyataan import berikut:

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

Tambahkan kode berikut untuk membuat objek klien:

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

Membuat objek BlobContainerClient

Anda dapat menggunakan BlobServiceClient objek untuk membuat objek baru BlobContainerClient (ContainerClient untuk JavaScript dan Python). Objek BlobContainerClient memungkinkan Anda berinteraksi dengan sumber daya kontainer tertentu. Sumber daya ini tidak perlu ada di akun penyimpanan bagi Anda untuk membuat objek klien. BlobContainerClient menyediakan metode untuk membuat, menghapus, atau mengonfigurasi kontainer, dan menyertakan metode untuk mencantumkan, mengunggah, dan menghapus blob di dalamnya. Untuk melakukan operasi pada blob tertentu dalam kontainer, Anda dapat membuat klien blob.

Contoh berikut menunjukkan cara membuat klien kontainer dari BlobServiceClient objek untuk berinteraksi dengan sumber daya kontainer tertentu:

.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

Jika pekerjaan Anda dilingkup secara sempit ke satu kontainer, Anda dapat memilih untuk membuat BlobContainerClient objek secara langsung tanpa menggunakan BlobServiceClient. Anda masih dapat mengatur opsi klien pada klien kontainer seperti yang Anda lakukan pada klien layanan.

Contoh berikut menunjukkan cara membuat klien kontainer secara langsung tanpa menggunakan 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

Membuat objek BlobClient

Untuk berinteraksi dengan sumber daya blob tertentu, buat BlobClient objek dari klien layanan atau klien kontainer. Objek BlobClient memungkinkan Anda berinteraksi dengan sumber daya blob tertentu. Sumber daya ini tidak perlu ada di akun penyimpanan bagi Anda untuk membuat objek klien. BlobClient menyediakan metode untuk mengunggah, mengunduh, menghapus, dan membuat rekam jepret blob.

Contoh berikut menunjukkan cara membuat klien blob untuk berinteraksi dengan sumber daya blob tertentu:

.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

Mengelola objek klien

Praktik terbaik untuk manajemen klien Azure SDK adalah memperlakukan klien sebagai singleton, yang berarti bahwa kelas hanya akan memiliki satu objek pada satu waktu. Tidak perlu menyimpan lebih dari satu instans klien untuk serangkaian parameter konstruktor atau opsi klien tertentu. Konsep ini dapat diimplementasikan dalam banyak hal, termasuk:

• Membuat satu objek klien dan meneruskannya sebagai parameter di seluruh aplikasi. Pendekatan ini ditunjukkan dalam contoh kode dalam artikel ini.
• Menyimpan instans klien di bidang. Untuk mempelajari selengkapnya tentang bidang C#, lihat Bidang (Panduan Pemrograman C#).
• Mendaftarkan objek klien sebagai singleton dalam kontainer injeksi dependensi pilihan Anda. Untuk informasi selengkapnya tentang injeksi dependensi di aplikasi ASP.NET Core, lihat Injeksi dependensi dengan Azure SDK untuk .NET.

Pendekatan ini jauh lebih efisien dalam skala besar daripada memanggil konstruktor untuk setiap klien yang Anda butuhkan.

Kekekalan klien dan keamanan utas

Klien Azure SDK tidak dapat diubah setelah dibuat, yang berarti Anda tidak dapat mengubah titik akhir yang disambungkannya, kredensial yang digunakan untuk otorisasi, atau nilai lain yang diteruskan sebagai opsi klien. Kekekalan klien juga berarti bahwa klien aman untuk berbagi dan menggunakan kembali di seluruh aplikasi.

Jika aplikasi Anda perlu menggunakan konfigurasi atau kredensial yang berbeda untuk klien dengan jenis yang sama, Anda dapat membuat instans klien untuk setiap set opsi konfigurasi.

Azure SDK menjamin bahwa semua metode instans klien aman dan independen satu sama lain. Desain ini memastikan bahwa berbagi dan menggunakan kembali instans klien selalu aman, bahkan di seluruh utas.

Langkah berikutnya

Untuk mempelajari selengkapnya tentang menggunakan pustaka klien Azure Storage untuk bekerja dengan sumber daya data, lihat artikel berikut ini:

• Memulai Azure Blob Storage dan .NET
• Mulai menggunakan Azure Blob Storage dan Java
• Memulai Azure Blob Storage dan JavaScript
• Mulai menggunakan Azure Blob Storage dan Python