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

או בשיטות

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