إنشاء كائنات العميل التي تتفاعل مع موارد البيانات وإدارتها

Azure SDKs هي مجموعات من المكتبات التي تم إنشاؤها لتسهيل استخدام خدمات Azure من لغات مختلفة. تم تصميم SDKs لتبسيط التفاعلات بين تطبيقك وموارد Azure. يبدأ العمل مع موارد Azure باستخدام SDK بإنشاء مثيل عميل. توضح هذه المقالة كيفية إنشاء كائنات العميل للتفاعل مع موارد البيانات في Azure Blob Storage، وتقدم أفضل الممارسات حول كيفية إدارة العملاء في التطبيق الخاص بك.

حول كائنات العميل

تسمح لك مكتبات عميل Azure Blob Storage بالتفاعل مع ثلاثة أنواع من الموارد في خدمة التخزين:

• حسابات التخزين⁧
• حاويات كائن ثنائي كبير الحجم
• الكائنات الثنائية كبيرة الحجم

اعتمادا على احتياجات التطبيق الخاص بك، يمكنك إنشاء كائنات العميل على أي من هذه المستويات الثلاثة.

بالنسبة إلى الكائنات الثنائية كبيرة الحجم، هناك عميل كائن ثنائي كبير الحجم عام يغطي عمليات الكائن الثنائي كبير الحجم الشائعة عبر جميع الأنواع، وهناك عملاء blob متخصصون لكل نوع (كائن ثنائي كبير الحجم للكتلة، وإلحاق blob، ونقطة الصفحة).

يسرد الجدول التالي فئات العميل المختلفة لكل لغة:

اللغة	الحِزم	فئة عميل الخدمة	فئة عميل الحاوية	فئات عميل Blob
.NET	Azure.Storage.Blobs Azure.Storage.Blobs.Models Azure.Storage.Blobs.Specialized	BlobServiceClient	BlobContainerClient	عميل الكائن الثنائي كبير الحجم BlockBlobClient AppendBlobClient PageBlobClient
Java	com.azure.storage.blob com.azure.storage.blob.models com.azure.storage.blob.specialized	BlobServiceClient BlobServiceAsyncClient BlobServiceClientBuilder	BlobContainerClient BlobContainerAsyncClient BlobContainerClientBuilder	عميل الكائن الثنائي كبير الحجم BlobAsyncClient BlobClientBuilder BlockBlobClient AppendBlobClient PageBlobClient
JavaScript	@azure/storage-blob	BlobServiceClient	ContainerClient	عميل الكائن الثنائي كبير الحجم BlockBlobClient AppendBlobClient PageBlobClient
Python	azure.storage.blob	BlobServiceClient	ContainerClient	BlobClient1

¹ بالنسبة إلى Python، BlobClient يتضمن أساليب أنواع الكائنات الثنائية كبيرة الحجم المتخصصة.

يمكن إنشاء مثيل لكل نوع عميل عن طريق استدعاء منشئ بسيط، أو تحميل زائد يأخذ خيارات تكوين مختلفة. بالنسبة إلى Java، يحتوي كل نوع عميل على فئة منفصلة توفر واجهة برمجة تطبيقات منشئ للمساعدة في التكوين وإنشاء مثيل. اعتمادا على لغة SDK، يتم تمرير خيارات تكوين العميل هذه إلى الدالة الإنشائية بطرق مختلفة. راجع مرجع الفئة من الجدول للحصول على التفاصيل.

تخويل كائن عميل

لكي يتمكن التطبيق من الوصول إلى موارد الكائن الثنائي كبير الحجم والتفاعل معها، يجب تخويل كائن العميل. تستخدم نماذج التعليمات البرمجية في هذه المقالة DefaultAzureCredential للمصادقة على Azure عبر أساس أمان Microsoft Entra. تتضمن عملية المصادقة الحصول على رمز مميز للوصول للتخويل. يتم تمرير رمز الوصول هذا كبيانات اعتماد عند إنشاء مثيل للعميل، وتستمر بيانات الاعتماد طوال مدة بقاء العميل. يجب تعيين دور Azure RBAC مناسب لمدير أمان Microsoft Entra الذي يطلب الرمز المميز الذي يمنح الوصول إلى بيانات الكائن الثنائي كبير الحجم. لمعرفة المزيد، راجع تعيين دور Azure للوصول إلى بيانات الكائن الثنائي كبير الحجم.

يمكن استخدام آليات التخويل التالية لمنح المستوى المناسب من الوصول إلى كائن عميل:

• معرف Microsoft Entra: يوصى به للأمان الأمثل
• توقيع الوصول المشترك (SAS): مدعوم وأكثر أمانا عند استخدام رمز SAS المميز لتفويض المستخدم
• مفتاح الوصول إلى الحساب (المفتاح المشترك): مدعوم، ولكن غير مستحسن لأنه يمكن أن يكون أقل أمانا

لمعرفة المزيد حول التخويل، راجع تخويل الوصول إلى البيانات في Azure Storage.

إنشاء كائن عميل

يبدأ العمل مع أي مورد Azure باستخدام SDK بإنشاء كائن عميل. في هذا القسم، ستتعلم كيفية إنشاء كائنات العميل للتفاعل مع ثلاثة أنواع من الموارد في خدمة التخزين: حسابات التخزين والحاويات والكائنات الثنائية كبيرة الحجم.

عندما ينشئ التطبيق الخاص بك كائن عميل، يمكنك تمرير URI يشير إلى نقطة النهاية إلى منشئ العميل. يمكنك إنشاء سلسلة نقطة النهاية يدويا، كما هو موضح في الأمثلة في هذه المقالة، أو يمكنك الاستعلام عن نقطة النهاية في وقت التشغيل باستخدام مكتبة إدارة تخزين Azure. لمعرفة كيفية الاستعلام عن نقطة نهاية، راجع الاستعلام عن نقطة نهاية Blob Storage.

إنشاء كائن BlobServiceClient

يسمح كائن معتمد BlobServiceClient لتطبيقك بالتفاعل مع الموارد على مستوى حساب التخزين. BlobServiceClient يوفر أساليب لاسترداد خصائص الحساب وتكوينها، بالإضافة إلى سرد الحاويات وإنشاءها وحذفها داخل حساب التخزين. كائن العميل هذا هو نقطة البداية للتفاعل مع الموارد في حساب التخزين.

السيناريو الشائع هو إنشاء مثيل لعميل خدمة واحد، ثم إنشاء عملاء حاوية وعملاء كائن ثنائي كبير الحجم من عميل الخدمة، حسب الحاجة. للعمل مع حاوية أو كائن ثنائي كبير الحجم محدد، يمكنك استخدام BlobServiceClient الكائن لإنشاء عميل حاوية أو عميل كائن ثنائي كبير الحجم. سيرث العملاء الذين تم إنشاؤهم BlobServiceClient من تكوين العميل الخاص به، بما في ذلك خيارات العميل وبيانات الاعتماد.

توضح الأمثلة التالية كيفية إنشاء كائن BlobServiceClient :

NET.

أضِف توجيهات using التالية:

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

Java

أضِف توجيهات import التالية:

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

جافا سكريبت

أضف عبارات require التالية:

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()
);

Python

أضف عبارات import التالية:

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

إنشاء كائن BlobContainerClient

يمكنك استخدام كائن BlobServiceClient لإنشاء كائن جديد BlobContainerClient (ContainerClient ل JavaScript وPython). BlobContainerClient يسمح لك الكائن بالتفاعل مع مورد حاوية معين. لا يحتاج هذا المورد إلى الوجود في حساب التخزين لإنشاء كائن العميل. BlobContainerClient يوفر أساليب لإنشاء حاوية أو حذفها أو تكوينها، ويتضمن أساليب لسرد الكائنات الثنائية كبيرة الحجم وتحميلها وحذفها داخلها. لتنفيذ عمليات على كائن ثنائي كبير الحجم محدد داخل الحاوية، يمكنك إنشاء عميل كائن ثنائي كبير الحجم.

توضح الأمثلة التالية كيفية إنشاء عميل حاوية من كائن BlobServiceClient للتفاعل مع مورد حاوية معين:

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

جافا سكريبت

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

إذا تم تحديد نطاق عملك بشكل ضيق إلى حاوية واحدة، فقد تختار إنشاء كائن BlobContainerClient مباشرة دون استخدام BlobServiceClient. لا يزال بإمكانك تعيين خيارات العميل على عميل حاوية تماما كما تفعل على عميل خدمة.

توضح الأمثلة التالية كيفية إنشاء عميل حاوية مباشرة دون استخدام 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;
}

جافا سكريبت

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

للتفاعل مع مورد كائن ثنائي كبير الحجم معين، قم بإنشاء كائن BlobClient من عميل خدمة أو عميل حاوية. BlobClient يسمح لك الكائن بالتفاعل مع مورد كائن ثنائي كبير الحجم محدد. لا يحتاج هذا المورد إلى الوجود في حساب التخزين لإنشاء كائن العميل. BlobClient يوفر أساليب لتحميل نسخ مطابقة للكائن الثنائي كبير الحجم وتنزيلها وحذفها وإنشاءها.

توضح الأمثلة التالية كيفية إنشاء عميل كائن ثنائي كبير الحجم للتفاعل مع مورد كائن ثنائي كبير الحجم معين:

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

جافا سكريبت

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

إدارة كائنات العميل

أفضل ممارسة لإدارة عميل Azure SDK هي التعامل مع العميل على أنه قاعدة بيانات أحادية، ما يعني أن الفئة سيكون لها كائن واحد فقط في كل مرة. ليست هناك حاجة للاحتفاظ بأكثر من مثيل واحد للعميل لمجموعة معينة من معلمات المنشئ أو خيارات العميل. يمكن تنفيذ هذا المفهوم بطرق عديدة، بما في ذلك:

• إنشاء كائن عميل واحد وتمريره كمعلمة في جميع أنحاء التطبيق. يظهر هذا الأسلوب في أمثلة التعليمات البرمجية في هذه المقالة.
• تخزين مثيل عميل في حقل. لمعرفة المزيد حول حقول C#، راجع الحقول (دليل البرمجة C#).
• تسجيل كائن العميل كقاعدة بيانات أحادية في حاوية حقن التبعية التي تختارها. لمزيد من المعلومات حول إدخال التبعية في تطبيقات ASP.NET Core، راجع إدخال التبعية باستخدام Azure SDK ل .NET.

هذا الأسلوب أكثر كفاءة على نطاق واسع من استدعاء الدالة الإنشائية لكل عميل تحتاجه.

عدم قابلية العميل للتغيير وسلامة مؤشر الترابط

عملاء Azure SDK غير قابلين للتغيير بعد إنشائهم، ما يعني أنه لا يمكنك تغيير نقطة النهاية التي يتصل بها أو بيانات الاعتماد المستخدمة للتخويل أو القيم الأخرى التي تم تمريرها كخيارات للعميل. يعني عدم قابلية العميل للتغيير أيضا أن العملاء آمنون للمشاركة وإعادة الاستخدام في جميع أنحاء التطبيق.

إذا كان تطبيقك بحاجة إلى استخدام تكوينات أو بيانات اعتماد مختلفة للعملاء من نفس النوع، يمكنك إنشاء مثيل لعميل لكل مجموعة من خيارات التكوين.

يضمن Azure SDK أن تكون جميع أساليب مثيل العميل آمنة ومستقلة عن بعضها البعض. يضمن هذا التصميم أن مشاركة مثيلات العميل وإعادة استخدامها آمنة دائما، حتى عبر مؤشرات الترابط.

الخطوات التالية

لمعرفة المزيد حول استخدام مكتبات عميل Azure Storage للعمل مع موارد البيانات، راجع المقالات التالية:

• بدء استخدام Azure Blob Storage و.NET
• بدء استخدام Azure Blob Storage وJava
• بدء استخدام Azure Blob Storage وJavaScript
• بدء استخدام Azure Blob Storage وPython