التشغيل السريع: إنشاء واجهة برمجة تطبيقات لتطبيق Table باستخدام Node.js وAzure Cosmos DB
ينطبق على: 
جدول
في هذا التشغيل السريع، يمكنك إنشاء حساب Azure Cosmos DB للجداول، واستخدام مستكشف البيانات والتطبيق Node.js المستنسخ من GitHub لإنشاء جداول وكيانات. Azure Cosmos DB عبارة عن خدمة قاعدة بيانات متعددة النماذج تتيح لك إنشاء قواعد بيانات المستندات والجدول والقيمة الرئيسية والرسم البياني والاستعلام عنها بسرعة مع إمكانات التوزيع العام والقياس الأفقي.
المتطلبات الأساسية
- حساب Azure مع اشتراك نشط. أنشئ حسابًا مجانًا.
- Node.js 0.10.29+ .
- Git.
عينات التطبيقات
قد يتم استنساخ نموذج التطبيق لهذا البرنامج التعليمي أو تنزيله من المستودع https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js. يتم تضمين كل من تطبيق البداية والتطبيق المكتمل في مستودع النموذج.
git clone https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js
يستخدم نموذج التطبيق بيانات الطقس كمثال لتوضيح قدرات واجهة برمجة التطبيقات للجدول. يتم تخزين الكائنات التي تمثل ملاحظات الطقس واستردادها باستخدام واجهة برمجة التطبيقات للجدول، بما في ذلك تخزين الكائنات بخصائص إضافية لتوضيح القدرات غير المخططة لواجهة برمجة التطبيقات للجدول.
1 - إنشاء حساب على Azure Cosmos DB
تحتاج أولا إلى إنشاء حساب Azure Cosmos DB Tables API الذي سيحتوي على الجدول (الجداول) المستخدمة في التطبيق الخاص بك. يمكن إجراء ذلك باستخدام مدخل Microsoft Azure أو Azure CLI أو Azure PowerShell.
سجل الدخول إلى مدخل Microsoft Azure واتبع هذه الخطوات لإنشاء حساب Azure Cosmos DB.
| الإرشادات | لقطة شاشة |
|---|---|
في مدخل Microsoft Azure:
|
|
| في الصفحة Azure Cosmos DB، حدد إنشاء. | 
|
| في الصفحة خيار تحديد واجهة برمجة التطبيقات، اختر الخيار جدول Azure. | 
|
على صفحة إنشاء حساب Azure Cosmos DB - جدول Azure، قم بتعبئة النموذج كما يلي.
|
|
2 - إنشاء جدول
بعد ذلك، تحتاج إلى إنشاء جدول داخل حساب Azure Cosmos DB الخاص بك لاستخدام التطبيق الخاص بك. بعكس قاعدة بيانات تقليدية، تحتاج فقط إلى تحديد اسم الجدول، وليس الخصائص (الأعمدة) في الجدول. مع تحميل البيانات في الجدول، سيتم إنشاء الخصائص (الأعمدة) تلقائياً حسب الحاجة.
في مدخل Microsoft Azure، أكمل الخطوات التالية لإنشاء جدول داخل حساب Azure Cosmos DB الخاص بك.
| الإرشادات | لقطة شاشة |
|---|---|
| في مدخل Microsoft Azure، انتقل إلى صفحة النظرة العامة لحساب Azure Cosmos DB. يمكنك الانتقال إلى صفحة النظرة العامة لحساب Azure Cosmos DB الخاص بك عن طريق كتابة اسم (cosmos-msdocs-tables-sdk-demo-XYZ) لحساب Azure Cosmos DB في شريط البحث العلوي والبحث تحت عنوان الموارد. حدد اسم حساب Azure Cosmos DB للانتقال إلى صفحة النظرة العامة. | 
|
| في صفحة النظرة العامة، حدد +إضافة جدول. سيتم تمرير مربع الحوار «جدول جديد» من الجانب الأيسر من الصفحة. | 
|
في مربع الحوار New Table، بادر بتعبئة النموذج على النحو التالي.
|
|
3 - الحصول على Azure Cosmos DB سلسلة الاتصال
للوصول إلى الجدول (الجداول) في Azure Cosmos DB، سيحتاج تطبيقك إلى سلسلة الاتصال الجدول لحساب CosmosDB Storage. يمكن استرداد سلسلة الاتصال باستخدام مدخل Microsoft Azure أو Azure CLI أو Azure PowerShell.
| الإرشادات | لقطة شاشة |
|---|---|
| على الجانب الأيمن من صفحة حساب Azure Cosmos DB، حدد موقع عنصر القائمة المسمى سلسلة الاتصال ضمن عنوان الإعدادات وحدده. سيتم نقلك إلى صفحة حيث يمكنك استرداد سلسلة الاتصال لحساب Azure Cosmos DB. | 
|
| انسخ قيمة سلسلة الاتصال الأساسية لاستخدامها في التطبيق الخاص بك. | 
|
4 - تثبيت SDK لجداول بيانات Azure لـ JS
للوصول إلى Azure Cosmos DB for Table من تطبيق nodejs، قم بتثبيت حزمة Azure Data Tables SDK .
npm install @azure/data-tables
5 - تكوين عميل الجدول في ملف env.js
انسخ حساب Azure Cosmos DB أو حساب التخزين سلسلة الاتصال من مدخل Microsoft Azure، وأنشئ كائن TableServiceClient باستخدام سلسلة الاتصال المنسوخة. بدّل إلى المجلد 1-strater-app أو 2-completed-app. ثم قم بإضافة قيمة متغيرات البيئة المقابلة في ملف configure/env.js.
const env = {
connectionString:"A connection string to an Azure Storage or Azure Cosmos DB account.",
tableName: "WeatherData",
};
تتصل Azure SDK بـ Azure باستخدام كائنات العميل لتنفيذ عمليات مختلفة على أساس Azure. TableClient الفئة هي الفئة المستخدمة للتواصل مع Azure Cosmos DB للجدول. سيقوم التطبيق عادة بإنشاء كائن واحد serviceClient لكل جدول لاستخدامه في جميع أنحاء التطبيق.
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
6 - تنفيذ عمليات جدول Azure Cosmos DB
يتم تنفيذ جميع عمليات جدول Azure Cosmos DB لنموذج التطبيق في serviceClient الكائن الموجود في tableClient.js الملف ضمن دليل الخدمة .
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
الحصول على صفوف من جدول
يحتوي العنصر serviceClient على طريقة باسم listEntities تسمح لك بتحديد صفوف من الجدول. في هذا المثال، نظراً لعدم تمرير أية معلمات إلى الأسلوب، سيتم تحديد جميع الصفوف من الجدول.
const allRowsEntities = serviceClient.listEntities();
تصفية الصفوف التي يتم إرجاعها من جدول
لتصفية الصفوف التي تم إرجاعها من جدول، يمكنك تمرير سلسلة تصفية نمط OData إلى listEntities الأسلوب . على سبيل المثال، إذا أردت الحصول على جميع قراءات الطقس لمدينة شيكاغو بين منتصف ليل 1 يوليو 2021 ومنتصف ليل 2 يوليو 2021 (شاملة)، فستمر في سلسلة التصفية التالية.
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00' and RowKey le '2021-07-02 12:00'
يمكنك عرض جميع عوامل تصفية OData على موقع OData على الويب في قسم Filter System Query Option.
عندما يتم تمرير المعلمة request.args إلى الأسلوب listEntities في فئة serviceClient، فإنها تنشئ سلسلة تصفية لكل قيمة خاصية غير خالية. ثم ينشئ سلسلة تصفية مجمعة عن طريق ربط جميع القيم مع عبارة "and". يتم تمرير سلسلة التصفية المدمجة listEntities هذه إلى الأسلوب الموجود serviceClient على الكائن وسيتم إرجاع الصفوف المطابقة لسلسلة التصفية فقط. يمكنك استخدام أسلوب مشابه في التعليمات البرمجية لإنشاء سلاسل تصفية مناسبة كما هو مطلوب من تطبيقك.
const filterEntities = async function (option) {
/*
You can query data according to existing fields
option provides some conditions to query,eg partitionKey, rowKeyDateTimeStart, rowKeyDateTimeEnd
minTemperature, maxTemperature, minPrecipitation, maxPrecipitation
*/
const filterEntitiesArray = [];
const filters = [];
if (option.partitionKey) {
filters.push(`PartitionKey eq '${option.partitionKey}'`);
}
if (option.rowKeyDateTimeStart) {
filters.push(`RowKey ge '${option.rowKeyDateTimeStart}'`);
}
if (option.rowKeyDateTimeEnd) {
filters.push(`RowKey le '${option.rowKeyDateTimeEnd}'`);
}
if (option.minTemperature !== null) {
filters.push(`Temperature ge ${option.minTemperature}`);
}
if (option.maxTemperature !== null) {
filters.push(`Temperature le ${option.maxTemperature}`);
}
if (option.minPrecipitation !== null) {
filters.push(`Precipitation ge ${option.minPrecipitation}`);
}
if (option.maxPrecipitation !== null) {
filters.push(`Precipitation le ${option.maxPrecipitation}`);
}
const res = serviceClient.listEntities({
queryOptions: {
filter: filters.join(" and "),
},
});
for await (const entity of res) {
filterEntitiesArray.push(entity);
}
return filterEntitiesArray;
};
إدراج بيانات باستخدام كائن TableEntity
أبسط طريقة لإضافة بيانات إلى جدول هي باستخدام كائن TableEntity . في هذا المثال، يتم تعيين البيانات من كائن نموذج إدخال إلى كائن TableEntity . يتم تعيين الخصائص الموجودة على كائن الإدخال الذي يمثل اسم محطة الطقس وتاريخ/وقت الملاحظة إلى PartitionKey خصائص و RowKey على التوالي التي تشكل معا مفتاحا فريدا للصف في الجدول. ثم يتم تعيين خصائص إضافية في كائن نموذج الإدخال إلى خصائص القاموس في كائن TableEntity. وأخيرا، createEntity يتم استخدام الأسلوب على serviceClient الكائن لإدراج البيانات في الجدول.
قم بتعديل الدالة insertEntity في التطبيق النموذجي لتحتوي على التعليمة البرمجية التالية.
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
تحديث/إدراج البيانات باستخدام كائن TableEntity
إذا حاولت إدراج صف في جدول باستخدام تركيبة مفتاح قسم/مفتاح صف الموجودة بالفعل في هذا الجدول، فسيظهر لك خطأ. لهذا السبب، يُفضل غالباً استخدام طريقة upsertEntity بدلاً من طريقة createEntity عند إضافة صفوف إلى جدول. إذا كانت تركيبة مفتاح/صف القسم المحدد موجودة بالفعل في الجدول، upsertEntity فسيحدث الأسلوب الصف الموجود. وإلا، فسيتم إضافة الصف إلى الجدول.
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
إدراج بيانات ذات خصائص متغيرة أو تحديثها/إدراجها
تتمثل إحدى مزايا استخدام Azure Cosmos DB للجدول في أنه إذا كان العنصر الذي يتم تحميله إلى جدول يحتوي على أي خصائص جديدة، فستضاف هذه الخصائص تلقائيا إلى الجدول والقيم المخزنة في Azure Cosmos DB. ليست هناك حاجة لتشغيل عبارات لغة تعريف البيانات (DDL)، مثل ALTER TABLE لإضافة أعمدة كما هو الحال في قاعدة البيانات التقليدية.
يمنح هذا النموذج المرونة للتطبيق عند التعامل مع مصادر البيانات التي قد تضيف أو تعدل البيانات التي تحتاج إلى تسجيلها بمرور الوقت أو عندما توفر مدخلات مختلفة بيانات مختلفة للتطبيق. في نموذج التطبيق، يمكننا محاكاة محطة الطقس التي ترسل ليس فقط بيانات الطقس الأساسية، ولكن أيضاً بعض القيم الإضافية. عند تخزين كائن بهذه الخصائص الجديدة في الجدول للمرة الأولى، ستتم إضافة الخصائص المطابقة (الأعمدة) تلقائياً إلى الجدول.
لإدراج مثل هذا الكائن أو رفعه باستخدام واجهة برمجة التطبيقات للجدول، قم بتعيين خصائص الكائن القابل للتوسيع في كائن TableEntity واستخدم createEntity الأساليب أو upsertEntity على serviceClient الكائن حسب الاقتضاء.
في نموذج التطبيق، يمكن للدالة upsertEntity أيضاً تنفيذ وظيفة إدراج أو رفع البيانات بخصائص متغيرة
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
تحديث كيان
يمكن تحديث الكيانات عن طريق استدعاء updateEntity الأسلوب على serviceClient الكائن .
في نموذج التطبيق، يتم تمرير هذا العنصر إلى الأسلوب upsertEntity في العنصر serviceClient. يقوم بتحديث كائن الكيان هذا ويستخدم طريقة upsertEntity لحفظ التحديثات في قاعدة البيانات.
const updateEntity = async function (entity) {
await serviceClient.updateEntity(entity, "Replace");
};
7 - تشغيل التعليمات البرمجية
قم بتشغيل نموذج التطبيق للتفاعل مع Azure Cosmos DB للجدول. في المرة الأولى التي تشغِّل فيها التطبيق، لن يكون هناك بيانات لأن الجدول فارغ. استخدم أياً من الأزرار الموجودة في الجزء العلوي من التطبيق لإضافة بيانات إلى الجدول.
يؤدي تحديد الزر Insert using Table Entity إلى فتح مربع حوار يسمح لك بإدراج أو تحديث/إدراج صف جديد باستخدام كائن TableEntity.
يؤدي تحديد الزر إدراج باستخدام بيانات قابلة للتوسيع إلى إحضار مربع حوار يمكنك من إدراج كائن بخصائص مخصصة، مما يوضح كيف يضيف Azure Cosmos DB for Table تلقائيا خصائص (أعمدة) إلى الجدول عند الحاجة. استخدم الزر Add Custom Field لإضافة خاصية جديدة واحدة أو أكثر وإظهار هذه الإمكانية.
استخدم الزر Insert Sample Data لتحميل بعض بيانات العينة في جدول Azure Cosmos DB.
حدد عنصر Filter Results في القائمة العلوية ليتم نقله إلى صفحة "Filter Results". في هذه الصفحة، املأ معايير التصفية لتوضيح كيفية إنشاء عبارة عامل تصفية وتم تمريرها إلى Azure Cosmos DB for Table.
تنظيف الموارد
عند الانتهاء من نموذج التطبيق، يجب إزالة جميع موارد Azure المتعلقة بهذه المقالة من حسابك على Azure. يمكنك إجراء ذلك عن طريق حذف مجموعة الموارد.
يمكن حذف مجموعة موارد باستخدام مدخل Microsoft Azure عن طريق إجراء ما يلي.
| الإرشادات | لقطة شاشة |
|---|---|
| للانتقال إلى مجموعة الموارد، في شريط البحث، اكتب اسم مجموعة الموارد. ثم في علامة التبويب Resource Groups، حدد اسم مجموعة الموارد. | 
|
| حدد Delete resource group من شريط الأدوات أعلى صفحة مجموعة الموارد. | 
|
سيظهر مربع حوار من يمين الشاشة يطلب منك تأكيد حذف مجموعة الموارد.
|
|
الخطوات التالية
في هذه البداية السريعة، تعلمت كيفية إنشاء حساب Azure Cosmos DB، وإنشاء جدول باستخدام مستكشف البيانات، وتشغيل تطبيق. يمكنك الآن الاستعلام عن بياناتك باستخدام واجهة برمجة التطبيقات للجدول.
الملاحظات
قريبًا: خلال عام 2024، سنتخلص تدريجيًا من GitHub Issues بوصفها آلية إرسال ملاحظات للمحتوى ونستبدلها بنظام ملاحظات جديد. لمزيد من المعلومات، راجع https://aka.ms/ContentUserFeedback.
إرسال الملاحظات وعرضها المتعلقة بـ