التشغيل السريع: إنشاء واجهة برمجة تطبيقات لتطبيق Table باستخدام Python SDK وAzure Cosmos DB
ينطبق على: 
جدول
يوضح هذا التشغيل السريع كيفية الوصول إلى واجهة برمجة تطبيقات Azure Cosmos DB للجدول من تطبيق Python. Azure Cosmos DB للجدول هو مخزن بيانات بلا مخطط يسمح للتطبيقات بتخزين بيانات NoSQL المنظمة في السحابة. لأنه يتم تخزين البيانات في تصميم بلا مخطط، يتم إضافة خصائص (أعمدة) جديدة تلقائياً إلى الجدول عند إضافة كائن بسمة جديدة إلى الجدول. يمكن لتطبيقات Python الوصول إلى Azure Cosmos DB للجدول باستخدام Azure Data Tables SDK لحزمة Python .
المتطلبات الأساسية
تتم كتابة نموذج التطبيق في Python 3.7 أو أحدث، على الرغم من أن المبادئ تنطبق على جميع تطبيقات Python 3.7+ . يمكنك استخدام Visual Studio Code باعتباره IDE.
في حال لم يكن لديك اشتراك في Azure، قم بإنشاءحساب مجاني قبل البدء.
عينات التطبيقات
قد يتم استنساخ نموذج التطبيق لهذا البرنامج التعليمي أو تنزيله من المستودع https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flask.
git clone https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flask.git
يتم تضمين مجلد عينة 1-starter-app و2-completed-app في مستودع العينة. يحتوي تطبيق 1-starter على بعض الوظائف المتبقية لك لإكمالها بخطوط وضعت عليها علامة "#TODO". قصاصات التعليمات البرمجية الموضحة في هذه المقالة هي الإضافات المقترحة لإكمال 1-starter-app.
يستخدم نموذج التطبيق المكتمل بيانات الطقس كمثال لتوضيح قدرات واجهة برمجة التطبيقات للجدول. يتم تخزين الكائنات التي تمثل ملاحظات الطقس واستردادها باستخدام واجهة برمجة التطبيقات للجدول، بما في ذلك تخزين الكائنات بخصائص إضافية لتوضيح القدرات بلا مخطط لواجهة برمجة التطبيقات للجدول. تظهر الصورة التالية التطبيق المحلي الذي يعمل في مستعرض، ويعرض بيانات الطقس المخزنة في Azure Cosmos DB for Table.
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.
|
|
| في صفحة نظرة عامة ، حدد +إضافة جدول. ينزلق مربع الحوار جدول جديد من الجانب الأيسر من الصفحة. | 
|
في مربع الحوار New Table، بادر بتعبئة النموذج على النحو التالي.
|
|
3 - الحصول على Azure Cosmos DB سلسلة الاتصال
للوصول إلى الجدول (الجداول) في Azure Cosmos DB، يحتاج تطبيقك إلى سلسلة الاتصال الجدول لحساب Cosmos DB Storage. يمكن استرداد سلسلة الاتصال باستخدام مدخل Microsoft Azure أو Azure CLI أو Azure PowerShell.
| الإرشادات | لقطة شاشة |
|---|---|
| على الجانب الأيسر من صفحة حساب Azure Cosmos DB، حدد موقع عنصر القائمة المسمى Connection strings ضمن عنوان Settings وحدده. سيتم نقلك إلى صفحة حيث يمكنك استرداد سلسلة الاتصال لحساب Azure Cosmos DB. | 
|
| انسخ قيمة سلسلة الاتصال الأساسية لاستخدامها في التطبيق الخاص بك. | 
|
4 - تركيب SDK لجداول بيانات Azure لـ Python
بعد إنشاء حساب Azure Cosmos DB، تكون خطوتك التالية هي تثبيت Microsoft Azure Data Tables SDK ل Python. للحصول على تفاصيل حول تثبيت SDK، راجع الملف README.rst في مستودع Azure Data Tables SDK لـ Python على GitHub.
قم بتثبيت مكتبة عميل Azure Tables للغة Python باستخدام النقطة:
pip install azure-data-tables
لا تنس أيضا تثبيت requirements.txt في مجلدات 1-starter-app أو 2-completed-app .
5 - تكوين عميل الجدول في ملف .env
انسخ سلسلة اتصال حساب Azure Cosmos DB من مدخل Microsoft Azure وأنشئ عنصر TableServiceClient باستخدام سلسلة الاتصال المنسوخة. قم بالتبديل إلى المجلد 1-starter-app أو 2-completed-app . بغض النظر عن التطبيق الذي تبدأ به، تحتاج إلى تحديد متغيرات البيئة في .env ملف.
# Configuration Parameters
conn_str = "A connection string to an Azure Cosmos DB account."
table_name = "WeatherData"
project_root_path = "Project abs path"
تتصل Azure SDK بـ Azure باستخدام كائنات العميل لتنفيذ عمليات مختلفة على أساس Azure. الكائن TableServiceClient هو الكائن المستخدم للاتصال ب Azure Cosmos DB للجدول. سيشتمل التطبيق عادةً على TableServiceClient واحد بشكل عام، وسيحتوي على TableClient لكل جدول.
على سبيل المثال، تنشئ التعليمات البرمجية التالية كائنا TableServiceClient باستخدام سلسلة الاتصال من متغير البيئة.
self.conn_str = os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)
6 - تنفيذ عمليات جدول Azure Cosmos DB
يتم تنفيذ جميع عمليات جدول Azure Cosmos DB لتطبيق العينة TableServiceHelper في الفئة الموجودة في ملف المساعد ضمن دليل تطبيق الويب. ستحتاج إلى استيراد TableServiceClient الفئة في أعلى هذا الملف للعمل مع الكائنات في مكتبة عميل azure.data.tables ل Python.
from azure.data.tables import TableServiceClient
في بداية الفئة TableServiceHelper، قم بإنشاء الدالة الإنشائية وإضافة متغير عضو للعنصر TableClient للسماح بإدخال العنصر TableClient في الفئة.
def __init__(self, table_name=None, conn_str=None):
self.table_name = table_name if table_name else os.getenv("table_name")
self.conn_str = conn_str if conn_str else os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)
self.table_client = self.table_service.get_table_client(self.table_name)
تصفية الصفوف التي يتم إرجاعها من جدول
لتصفية الصفوف التي تم إرجاعها من جدول، يمكنك تمرير سلسلة تصفية نمط OData إلى query_entities الأسلوب . على سبيل المثال، إذا أردت الحصول على جميع قراءات الطقس لمدينة شيكاغو بين منتصف ليل 1 يوليو 2021 ومنتصف ليل 2 يوليو 2021 (شاملة)، فستمر في سلسلة التصفية التالية.
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00 AM' and RowKey le '2021-07-02 12:00 AM'
يمكنك عرض عوامل تصفية OData ذات الصلة على موقع ويب جداول بيانات azure في القسم عوامل تصفية الكتابة.
عندما يتم تمرير المعلمة request.args إلى الأسلوب query_entity في فئة TableServiceHelper، فإنها تنشئ سلسلة تصفية لكل قيمة خاصية غير خالية. ثم ينشئ سلسلة تصفية مجمعة عن طريق ربط جميع القيم مع عبارة "and". يتم تمرير سلسلة التصفية المدمجة query_entities هذه إلى الأسلوب على TableClient الكائن ويتم إرجاع الصفوف المطابقة لسلسلة التصفية فقط. يمكنك استخدام أسلوب مشابه في التعليمات البرمجية لإنشاء سلاسل تصفية مناسبة كما هو مطلوب من تطبيقك.
def query_entity(self, params):
filters = []
if params.get("partitionKey"):
filters.append("PartitionKey eq '{}'".format(params.get("partitionKey")))
if params.get("rowKeyDateStart") and params.get("rowKeyTimeStart"):
filters.append("RowKey ge '{} {}'".format(params.get("rowKeyDateStart"), params.get("rowKeyTimeStart")))
if params.get("rowKeyDateEnd") and params.get("rowKeyTimeEnd"):
filters.append("RowKey le '{} {}'".format(params.get("rowKeyDateEnd"), params.get("rowKeyTimeEnd")))
if params.get("minTemperature"):
filters.append("Temperature ge {}".format(params.get("minTemperature")))
if params.get("maxTemperature"):
filters.append("Temperature le {}".format(params.get("maxTemperature")))
if params.get("minPrecipitation"):
filters.append("Precipitation ge {}".format(params.get("minPrecipitation")))
if params.get("maxPrecipitation"):
filters.append("Precipitation le {}".format(params.get("maxPrecipitation")))
return list(self.table_client.query_entities(" and ".join(filters)))
إدراج بيانات باستخدام كائن TableEntity
أبسط طريقة لإضافة بيانات إلى جدول هي باستخدام كائن TableEntity . في هذا المثال، يتم تعيين البيانات من كائن نموذج إدخال إلى كائن TableEntity . يتم تعيين الخصائص الموجودة على كائن الإدخال الذي يمثل اسم محطة الطقس وتاريخ/وقت الملاحظة إلى PartitionKey خصائص و RowKey على التوالي، والتي تشكل معا مفتاحا فريدا للصف في الجدول. ثم يتم تعيين الخصائص الإضافية على كائن نموذج الإدخال إلى خصائص القاموس على كائن TableEntity. وأخيرا، create_entity يتم استخدام الأسلوب على TableClient الكائن لإدراج البيانات في الجدول.
قم بتعديل الدالة insert_entity في التطبيق النموذجي لتحتوي على التعليمة البرمجية التالية.
def insert_entity(self):
entity = self.deserialize()
return self.table_client.create_entity(entity)
@staticmethod
def deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
return params
تحديث/إدراج البيانات باستخدام كائن TableEntity
إذا حاولت إدراج صف في جدول باستخدام تركيبة مفتاح قسم/مفتاح صف موجودة حاليا في هذا الجدول، فسيظهر لك خطأ. لهذا السبب، غالبا ما يفضل استخدام upsert_entity بدلا من create_entity الأسلوب عند إضافة صفوف إلى جدول. إذا كانت تركيبة مفتاح/صف القسم المحدد موجودة بالفعل في الجدول، يقوم upsert_entity الأسلوب بتحديث الصف الموجود. وإلا، تتم إضافة الصف إلى الجدول.
def upsert_entity(self):
entity = self.deserialize()
return self.table_client.upsert_entity(entity)
@staticmethod
def deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
return params
إدراج بيانات ذات خصائص متغيرة أو تحديثها/إدراجها
تتمثل إحدى مزايا استخدام Azure Cosmos DB للجدول في أنه إذا كان العنصر الذي يتم تحميله إلى جدول يحتوي على أي خصائص جديدة، فستضاف هذه الخصائص تلقائيا إلى الجدول والقيم المخزنة في Azure Cosmos DB. ليست هناك حاجة لتشغيل عبارات DDL مثل ALTER TABLE لإضافة أعمدة كما هو الحال في قاعدة بيانات تقليدية.
يمنح هذا النموذج المرونة للتطبيق عند التعامل مع مصادر البيانات التي قد تضيف أو تعدل البيانات التي تحتاج إلى تسجيلها بمرور الوقت أو عندما توفر مدخلات مختلفة بيانات مختلفة للتطبيق. في نموذج التطبيق، يمكننا محاكاة محطة الطقس التي ترسل ليس فقط بيانات الطقس الأساسية ولكن أيضا بعض القيم الإضافية. عند تخزين كائن بهذه الخصائص الجديدة في الجدول للمرة الأولى، تتم إضافة الخصائص المقابلة (الأعمدة) تلقائيا إلى الجدول.
لإدراج مثل هذا الكائن أو رفعه باستخدام واجهة برمجة التطبيقات للجدول، قم بتعيين خصائص الكائن القابل للتوسيع في كائن TableEntity واستخدم create_entity الأساليب أو upsert_entity على TableClient الكائن حسب الاقتضاء.
في نموذج التطبيق، يمكن للدالة upsert_entity أيضاً تنفيذ وظيفة إدراج أو رفع البيانات بخصائص متغيرة
def insert_entity(self):
entity = self.deserialize()
return self.table_client.create_entity(entity)
def upsert_entity(self):
entity = self.deserialize()
return self.table_client.upsert_entity(entity)
@staticmethod
def deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
return params
تحديث كيان
يمكن تحديث الكيانات عن طريق استدعاء update_entity الأسلوب على TableClient الكائن .
في نموذج التطبيق، يتم تمرير هذا الكائن إلى أسلوب upsert_entity في فئة TableClient. يقوم بتحديث كائن الكيان هذا ويستخدم طريقة upsert_entity لحفظ التحديثات في قاعدة البيانات.
def update_entity(self):
entity = self.update_deserialize()
return self.table_client.update_entity(entity)
@staticmethod
def update_deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = params.pop("ObservationDate")
return params
إزالة كيان
لإزالة كيان من جدول، قم باستدعاء delete_entity الأسلوب على TableClient الكائن باستخدام مفتاح القسم ومفتاح الصف للكائن.
def delete_entity(self):
partition_key = request.form.get("StationName")
row_key = request.form.get("ObservationDate")
return self.table_client.delete_entity(partition_key, row_key)
7 - تشغيل التعليمات البرمجية
قم بتشغيل نموذج التطبيق للتفاعل مع Azure Cosmos DB للجدول. على سبيل المثال، بدءا من مجلد 2-completed-app ، مع تثبيت المتطلبات، يمكنك استخدام:
python3 run.py webapp
راجع ملف README.md في نموذج جذر المستودع لمزيد من المعلومات حول تشغيل نموذج التطبيق.
في المرة الأولى التي تشغِّل فيها التطبيق، لن يكون هناك بيانات لأن الجدول فارغ. استخدم أياً من الأزرار الموجودة في الجزء العلوي من التطبيق لإضافة بيانات إلى الجدول.
يؤدي تحديد الزر Insert using Table Entity إلى فتح مربع حوار يسمح لك بإدراج أو تحديث/إدراج صف جديد باستخدام كائن TableEntity.
يؤدي تحديد الزر إدراج باستخدام بيانات قابلة للتوسيع إلى إحضار مربع حوار يمكنك من إدراج كائن بخصائص مخصصة، مما يوضح كيف يضيف Azure Cosmos DB for Table تلقائيا خصائص (أعمدة) إلى الجدول عند الحاجة. استخدم الزر Add Custom Field لإضافة خاصية جديدة واحدة أو أكثر وإظهار هذه الإمكانية.
استخدم الزر Insert Sample Data لتحميل بعض بيانات العينة في جدول Azure Cosmos DB.
بالنسبة إلى مجلد عينة 1-starter-app، ستحتاج على الأقل إلى إكمال التعليمات البرمجية للدالة
submit_transactionلإدراج بيانات العينة للعمل.يتم تحميل البيانات النموذجية من ملف sample_data.json . يخبر المتغير
project_root_path.env التطبيق بمكان العثور على هذا الملف. على سبيل المثال، إذا كنت تقوم بتشغيل التطبيق من مجلد 1-starter-app أو مجلد 2-completed-app ، فاضبطproject_root_pathعلى "" (فارغ).
حدد عنصر 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.
إرسال الملاحظات وعرضها المتعلقة بـ