التشغيل السريع: مكتبة عميل Azure Blob Storage ل C++‎

ابدأ مع مكتبة عميل Azure Blob Storage ل C++. تخزين Azure Blob عبارة عن حل تخزين كائن من Microsoft للسحابة. يُرجى اتباع هذه الخطوات لتثبيت الحزمة وتجربة التعليمات البرمجية للمهام الأساسية.

| نماذج | التعليمات البرمجية | المصدر لمكتبة الوثائق المرجعية لواجهة برمجة التطبيقات |

المتطلبات الأساسية

• اشتراك Azure - إنشاء اشتراك مجاني
• حساب تخزين Azure - إنشاء حساب تخزين
• محول C++ البرمجي
• CMake
• vcpkg - مدير حزم C وC++

الإعداد

يرشدك هذا القسم خلال إعداد مشروع للعمل مع مكتبة عميل Azure Blob Storage ل C++. أسهل طريقة للحصول على Azure SDK ل C++ هي استخدام مدير الحزمة vcpkg .

قم بتثبيت الحِزَم

vcpkg install استخدم الأمر لتثبيت مكتبة Azure Blob Storage ل C++ والتبعيات الضرورية:

Console

vcpkg.exe install azure-storage-blobs-cpp

مكتبة Azure Identity مطلوبة للاتصالات بدون كلمة مرور بخدمات Azure:

Console

vcpkg.exe install azure-identity-cpp

لمزيد من المعلومات حول إعداد المشروع والعمل مع Azure SDK ل C++، راجع Azure SDK ل C++ readme.

إنشاء مشروع

في Visual Studio، قم بإنشاء تطبيق وحدة تحكم C++ جديد لنظام التشغيل Windows يسمى BlobQuickstart.

نموذج الكائن

يتم تحسين Azure Blob Storage لتخزين كميات هائلة من البيانات غير المهيكلة. البيانات غير منظمة البنية هي بيانات لا تلتزم بنموذج بيانات أو تعريف معين، مثل البيانات النصية أو الثنائية. يوفر مخزن كائن ثنائي كبير الحجم ثلاثة أنواع من الموارد:

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

يعرض الرسم التخطيطي التالي العلاقة بين هذه الموارد.

استخدم الفئات C++ هذه للتفاعل مع هذه الموارد:

• BlobServiceClient: BlobServiceClient تسمح لك الفئة بمعالجة موارد Azure Storage وحاويات كائن تخزين البيانات الثنائية الكبيرة.
• ContainerClient: تسمح لك الفئة BlobContainerClient بمعالجة حاويات Azure Storage والنقط الخاصة بهم.
• BlobClient: BlobClient تسمح الفئة لك بمعالجة نقط تخزين Azure. هي الفئة الأساسية لجميع فئات كائن ثنائي كبير الحجم المتخصصة.
• BlockBlobClient: BlockBlobClient تسمح لك الفئة بمعالجة الكائنات الثنائية كبيرة الحجم لكتلة تخزين Azure.

أمثلة على التعليمات البرمجية

توضح لك أمثلة أجزاء التعليمات البرمجية هذه كيفية القيام بالمهام التالية باستخدام مكتبة عميل Azure Blob Storage لـ C++‎:

• إضافة ملفات التضمين
• المصادقة على Azure وتخويل الوصول إلى بيانات الكائن الثنائي كبير الحجم
• إنشاء حاوية
• تحميل النقط إلى حاوية
• سرد الكائنات الثنائية كبيرة الحجم في حاوية
• تنزيل كائنات تخزين البيانات الثنائية الكبيرة
• حذف حاوية

إضافة تضمين ملفات

من دليل المشروع:

1. افتح ملف حل BlobQuickstart.sln في Visual Studio
2. داخل Visual Studio، افتح الملف المصدر BlobQuickstart.cpp
3. إزالة أي تعليمة برمجية داخل main تم إنشاؤها تلقائيا
4. إضافة #include عبارات و using namespace

C++‎

#include <iostream>
#include <azure/core.hpp>
#include <azure/identity/default_azure_credential.hpp>
#include <azure/storage/blobs.hpp>

using namespace Azure::Identity;
using namespace Azure::Storage::Blobs;

المصادقة على Azure وتخويل الوصول إلى بيانات الكائن الثنائي كبير الحجم

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

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

لا تتطلب كلمة مرور (موصى به)

توفر مكتبة Azure Identity دعم مصادقة الرمز المميز ل Microsoft Entra عبر Azure SDK. يوفر مجموعة من TokenCredential التطبيقات التي يمكن استخدامها لإنشاء عملاء Azure SDK الذين يدعمون مصادقة الرمز المميز ل Microsoft Entra. DefaultAzureCredential يدعم أساليب مصادقة متعددة ويحدد الأسلوب الذي يجب استخدامه في وقت التشغيل.

تعيين أدوار لحساب مستخدم Microsoft Entra

عند التطوير محليًا، تأكد من أن حساب المستخدم الذي يصل إلى بيانات الكائن الثنائي كبير الحجم لديه الأذونات الصحيحة. ستحتاج إلى Storage Blob Data Contributor لقراءة بيانات الكائن الثنائي كبير الحجم وكتابتها. لتعيين هذا الدور لنفسك، ستحتاج إلى تعيين دور المستخدم Access مسؤول istrator، أو دور آخر يتضمن إجراء Microsoft.Authorization/roleAssignments/write. يمكنك تعيين أدوار Azure RBAC لمستخدم باستخدام مدخل Microsoft Azure أو Azure CLI أو Azure PowerShell. يمكنك معرفة المزيد حول النطاقات المتوفرة لتعيينات الأدوار في صفحة نظرة عامة على النطاق.

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

سيقوم المثال التالي بتعيين دور Storage Blob Data Contributor إلى حساب المستخدم الخاص بك، والذي يوفر حق الوصول للقراءة والكتابة إلى بيانات blob في حساب التخزين الخاص بك.

هام

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

مدخل Microsoft Azure

1. في مدخل Microsoft Azure، حدد موقع حساب التخزين الخاص بك باستخدام شريط البحث الرئيسي أو شريط التنقل الأيسر.

2. في صفحة نظرة عامة على حساب التخزين، حدد التحكم بالوصول (IAM) من القائمة اليسرى.

3. حدد صفحة التحكم بالوصول (IAM)، وحدد علامة تبويب تعيينات الدور.

4. حدد + إضافة من القائمة العلوية ثم إضافة تعيين الدور من القائمة المنسدلة الناتجة.

   

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

6. ضمن تعيين الوصول إلى، حدد المستخدم أو المجموعة أو كيان الخدمة، ثم اختر + تحديد الأعضاء.

7. في مربع الحوار، ابحث عن اسم مستخدم Microsoft Entra (عنوان بريدك الإلكتروني user@domain عادة) ثم اختر تحديد في أسفل مربع الحوار.

8. حدد مراجعة + تعيين للانتقال إلى الصفحة النهائية، ثم مراجعة + تعيين مرة أخرى لإكمال العملية.

Azure CLI

لتعيين دور على مستوى المورد باستخدام Azure CLI، يجب أولاً استرداد معرف المورد باستخدام الأمر az storage account show. يمكنك تصفية خصائص الإخراج باستخدام المعلمة --query.

Azure CLI

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

انسخ الإخراج Id من الأمر السابق. يمكنك بعد ذلك تعيين الأدوار باستخدام أمر az role لـ Azure CLI.

Azure CLI

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

PowerShell

لتعيين دور على مستوى المورد باستخدام Azure PowerShell، يجب أولا استرداد معرف المورد باستخدام Get-AzResource الأمر .

Azure PowerShell

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

انسخ القيمة Id من إخراج الأمر السابق. يمكنك بعد ذلك تعيين الأدوار باستخدام الأمر New-AzRoleAssignment في PowerShell.

Azure PowerShell

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

تسجيل الدخول وتوصيل التعليمات البرمجية للتطبيق الخاص بك ب Azure باستخدام DefaultAzureCredential

يمكنك تخويل الوصول إلى البيانات في حساب التخزين الخاص بك باستخدام الخطوات التالية:

1. تأكد من مصادقتك باستخدام نفس حساب Microsoft Entra الذي قمت بتعيين الدور له على حساب التخزين الخاص بك. يمكنك المصادقة عبر Azure CLI. سجل الدخول إلى Azure من خلال Azure CLI باستخدام الأمر التالي:

   Azure CLI

   az login
   

2. لاستخدام DefaultAzureCredential، تأكد من تثبيت حزمة azure-identity-cpp وإضافة ما يلي#include:

   C++‎

   #include <azure/identity/default_azure_credential.hpp>
   

3. أضف هذه التعليمة البرمجية إلى نهاية main(). عند تشغيل التعليمات البرمجية على محطة العمل المحلية الخاصة بك، DefaultAzureCredential يستخدم بيانات اعتماد المطور ل Azure CLI للمصادقة على Azure.

   C++‎

   // Initialize an instance of DefaultAzureCredential
    auto defaultAzureCredential = std::make_shared<DefaultAzureCredential>();
   
    auto accountURL = "https://<storage-account-name>.blob.core.windows.net";
    BlobServiceClient blobServiceClient(accountURL, defaultAzureCredential);
   

4. تأكد من تحديث اسم حساب التخزين في URI للكائن الخاص بك BlobServiceClient . يمكن العثور على اسم حساب التخزين في صفحة النظرة العامة لمدخل Microsoft Azure.

   

   ملاحظة

   عند استخدام C++ SDK في بيئة إنتاج، يوصى بتمكين بيانات الاعتماد التي تعرف أن تطبيقك سيستخدمها فقط. بدلا من استخدام DefaultAzureCredential، يجب تخويل استخدام نوع بيانات اعتماد معين، أو باستخدام ChainedTokenCredential مع بيانات الاعتماد المدعومة.

سلسلة الاتصال

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

ملاحظة

لتخويل الوصول إلى البيانات باستخدام مفتاح الوصول إلى حساب التخزين، ستحتاج إلى أذونات لإجراء Azure RBAC التالي: Microsoft.Storage/storageAccounts/listkeys/action. الدور المضمن الأقل امتيازا مع أذونات لهذا الإجراء هو القارئ والوصول إلى البيانات، ولكن أي دور يتضمن هذا الإجراء سيعمل.

مدخل Microsoft Azure

1. سجل الدخول إلى مدخل Azure.

2. حدد موقع حساب التخزين الخاص بك.

3. في جزء قائمة حساب التخزين، ضمن Security + networking، حدد Access keys. هنا، يمكنك عرض مفاتيح الوصول إلى الحساب، وسلسلة الاتصال الكامل لكل مفتاح.

4. في جزء مفاتيح الوصول، حدد إظهار المفاتيح.

5. في قسم key1، حدد موقع قيمة سلسلة الاتصال ion. حدد أيقونة نسخ إلى الحافظة لنسخ سلسلة الاتصال. ستضيف قيمة سلسلة الاتصال إلى متغير البيئة في القسم التالي.

   

Azure CLI

يمكنك عرض سلسلة الاتصال لحساب التخزين الخاص بك باستخدام الأمر az storage account show-connection-string.

Azure CLI

az storage account show-connection-string --name "<your-storage-account-name>"

PowerShell

يمكنك تجميع سلسلة اتصال مع PowerShell باستخدام الأمرين Get-AzStorageAccount وGet-AzStorageAccountKey.

PowerShell

$saName = "yourStorageAccountName"
$rgName = "yourResourceGroupName"
$sa = Get-AzStorageAccount -StorageAccountName $saName -ResourceGroupName $rgName

$saKey = (Get-AzStorageAccountKey -ResourceGroupName $rgName -Name $saName)[0].Value

'DefaultEndpointsProtocol=https;AccountName=' + $saName + ';AccountKey=' + $saKey + ';EndpointSuffix=core.windows.net'

تكوين سلسلة اتصال التخزين الخاص بك

بعد نسخ سلسلة الاتصال، سجله في متغير البيئة الجديد على الجهاز المحلي الذي يقوم بتشغيل التطبيق. لتعيين متغير البيئة، يجب فتح إطار وحدة التحكم واتباع الإرشادات الخاصة بنظام التشغيل. استبدل <yourconnectionstring> بسلسلة الاتصال الفعلية الخاصة بك.

Windows:

Windows Command Prompt

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

بعد إضافة متغير البيئة في Windows، يجب بدء تشغيل مثيل جديد من نافذة الأمر.

Linux:

Bash

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

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

أضف هذه التعليمة البرمجية إلى نهاية main():

C++‎

    // Retrieve the connection string for use with the application. The storage
    // connection string is stored in an environment variable on the machine
    // running the application called AZURE_STORAGE_CONNECTION_STRING.
    // Note that _MSC_VER is set when using MSVC compiler.
    static const char* AZURE_STORAGE_CONNECTION_STRING = "AZURE_STORAGE_CONNECTION_STRING";

#if !defined(_MSC_VER)
    const char* connectionString = std::getenv(AZURE_STORAGE_CONNECTION_STRING);
#else
	// Use getenv_s for MSVC
	size_t requiredSize;
	getenv_s(&requiredSize, NULL, NULL, AZURE_STORAGE_CONNECTION_STRING);
	if (requiredSize == 0) {
		throw std::runtime_error("missing connection string from env.");
	}
	std::vector<char> value(requiredSize);
	getenv_s(&requiredSize, value.data(), value.size(), AZURE_STORAGE_CONNECTION_STRING);
	std::string connectionStringStr = std::string(value.begin(), value.end());
	const char* connectionString = connectionStringStr.c_str();
#endif

	auto blobServiceClient = BlobServiceClient::CreateFromConnectionString(connectionString);

هام

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

إنشاء حاوية

اختر اسمًا للحاوية الجديدة. ثم قم بإنشاء مثيل للحاوية BlobContainerClient وإنشاءها.

هام

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

أضف هذه التعليمة البرمجية إلى نهاية main():

C++‎

std::string containerName = "myblobcontainer";
auto containerClient = blobServiceClient.GetBlobContainerClient("myblobcontainer");

// Create the container if it does not exist
std::cout << "Creating container: " << containerName << std::endl;
containerClient.CreateIfNotExists();

تحميل الكائنات الثنائية كبيرة الحجم إلى حاوية

جزء التعليمة البرمجية المكررة التالي:

1. يعلن عن سلسلة تحتوي على "Hello Azure!"
2. الحصول على مرجع إلى كائن BlockBlobClient عن طريق استدعاء GetBlockBlobClient على الحاوية من قسم إنشاء حاوية .
3. تحميل السلسلة إلى الكائن الثنائي كبير الحجم عن طريق استدعاء الدالة UploadFrom . تقوم هذه الدالة بإنشاء كائن ثنائي كبير الحجم إذا لم يكن موجودًا بالفعل أو تحديثه إذا كان موجودًا.

أضف هذه التعليمة البرمجية إلى نهاية main():

C++‎

std::string blobName = "blob.txt";
uint8_t blobContent[] = "Hello Azure!";
// Create the block blob client
BlockBlobClient blobClient = containerClient.GetBlockBlobClient(blobName);

// Upload the blob
std::cout << "Uploading blob: " << blobName << std::endl;
blobClient.UploadFrom(blobContent, sizeof(blobContent));

سرد الكائنات الثنائية كبيرة الحجم في حاوية

سرد الكائنات الثنائية كبيرة الحجم في الحاوية عن طريق استدعاء الدالة ListBlobs . تمت إضافة كائن ثنائي واحد كبير فقط إلى الحاوية، ومن ثمَّ فإن العملية تُرجع ذلك الكائن الثنائي إلى تلك النقطة فقط.

أضف هذه التعليمة البرمجية إلى نهاية main():

C++‎

std::cout << "Listing blobs..." << std::endl;
auto listBlobsResponse = containerClient.ListBlobs();
for (auto blobItem : listBlobsResponse.Blobs)
{
    std::cout << "Blob name: " << blobItem.Name << std::endl;
}

تنزيل كائنات تخزين البيانات الثنائية الكبيرة

الحصول على خصائص كائن ثنائي كبير الحجم الذي تم تحميله. ثم قم بتعريف كائن جديد std::vector<uint8_t> وتغيير حجمه باستخدام خصائص الكائن الثنائي كبير الحجم الذي تم تحميله. قم بتنزيل الكائن الثنائي كبير الحجم الذي تم إنشاؤه مسبقا في الكائن الجديد std::vector<uint8_t> عن طريق استدعاء الدالة DownloadTo في الفئة الأساسية BlobClient . وأخيرًا، عرض بيانات كائن ثنائي كبير الحجم التي تم تحميلها.

أضف هذه التعليمة البرمجية إلى نهاية main():

C++‎

auto properties = blobClient.GetProperties().Value;
std::vector<uint8_t> downloadedBlob(properties.BlobSize);

blobClient.DownloadTo(downloadedBlob.data(), downloadedBlob.size());
std::cout << "Downloaded blob contents: " << std::string(downloadedBlob.begin(), downloadedBlob.end()) << std::endl;

حذف كائن ثنائي كبير الحجم

تحذف التعليمات البرمجية التالية الكائن الثنائي كبير الحجم من حاوية Azure Blob Storage عن طريق استدعاء الدالة BlobClient.Delete .

C++‎

std::cout << "Deleting blob: " << blobName << std::endl;
blobClient.Delete();

احذف حاوية

تنظف التعليمات البرمجية التالية الموارد التي أنشأها التطبيق عن طريق حذف الحاوية بأكملها باستخدام BlobContainerClient.حذف.

أضف هذه التعليمة البرمجية إلى نهاية main():

C++‎

std::cout << "Deleting container: " << containerName << std::endl;
containerClient.Delete();

تشغيل التعليمات البرمجية

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

يتشابه إخراج التطبيق مع المثال التالي:

Output

Azure Blob Storage - C++ quickstart sample
Creating container: myblobcontainer
Uploading blob: blob.txt
Listing blobs...
Blob name: blob.txt
Downloaded blob contents: Hello Azure!
Deleting blob: blob.txt
Deleting container: myblobcontainer

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

في هذا التشغيل السريع، تعلمت كيفية تحميل وتنزيل وسرد الكائنات الثنائية كبيرة الحجم باستخدام C++. تعلمت أيضًا كيفية إنشاء حاوية مخزن Azure للكائنات الثنائية كبيرة الحجم وحذفها.

للاطلاع على عينة ‎C++ Blob Storage، تابع ما يلي:

مكتبة عميل Azure Blob Storage لعينات C++‎