الوحدة 6: النقل من Cloud Datastore إلى Cloud Firestore

1. نظرة عامة

تهدف سلسلة الدروس التطبيقية حول الترميز هذه (البرامج التعليمية العملية التي تناسب وتيرة المتعلّم) إلى مساعدة مطوّري Google App Engine (الإصدار العادي) في تحديث تطبيقاتهم من خلال إرشادهم خلال سلسلة من عمليات نقل البيانات. تتضمّن معظم عمليات النقل هذه التوقّف عن استخدام الخدمات الأصلية المجمَّعة في وقت التشغيل لأنّ أوقات التشغيل من الجيل التالي أكثر مرونة، ما يمنح المستخدمين مجموعة أكبر من خيارات الخدمة. تتضمّن إحدى طرق تحديث التطبيق الترقية إلى منتج أحدث، وهذا هو موضوع هذا الدرس التطبيقي حول الترميز.

يمكن لمستخدمي App Engine الذين يصلون إلى Datastore باستخدام مكتبات برامج Cloud NDB أو Cloud Datastore مواصلة استخدامها بدون الحاجة إلى إجراء أي عمليات نقل إضافية. ومع ذلك، تمثّل Cloud Firestore أحدث مخزن بيانات NoSQL قابل للتوسّع وعالي التوفّر ويتضمّن ميزات من قاعدة بيانات Firebase في الوقت الفعلي.

أنت في المكان المناسب إذا كنت مطوّرًا تشعر بالحاجة إلى استخدام Firestore للاستفادة من ميزاته أو لديك على الأقل اهتمام كافٍ باستكشاف ما تتطلبه عملية نقل البيانات. يوضّح لك هذا الفيديو التعليمي كيفية نقل تطبيق App Engine يستخدم Cloud Datastore إلى Cloud Firestore.

تحذير: هذا النوع من عمليات نقل البيانات اختياري ومكلف. يتطلّب التبديل إلى Firestore من المستخدمين استخدام مشروع مختلف (وربما جديد). يمكن لمشاريع السحابة الإلكترونية استخدام إما Datastore أو Firestore، ولكن ليس كليهما. لا يمكن تغيير هذا الإعداد بعد ضبطه. بما أنّ جميع تطبيقات App Engine القديمة تستخدم Datastore، يجب استخدام مشروع مختلف لاستخدام Firestore.

ستتعرّف على كيفية

• التعرّف على الاختلافات بين Datastore وFirestore
• نقل البيانات من Cloud Datastore إلى Cloud Firestore

المتطلبات

• مشروع Google Cloud Platform يتضمّن ما يلي:
  • حساب فوترة نشط على Google Cloud Platform
  • تفعيل App Engine
• مهارات أساسية في لغة Python
• معرفة عملية بالأوامر الشائعة على نظام التشغيل Linux
• معرفة أساسية بشأن تطوير ونشر تطبيقات App Engine
• ننصحك بإكمال الدرس التطبيقي حول الترميز 3، بما في ذلك تكييف البرنامج إلى Python 3، قبل البدء في هذا الدرس (الدرس 6).
• تطبيق يعمل في الوحدة 3 من Cloud Datastore Python 3 App Engine

استطلاع الرأي

كيف ستستخدم هذا الدرس التطبيقي حول الترميز؟

قراءة المحتوى فقط قراءة المحتوى وإكمال التمارين

2. الخلفية

أصبح Datastore في App Engine منتجًا مستقلاً في عام 2013، وهو Google Cloud Datastore، ويمكن للمطوّرين الآن الوصول إليه خارج App Engine. في العام التالي، استحوذت Google على Firebase. في ذلك الوقت، كانت تُعرف بقاعدة بياناتها في الوقت الفعلي.

على مدار السنوات القليلة التالية، عمل فريقا Firebase وCloud Datastore على دمج بعض ميزات Firebase في Datastore. نتيجةً لذلك، تم إصدار الجيل التالي من Cloud Datastore في عام 2017. تمت إعادة تسمية الخدمة إلى Cloud Firestore لتوضيح أنّها تتضمّن بعض ميزات Firebase.

أصبحت Cloud Firestore آلية التخزين التلقائية NoSQL لمشاريع Google Cloud. يمكن للتطبيقات الجديدة استخدام Cloud Firestore بشكلٍ أصلي، بينما تم تحويل قواعد بيانات Datastore الحالية إلى Firestore في الخلفية، وتعمل الآن باسم "Firestore في وضع Datastore" للحفاظ على التوافق مع عمليات Datastore. نتيجةً لذلك، لا يمكن للتطبيقات تشغيل Cloud Firestore إلا في أحد هذين الوضعين، ولا يمكن تغيير الوضع بعد ضبطه.

في الوقت الحالي، عندما ينشئ المستخدمون مشاريع جديدة ويختارون أحد حلول NoSQL، يُطلب منهم اختيار إما Firestore في وضع Datastore أو Firestore في الوضع الأصلي. بعد أن يضيف المستخدمون عناصر Datastore، لا يمكنهم التبديل إلى Firestore، وبالمثل، بعد اختيار وضع Firestore الأصلي، لن يتمكّنوا من التبديل مرة أخرى إلى Datastore (أو بالأحرى، Firestore في وضع Datastore). لمزيد من التفاصيل، يُرجى الاطّلاع على صفحة الاختيار بين وضع Cloud Firestore في Datastore أو وضع Firestore الأصلي في المستندات. لنقل تطبيق إلى Firestore، يجب إنشاء مشروع جديد وتصدير Datastore ثم استيراده إلى Firestore. الغرض من هذا البرنامج التعليمي هو إعطاء المطوّرين فكرة عن الاختلافات بين استخدام Cloud Datastore وCloud Firestore.

هذه عملية نقل بيانات لا نتوقّع أن يجريها المستخدمون، ولهذا السبب هي عملية نقل بيانات اختيارية. على الرغم من المزايا الواضحة لاستخدام Cloud Firestore بشكلٍ أصلي، مثل مصادقة العميل ودمج قواعد Firebase وقاعدة بيانات Firebase في الوقت الفعلي، فإنّ خطوات نقل البيانات "غير مريحة":

• يجب استخدام مشروع مختلف عن مشروع تطبيقك الحالي.
• لا يمكن التبديل إلى Firestore في الوضع الأصلي في مشروع أضاف فيه تطبيق عناصر Datastore.
• وبالمثل، لا يمكن لمشروع تم فيه اختيار Firestore في الوضع الأصلي العودة إلى Firestore في وضع Datastore.
• لا تتوفّر أداة نقل يمكنها بث البيانات من مشروع إلى آخر.
• لا تتوفّر بعض ميزات Datastore المهمة، بما في ذلك مساحات الأسماء ومعدّل نقل بيانات كتابة أعلى (>10,000/ثانية)، في Firestore.
• أدوات التصدير والاستيراد "بدائية" وتتضمّن سيناريوهات "الكل أو لا شيء".
  • إذا كان تطبيقك يحتوي على العديد من عناصر Datastore، قد يستغرق تصديرها ثم استيرادها إلى Firestore عدة ساعات.
  • وخلال هذه الفترة، لن يتمكّن تطبيقك أو خدمتك من كتابة البيانات أو تعديلها.
  • يتم احتساب أنشطة النقل ضمن الاستخدام العادي، لذا ننصحك بتوزيعها (على الحصص اليومية إذا أمكن) لتقليل التكاليف.
  • بما أنّ خدمتك الجديدة تعمل في مشروع مختلف، ستحتاج إلى فترة زمنية لنشر تحديثات نظام أسماء النطاقات.
• تتضمّن Datastore وFirestore نماذج بيانات متشابهة ولكنها مختلفة، لذا يتطلّب نقل البيانات تعديل طريقة عمل التطبيق أو الخدمة
  • استعلامات العناصر الأصل من Datastore هي الآن استعلامات المجموعات في Firestore (الإعداد التلقائي)
  • طلبات البحث من النوع العام من Datastore هي طلبات بحث عن مجموعات في Firestore
  • تختلف الفهارس وطريقة التعامل معها وما إلى ذلك.

مع ذلك، إذا كان لديك تطبيق بسيط إلى حدّ ما تريد نقله، أو كنت تستعد لمحاكاة عملية نقل من هذا النوع، أو كنت تريد ببساطة معرفة الفرق بين Datastore وFirestore، يُرجى مواصلة القراءة.

مستخدمو Python 2: لا يتوفّر هذا الدرس التطبيقي الاختياري حول نقل البيانات إلا في Python 3، ولكن بما أنّ Firestore يتيح أيضًا استخدام الإصدار 2.x، يمكن للمستخدمين استنتاج الاختلافات في الاستخدام. أحد الأمثلة على ذلك هو أنّ سجلات Firestore تستخدم سلاسل Unicode (بدلاً من سلاسل البايت)، لذا يلزم توفّر مؤشر u'' بادئ لأحرف السلسلة في Python 2، ما يعني أنّ دالة 2.x store_visit() ستكون على النحو التالي:

def store_visit(remote_addr, user_agent):
    doc_ref = fs_client.collection(u'Visit')
    doc_ref.add({
        u'timestamp': datetime.now(),
        u'visitor': u'{}: {}'.format(remote_addr, user_agent),
    })

عدا ذلك، من المفترض أن تعمل مكتبة البرامج بالطريقة نفسها. المشكلة الأخرى الوحيدة التي يجب أخذها في الاعتبار هي أنّ مكتبة Cloud Firestore الإصدار 2.x "متوقّفة" من حيث التطوير، لذا لن تتوفّر الميزات الأحدث إلا في مكتبة برامج Firestore الإصدار 3.x.

في ما يلي الخطوات الأساسية لهذا البرنامج التعليمي:

1. الإعداد/العمل التحضيري
2. إضافة مكتبة Cloud Firestore
3. تعديل ملفات التطبيق

3- الإعداد/العمل التحضيري

قبل البدء في الجزء الرئيسي من البرنامج التعليمي، لنقم بإعداد مشروعنا والحصول على الرمز البرمجي ثم نشر التطبيق الأساسي حتى نعرف أنّنا بدأنا برمز برمجي يعمل.

1. إعداد المشروع

ننصحك بإعادة استخدام المشروع نفسه الذي استخدمته لإكمال الدرس التطبيقي حول الترميز في الوحدة 3. يمكنك بدلاً من ذلك إنشاء مشروع جديد تمامًا أو إعادة استخدام مشروع حالي آخر. تأكَّد من أنّ المشروع يتضمّن حساب فوترة نشطًا وأنّ خدمة App Engine (التطبيق) مفعَّلة.

2. الحصول على نموذج تطبيق أساسي

من المتطلبات الأساسية لهذا الدرس التطبيقي حول الترميز أن يكون لديك نموذج تطبيق من الوحدة 3. إذا لم يكن لديك نموذج، يُرجى إكمال الدليل التوجيهي/التعليمي للوحدة 3 (الرابط أعلاه) قبل المتابعة هنا. وإذا كنت على دراية بمحتواه، يمكنك البدء مباشرةً بالحصول على رمز الوحدة التدريبية 3 أدناه.

سواء استخدمت الرمز الخاص بك أو الرمز الخاص بنا، سنبدأ بالرمز البرمجي الخاص بالوحدة 3. يرشدك هذا الدرس العملي حول الترميز في الوحدة 6 إلى كل خطوة، وعند الانتهاء منه، من المفترض أن يشبه الرمز البرمجي عند نقطة FINISH. (لا يتوفّر هذا البرنامج التعليمي إلا لإصدار Python 3).

• البدء: مستودع الوحدة التدريبية 3
• إنهاء: مستودع الوحدة التدريبية 6
• المستودع بأكمله (نسخ أو تنزيل ملف ZIP)

يجب أن يبدو دليل ملفات الوحدة التدريبية 3 (الخاص بك أو الخاص بنا) على النحو التالي:

$ ls
README.md               main.py                 templates
app.yaml                requirements.txt

3- (إعادة) نشر تطبيق الوحدة 3

في ما يلي الخطوات المتبقية التي يجب تنفيذها الآن:

1. أعِد التعرّف على أداة سطر الأوامر gcloud (إذا لزم الأمر).
2. (إعادة) نشر رمز الوحدة التدريبية 3 على App Engine (إذا لزم الأمر)

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

ملاحظة: لا يتوافق هذا البرنامج التعليمي إلا مع Python 3. إذا كان لديك تطبيق Python 2 وأردت نقل البيانات من Datastore إلى Firestore، راجِع قسم المتطلبات أدناه.

متطلبات Python 2

• تأكَّد من أنّ app.yaml (لا يزال) يشير إلى الحِزم المجمّعة التابعة لجهات خارجية: grpcio وsetuptools.
• تأكَّد من أنّ appengine_config.py لا يزال يستخدم pkg_resources وgoogle.appengine.ext.vendor لتوجيه التطبيق إلى المراجع التابعة لجهات خارجية.
• في القسم التالي، تحديث requirements.txt، عليك استخدام google-cloud-firestore==1.9.0 لأنّ هذا هو الإصدار النهائي المتوافق مع الإصدار 2.x من مكتبة برامج Python Firestore.
  • إذا كان requirements.txt يتضمّن إدخالاً لـ google-cloud-core، اتركه كما هو.
  • احذف lib وأعِد تثبيته باستخدام pip install -t lib -r requirements.txt.

4. تعديل ملفات الإعداد (إضافة مكتبة Cloud Firestore)

بعد عملية الإعداد، يجب تعديل الإعدادات ثم ملفات التطبيق. بالنسبة إلى الخيار الأول، التغيير الوحيد في الإعداد هو استبدال الحزمة الثانوية في ملف requirements.txt، لذا لننفّذ ذلك الآن.

استبدِل السطر google-cloud-datastore بالسطر google-cloud-firestore في requirements.txt ليصبح على النحو التالي:

Flask==1.1.2
google-cloud-firestore==2.0.2

ننصح باستخدام أحدث إصدارات كل مكتبة، وأرقام الإصدارات المذكورة أعلاه هي الأحدث في وقت كتابة هذا المستند. يتم تعديل الرمز في مجلد FINISH repo بشكلٍ متكرّر وقد يتضمّن إصدارًا أحدث.

لن نُجري أي تغييرات أخرى على الإعدادات، لذا سيبقى app.yaml وtemplates/index.html كما هما.

5- تعديل ملفات التطبيق

لا يوجد سوى ملف تطبيق واحد، وهو main.py، لذا فإنّ جميع التغييرات في هذا القسم تؤثّر في هذا الملف فقط.

1. عمليات الاستيراد

يُعدّ تبديل استيراد الحزمة تغييرًا بسيطًا من datastore إلى firestore:

• قبل:

from google.cloud import datastore

• AFTER:

from google.cloud import firestore

2. الوصول إلى Firestore

بعد تهيئة Flask، أنشئ عميل Firestore. أجرِ تغييرًا مشابهًا لما سبق ولكن لعملية تهيئة العميل:

• قبل:

app = Flask(__name__)
ds_client = datastore.Client()

• AFTER:

app = Flask(__name__)
fs_client = firestore.Client()

من خلال إجراء عملية النقل من Cloud NDB إلى Cloud Datastore، تكون قد أنجزت الجزء الأصعب من عملية الانتقال إلى Cloud Firestore. باستخدام Datastore، يمكنك إنشاء سجلات بيانات على شكل كيانات تتألف من خصائص شائعة وتجميعها حسب المفاتيح. إنّ سجلات البيانات في Firestore هي مستندات تتألف من أزواج المفتاح/القيمة، ويتم تجميعها معًا في مجموعات. يتطلّب الانتقال من Datastore التفكير في هذه الاختلافات لأنّها ستظهر عند إنشاء سجلّات البيانات وكذلك عند الاستعلام عنها. قد تختلف النتائج حسب مدى تعقيد رمز Datastore.

بالنسبة إلى Datastore، يمكنك إجراء طلبات بحث استنادًا إلى نوع الكيان بالإضافة إلى معايير الفلترة والترتيب. في Firestore، تتشابه عملية طلب البيانات. لنلقِ نظرة على مثال سريع، مع افتراض قيم طلب البحث والعملاء (ds_client أو fs_client، على التوالي) وعمليات الاستيراد التالية:

from datetime import datetime
from firestore.Query import DESCENDING

OCT1 = datetime(2020, 10, 1)
LIMIT = 10

بالنسبة إلى Datastore، لنبحث عن أحدث 10 عناصر Visit أحدث من 1 تشرين الأول (أكتوبر) 2020 بترتيب تنازلي:

query = ds_client.query(kind='Visit')
query.add_filter('timestamp', '>=', datetime(2020, 10, 1))
query.order = ['-timestamp']
return query.fetch(limit=LIMIT)

يمكنك تنفيذ الإجراء نفسه في Firestore من Visit المجموعة:

query = fs_client.collection('Visit')
query.where('timestamp', '>=', datetime(2020, 10, 1))
query.order_by('timestamp', direction=DESCENDING)
return query.limit(LIMIT).stream()

طلب البحث في نموذج التطبيق أبسط (لا يتضمّن عبارة "WHERE"). للمراجعة، إليك رمز Cloud Datastore:

• قبل:

def store_visit(remote_addr, user_agent):
    entity = datastore.Entity(key=ds_client.key('Visit'))
    entity.update({
        'timestamp': datetime.now(),
        'visitor': '{}: {}'.format(remote_addr, user_agent),
    })
    ds_client.put(entity)

def fetch_visits(limit):
    query = ds_client.query(kind='Visit')
    query.order = ['-timestamp']
    return query.fetch(limit=limit)

عند نقل البيانات إلى Firestore، ستجد أنّ إنشاء مستندات جديدة يشبه الكيانات، وستكون طلبات البحث كما هو موضّح سابقًا.

• AFTER:

def store_visit(remote_addr, user_agent):
    doc_ref = fs_client.collection('Visit')
    doc_ref.add({
        'timestamp': datetime.now(),
        'visitor': '{}: {}'.format(remote_addr, user_agent),
    })

def fetch_visits(limit):
    visits_ref = fs_client.collection('Visit')
    visits = (v.to_dict() for v in visits_ref.order_by('timestamp',
            direction=firestore.Query.DESCENDING).limit(limit).stream())
    return visits

تظل الدالة الرئيسية root() كما هي، وكذلك ملف النموذج index.html. تحقَّق من التغييرات التي أجريتها، ثم احفظها ونفِّذها وتأكَّد من صحتها.

6. الملخّص/التنظيف

نشر التطبيق

أعِد نشر تطبيقك باستخدام gcloud app deploy، وتأكَّد من أنّه يعمل. من المفترض أن يتطابق الرمز البرمجي الآن مع الرمز البرمجي في مستودع الوحدة 6 (أو الإصدار 2.x إذا كنت تفضّل ذلك).

إذا انتقلت إلى هذه السلسلة بدون إجراء أي من الدروس العملية السابقة، لن يتغيّر التطبيق نفسه، بل سيسجّل جميع الزيارات إلى صفحة الويب الرئيسية (/) وسيظهر على النحو التالي بعد زيارة الموقع الإلكتروني عدة مرات:

تهانينا على إكمال عملية نقل بيانات الوحدة 6 الاختيارية هذه. من المحتمل أن تكون هذه إحدى عمليات النقل الأخيرة التي يمكنك إجراؤها فيما يتعلّق بتخزين البيانات في App Engine، إن لم تكن الأخيرة. يمكنك أيضًا نقل تطبيقك إلى حاوية على Cloud Run إذا لم يسبق لك إجراء ذلك (راجِع الوحدتَين 4 و5، والبرامج التعليمية المرتبطة أدناه).

اختياري: التنظيف

ماذا عن التنظيف لتجنُّب تحصيل الرسوم منك إلى أن تصبح مستعدًا للانتقال إلى الدرس العملي التالي حول نقل البيانات؟ بصفتك مطوّرًا حاليًا، من المحتمل أنّك على دراية بمعلومات الأسعار في App Engine.

ملاحظة مهمة: لم تكن أوقات تشغيل App Engine الأصلية تتطلّب حساب فوترة نشطًا، ولكن لم يعُد هذا هو الحال (بدءًا من تشرين الثاني (نوفمبر) 2019، وتم فرض ذلك بدءًا من نيسان (أبريل) 2020). ومع ذلك، يمكنك الاطمئنان إلى أنّ App Engine لا يزال يتضمّن مستوى وصول مجانيًا لن يتم تحصيل أي رسوم منك إلا في حال تجاوز هذه الحدود.

اختياري: إيقاف التطبيق

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

من ناحية أخرى، إذا كنت لن تواصل عمليات النقل وأردت حذف كل شيء تمامًا، يمكنك إيقاف مشروعك.

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

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

• الوحدة 7: قوائم انتظار المهام الفورية في App Engine (مطلوبة إذا كنت تستخدم قوائم انتظار المهام الفورية)
  • إضافة مهام دفع App Engine taskqueue إلى تطبيق الوحدة 1
  • إعداد المستخدمين لنقل البيانات إلى Cloud Tasks في الوحدة التدريبية 8
• الوحدة 4: نقل البيانات إلى Cloud Run باستخدام Docker
  • وضع تطبيقك في حاوية لتشغيله على Cloud Run باستخدام Docker
  • تتيح لك عملية النقل هذه البقاء على الإصدار 2 من Python.
• الوحدة 5: نقل البيانات إلى Cloud Run باستخدام Cloud Buildpacks
  • وضع تطبيقك في حاوية لتشغيله على Cloud Run باستخدام Cloud Buildpacks
  • لا تحتاج إلى معرفة أي شيء عن Docker أو الحاويات أو Dockerfiles.
  • يجب أن يكون تطبيقك قد تم نقله إلى Python 3 (لا تتوافق حزم الإنشاء مع Python 2)

7. مراجع إضافية

مشاكل/ملاحظات حول دروس الترميز التطبيقية الخاصة بوحدة نقل البيانات في App Engine

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

• البحث عن المشاكل
• تسجيل مشكلة أو ملاحظات جديدة

مراجع لنقل البيانات

يمكنك العثور على روابط لمجلدات المستودع في الوحدة التدريبية 3 (البداية) والوحدة التدريبية 6 (النهاية) في الجدول أدناه. يمكن أيضًا الوصول إليها من مستودع جميع عمليات نقل البيانات في App Engine الذي يمكنك استنساخه أو تنزيل ملف ZIP منه.

Codelab	Python 2	Python 3
الوحدة 3	(الرمز)	code
الوحدة 6	(غير متوفر)	code

موارد App Engine

في ما يلي مراجع إضافية بشأن عملية النقل المحدّدة هذه:

• مراجع Python Cloud Datastore وCloud Firestore
  • مستندات مكتبة برامج Google Cloud Datastore
  • مستودع مكتبة برامج Google Cloud Datastore
  • مستندات مكتبة برامج Google Cloud Firestore
  • مستودع مكتبة برامج Google Cloud Firestore
• نقل البيانات إلى Python 3 وبيئة التشغيل من الجيل التالي في "محرّك تطبيقات Google"
  • الصفحة الرئيسية لعملية نقل البيانات
  • نقل ملفات إعدادات App Engine
• معلومات عامة
  • Python على Google Cloud Platform
  • مكتبات برامج Python في Google Cloud