ماژول 6: مهاجرت از Cloud Datastore به Cloud Firestore

1. بررسی اجمالی

هدف این سری از نرم‌افزارهای کد (آموزش‌های عملی و خودکار) به توسعه‌دهندگان Google App Engine (استاندارد) کمک می‌کند تا برنامه‌های خود را با هدایت آن‌ها از طریق یک سری مهاجرت مدرن‌سازی کنند. اکثر این انتقال‌ها شامل دور شدن از سرویس‌های همراه با زمان اجرا اصلی است، زیرا زمان‌های اجرا نسل بعدی انعطاف‌پذیرتر هستند و گزینه‌های خدمات متنوع‌تری را در اختیار کاربران قرار می‌دهند. یکی دیگر از راه‌های مدرن‌سازی اپلیکیشن، ارتقا به یک محصول جدیدتر است، و این موضوع این نرم‌افزار است.

کاربران App Engine که با کتابخانه‌های سرویس گیرنده Cloud NDB یا Cloud Datastore به Datastore دسترسی پیدا می‌کنند، بسیار خوب هستند و نیازی به مهاجرت بیشتر ندارند. با این حال، Cloud Firestore نشان‌دهنده جدیدترین، مقیاس‌پذیر، بسیار در دسترس، ذخیره‌گاه داده NoSQL با ویژگی‌های پایگاه داده بیدرنگ Firebase است .

اگر توسعه‌دهنده‌ای هستید که مجبور به استفاده از Firestore برای استفاده از ویژگی‌های آن هستید یا حداقل علاقه کافی برای کشف آنچه مهاجرت مستلزم آن است، در جای مناسبی هستید. این آموزش به شما می آموزد که چگونه یک برنامه App Engine را با استفاده از Cloud Datastore به Cloud Firestore منتقل کنید.

شما یاد خواهید گرفت که چگونه

  • تفاوت بین Datastore و Firestore را بشناسید
  • از Cloud Datastore به Cloud Firestore مهاجرت کنید

آنچه شما نیاز دارید

نظرسنجی

چگونه از این کد لبه استفاده خواهید کرد؟

فقط آن را بخوانید آن را بخوانید و تمرینات را کامل کنید

2. پس زمینه

Datastore App Engine در سال 2013 به محصول خود تبدیل شد ، Google Cloud Datastore، و اکنون برای توسعه دهندگان خارج از App Engine قابل دسترسی است. سال بعد، Firebase توسط گوگل خریداری شد. در آن زمان، به دلیل پایگاه داده بلادرنگ خود شناخته شده بود.

طی چند سال آینده، تیم‌های Firebase و Cloud Datastore روی ادغام برخی از ویژگی‌های Firebase در Datastore کار کردند. در نتیجه، در سال 2017، نسل بعدی Cloud Datastore عرضه شد . برای انعکاس به ارث بردن برخی از ویژگی های Firebase، آن را به عنوان Cloud Firestore تغییر نام داد.

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، مراحل انتقال "ناخوشایند" هستند:

  • شما باید از پروژه ای متفاوت از پروژه برنامه فعلی خود استفاده کنید.
  • پروژه‌ای که در آن یک برنامه موجودیت‌های Datastore را اضافه کرده است، نمی‌تواند در حالت بومی به Firestore تغییر وضعیت دهد
  • به طور مشابه، پروژه ای که Firestore را در حالت بومی انتخاب کرده باشد، نمی تواند در حالت Datastore به Firestore برگردد.
  • هیچ ابزار مهاجرتی وجود ندارد که بتواند داده ها را از یک پروژه به پروژه دیگر منتقل کند.
  • برخی از ویژگی‌های حیاتی Datastore، از جمله فضاهای نام و توان نوشتن بالاتر (> 10k/s)، از Firestore در دسترس نیستند .
  • ابزار صادرات و واردات سناریوهای «ابتدایی» و «همه یا هیچ» هستند.
    • اگر برنامه شما دارای موجودیت های Datastore زیادی است، ممکن است چندین ساعت طول بکشد تا صادر شود و سپس وارد Firestore شود.
    • در این مدت، برنامه/سرویس شما قادر به نوشتن/به‌روزرسانی داده‌ها نخواهد بود.
    • فعالیت های مهاجرت در استفاده عادی به حساب می آیند. ممکن است بخواهید آن را پخش کنید (در صورت امکان در سهمیه های روزانه) تا هزینه ها را به حداقل برسانید.
    • از آنجایی که سرویس جدید شما در پروژه دیگری اجرا می شود، برای انتشار به یک پنجره برای به روز رسانی DNS نیاز دارید.
  • Datastore و Firestore مدل‌های داده مشابه اما متفاوتی دارند، بنابراین انتقال نیاز به به‌روزرسانی نحوه عملکرد برنامه/سرویس دارد.
    • پرس‌وجوهای اجدادی از Datastore اکنون عبارت‌اند از پرس‌وجوهای مجموعه Firestore (پیش‌فرض)
    • پرس و جوهای نوع گسترده از Datastore پرس و جوهای گروهی Firestore Collection هستند
    • شاخص ها و مدیریت متفاوت است و غیره.

تمام آنچه گفته شد، اگر یک برنامه نسبتاً ساده دارید که باید برای مهاجرت در نظر بگیرید، برای شبیه‌سازی چنین مهاجرتی آماده می‌شوید، یا به سادگی اینجا برای یادگیری در مورد Datastore در مقابل Firestore، لطفا ادامه دهید!

کاربران Python 2: این Codelab انتقال اختیاری فقط در Python 3 ارائه شده است، اما از آنجایی که Cloud Firestore از 2.x نیز پشتیبانی می کند، کاربران می توانند تفاوت های استفاده را درون یابی کنند. یک مثال این است که رکوردهای Firestore از رشته‌های یونیکد (به‌جای رشته‌های بایت) استفاده می‌کنند، بنابراین یک نشانگر اصلی u'' برای حروف الفبای رشته پایتون 2 مورد نیاز است، به این معنی که یک تابع store_visit() 2.x به شکل زیر خواهد بود:

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),
    })

به غیر از آن، کتابخانه مشتری باید به طور مشابه عمل کند. تنها موضوع دیگری که باید مورد توجه قرار گیرد این است که کتابخانه 2.x Cloud Firestore تا آنجا که توسعه می‌رود، "یخ زده" است، بنابراین ویژگی‌های بیشتر/جدیدتر فقط در کتابخانه مشتری Firestore 3.x در دسترس خواهند بود.

در ادامه این مهاجرت، مراحل اولیه این آموزش به شرح زیر است:

  1. راه اندازی/پیش کار
  2. کتابخانه Cloud Firestore را اضافه کنید
  3. به روز رسانی فایل های برنامه

3. راه اندازی/پیش کار

قبل از شروع بخش اصلی آموزش، بیایید پروژه خود را راه‌اندازی کنیم، کد را دریافت کنیم، سپس برنامه پایه را اجرا کنیم تا بدانیم با کد کار شروع کرده‌ایم.

1. پروژه راه اندازی

توصیه می‌کنیم از همان پروژه‌ای که برای تکمیل ماژول 3 استفاده کردید، دوباره استفاده کنید. از طرف دیگر، می توانید یک پروژه کاملاً جدید ایجاد کنید یا از پروژه موجود دیگری استفاده مجدد کنید. مطمئن شوید که پروژه دارای حساب صورتحساب فعال است و App Engine (برنامه) فعال است.

2. برنامه نمونه پایه را دریافت کنید

یکی از پیش نیازهای این نرم افزار کد، داشتن یک برنامه نمونه کار با ماژول 3 است. اگر یکی ندارید، قبل از اینکه به اینجا بروید، آموزش ماژول 3 (لینک بالا) را کامل کنید. در غیر این صورت، اگر قبلاً با محتویات آن آشنا هستید، می توانید با گرفتن کد ماژول 3 زیر شروع کنید.

چه از ما استفاده کنید چه از کد ما، کد ماژول 3 جایی است که ما شروع می کنیم. این کد ماژول 6 شما را در هر مرحله راهنمایی می کند، و پس از تکمیل، باید شبیه کد در نقطه FINISH باشد. (این آموزش فقط برای پایتون 3 موجود است.)

دایرکتوری فایل های ماژول 3 (مال شما یا ما) باید به شکل زیر باشد: 

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

3. (دوباره) استقرار برنامه ماژول 3

مراحل پیش‌کار باقی‌مانده برای اجرا اکنون:

  1. با ابزار خط فرمان gcloud مجدداً آشنا شوید (در صورت لزوم)
  2. (کد ماژول 3 را مجدداً در App Engine قرار دهید (در صورت لزوم.)

هنگامی که آن مراحل را با موفقیت انجام دادید و عملیاتی بودن آن را تأیید کردید، در این آموزش به جلو می رویم و با فایل های پیکربندی شروع می کنیم.

الزامات پایتون 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
  • بعد از: 
from google.cloud import firestore

2. دسترسی به Firestore

پس از مقداردهی اولیه Flask، مشتری Firestore خود را ایجاد کنید. یک تغییر مشابه در بالا انجام دهید اما برای مقداردهی اولیه مشتری:

  • قبل از:
app = Flask(__name__)
ds_client = datastore.Client()
  • بعد از:
app = Flask(__name__)
fs_client = firestore.Client()

با انجام انتقال از Cloud NDB به Cloud Datastore، شما قبلاً کارهای سنگین را برای رسیدن به Cloud Firestore انجام داده اید. با Datastore، رکوردهای داده را در قالب Entities متشکل از Properties مشترک ایجاد می کنید و آنها را بر اساس کلیدها گروه بندی می کنید . رکوردهای داده در Firestore اسنادی هستند که از جفت‌های کلید-مقدار تشکیل شده‌اند و با هم در مجموعه‌ها گروه‌بندی می‌شوند . مهاجرت از Datastore مستلزم این است که در مورد این تفاوت‌ها فکر کنید زیرا زمانی که سوابق داده‌ها را ایجاد می‌کنید و همچنین برای آنها پرس و جو می‌کنید، این تفاوت‌ها محقق می‌شوند. نتایج شما ممکن است بسته به پیچیدگی کد Datastore شما متفاوت باشد.

برای Datastore، پرس و جوهایی را بر اساس نوع Entity همراه با معیارهای فیلتر و مرتب سازی انجام می دهید. برای 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)

انجام همین کار برای Firestor، از مجموعه 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، اسناد جدیدی شبیه به موجودیت‌ها و پرس و جوهایی که قبلا نشان داده شد ایجاد می‌کنید.

  • بعد از:
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 اگر ترجیح شما بود) مطابقت داشته باشد.

اگر بدون انجام هیچ یک از کدهای قبلی وارد این سری شده اید، خود برنامه تغییر نمی کند. تمام بازدیدهای صفحه اصلی وب ( / ) را ثبت می کند و وقتی به اندازه کافی از سایت بازدید کردید به این شکل به نظر می رسد:

برنامه visitme

برای تکمیل این انتقال اختیاری ماژول 6 تبریک می گویم. این احتمالاً یکی از، اگر نه آخرین، مهاجرت هایی است که می توانید تا جایی که ذخیره داده های App Engine انجام دهید. اگر قبلاً این کار را نکرده‌اید، یکی از جابه‌جایی‌های جایگزینی که می‌توانید در نظر بگیرید این است که برنامه خود را برای Cloud Run محفظه کنید (به ماژول‌های 4 و 5، کدهای مرتبط در زیر مراجعه کنید).

اختیاری: تمیز کردن

در مورد تمیز کردن برای جلوگیری از دریافت صورت‌حساب تا زمانی که آماده باشید به آزمایشگاه کد مهاجرت بعدی بروید، چطور؟ به‌عنوان توسعه‌دهندگان موجود، احتمالاً از قبل از اطلاعات قیمت‌گذاری App Engine به‌روز هستید.

اختیاری: برنامه را غیرفعال کنید

اگر هنوز برای رفتن به آموزش بعدی آماده نیستید، برای جلوگیری از تحمیل هزینه ، برنامه خود را غیرفعال کنید . هنگامی که برای رفتن به کد بعدی آماده شدید، می توانید آن را دوباره فعال کنید. در حالی که برنامه شما غیرفعال است، هیچ ترافیکی برای پرداخت هزینه دریافت نمی‌کند، اما مورد دیگری که می‌توانید برای آن صورت‌حساب دریافت کنید، استفاده از Firestore شما در صورت فراتر رفتن از سهمیه رایگان است، بنابراین به اندازه‌ای حذف کنید که زیر آن محدودیت قرار بگیرید.

از طرف دیگر، اگر نمی‌خواهید مهاجرت را ادامه دهید و می‌خواهید همه چیز را به طور کامل حذف کنید، می‌توانید پروژه خود را خاموش کنید .

مراحل بعدی

فراتر از این آموزش، چندین کد ماژول مهاجرت دیگر وجود دارد که می توانید در نظر بگیرید:

  • ماژول 7: App Engine Push Task Queues (الزامی در صورت استفاده از [push] Task Queues)
    • وظایف فشار taskqueue موتور برنامه را به برنامه ماژول 1 اضافه می کند
    • کاربران را برای مهاجرت به Cloud Tasks در ماژول 8 آماده می کند
  • ماژول 4: با Docker به Cloud Run مهاجرت کنید
    • برنامه خود را برای اجرا در Cloud Run with Docker محفظه کنید
    • این مهاجرت به شما امکان می دهد در پایتون 2 بمانید.
  • ماژول 5: با Cloud Buildpacks به Cloud Run مهاجرت کنید
    • برنامه خود را برای اجرا در Cloud Run با Cloud Buildpacks کانتینری کنید
    • نیازی نیست در مورد Docker، کانتینرها یا Dockerfile چیزی بدانید.
    • نیاز دارد که برنامه شما قبلاً به پایتون 3 منتقل شده باشد (Buildpacks از Python 2 پشتیبانی نمی کند)

7. منابع اضافی

مشکلات/بازخورد مربوط به ماژول کدهای ماژول مهاجرت موتور برنامه

اگر مشکلی در این کد لبه پیدا کردید، لطفاً قبل از تشکیل پرونده ابتدا مشکل خود را جستجو کنید. پیوندهایی برای جستجو و ایجاد مسائل جدید:

منابع مهاجرت

پیوندهای پوشه‌های مخزن برای ماژول 3 (START) و ماژول 6 (FINISH) را می‌توانید در جدول زیر پیدا کنید. همچنین می‌توانید از مخزن برای همه مهاجرت‌های App Engine که می‌توانید یک فایل ZIP را شبیه‌سازی یا دانلود کنید، دسترسی پیدا کنید.

Codelab

پایتون 2

پایتون 3

ماژول 3

( کد )

کد

ماژول 6

(n/a)

کد

منابع App Engine

در زیر منابع اضافی در مورد این مهاجرت خاص آمده است: