ישויות, מאפיינים ומפתחות

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

מאגר הנתונים תומך במגוון סוגי נתונים לערכי מאפיינים. לדוגמה:

  • מספרים שלמים
  • מספרים בשיטת נקודה צפה
  • מחרוזות
  • תאריכים
  • נתונים בינאריים

רשימה מלאה של הסוגים זמינה במאמר מאפיינים וסוגי ערכים.

לכל ישות ב-Datastore יש מפתח שמזהה אותה באופן ייחודי. המפתח מורכב מהרכיבים הבאים:

  • מרחב השמות של הישות, שמאפשר ריבוי דיירים
  • סיווג הישות, שמסווג אותה לצורך שאילתות ב-Datastore
  • מזהה של הישות הספציפית, שיכול להיות אחד מהבאים:
    • מחרוזת שם המפתח
    • מזהה מספרי שהוא מספר שלם
  • ancestor path אופציונלי שמציין את מיקום הישות בהיררכיית Datastore

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

‫Java App Engine SDK כולל API פשוט, שמופיע בחבילה com.google.appengine.api.datastore, שתומך בתכונות של Datastore באופן ישיר. כל הדוגמאות במסמך הזה מבוססות על API ברמה נמוכה. אתם יכולים להשתמש בו ישירות באפליקציה שלכם או כבסיס ליצירת שכבת ניהול נתונים משלכם.

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

סוגים ומזהים

כל ישות ב-Datastore היא מסוג מסוים,שמסווג את הישות לצורך שאילתות: לדוגמה, באפליקציה של משאבי אנוש יכול להיות שכל עובד בחברה מיוצג על ידי ישות מסוג Employee. ב-Java Datastore API, מציינים את הסוג של ישות כשיוצרים אותה, כארגומנט לבונה Entity().‫ כל השמות של סוגים שמתחילים בשני קווים תחתונים (__) שמורים ואין אפשרות להשתמש בהם.

בדוגמה הבאה נוצרת ישות מסוג Employee, מאכלסים את ערכי המאפיינים שלה ושומרים אותה ב-Datastore:

Entity employee = new Entity("Employee", "asalieri");
employee.setProperty("firstName", "Antonio");
employee.setProperty("lastName", "Salieri");
employee.setProperty("hireDate", new Date());
employee.setProperty("attendedHrTraining", true);

DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();
datastore.put(employee);

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

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

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

Entity employee = new Entity("Employee", "asalieri");

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

Entity employee = new Entity("Employee");

הקצאת מזהים

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

  • המדיניות default יוצרת רצף אקראי של מזהים לא בשימוש, שמתפלגים באופן אחיד בקירוב. כל מזהה יכול להיות באורך של עד 16 ספרות עשרוניות.
  • המדיניות legacy יוצרת רצף של מזהים קטנים של מספרים שלמים לא עוקבים.

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