מעבר ל-Cloud NDB

מיקומים של App Engine

‫App Engine הוא אזורי, כלומר התשתית שמריצה את האפליקציות שלכם ממוקמת באזור ספציפי, ו-Google מנהלת אותה כך שהיא זמינה באופן יתירתי בכל התחומים באותו אזור.

הקריטריונים העיקריים לבחירת האזור שבו האפליקציות יפעלו הם זמן האחזור, הזמינות או העמידות. בדרך כלל אפשר לבחור את האזור הקרוב ביותר למשתמשים באפליקציה, אבל כדאי גם לבדוק אילו מיקומים נתמכים ב-App Engine ואילו מיקומים נתמכים במוצרים ובשירותים אחרים שלGoogle Cloud שבהם האפליקציה משתמשת. שימוש בשירותים בכמה מיקומים יכול להשפיע על זמן האחזור של האפליקציה וגם על התמחור שלה.

אחרי שמגדירים את האזור של אפליקציה, אי אפשר לשנות אותו.

אם כבר יצרתם אפליקציית App Engine, תוכלו לראות את האזור שלה באחת מהדרכים הבאות:

מריצים את הפקודה gcloud app describe.
פותחים את מרכז הבקרה של App Engine במסוף Google Cloud . האזור מופיע בחלק העליון של הדף.

‫Cloud NDB היא ספריית לקוח ל-Python שמחליפה את App Engine NDB. ‫NDB של App Engine מאפשר לאפליקציות Python 2 לאחסן נתונים במסדי נתונים של Datastore ולהריץ עליהם שאילתות. ‫Cloud NDB מאפשר לאפליקציות Python 2 ו-Python 3 לאחסן נתונים ולשלוח שאילתות לגביהם באותם מסדי נתונים, אבל המוצר שמנהל את מסדי הנתונים האלה השתנה מ-Datastore ל-Firestore במצב Datastore. למרות שספריית Cloud NDB יכולה לגשת לכל הנתונים שנוצרו באמצעות App Engine NDB, לא ניתן לגשת לנתונים מובְנים מסוימים שאוחסנו באמצעות Cloud NDB באמצעות App Engine NDB. לכן, המעבר ל-Cloud NDB הוא בלתי הפיך.

מומלץ להעביר את האפליקציה ל-Cloud NDB לפני שמשדרגים אותה ל-Python 3. הגישה המצטברת הזו להעברה מאפשרת לכם לשמור על אפליקציה מתפקדת שניתן לבדוק אותה לאורך תהליך ההעברה.

‫Cloud NDB נועד להחליף את התכונות ב-App Engine NDB, ולכן הוא לא יתמוך בתכונות חדשות של Firestore במצב Datastore. מומלץ שאפליקציות חדשות ב-Python 3 ישתמשו בספריית הלקוח במצב Datastore במקום ב-Cloud NDB.

מידע נוסף על Cloud NDB זמין בדפים הבאים ב-GitHub:

השוואה בין App Engine NDB ו-Cloud NDB

תכונות דומות:

‫Cloud NDB תומך כמעט בכל התכונות שנתמכות ב-App Engine NDB, עם הבדלים קלים בלבד בתחביר של השיטות.

ההבדלים:

ממשקי API של App Engine NDB שמסתמכים על שירותים ספציפיים של זמן ריצה ב-App Engine Python 2.7 עודכנו או הוסרו מ-Cloud NDB.
תכונות חדשות ב-Python 3 וב-Django ביטלו את הצורך ב-google.appengine.ext.ndb.django_middleware. במקום זאת, אפשר לכתוב בקלות תוכנת ביניים משלכם בכמה שורות קוד בלבד.
כדי להשתמש ב-App Engine NDB, האפליקציות ומסד הנתונים של Datastore צריכים להיות באותו פרויקט Google Cloud , ו-App Engine מספק את פרטי הכניסה באופן אוטומטי. ל-Cloud NDB יש גישה למסדי נתונים במצב Datastore בכל פרויקט, כל עוד הלקוח מאומת בצורה תקינה. ההתנהגות הזו עקבית עם ממשקי API אחרים ועם ספריות לקוח. Google Cloud
‫Cloud NDB לא משתמש בשירות App Engine Memcache כדי לשמור נתונים במטמון.

במקום זאת, Cloud NDB יכול לשמור נתונים במטמון בחנות נתונים בזיכרון Redis שמנוהלת על ידי Memorystore,‏ Redis Labs או מערכות אחרות. למרות שכרגע יש תמיכה רק במאגרי נתונים של Redis,‏ Cloud NDB הכללי והגדיר שמירה במטמון בממשק המופשט GlobalCache, שיכול לתמוך בהטמעות קונקרטיות נוספות.

כדי לגשת ל-Memorystore for Redis, האפליקציה צריכה להשתמש בחיבור לרשת (VPC) מאפליקציית serverless.

ל-Memorystore for Redis ול-Serverless VPC Access אין רמת שימוש חינמית, ויכול להיות שהמוצרים האלה לא זמינים באזור של האפליקציה שלכם. מידע נוסף זמין במאמר לפני שמתחילים בהעברה.

הרשימה המלאה של ההבדלים זמינה בהערות ההעברה לפרויקט Cloud NDB GitHub.

דוגמאות קוד:

פעולות בסיסיות במסד נתונים באמצעות App Engine NDB
פעולות בסיסיות במסד נתונים באמצעות Cloud NDB

לפני שמתחילים בהעברה

לפני שמתחילים בהעברה:

אם עדיין לא עשיתם זאת, צריך להגדיר את סביבת הפיתוח של Python כך שתשתמש בגרסת Python שתואמת ל- Google Cloud, ולהתקין כלי בדיקה ליצירת סביבות Python מבודדות.
קובעים אם צריך לשמור נתונים במטמון.
אם אתם צריכים לשמור נתונים במטמון, ודאו שהאזור של האפליקציה נתמך על ידי Serverless VPC Access ו-Memorystore for Redis.
הסבר על ההרשאות במצב Datastore

איך קובעים אם צריך לשמור נתונים במטמון

אם האפליקציה שלכם צריכה לשמור נתונים במטמון, חשוב לדעת של-Memorystore for Redis ול-Serverless VPC Access אין רמת שירות בחינם, והם לא תומכים בכלGoogle Cloud האזורים.

באופן כללי:

אם האפליקציה קוראת את אותם נתונים לעיתים קרובות, שמירת נתונים במטמון יכולה להקטין את זמן האחזור.
ככל שהאפליקציה מציגה יותר בקשות, כך ההשפעה של שמירת נתונים במטמון גדולה יותר.

כדי לראות עד כמה אתם מסתמכים כרגע על נתונים שנשמרו במטמון, אפשר לעיין בלוח הבקרה של Memcache כדי לראות את היחס בין מציאות במטמון לבין החמצות במטמון. אם היחס גבוה, סביר להניח שלשימוש במטמון נתונים תהיה השפעה גדולה על צמצום זמן האחזור של האפליקציה.

מעבר אל App Engine Memcache

מידע על התמחור זמין במאמרים תמחור של Memorystore ותמחור של Serverless VPC Access.

אישור האזור של האפליקציה

אם אתם צריכים לשמור נתונים במטמון, ודאו שהאזור של האפליקציה נתמך על ידי Memorystore for Redis וחיבור לרשת (VPC) מאפליקציית serverless:

אפשר לראות את האזור של האפליקציה, שמופיע בחלק העליון של לוח הבקרה של App Engine במסוף Google Cloud .

מעבר אל App Engine

האזור מופיע בחלק העליון של הדף, ממש מתחת לכתובת ה-URL של האפליקציה.
מוודאים שהאפליקציה נמצאת באחד האזורים שנתמכים על ידי חיבור לרשת (VPC) מאפליקציית serverless.
כדי לוודא שהאפליקציה שלכם נמצאת באחד מהאזורים שנתמכים על ידי Memorystore for Redis, אתם יכולים להיכנס לדף Create connector ולעיין באזורים שמופיעים ברשימה Regions.

מעבר אל Serverless VPC Access

אם האפליקציה לא נמצאת באזור שנתמך על ידי Memorystore for Redis ו-Serverless VPC Access:

יוצרים Google Cloud פרויקט.
יוצרים אפליקציית App Engine חדשה בפרויקט ובוחרים אזור נתמך.
יוצרים את Google Cloud השירותים שהאפליקציה משתמשת בהם בפרויקט החדש.

אפשרות אחרת היא לעדכן את האפליקציה כך שתשתמש בשירותים הקיימים בפרויקט הישן, אבל יכול להיות שהתמחור ושימוש המשאבים יהיו שונים כשמשתמשים בשירותים בפרויקט ובאזור אחרים. מידע נוסף זמין במסמכי התיעוד של כל שירות.
פורסים את האפליקציה בפרויקט החדש.

הסבר על ההרשאות במצב Datastore

כל אינטראקציה עם שירות Google Cloud צריכה להיות מאושרת. לדוגמה, כדי לאחסן נתונים במסד נתונים במצב Datastore או לשלוח אליו שאילתות, האפליקציה צריכה לספק את פרטי הכניסה של חשבון שיש לו הרשאה לגשת למסד הנתונים.

כברירת מחדל, האפליקציה מספקת את פרטי הכניסה של חשבון השירות שמוגדר כברירת מחדל ב-App Engine, שיש לו הרשאה לגשת למסדי נתונים באותו פרויקט שבו נמצאת האפליקציה.

אם אחד מהתנאים הבאים מתקיים, תצטרכו להשתמש בטכניקת אימות חלופית שמספקת באופן מפורש פרטי כניסה:

האפליקציה ומסד הנתונים במצב Datastore נמצאים בGoogle Cloud פרויקטים שונים.
שיניתם את התפקידים שהוקצו לחשבון השירות שמוגדר כברירת מחדל ב-App Engine.

מידע על טכניקות אימות חלופיות זמין במאמר הגדרת אימות לאפליקציות ייצור מסוג Server to Server.

סקירה כללית של תהליך המיגרציה

כדי לבצע מיגרציה ל-Cloud NDB:

עדכון אפליקציית Python:
1. מתקינים את ספריית הלקוח Cloud NDB.
2. מעדכנים את הצהרות הייבוא כדי לייבא מודולים מ-Cloud NDB.
3. מוסיפים קוד שיוצר לקוח Cloud NDB. הלקוח יכול לקרוא את משתני הסביבה של האפליקציה ולהשתמש בנתונים כדי לאמת במצב Datastore.
4. מוסיפים קוד שמשתמש בהקשר של זמן הריצה של הלקוח כדי לשמור על הפרדה בין השמירה במטמון לבין העסקאות בין השרשורים.
5. מסירים או מעדכנים קוד שמשתמש בשיטות ובמאפיינים שכבר לא נתמכים.
הפעלת שמירה במטמון.
בודקים את העדכונים.
פריסת האפליקציה ב-App Engine.

כמו בכל שינוי שאתם מבצעים באפליקציה, כדאי להשתמש בפיצול תנועה כדי להגדיל את התנועה בהדרגה. לפני שמפנים עוד תנועה לאפליקציה המעודכנת, חשוב לעקוב אחרי האפליקציה כדי לוודא שאין בעיות במסד הנתונים.

עדכון אפליקציית Python

התקנת ספריית Cloud NDB לאפליקציות Python

כדי להתקין את ספריית הלקוח Cloud NDB באפליקציית Python ב-App Engine:

מעדכנים את הקובץ app.yaml. פועלים לפי ההוראות שמתאימות לגרסת Python:
‫Python 2
באפליקציות Python 2, מוסיפים את הגרסאות האחרונות של הספריות grpcio ו-setuptools.

קובץ app.yaml לדוגמה:
```
runtime: python27
threadsafe: yes
api_version: 1

libraries:
- name: grpcio
  version: latest
- name: setuptools
  version: latest
```
Python 3
באפליקציות Python 3, מציינים את הרכיב runtime עם גרסת Python 3 נתמכת, ומוחקים שורות מיותרות. לדוגמה, קובץ app.yaml יכול להיראות כך:
```
runtime: python310 # or another support version
```
סביבת זמן הריצה של Python 3 מתקינה ספריות באופן אוטומטי, כך שלא צריך לציין ספריות מובנות מסביבת זמן הריצה הקודמת של Python 2. אם האפליקציה שלכם ב-Python 3 משתמשת בשירותים אחרים שצורפו לחבילה מדור קודם במהלך ההעברה, אל תשנו את הקובץ app.yaml.
מעדכנים את הקובץ requirements.txt. פועלים לפי ההוראות שמתאימות לגרסת Python:
‫Python 2
מוסיפים את ספריות הלקוח של Cloud NDB לרשימת התלויות בקובץ requirements.txt.
```
google-cloud-ndb
```
לאחר מכן מריצים את הפקודה pip install -t lib -r requirements.txt כדי לעדכן את רשימת הספריות שזמינות לאפליקציה.
Python 3
מוסיפים את ספריות הלקוח של Cloud NDB לרשימת התלויות בקובץ requirements.txt.
```
google-cloud-ndb
```
‫App Engine מתקין את התלות האלה באופן אוטומטי במהלך פריסת האפליקציה בסביבת זמן הריצה של Python 3, לכן צריך למחוק את התיקייה lib אם היא קיימת.
באפליקציות Python 2, אם האפליקציה משתמשת בספריות מובנות או בספריות שהועתקו שצוינו בספרייה lib, צריך לציין את הנתיבים האלה בקובץ appengine_config.py:
```
import pkg_resources
from google.appengine.ext import vendor

# Set PATH to your libraries folder.
PATH = 'lib'
# Add libraries installed in the PATH folder.
vendor.add(PATH)
# Add libraries to pkg_resources working set to find the distribution.
pkg_resources.working_set.add_entry(PATH)
```
חשוב להשתמש במודולpkg_resources כדי לוודא שהאפליקציה משתמשת בהפצה הנכונה של ספריות הלקוח.

בדוגמה הקודמת, הקובץ appengine_config.py מניח שהתיקייה lib נמצאת בספריית העבודה הנוכחית. אם אתם לא יכולים להבטיח שהתיקייה lib תמיד תהיה בספריית העבודה הנוכחית, צריך לציין את הנתיב המלא לתיקייה lib. לדוגמה:
```
import os
path = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'lib')
```
כשפורסים את האפליקציה, App Engine מעלה את כל הספריות בספרייה שצוינה בקובץ appengine_config.py.

עדכון הצהרות ייבוא

המיקום של מודול ה-NDB הועבר אל google.cloud.ndb. מעדכנים את הצהרות הייבוא של האפליקציה כמו שמוצג בטבלה הבאה:

הסרה	החלף ב
`from google.appengine.ext import ndb`	`from google.cloud import ndb`

יצירת לקוח Cloud NDB

בדומה לספריות לקוח אחרות שמבוססות על Google Cloud ממשקי API, השלב הראשון בשימוש ב-Cloud NDB הוא ליצור אובייקט Client. הלקוח מכיל פרטי כניסה ונתונים אחרים שנדרשים כדי להתחבר למצב Datastore. לדוגמה:

from google.cloud import ndb

client = ndb.Client()

בתרחיש ההרשאה שמוגדר כברירת מחדל שתיארנו קודם, לקוח Cloud NDB מכיל פרטי כניסה מחשבון השירות שמוגדר כברירת מחדל של App Engine, שיש לו הרשאה ליצור אינטראקציה עם מצב Datastore. אם אתם לא עובדים בתרחיש ברירת המחדל הזה, תוכלו לקרוא את המאמר Application Default Credentials (ADC) כדי לקבל מידע על אופן אספקת פרטי הכניסה.

שימוש בהקשר של זמן הריצה של הלקוח

בנוסף לאישורים שנדרשים לאינטראקציה עם מצב Datastore, לקוח Cloud NDB מכיל את ה-method‏ context() שמחזירה הקשר של זמן ריצה. ההקשר של זמן הריצה מבודד את בקשות השמירה במטמון ואת בקשות העסקאות מאינטראקציות מקבילות אחרות במצב Datastore.

כל האינטראקציות עם מצב Datastore צריכות להתרחש בהקשר של זמן ריצה של NDB. מכיוון שיצירת הגדרת מודל לא יוצרת אינטראקציה עם מצב Datastore, אפשר להגדיר את מחלקת המודל לפני שיוצרים לקוח Cloud NDB ומאחזרים הקשר של זמן ריצה, ואז להשתמש בהקשר של זמן הריצה ב-handler של הבקשה כדי לקבל נתונים ממסד הנתונים.

לדוגמה:

from google.cloud import ndb


class Book(ndb.Model):
    title = ndb.StringProperty()


client = ndb.Client()


def list_books():
    with client.context():
        books = Book.query()
        for book in books:
            print(book.to_dict())

אפליקציות מרובות-הליכים

הקשר של זמן הריצה שמוחזר על ידי לקוח Cloud NDB רלוונטי רק לשרשור יחיד. אם האפליקציה משתמשת בכמה שרשורים לבקשה אחת, צריך לאחזר הקשר נפרד של זמן הריצה לכל שרשור שישתמש בספריית Cloud NDB.

שימוש בהקשר של זמן ריצה עם מסגרות WSGI

אם אפליקציית האינטרנט שלכם משתמשת במסגרת WSGI, אתם יכולים ליצור באופן אוטומטי הקשר חדש של זמן ריצה לכל בקשה. לשם כך, צריך ליצור אובייקט של תוכנת ביניים שמחלץ את ההקשר של זמן הריצה, ואז לעטוף את האפליקציה באובייקט של תוכנת הביניים.

בדוגמה הבאה לשימוש בתוכנת ביניים עם Flask:

השיטה middleware יוצרת אובייקט של תוכנת ביניים WSGI בהקשר של זמן הריצה של לקוח NDB.
אפליקציית Flask עטופה באובייקט של תוכנת ביניים.
לאחר מכן, Flask יעביר כל בקשה דרך אובייקט התוכנה, שיאחזר הקשר חדש של זמן ריצה של NDB לכל בקשה.

from flask import Flask

from google.cloud import ndb


client = ndb.Client()


def ndb_wsgi_middleware(wsgi_app):
    def middleware(environ, start_response):
        with client.context():
            return wsgi_app(environ, start_response)

    return middleware


app = Flask(__name__)
app.wsgi_app = ndb_wsgi_middleware(app.wsgi_app)  # Wrap the app in middleware.


class Book(ndb.Model):
    title = ndb.StringProperty()


@app.route("/")
def list_books():
    books = Book.query()
    return str([book.to_dict() for book in books])

שימוש בהקשר של זמן ריצה עם Django

תוכנת הביניים של Django שמסופקת על ידי ספריית App Engine NDB לא נתמכת על ידי ספריית Cloud NDB. אם השתמשתם בתוכנת הביניים הזו (google.appengine.ext.ndb.django_middleware) באפליקציה שלכם, צריך לפעול לפי השלבים הבאים כדי לעדכן את האפליקציה:

משתמשים במערכת התוכנה של Django כדי ליצור הקשר חדש בזמן ריצה לכל בקשה.

בדוגמה הבאה:

השיטה ndb_django_middleware יוצרת לקוח Cloud NDB.
השיטה middleware יוצרת אובייקט של תוכנת ביניים בהקשר של זמן הריצה של לקוח NDB.

from google.cloud import ndb


# Once this middleware is activated in Django settings, NDB calls inside Django
# views will be executed in context, with a separate context for each request.
def ndb_django_middleware(get_response):
    client = ndb.Client()

    def middleware(request):
        with client.context():
            return get_response(request)

    return middleware

בקובץ settings.py של Django, מעדכנים את ההגדרה MIDDLEWARE כך שיופיע בה רשימה של תוכנות הביניים החדשות שיצרתם במקום google.appengine.ext.ndb.NdbDjangoMiddleware.

מערכת Django תעביר עכשיו כל בקשה דרך אובייקט התוכנה שמתווכת בין מערכות שונות שציינתם בהגדרה MIDDLEWARE, והאובייקט הזה יאחזר הקשר חדש של זמן ריצה של NDB לכל בקשה.

עדכון קוד לממשקי NDB API שהוסרו או השתנו

ממשקי NDB API שמסתמכים על ממשקי API ושירותים ספציפיים של App Engine עודכנו או הוסרו מהספרייה של Cloud NDB.

אם הקוד שלכם משתמש באחד מממשקי ה-API הבאים של NDB, תצטרכו לעדכן אותו:

google.appengine.ext.ndb.Model ומאפייני המודל
google.appengine.ext.ndb.Key
‫google.appengine.ext.ndb.query.QueryOptions ו-PropertyOrder
google.appengine.ext.ndb.utils
google.appengine.api.namespacemanager
google.appengine.api.ext.ndb.tasklets
google.appengine.api.datastore_errors

מודלים ומאפייני מודלים

השיטות הבאות מ-google.appengine.ext.ndb.Model לא זמינות בספריית Cloud NDB כי הן משתמשות בממשקי API ספציפיים ל-App Engine שכבר לא זמינים.

הסרנו API	החלפה
‫`Model.get_indexes` וגם `Model.get_indexes_async`	ללא
‫`Model._deserialize` וגם `Model._serialize`	ללא
`Model.make_connection`	ללא

בטבלה הבאה מתוארים מאפייני google.appengine.ext.ndb.Model ספציפיים בספריית Cloud NDB שעברו שינוי:

מאפיין (property)	שינוי
`TextProperty`	לא ניתן להוסיף לאינדקס את `google.cloud.ndb.TextProperty`. אם תנסו להגדיר את `google.cloud.ndb.TextProperty.indexed`, תופיע שגיאה `NotImplementedError`.
`StringProperty`	‫`StringProperty` תמיד עובר אינדוקס. אם תנסו להגדיר את `google.cloud.ndb.StringProperty.indexed`, תופיע `NotImplementedError`.
כל המאפיינים עם הארגומנטים `name` או `kind` בקונסטרוקטור.	‫`name` או `kind` חייבים להיות מסוג הנתונים `str`, כי `unicode` הוחלף ב-`str` ב-Python 3.

המחלקות וה-methods בטבלה הבאה כבר לא זמינות, כי הן משתמשות במשאבים ספציפיים ל-App Engine שכבר לא זמינים.

google.appengine.ext.ndb.model.Property:
_db_get_value
_db_set_value
_db_set_compressed_meaning
_db_set_uncompressed_meaning
__creation_counter_global

הסרנו API	החלפה
‫`google.appengine.ext.ndb.msgprop.MessageProperty` וגם `google.appengine.ext.ndb.msgprop.EnumProperty`	ללא אם תנסו ליצור את האובייקטים האלה, תופיע הודעת שגיאה `NotImplementedError`.
ללא השיטות האלה מסתמכות על מאגרי פרוטוקולים במצב Datastore שהשתנו.
`Model.make_connection`	ללא

מקשים

השיטות הבאות מ-google.appengine.ext.ndb.Key לא זמינות בספריית Cloud NDB. השיטות האלה שימשו להעברת מפתחות אל ומממשק ה-API של DB Datastore, שכבר לא נתמך (DB היה קודמו של App Engine NDB).

הסרנו API	החלפה
‫`Key.from_old_key` וגם `Key.to_old_key`	ללא

בנוסף, חשוב לשים לב לשינויים הבאים:

App Engine NDB	Cloud NDB
הסוגים והמזהים של המחרוזות צריכים להיות קטנים מ-500 בייטים	הסוגים והמזהים של המחרוזות צריכים להיות קצרים מ-1,500 בייט.
‫`Key.app()` מחזירה את מזהה הפרויקט שציינתם כשנוצר המפתח.	יכול להיות שהערך שמוחזר על ידי `google.cloud.ndb.Key.app()` שונה מהמזהה המקורי שהועבר אל הבונה. הסיבה לכך היא שמזהי אפליקציות עם קידומת כמו s~example הם מזהים מדור קודם מ-App Engine. הם הוחלפו במזהי פרויקט מקבילים, כמו example.

שאילתות

בדומה ל-App Engine NDB,‏ Cloud NDB מספק מחלקה QueryOptions (google.cloud.ndb.query.QueryOptions) שמאפשרת לכם לעשות שימוש חוזר בקבוצה ספציפית של אפשרויות שאילתה, במקום להגדיר אותן מחדש לכל שאילתה. עם זאת, QueryOptions ב-Cloud NDB לא יורש מ-google.appengine.datastore.datastore_rpc.Configuration ולכן לא תומך בשיטות של ...datastore_rpc.Configuration.

בנוסף, google.appengine.datastore.datastore_query.Order הוחלף ב-google.cloud.ndb.query.PropertyOrder. בדומה ל-Order, המחלקה PropertyOrder מאפשרת לציין את סדר המיון בכמה שאילתות. ה-constructor‏ PropertyOrder זהה ל-constructor של Order. רק השם של הכיתה השתנה.

הסרנו API	החלפה
מאת `google.appengine.datastore.datastore_rpc.Configuration`: `deadline(value)` `on_completion(value)` `read_policy(value)` `force_writes(value)` `max_entity_groups_per_rpc(value)` `max_allocate_ids_keys(value)` `max_rpc_bytes(value)` `max_get_keys(value)` `max_put_entities(value)` `max_delete_keys(value)` תיאור של השיטות האלה מופיע בקוד המקור.	ללא
`google.appengine.ext.ndb.Order` לדוגמה: `order=Order(-Account.birthday, Account.name)`	`google.cloud.ndb.PropertyOrder` לדוגמה: `google.cloud.ndb.PropertyOrder(-Account.birthday, Account.name)`

Utils

המודול ndb.utils (google.appengine.ext.ndb.utils) לא זמין יותר. רוב השיטות במודול הזה היו פנימיות ל-App Engine NDB, חלק מהשיטות בוטלו בגלל הבדלים בהטמעה ב-NDB החדש, ושיטות אחרות הפכו ללא רלוונטיות בגלל תכונות חדשות של Python 3.

לדוגמה, מעצב המיקום במודול utils הישן הצהיר שרק n הארגומנטים הראשונים של פונקציה או שיטה יכולים להיות מיקומיים. עם זאת, ב-Python 3 אפשר לעשות את זה באמצעות ארגומנטים של מילות מפתח בלבד. מה שהיה כתוב בעבר:

@utils.positional(2)
def function1(arg1, arg2, arg3=None, arg4=None)
  pass

אפשר לכתוב את זה כך ב-Python 3:

def function1(arg1, arg2, *, arg3=None, arg4=None)
  pass

מרחבי שמות

מרחבי שמות מאפשרים לאפליקציה עם ריבוי דיירים להשתמש במאגרי נתונים נפרדים לכל דייר, ועדיין להשתמש באותו מסד נתונים במצב Datastore. כלומר, כל דייר מאחסן נתונים במרחב שמות משלו.

במקום להשתמש ב-google.appengine.api.namespacemanager שספציפי ל-App Engine, מציינים מרחב שמות שמוגדר כברירת מחדל כשיוצרים לקוח Cloud NDB, ואז משתמשים במרחב השמות שמוגדר כברירת מחדל על ידי קריאה לשיטות Cloud NDB בהקשר של זמן הריצה של הלקוח. התבנית הזו זהה לתבנית של ממשקי API אחרים Google Cloud שתומכים במרחבי שמות.

הסרנו API	החלפה
`google.appengine.api.namespace_manager.namespace_manager.set_namespace(str)` וגם `google.appengine.api.namespacemanager.getnamespace()`	client=google.cloud.ndb.Client(namespace="my namespace") with client.context() as context: key = ndb.Key("SomeKind", "SomeId") או key-non-default-namespace=ndb.Key("SomeKind," "AnotherId", namespace="non-default-nspace")
כל שאר השיטות של `google.appengine.api.namespacemanager`	ללא

Tasklets

מעכשיו אפשר להשתמש ב-Tasklets בהצהרת return רגילה כדי להחזיר תוצאה במקום להפעיל חריגה של Return. לדוגמה:

ספריית NDB של App Engine	ספריית Cloud NDB
@ndb.tasklet def get_cart(): cart = yield CartItem.query().fetch_async() raise Return(cart)	@ndb.tasklet def get_cart(): cart = yield CartItem.query().fetch_async() return cart

שימו לב: עדיין אפשר להחזיר תוצאות ב-Cloud NDB על ידי העלאת חריגה (exception), אבל לא מומלץ לעשות זאת.Return

בנוסף, השיטות וסוגי המשנה הבאים של Tasklets כבר לא זמינים, בעיקר בגלל שינויים באופן שבו נוצר ומשמש הקשר של NDB בספריית Cloud NDB.

הסרנו API	החלפה
מאת `google.appengine.api.ext.ndb.tasklets`: `add_flow_exception` `make_context` `make_default_context` `set_context`	ללא
מאת `google.appengine.api.ext.ndb.tasklets`: `QueueFuture` `ReducedFuture` `SerialQueueFuture`	ללא

חריגים

מודול google.cloud.ndb.exceptions בספריית Cloud NDB מכיל הרבה מהחריגים שקיימים בספריית App Engine NDB, אבל לא כל החריגים הישנים זמינים בספרייה החדשה. בטבלה הבאה מפורטות החריגות שכבר לא זמינות:

הסרנו API	החלפה
from `google.appengine.api.datastore_errors`: `BadKeyError` `BadPropertyError` `CommittedButStillApplying` `EntityNotFoundError` `InternalError` `NeedIndexError` `QueryNotFoundError` `ReferencePropertyResolveError` `Timeout` `TransactionFailedError` `TransactionNotFoundError`	`google.cloud.ndb.exceptions`

הפעלת שמירת נתונים במטמון

‫Cloud NDB יכול לשמור נתונים במטמון בחנות נתונים בזיכרון של Redis שמנוהלת על ידי Memorystore,‏ Redis Labs או מערכות אחרות. במדריך הזה מוסבר איך להשתמש ב-Memorystore for Redis כדי לשמור נתונים במטמון:

הגדרת חיבור לרשת (VPC) מאפליקציית serverless
הגדרת Memorystore for Redis
מוסיפים את כתובת ה-URL של החיבור ל-Redis לאפליקציה.
יצירת אובייקט RedisCache.

הגדרת חיבור לרשת (VPC) מאפליקציית serverless

האפליקציה יכולה לתקשר עם Memorystore רק דרך מחבר של חיבור לרשת (VPC) מאפליקציית serverless. כדי להגדיר מחבר של חיבור לרשת (VPC) מאפליקציית serverless:

הגדרה של Memorystore for Redis

כדי להגדיר את Memorystore for Redis:

יצירת מכונת Redis ב-Memorystore. כשיוצרים את המופע:
- בקטע Region, בוחרים באותו אזור שבו נמצאת אפליקציית App Engine.
- בקטע רשת מורשית, בוחרים את אותה רשת שבה משתמש מחבר הגישה לרשת (VPC) מאפליקציית serverless.
חשוב לשים לב לכתובת ה-IP ולמספר היציאה של מופע Redis שיוצרים. תשתמשו במידע הזה כשמפעילים שמירת נתונים במטמון ב-Cloud NDB.

חשוב להשתמש בפקודה gcloud beta כדי לפרוס את עדכוני האפליקציה. רק הפקודה beta יכולה לעדכן את האפליקציה שלכם כדי להשתמש במחבר VPC.

הוספת כתובת ה-URL של חיבור Redis

כדי להתחבר למטמון Redis, מוסיפים את משתנה הסביבה REDIS_CACHE_URL לקובץ app.yaml של האפליקציה. הערך של REDIS_CACHE_URL מופיע באופן הבא:

redis://IP address for your instance:port

לדוגמה, אפשר להוסיף את השורות הבאות לקובץ app.yaml של האפליקציה:

     env_variables:
      REDIS_CACHE_URL: redis://10.0.0.3:6379

יצירה של אובייקט מטמון Redis ושימוש בו

אם הגדרתם את REDIS_CACHE_URL כמשתנה סביבה, אתם יכולים ליצור אובייקט RedisCache בשורה אחת של קוד, ואז להשתמש במטמון על ידי העברתו אל Client.context() כשאתם מגדירים את הקשר של זמן הריצה:

client = ndb.Client()
global_cache = ndb.RedisCache.from_environment()

with client.context(global_cache=global_cache):
  books = Book.query()
  for book in books:
      print(book.to_dict())

אם לא מגדירים את REDIS_CACHE_URL כמשתנה סביבה, צריך ליצור אובייקט של לקוח Redis ולהעביר אותו לבונה ndb.RedisCache(). לדוגמה:

global_cache = ndb.RedisCache(redis.StrictRedis(host=IP-address, port=redis_port))

שימו לב שלא צריך להצהיר על תלות בספריית הלקוח של Redis, כי ספריית Cloud NDB כבר תלויה בספריית הלקוח של Redis.

בדוגמה הבאה מוצגת דרך ליצירת לקוח Redis. אפשר לעיין באפליקציה לדוגמה של Memorystore.

בדיקת העדכונים

כדי להגדיר מסד נתונים לבדיקה ולהריץ את האפליקציה באופן מקומי לפני הפריסה ב-App Engine:

מריצים את האמולטור המקומי של מצב Datastore כדי לאחסן ולאחזר נתונים.

חשוב לפעול לפי ההוראות להגדרת משתני סביבה כדי שהאפליקציה תתחבר לאמולטור במקום לסביבת הייצור של מצב Datastore.

אפשר גם לייבא נתונים לאמולטור אם רוצים להתחיל את הבדיקה עם נתונים שכבר נטענו מראש במסד הנתונים.
משתמשים בשרת הפיתוח המקומי כדי להריץ את האפליקציה.

כדי לוודא שמשתנה הסביבה GOOGLE_CLOUD_PROJECT מוגדר בצורה נכונה במהלך פיתוח מקומי, מפעילים את dev_appserver באמצעות הפרמטר הבא:
```
--application=PROJECT_ID
```
מחליפים את PROJECT_ID במזהה הפרויקט ב- Google Cloud . אפשר להריץ את הפקודה gcloud config list project כדי למצוא את מזהה הפרויקט, או לעיין בדף הפרויקט במסוף Google Cloud .

פריסת האפליקציה

אחרי שהאפליקציה פועלת בשרת הפיתוח המקומי ללא שגיאות:

בדיקת האפליקציה ב-App Engine.
אם האפליקציה פועלת ללא שגיאות, משתמשים בפיצול תנועה כדי להגדיל בהדרגה את התנועה לאפליקציה המעודכנת. חשוב לעקוב אחרי האפליקציה כדי לוודא שאין בעיות במסד הנתונים לפני שמפנים אליה עוד תנועה.

המאמרים הבאים

למדריך מעשי, אפשר לעיין ב-codelab בנושא מעבר מ-App Engine ndb ל-Cloud NDB.
פרטים נוספים מופיעים במאמרי העזרה בנושא Cloud NDB.