יצירה של מפתחות ישויות ושימוש בהם

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

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

ציון שם מפתח משלכם

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

account = Account(
    username='Sandy', userid=1234, email='sandy@example.com',
    id='sandy@example.com')

return account.key.id()  # returns 'sandy@example.com'

אפשר גם להגדיר את שם המפתח ישירות:

account.key = ndb.Key('Account', 'sandy@example.com')

# You can also use the model class object itself, rather than its name,
# to specify the entity's kind:
account.key = ndb.Key(Account, 'sandy@example.com')

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

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

# note: no id kwarg
account = Account(username='Sandy', userid=1234, email='sandy@example.com')
account.put()
# account.key will now have a key of the form: ndb.Key(Account, 71321839)
# where the value 71321839 was generated by Datastore for us.

שימוש בנתיב של ישות האב במפתח

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

המפתח המלא שמזהה ישות מורכב מרצף של זוגות מזהה-סיווג שמציינים את נתיב ישות האב שלה ומסתיימים בזוגות של הישות עצמה. שיטת הבנאי של המחלקה Key מקבלת רצף כזה של סוגים ומזהים ומחזירה אובייקט שמייצג את המפתח של הישות המתאימה.

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

class Revision(ndb.Model):
    message_text = ndb.StringProperty()
... 
ndb.Key('Account', 'sandy@example.com', 'Message', 123, 'Revision', '1')
ndb.Key('Account', 'sandy@example.com', 'Message', 123, 'Revision', '2')
ndb.Key('Account', 'larry@example.com', 'Message', 456, 'Revision', '1')
ndb.Key('Account', 'larry@example.com', 'Message', 789, 'Revision', '2')

בדוגמה, ('Account', 'sandy@example.com'),‏ ('Message', 123) ו-('Revision', '1') הם דוגמאות לזוגות של סוג ומזהה.

שימו לב ש-Message הוא לא מחלקה של מודל, אלא משמש רק לקיבוץ של עדכונים, ולא לאחסון נתונים.

כמו שרואים בקוד לדוגמה, סוג הישות מצוין על ידי הזוג האחרון של שם הסוג ברשימה: ndb.Key('Revision', '1').

שימוש בפרמטרים עם שם

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

ndb.Key('Account', 'sandy@example.com', 'Message', 123, 'Revision', '1')

ndb.Key('Revision', '1', parent=ndb.Key(
    'Account', 'sandy@example.com', 'Message', 123))

ndb.Key('Revision', '1', parent=ndb.Key(
    'Message', 123, parent=ndb.Key('Account', 'sandy@example.com')))

ציון ישות שורש

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

sandy_key = ndb.Key(Account, 'sandy@example.com')

ציון ישות עם ישויות אב

כדי להוסיף הודעה חדשה עם מפתחות הורה

account_key = ndb.Key(Account, 'sandy@example.com')

# Ask Datastore to allocate an ID.
new_id = ndb.Model.allocate_ids(size=1, parent=account_key)[0]

# Datastore returns us an integer ID that we can use to create the message
# key
message_key = ndb.Key('Message', new_id, parent=account_key)

# Now we can put the message into Datastore
initial_revision = Revision(
    message_text='Hello', id='1', parent=message_key)
initial_revision.put()

למפתחות שנוצרו עם הורה, השיטה parent() מחזירה מפתח שמייצג את ישות האם:

message_key = initial_revision.key.parent()

שימוש במזהי מפתחות נומריים

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

כדי להזמין טווח של מזהים, משתמשים בשיטת המחלקה allocate_ids() של מחלקת המודל:

  • להקצות מספר מסוים של מזהים
  • להקצות את כל המזהים עד לערך מקסימלי נתון.

הקצאת מזהים

כדי להקצות 100 מזהים למחלקה נתונה של מודל MyModel:

first, last = MyModel.allocate_ids(100)

כדי להקצות 100 מזהים לישויות עם מפתח אב p:

first, last = MyModel.allocate_ids(100, parent=p)

הערכים שמוחזרים, first ו-last, הם המזהים הראשונים והאחרונים (כולל) שהוקצו. אפשר להשתמש בהם כדי ליצור מפתחות באופן הבא:

keys = [ndb.Key(MyModel, id) for id in range(first, last+1)]

מובטח שהמפתחות האלה לא הוחזרו בעבר על ידי מחולל המזהים הפנימי של מאגר הנתונים, וגם לא יוחזרו על ידי קריאות עתידיות למחולל המזהים הפנימי. עם זאת, השיטה allocate_ids() לא בודקת אם המזהים שמוחזרים קיימים במאגר הנתונים, אלא רק מבצעת אינטראקציה עם מחולל המזהים.

כדי להקצות את כל המזהים עד ערך מקסימלי נתון:

first, last = MyModel.allocate_ids(max=N)

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