التدريب - تكوين مكتبة العميل وتهيئتها

  • 10 دقائق

يكون سير العمل المعتاد للتطبيقات التي تستخدم موقع تخزين الكائنات الثنائية كبيرة الحجم كما يلي:

  1. استرداد التكوين: عند بدء التشغيل، بادر بتحميل تكوين حساب التخزين، ويكون عبارة عن سلسلة اتصال حساب التخزين.

  2. تهيئة العميل: لتهيئة مكتبة عميل Azure Storage، استخدم سلسلة الاتصال. تنشئ هذه التهيئة الكائنات التي يستخدمها التطبيق للعمل مع واجهة برمجة تطبيقات تخزين Blob.

  3. الاستخدام: للعمل على الحاويات والكائنات الثنائية كبيرة الحجم، قم بإجراء استدعاءات واجهة برمجة التطبيقات باستخدام مكتبة العميل.

تكوين سلسلة الاتصال

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

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

التحذير

لا تضع مفاتيح حساب التخزين في التعليمات البرمجية أو في ملفات التكوين غير المحمية. تتيح مفاتيح حساب التخزين الوصول الكامل إلى حساب التخزين الخاص بك. يمكن أن يؤدي تسريب مفتاح إلى تلف لا يمكن إصلاحه وفواتير كبيرة. للحصول على إرشادات التخزين والنصائح عن كيفية استرداد من مفتاح مُسَرَّب، راجع قسم المزيد من القراءة بنهاية هذه الوحدة.

تهيئة نموذج عنصر وحدة تخزين Blob

في Azure Storage SDK لـ .NET، يكون النمط القياسي لاستخدام موقع تخزين الكائنات الثنائية كبيرة الحجم، كما يلي:

  1. إنشاء مثيل لعنصر BlobServiceClient جديد وتوفير سلسلة الاتصال بحساب التخزين الخاص بك.

  2. للحصول على BlobContainerClient، قم باستدعاء GetBlobContainerClient على BlobServiceClient باسم الحاوية التي تريد التفاعل معها أو إنشائها.

في التعليمات البرمجية، تبدو هذه الخطوات مثل هذا.

BlobServiceClient blobServiceClient = new BlobServiceClient(storageConfig.ConnectionString);
BlobContainerClient containerClient = blobServiceClient.GetBlobContainerClient(storageConfig.FileContainerName);

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

في SDK لخدمة Azure Storage من أجل SDK، يتكون النمط القياسي لاستخدام مخزن البيانات الثنائية كبيرة الحجم من الخطوات التالية:

  1. قم بإنشاء BlobServiceClient عن طريق إنشاء كائن BlobServiceClientBuilder جديد باستخدام سلسلة الاتصال لحساب التخزين الخاص بك.

  2. احصل على BlobContainerClient باستدعاء أسلوب getBlobContainerClient على BlobServiceClient باسم الحاوية التي تريد التفاعل معها أو تريد إنشاءها.

في التعليمات البرمجية، تبدو هذه الخطوات مثل هذا.

BlobServiceClient blobServiceClient = BlobServiceClientBuilder()
    .connectionString(connectionString)
    .buildClient();
BlobContainerClient containerClient = blobServiceClient.getBlobContainerClient(containerName);

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

إنشاء حاويات عند بدء التشغيل

لإنشاء حاوية عند بدء تشغيل تطبيقك أو عندما يحاول التطبيق استخدام حاوية لأول مرة، اتصل بـ CreateIfNotExistsAsync على BlobContainerClient.

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

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

تمرين

استنساخ واستكشاف التطبيق غير مكتملة

  1. أولا، استنسخ تطبيق البداية من GitHub. للحصول على نسخة من التعليمات البرمجية المصدر وفتحها في المحرر، قم بتشغيل الأوامر التالية في Azure Shell CLI:

    git clone https://github.com/MicrosoftDocs/mslearn-store-data-in-azure.git
cd mslearn-store-data-in-azure/store-app-data-with-azure-blob-storage/src/start
code .

  2. في المحرر، افتح الملف Controllers/FilesController.cs. لا يوجد عمل للقيام به هنا، ولكن يمكنك إلقاء نظرة سريعة على ما يقوم به التطبيق.

    تطبيق وحدة تحكم هذا API مع ثلاثة إجراءات:

    • الفهرس: (GET /api/Files) إرجاع قائمة عناوين URL، واحدة لكل ملف تم تحميله. تستدعي واجهة التطبيق الأمامية هذا الأسلوب لإنشاء قائمة من الارتباطات التشعبية إلى الملفات التي تم تحميلها.
    • تحميل: (POST /api/Files) يتلقى ملفا تم تحميله ويحفظه.
    • تنزيل: (GET /api/Files/{filename}) تنزيل ملف فردي باسمه.

    للقيام بعملها، يستخدم كل أسلوب مثيلا IStorage يسمى storage. هناك تنفيذ غير كامل ل IStorage في Models/BlobStorage.cs للتعبئة.

إضافة حزمة NuGet

  • إضافة مرجع إلى SDK تخزين Azure. قم بتشغيل الأوامر التالية في Azure Shell CLI:

    dotnet add package Azure.Storage.Blobs
dotnet restore

    يضمن هذا الأمر أنك تستخدم أحدث إصدار من مكتبة عميل Blob Storage.

تكوين

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

عندما يتعلق الأمر باستخدام التكوين، يتضمن تطبيق البداية السباكة التي تحتاجها. IOptions<AzureStorageConfig> تحتوي معلمة الدالة الإنشائية في BlobStorage على خاصيتين: سلسلة الاتصال حساب التخزين واسم الحاوية التي يستخدمها تطبيقك لتخزين الكائنات الثنائية كبيرة الحجم. توجد تعليمة برمجية في ConfigureServices بـ Startup.cs التي تقوم بتحميل القيم من التهيئة عند بدء تشغيل التطبيق.

تهيئة

  1. في المحرر، افتح Models/BlobStorage.cs. في أعلى الملف، أضف العبارات التالية using لإعداده للتعليمات البرمجية التي ستقوم بإضافتها.

    using Azure;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;

  2. حدد موقع الأسلوب Initialize. يستدعي تطبيقك هذا الأسلوب عند استخدامه BlobStorage للمرة الأولى. إذا كنت تشعر بالفضول، يمكنك إلقاء نظرة على ConfigureServices Startup.csلمعرفة كيفية إجراء المكالمة.

    Initialize هو المكان الذي تريد إنشاء الحاوية فيه إذا لم تكن موجودة بالفعل. استبدل التنفيذ الحالي للتعليمات Initialize البرمجية التالية، واحفظ عملك باستخدام CTRL+S.

    public Task Initialize()
{
    BlobServiceClient blobServiceClient = new BlobServiceClient(storageConfig.ConnectionString);
    BlobContainerClient containerClient = blobServiceClient.GetBlobContainerClient(storageConfig.FileContainerName);
    return containerClient.CreateIfNotExistsAsync();
}

استنساخ واستكشاف التطبيق غير مكتملة

  1. أولا، استنسخ تطبيق البداية من GitHub. للحصول على نسخة من التعليمات البرمجية المصدر وفتحها في المحرر، قم بتشغيل الأوامر التالية في Azure Shell CLI:

    git clone https://github.com/MicrosoftDocs/mslearn-store-data-in-azure.git
cd mslearn-store-data-in-azure/store-java-ee-application-data-with-azure-blob-storage/start
code .

  2. في المحرر، افتح الملف src/main/java/com/microsoft/azure/samples/jsf/IndexBean.java. لا يوجد عمل للقيام به هنا، ولكن يمكنك إلقاء نظرة سريعة على ما يقوم به التطبيق.

    ينفذ هذا الطلب الذي تم تحديد نطاقه ثلاثة إجراءات يتم استخدامها بواسطة صفحة src/main/webapp/index.xhtml Java Server Faces (JSF):

    • listFileNames: إرجاع قائمة بأسماء الملفات، واحد لكل ملف تم تحميله. تستدعي صفحة index.xhtml هذه الطريقة لإنشاء قائمة بالارتباطات التشعبية إلى الملفات التي تم تحميلها.
    • تحميل: يتلقى ملفاً تم تحميله ويحفظه. يتم إدخال محتوى الملف وبيانات التعريف في خاصية uploadedFile بواسطة إطار عمل JSF.
    • تنزيل: لتنزيل ملف فردي باسمه.

    للقيام بعملها، تستخدم كل طريقة Storage مثيلاً يسمى storage. هناك تنفيذ غير كامل ل Storage في src/main/java/com/microsoft/azure/samples/service/BlobStorage.java للتعبئة.

أضف Azure Storage SDK لمرجع Java

نوصي باستخدام Azure BOM لإضافة مكتبات عميل Azure إلى المشروع. يوفر طريقة بسيطة وأنيقة للتنسيق باستخدام مكتبات عملاء Azure متعددة مع ضمان الحد الأدنى من تعارضات التبعية.

  1. في المحرر، افتح الملف pom.xml.

  2. لإضافة Azure BOM إلى المشروع، أضف القسم التالي dependencyManagement ضمن project علامة xml.

    <dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-sdk-bom</artifactId>
      <version>1.0.6</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

  3. لإضافة Azure Storage SDK ل Java، أضف ما يلي dependency إلى project/dependencies قسم xml.

    <dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-blob</artifactId>
</dependency>

تكوين

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

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

تهيئة

  1. في المحرر، افتح src/main/java/com/microsoft/azure/samples/service/BlobStorage.java. في أعلى الملف، أضف العبارات التالية import لإعداده للتعليمات البرمجية التي ستقوم بإضافتها.

    import java.util.stream.Collectors;

import com.azure.storage.blob.BlobClient;
import com.azure.storage.blob.BlobContainerClient;
import com.azure.storage.blob.BlobServiceClient;
import com.azure.storage.blob.BlobServiceClientBuilder;
import com.azure.storage.blob.models.BlobItem;

  2. أضف خاصية فئة في فئة BlobStorage للاحتفاظ بالمرجع BlobContainerClient.

    private BlobContainerClient blobContainerClient;

    تلميح

    عملاء Azure عديمي الحالة وآمنون. يوصى بتخزين مثيلاتها مؤقتًا عند الاقتضاء. على سبيل المثال، يستخدم التطبيق الذي تعمل عليه حاوية واحدة ذات اسم ثابت، لذلك من الأفضل تخزينها مؤقتاً في نطاق عمر التطبيق. تمت إضافة BlobStorage إلى @Singleton لذا يوصى بتخزين المرجع BlobContainerClient في الحقل الخاص به.

  3. حدد طريقة init مع التعليق التوضيحي @PostConstruct. يستدعي تطبيقك هذه الطريقة بعد إنشاء المثيل BlobStorage وقبل استخدامه للمرة الأولى.

    init هو مكان إنشاء الحاوية الخاصة بك إذا لم تكن موجودة بالفعل. استبدل التنفيذ الحالي للتعليمات init البرمجية التالية، واحفظ عملك.

    @PostConstruct
private void init() {
    String connectionString = System.getenv("STORAGE_CONNECTION_STRING");
    String containerName = System.getenv("STORAGE_CONTAINER_NAME");
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .connectionString(connectionString)
        .buildClient();
    blobContainerClient = blobServiceClient.getBlobContainerClient(containerName);
    if (!blobContainerClient.exists()) {
        blobContainerClient.create();
    }
}