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

כל ישות מזוהה באמצעות מפתח שהוא ייחודי במופע 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.

שימוש בנתיב של רכיב ה-ancestor במפתח

רצף הישויות שמתחיל בישות שורש וממשיך מישות אב לישות צאצא, עד לישות נתונה, מהווה את נתיב האב של הישות הזו. ישות, ישות האב שלה, ישות האב של ישות האב וכן הלאה באופן רקורסיבי, הן האבות הקדמונים של הישות. הישויות ב-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 הוא המזהה האחרון שהוקצה.