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

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

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

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

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

اعداد

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

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

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

vcpkg.exe install azure-storage-blobs-cpp

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

vcpkg.exe install azure-identity-cpp

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

إنشاء مشروع

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

نموذج الكائن

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

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

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

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

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

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

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

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

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

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

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

#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 الخاص بك

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

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

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

هام

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

مدخل Microsoft Azure

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

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

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

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

   

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

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

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

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

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

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

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

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

بوويرشيل

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

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

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

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

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

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

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

   az login
   

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

   #include <azure/identity/default_azure_credential.hpp>
   

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

   // 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. الدور المضمن الأقل امتيازا مع أذونات لهذا الإجراء هو Reader and Data Access، ولكن أي دور يتضمن هذا الإجراء سيعمل.

مدخل Microsoft Azure

1. قم بتسجيل الدخول إلى بوابة Azure.

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

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

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

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

   

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

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

بوويرشيل

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

$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> بسلسلة الاتصال الفعلية الخاصة بك.

ويندوز:

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

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

لينكس:

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

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

أضف هذا الرمز إلى نهاية main():

    // 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():

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

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

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

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 .

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

حذف حاوية

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

أضف هذا الرمز إلى نهاية main():

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

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

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

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

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 Blob Storage وحذفها.

للاطلاع على عينة تخزين كائن ثنائي كبير الحجم في C++، تابع إلى:

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