פונקציות NDB

פונקציות

‫ndb.add_flow_exception(exc)

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

ארגומנטים

exc

מחלקה של חריגה שלא אמורה להירשם ביומן.

כברירת מחדל, היוצאים מן הכלל הבאים לא מתועדים ביומן:

‫webob.exc.HTTPException (and its subclasses)
ndb.Rollback

‪ndb.delete_multi(keys, **ctx_options)

מחיקת ישויות שזוהו על ידי רצף המפתחות שהועבר.

ארגומנטים

keys: רצף של מקשים
**ctx_options: אפשרויות הקשר

ndb.delete_multi_async(keys, **ctx_options)

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

ארגומנטים

keys: רצף של מקשים
**ctx_options: אפשרויות הקשר

‪ndb.get_multi(keys, **ctx_options)

Fetches entities identified by the passed sequence of keys.

ארגומנטים

keys: רצף של מקשים
**ctx_options: אפשרויות הקשר

ndb.get_multi_async(keys, **ctx_options)

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

ארגומנטים

keys: רצף של מקשים
**ctx_options: אפשרויות הקשר

ndb.in_transaction()

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

@ndb.non_transactional @ndb.non_transactional(allow_existing=True)

Decorator כדי לוודא שפונקציה פועלת מחוץ לעסקה.

ארגומנטים:

allow_existing: If True (ברירת המחדל) ואם הפונקציה המעוטרת מופעלת על ידי קוד בעסקה, הפונקציה פועלת באופן עצמאי ללא קשר לעסקה. אם False ואם הפונקציה המקושטת מופעלת על ידי קוד בטרנזקציה, המערכת מעלה חריגה.

‪ndb.put_multi(entities, **ctx_options)

מאחסן רצף של מופעים של Model.

ארגומנטים

entities: רצף של מופעים של Model
**ctx_options: אפשרויות הקשר

ndb.put_multi_async(entities, **ctx_options)

מאחסנת באופן אסינכרוני רצף של מופעים של Model.

ארגומנטים

entities: רצף של מופעים של Model
**ctx_options: אפשרויות הקשר

‪ndb.transaction(callback, **ctx_options)

הפעלת קריאה חוזרת בעסקה.

ארגומנטים

callback: פונקציה או tasklet להפעלה
**ctx_options: אפשרויות של עסקאות

ndb.transaction_async(callback, **ctx_options)

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

ארגומנטים

callback: פונקציה או tasklet להפעלה
**ctx_options: אפשרויות של עסקאות

הפונקציה מחזירה Future. הערך שמוחזר מה-Future הוא הערך שמוחזר מcallback, או שמוחזרת שגיאה מcallback או TransactionFailedError אם העסקה נכשלת.

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

def my_callback(key, inc):
  ...

transaction(lambda: my_callback(Key(...), 1))

@ndb.transactional
@ndb.transactional(**ctx_options)

Decorator שגורם להרצה אוטומטית של פונקציה בטרנזקציה.

ארגומנטים:

ל-decorator הזה יכולות להיות אפשרויות של טרנזקציות.

אפשרויות הקשר, אפשרויות עסקה

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

הנה כמה דוגמאות לשימוש באפשרויות ההקשר. כדי להגדיר את תאריך היעד של ה-RPC לשנייה אחת כשקוראים ישות, אפשר להשתמש בפקודה:

key.get(deadline=1)

כדי להגדיר את זמן קצוב לתפוגה של Memcache ל-30 שניות כשכותבים ישות, אפשר להשתמש בפקודה:

ent.put(ndb_memcache_timeout=30)

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

key.delete(use_datastore=False)

ארגומנטי מילות המפתח המיוחדים options ו-config (שמשמעותם זהה מסיבות היסטוריות) מאפשרים לציין כמה אפשרויות כאובייקט Configuration. יכול להיות שזה אובייקט ndb.ContextOptions או (במקרה של פונקציות טרנזקציונליות ודקורטור) אובייקט ndb.TransactionOptions. לדוגמה, key.get(options=ndb.ContextOptions(use_cache=True)) שווה ל- key.get(use_cache=True). אפשר לבטל את האפשרויות שמוגדרות באובייקט אפשרויות כזה באמצעות פרמטרים של מילות מפתח.

אלה אפשרויות ההקשר שזמינות:

אפשרות	סוג	תיאור
`deadline`	`float`	הגבלת משך הקריאה למאגר הנתונים, שצוינה כמספר שניות. (כברירת מחדל, השיחה מופרעת רק בגלל המועד האחרון של בקשת הטיפול).
`read_policy`	`ndb.EVENTUAL_CONSISTENCY`	מגדירים את הערך הזה ל-`ndb.EVENTUAL_CONSISTENCY` אם רוצים לקבל תוצאות מהר יותר, גם אם יכול להיות שהן לא עדכניות, במקום לחכות עד שמאגר הנתונים יסיים להחיל שינויים על כל התוצאות שמוחזרות.
`force_writes`	`bool`	המדיניות הזו קובעת אם בקשת כתיבה צריכה להצליח גם אם האפליקציה היא לקריאה בלבד. (ההגדרה הזו רלוונטית רק לתקופות של קריאה בלבד שהמשתמשים יכולים לשלוט בהן).
`use_cache`	`bool`	המדיניות הזו קובעת אם לשמור ישויות במטמון בתוך התהליך. היא מבטלת את מדיניות המטמון בתוך התהליך עבור הפעולה הזו.
`use_memcache`	`bool`	הגדרה שקובעת אם יש לאחסן ישויות ב-memcache. ההגדרה הזו מבטלת את מדיניות ה-memcache עבור הפעולה הזו.
`use_datastore`	`bool`	ההגדרה קובעת אם יש לאחסן ישויות ב-Datastore. היא מבטלת את מדיניות Datastore עבור הפעולה הזו.
`memcache_timeout`	`int`	משך החיים המקסימלי של ישויות ב-memcache. הערך הזה מבטל את מדיניות הזמן הקצוב לתפוגה של memcache עבור הפעולה הזו.
`max_memcache_items`	`int`	גודל הקבוצה המקסימלי לתכונת יצירת הקבוצות האוטומטית של שיטות ה-memcache של Context. לדוגמה, עם גודל ברירת המחדל של `max_memcache_items` (100), עד 100 פעולות הגדרה של memcache ישולבו לפעולה אחת של `set_multi`.
לגבי חלק מהפונקציות שקשורות לעסקאות, זמינות אפשרויות העסקה הבאות (בנוסף לאפשרויות ההקשר שמועברות בירושה שצוינו למעלה):
אפשרות	סוג	תיאור
`xg`	`bool`	אפשר לבצע עסקאות בין קבוצות (`XG`). `False` כברירת מחדל.
`propagation`	`int`	‫NDB מספק תמיכה מוגבלת בעסקאות בתוך עסקאות, שנקראות 'עסקאות מקוננות'. פרמטר ההפצה קובע מה קורה אם הקוד מנסה להתחיל טרנזקציה מקוננת. מדיניות ההפצה של `@ndb.transactional` מוגדרת כברירת מחדל ל-`ALLOWED`. מדיניות ההפצה של `ndb.transaction()` מוגדרת כברירת מחדל ל-`NESTED`. ‫NDB לא תומך במדיניות `NESTED`, ולכן הקוד שלכם יחזיר חריגה מסוג `BadRequestError`. במקרה הזה, NDB מגדיר ערך ברירת מחדל לא נתמך, כדי שהמתכנתים יהיו מודעים באופן מפורש למגבלות של טרנזקציות מקוננות. הפרמטר propagation יכול לקבל אחד מהערכים הבאים: `ndb.TransactionOptions.NESTED` מדיניות ההפצה `NESTED` תבצע את כל השינויים בעסקאות החיצוניות והפנימיות יחד, כשהמדיניות החיצונית תתחייב. עם זאת, אם מתרחשת חריגה בעסקה הפנימית, כל השינויים שמתבצעים בה נמחקים, אבל העסקה החיצונית יכולה להתאושש ולהמשיך. המדיניות `NESTED` לא נתמכת. אם משתמשים במדיניות הזו, הקוד יחזיר חריגה מסוג `BadRequestError`. `ndb.TransactionOptions.MANDATORY` תמיד מעבירים טרנזקציה קיימת; מוציאים חריגה אם אין טרנזקציה קיימת. אם פונקציה שמשתמשת במדיניות הזו יוצרת חריגה, כנראה שלא בטוח לטפל בחריגה ולבצע את העסקה החיצונית. יכול להיות שהפונקציה השאירה את העסקה החיצונית במצב לא תקין. `ndb.TransactionOptions.ALLOWED` אם יש עסקה קיימת, מעבירים אותה. אם פונקציה שמשתמשת במדיניות הזו יוצרת חריגה, כנראה שלא בטוח לטפל בחריגה ולבצע את העסקה החיצונית. יכול להיות שהפונקציה השאירה את העסקה החיצונית במצב לא תקין. `ndb.TransactionOptions.INDEPENDENT` תמיד להשתמש בעסקה חדשה, ולהשהות את כל העסקאות הקיימות. פונקציה שמשתמשת במדיניות הזו לא צריכה להחזיר ישויות שנקראו בעסקה החדשה, כי הישויות לא עקביות מבחינת העסקה עם העסקה של המתקשר.
`retries`	`int`	כמה פעמים לנסות שוב באופן אוטומטי במקרה של כשלים בעסקאות. הערך אפס מציין ניסיון אחד ללא ניסיון חוזר.

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

פעולות עם אפשרויות שונות מקובצות יחד כשמופעלת אפשרות של אצווה אוטומטית. לדוגמה, אם משתמשים ב-put_async() כדי לכתוב כמה ישויות עם deadline = 5 וכמה בלי לציין תאריך יעד, וכולן עומדות בדרישות לאיגום אוטומטי, המאגד האוטומטי יבצע שתי קריאות RPC נפרדות – אחת לקבוצת הישויות עם deadline = 5 ואחת לקבוצה השנייה – גם אם תאריך היעד של ברירת המחדל של ה-RPC הוא גם 5. זה קורה גם אם האפשרות שצוינה לא רלוונטית לפעולת ה-RPC (לדוגמה, ndb_should_cache).

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