Veri kaynaklarıyla etkileşim kuran istemci nesneleri oluşturma ve yönetme

Makale
03/25/2023

Azure SDK'ları, farklı dillerden Azure hizmetlerini kullanmayı kolaylaştırmak için oluşturulmuş kitaplık koleksiyonlarıdır. SDK'lar, uygulamanızla Azure kaynakları arasındaki etkileşimleri basitleştirmek için tasarlanmıştır. SDK kullanarak Azure kaynaklarıyla çalışma, istemci örneği oluşturmayla başlar. Bu makalede, Azure Blob Depolama'daki veri kaynaklarıyla etkileşim kurmak için istemci nesnelerinin nasıl oluşturulacağı gösterilmektedir ve uygulamanızdaki istemcilerin nasıl yönetileceğini gösteren en iyi yöntemler sunulmaktadır.

İstemci nesneleri hakkında

Azure Blob Depolama istemci kitaplıkları, depolama hizmetindeki üç tür kaynakla etkileşim kurmanızı sağlar:

Depolama hesapları
Blob kapsayıcıları
Bloblar

Uygulamanızın gereksinimlerine bağlı olarak, bu üç düzeyden herhangi birinde istemci nesneleri oluşturabilirsiniz.

Bloblar için, tüm türlerdeki yaygın blob işlemlerini kapsayan genel bir blob istemcisi vardır ve her tür için özel blob istemcileri vardır (blok blobu, ekleme blobu ve sayfa blobu).

Aşağıdaki tabloda her dil için farklı istemci sınıfları listelenir:

Dil	Paketler	Hizmet istemci sınıfı	Kapsayıcı istemci sınıfı	Blob istemci sınıfları
.NET	Azure. Depolama. Blob Azure. Depolama. Bloblar.Modeller Azure. Depolama. Bloblar.Özelleştirilmiş	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	BlobClient¹

¹ Python için özel BlobClient blob türleri için yöntemler içerir.

Her istemci türü, basit bir oluşturucu çağrılarak veya çeşitli yapılandırma seçeneklerini alan bir aşırı yüklemeyle örneklenebilir. Java için her istemci türü, yapılandırma ve örnek oluşturma konusunda yardımcı olacak bir oluşturucu API'sini sağlayan ayrı bir sınıfa sahiptir. Dil SDK'sına bağlı olarak, bu istemci yapılandırma seçenekleri oluşturucuya farklı şekillerde geçirilir. Ayrıntılar için tablodan sınıf başvurusuna bakın.

İstemci nesnesini yetkilendirme

Bir uygulamanın blob kaynaklarına erişmesi ve bunlarla etkileşim kurması için bir istemci nesnesi yetkilendirilmelidir. Bu makaledeki kod örnekleri, Microsoft Entra güvenlik sorumlusu aracılığıyla Azure'da kimlik doğrulaması yapmak için DefaultAzureCredential kullanır. Kimlik doğrulama işlemi, yetkilendirme için bir erişim belirteci almayı içerir. bu erişim belirteci, istemci örneği oluşturulurken kimlik bilgisi olarak geçirilir ve kimlik bilgisi istemci ömrü boyunca devam eder. Belirteci isteyen Microsoft Entra güvenlik sorumlusuna blob verilerine erişim izni veren uygun bir Azure RBAC rolü atanmalıdır. Daha fazla bilgi edinmek için bkz . Blob verilerine erişim için Azure rolü atama.

İstemci nesnesine uygun erişim düzeyini vermek için aşağıdaki yetkilendirme mekanizmaları kullanılabilir:

Microsoft Entra Id: en iyi güvenlik için önerilir
Paylaşılan erişim imzası (SAS): kullanıcı temsilcisi SAS belirteci kullanılırken desteklenir ve en güvenlisi
Hesap erişim anahtarı (Paylaşılan Anahtar): desteklenir, ancak daha az güvenli olabileceği için önerilmez

Yetkilendirme hakkında daha fazla bilgi edinmek için bkz. Azure Depolama'de verilere erişimi yetkilendirme.

İstemci nesnesi oluşturma

SDK kullanarak herhangi bir Azure kaynağıyla çalışma, bir istemci nesnesi oluşturmakla başlar. Bu bölümde, depolama hizmetindeki üç kaynak türüyle etkileşim kurmak için istemci nesneleri oluşturmayı öğreneceksiniz: depolama hesapları, kapsayıcılar ve bloblar.

Uygulamanız bir istemci nesnesi oluşturduğunda, uç noktaya başvuran bir URI'yi istemci oluşturucusuna geçirirsiniz. Bu makaledeki örneklerde gösterildiği gibi uç nokta dizesini el ile oluşturabilir veya Azure Depolama yönetim kitaplığını kullanarak çalışma zamanında uç noktayı sorgulayabilirsiniz. Uç noktayı sorgulamayı öğrenmek için bkz. Blob Depolama uç noktasını sorgulama.

BlobServiceClient nesnesi oluşturma

Yetkili BlobServiceClient bir nesne, uygulamanızın depolama hesabı düzeyindeki kaynaklarla etkileşim kurmasına olanak tanır. BlobServiceClient hesap özelliklerini alıp yapılandırmanın yanı sıra depolama hesabı içindeki kapsayıcıları listelemek, oluşturmak ve silmek için yöntemler sağlar. Bu istemci nesnesi, depolama hesabındaki kaynaklarla etkileşim kurmak için başlangıç noktasıdır.

Yaygın bir senaryo, tek bir hizmet istemcisi örneği oluşturmak, ardından gerektiğinde hizmet istemcisinden kapsayıcı istemcileri ve blob istemcileri oluşturmaktır. Belirli bir kapsayıcı veya blobla çalışmak için nesnesini kullanarak BlobServiceClient bir kapsayıcı istemcisi veya blob istemcisi oluşturabilirsiniz. ' BlobServiceClient den oluşturulan istemciler, istemci seçenekleri ve kimlik bilgileri de dahil olmak üzere istemci yapılandırmasını devralır.

Aşağıdaki örneklerde bir nesnenin nasıl oluşturulacağı gösterilmektedir BlobServiceClient :

Aşağıdaki using yönergeleri ekleyin:

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

İstemci nesnesini oluşturmak için aşağıdaki kodu ekleyin:

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

    return client;
}

Aşağıdaki import yönergeleri ekleyin:

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

İstemci nesnesini oluşturmak için aşağıdaki kodu ekleyin:

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

Aşağıdaki require deyimlerini ekleyin:

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

İstemci nesnesini oluşturmak için aşağıdaki kodu ekleyin:

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

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

Aşağıdaki import deyimlerini ekleyin:

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

İstemci nesnesini oluşturmak için aşağıdaki kodu ekleyin:

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 nesnesi oluşturma

Bir nesneyi kullanarak BlobServiceClient yeni BlobContainerClient bir nesne oluşturabilirsiniz (ContainerClient JavaScript ve Python için). BlobContainerClient Nesne, belirli bir kapsayıcı kaynağıyla etkileşim kurmanızı sağlar. İstemci nesnesini oluşturabilmeniz için bu kaynağın depolama hesabında bulunması gerekmez. BlobContainerClient kapsayıcı oluşturmak, silmek veya yapılandırmak için yöntemler sağlar ve içindeki blobları listelemek, karşıya yüklemek ve silmek için yöntemler içerir. Kapsayıcı içindeki belirli bir blob üzerinde işlem gerçekleştirmek için bir blob istemcisi oluşturabilirsiniz.

Aşağıdaki örneklerde, belirli bir kapsayıcı kaynağıyla etkileşim kurmak için bir BlobServiceClient nesneden kapsayıcı istemcisi oluşturma işlemi gösterilmektedir:

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

Çalışmanızın kapsamı dar kapsamlı tek bir kapsayıcıysa, kullanmadan BlobServiceClientdoğrudan bir BlobContainerClient nesne oluşturmayı seçebilirsiniz. Hizmet istemcisinde olduğu gibi kapsayıcı istemcisinde de istemci seçeneklerini ayarlayabilirsiniz.

Aşağıdaki örneklerde, kullanmadan BlobServiceClientdoğrudan bir kapsayıcı istemcisinin nasıl oluşturulacağı gösterilmektedir:

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

BlobClient nesnesi oluşturma

Belirli bir blob kaynağıyla etkileşim kurmak için bir hizmet istemcisinden veya kapsayıcı istemcisinden bir nesne oluşturun BlobClient . Nesne BlobClient , belirli bir blob kaynağıyla etkileşim kurmanızı sağlar. İstemci nesnesini oluşturabilmeniz için bu kaynağın depolama hesabında bulunması gerekmez. BlobClient bir blobun anlık görüntülerini karşıya yüklemek, indirmek, silmek ve oluşturmak için yöntemler sağlar.

Aşağıdaki örneklerde, belirli bir blob kaynağıyla etkileşim kurmak için bir blob istemcisinin nasıl oluşturulacağı gösterilmektedir:

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

İstemci nesnelerini yönetme

Azure SDK istemci yönetimi için en iyi yöntem, bir istemciyi tekil olarak ele almaktır; bu da bir sınıfın aynı anda yalnızca bir nesnesi olacağı anlamına gelir. Belirli bir oluşturucu parametreleri veya istemci seçenekleri kümesi için bir istemcinin birden fazla örneğini tutmanız gerekmez. Bu kavram, aşağıdakiler de dahil olmak üzere birçok şekilde uygulanabilir:

Tek bir istemci nesnesi oluşturma ve bunu uygulama genelinde parametre olarak geçirme. Bu yaklaşım, bu makaledeki kod örneklerinde gösterilmiştir.
İstemci örneğini bir alanda depolama. C# alanları hakkında daha fazla bilgi edinmek için bkz . Alanlar (C# Programlama Kılavuzu).
İstemci nesnesini seçtiğiniz bir bağımlılık ekleme kapsayıcısında tekil olarak kaydetme. ASP.NET Core uygulamalarında bağımlılık ekleme hakkında daha fazla bilgi için bkz . .NET için Azure SDK ile bağımlılık ekleme.

Bu yaklaşım, ihtiyacınız olan her istemci için bir oluşturucu çağırmaktan çok daha verimlidir.

İstemci değişmezliği ve iş parçacığı güvenliği

Azure SDK istemcileri oluşturulduktan sonra sabittir; başka bir deyişle bağlandığı uç noktayı, yetkilendirme için kullanılan kimlik bilgilerini veya istemci seçenekleri olarak geçirilen diğer değerleri değiştiremezsiniz. İstemci değişmezliği, istemcilerin uygulama genelinde paylaşılıp yeniden kullanılmasının güvenli olduğu anlamına da gelir.

Uygulamanızın aynı türdeki istemciler için farklı yapılandırmalar veya kimlik bilgileri kullanması gerekiyorsa, her yapılandırma seçeneği kümesi için bir istemci örneği oluşturabilirsiniz.

Azure SDK, tüm istemci örneği yöntemlerinin iş parçacığı açısından güvenli ve birbirinden bağımsız olduğunu garanti eder. Bu tasarım, istemci örneklerini paylaşmanın ve yeniden kullanmanın iş parçacıkları arasında bile her zaman güvenli olmasını sağlar.

Sonraki adımlar

Veri kaynaklarıyla çalışmak üzere Azure Depolama istemci kitaplıklarını kullanma hakkında daha fazla bilgi edinmek için aşağıdaki makalelere bakın:

Aracılığıyla paylaş

Veri kaynaklarıyla etkileşim kuran istemci nesneleri oluşturma ve yönetme

İstemci nesneleri hakkında

İstemci nesnesini yetkilendirme

İstemci nesnesi oluşturma

BlobServiceClient nesnesi oluşturma

BlobContainerClient nesnesi oluşturma

BlobClient nesnesi oluşturma

İstemci nesnelerini yönetme

İstemci değişmezliği ve iş parçacığı güvenliği

Sonraki adımlar

Geri Bildirim

Geri Bildirim

Ek kaynaklar