יצירה, אחזור, עדכון ומחיקה של ישויות

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

מידע נוסף על ישויות מופיע במאמרים בנושא נתיבי אב וטרנזקציות.

יצירת ישויות והגדרת מאפיינים

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

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

sandy = Account(
    username='Sandy', userid=123, email='sandy@example.com')

הקוד הזה יוצר אובייקט בזיכרון הראשי של התוכנית. עם זאת, חשוב לזכור שהישות נעלמת כשהתהליך מסתיים, ולכן צריך גם לשמור את הישות ב-Datastore באמצעות קריאה ל-put(), באופן הבא:

sandy_key = sandy.put()

שימו לב שהפעולה הזו מחזירה מפתח שאפשר להשתמש בו כדי לאחזר את הישות מ-Datastore בהמשך.

מגדירים מאפיינים באמצעות אחת מהאפשרויות הבאות:

  • מציינים את המאפיינים של הישות בבנאי באמצעות ארגומנטים של מילות מפתח: 
    sandy = Account(
    username='Sandy', userid=123, email='sandy@example.com')
  • הגדרת מאפיינים באופן ידני אחרי יצירת הישות: 
    sandy = Account()
sandy.username = 'Sandy'
sandy.userid = 123
sandy.email = 'sandy@example.com'
  • אפשר להשתמש בשיטת הנוחות populate() כדי להגדיר כמה מאפיינים בפעולה אחת: 
    sandy = Account()
sandy.populate(
    username='Sandy',
    userid=123,
    email='sandy@gmail.com')

בכל דרך שתבחרו להגדיר את המאפיינים של הישות, סוגי המאפיינים (במקרה הזה, StringProperty ו-IntegerProperty) יאכפו בדיקת סוגים.

לדוגמה:

bad = Account(
    username='Sandy', userid='not integer')  # raises an exception
... 
sandy.username = 42  # raises an exception

אחזור ישויות ממפתחות

אם יש לכם מפתח של ישות, אתם יכולים לאחזר את הישות מ-Datastore:

sandy = sandy_key.get()

השיטות Key kind() ו-id() מאחזרות את סוג הישות ואת המזהה שלה מהמפתח:

kind_string = sandy_key.kind()  # returns 'Account'
ident = sandy_key.id()  # returns '2'

אפשר גם להשתמש במפתח של ישות כדי לקבל מחרוזת מקודדת שמתאימה להטמעה בכתובת URL:

url_string = sandy_key.urlsafe()

התוצאה תהיה כמו agVoZWxsb3IPCxIHQWNjb3VudBiZiwIM, ואפשר יהיה להשתמש בה בהמשך כדי לשחזר את המפתח ולאחזר את הישות המקורית:

sandy_key = ndb.Key(urlsafe=url_string)
sandy = sandy_key.get()

שימו לב שהמחרוזת שמתאימה לכתובת URL נראית מוצפנת, אבל היא לא מוצפנת! אפשר לפענח אותו בקלות כדי לשחזר את סוג הישות והמזהה המקוריים:

key = Key(urlsafe=url_string)
kind_string = key.kind()
ident = key.id()

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

עדכון ישויות

כדי לעדכן ישות קיימת, מאחזרים אותה מ-Datastore, משנים את המאפיינים שלה ומאחסנים אותה שוב:

sandy = key.get()
sandy.email = 'sandy@example.co.uk'
sandy.put()

במקרה הזה אפשר להתעלם מהערך שמוחזר על ידי put(), כי מפתח של ישות לא משתנה כשמעדכנים אותה.

מחיקת ישויות

כשאין יותר צורך בישות, אפשר להסיר אותה מ-Datastore באמצעות השיטה delete() של המפתח:

sandy.key.delete()

שימו לב: זו פעולה על המפתח, ולא על הישות עצמה. היא תמיד מחזירה None.

מחיקת ישויות בכמות גדולה

אם אתם צריכים למחוק מספר גדול של ישויות, מומלץ להשתמש ב-Dataflow כדי למחוק ישויות בכמות גדולה.

שימוש בפעולות גורפות

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

בדוגמה הבאה אפשר לראות איך עושים את זה:

list_of_keys = ndb.put_multi(list_of_entities)
list_of_entities = ndb.get_multi(list_of_keys)
ndb.delete_multi(list_of_keys)

בדוגמת הקוד שלמעלה, מעבירים רשימה של אובייקטים של מפתחות אל ndb.get_multi כדי לאחזר כמה ישויות באצווה; ndb.get_multi מחזירה רשימה של אובייקטים של ישויות, עם ערכים של None למפתחות שאין להם ישות תואמת ב-Datastore. אחזור הישויות בדרך הזו מוביל לפחות קריאות ל-Datastore עבור כל האצווה (מספר הקריאות לכל אצווה תלוי בהגדרות של גודל האצווה).