העברה מ-App Engine Datastore ל-Firestore במצב Datastore

במדריך הזה מוסבר איך לבצע מיגרציה מ-App Engine Datastore אל Firestore במצב Datastore (שנקרא גם Datastore).

‫Firestore במצב Datastore דומה ל-App Engine Datastore, כי שניהם מתייחסים לאותו שירות Datastore בסיסי. ל-App Engine Datastore יש גישה רק דרך השירותים המצורפים מדור קודם של App Engine, אבל Firestore במצב Datastore הוא מוצר עצמאי Google Cloud שיש לו גישה דרך ספריות הלקוח של Cloud.

‫Firestore במצב Datastore מציע גם רמת שירות חינמית, ומאפשר לכם לנהל מסד נתונים מסוג NoSQL לאחסון מסמכים עם יכולת הרחבה גבוהה. בנוסף, הוא מעניק לכם גמישות לעבור בעתיד ל-Cloud Run או לפלטפורמה אחרת לאירוח אפליקציות Google Cloud .

לפני שמתחילים

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

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

    ‫Firestore במצב Datastore מציע שימוש בחינם עם מגבלות יומיות, ואחסון, קריאה וכתיבה ללא הגבלה לחשבונות בתשלום. בזמן שהאפליקציות של App Engine מושבתות, הן לא מקבלות תנועה ולכן לא יחויבו עליה. עם זאת, יכול להיות שיהיה חיוב על השימוש ב-Datastore אם הוא חורג ממכסת השימוש בחינם.

  3. מפעילים את ממשקי ה-API הבאים בפרויקט שמכיל את האפליקציה:

    • ‫Artifact Registry API לאחסון ולניהול של ארטיפקטים של בנייה
    • ‫Cloud Build API כדי לפתח, לבדוק ולפרוס את האפליקציה באופן רציף.

    • ‫Cloud Datastore API להעברה מ-Datastore בחבילה של App Engine ל-Firestore במצב Datastore.

      הפעלת ממשקי API

  4. יש לכם אפליקציית App Engine קיימת שמופעלת ב-Java 8 או 11 ומחוברת לשירות App Engine Datastore.

סקירה כללית על התהליך

באופן כללי, תהליך המעבר אל Firestore במצב Datastore מ-App Engine Datastore מורכב מהשלבים הבאים:

  1. עדכון קובצי תצורה
  2. עדכון אפליקציית Java
    1. עדכון הצהרות הייבוא
    2. שינוי אופן הגישה של האפליקציה לשירות Datastore
    3. קבלת מפתח שנוצר על ידי Datastore
    4. שינוי של יצירת ישות
  3. אישור העסקה
  4. תוצאות השאילתה

עדכון קובצי תצורה

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

מעדכנים את קובץ pom.xml של אפליקציית Java הבסיסית:

  1. מסירים את הייבוא של App Engine SDK appengine-api-1.0-sdk, כמו הייבוא הבא:

    <dependency>
  <groupId>com.google.appengine</groupId>
  <artifactId>appengine-api-1.0-sdk</artifactId>
  <version>2.0.4</version>
</dependency>

  2. מוסיפים את לקוח Datastore, כמו בדוגמה הבאה:

    <dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-datastore</artifactId>
  <!-- Use latest version -->
  <version>2.2.9</version>
</dependency>

עדכון אפליקציית Java

עדכון הצהרות ייבוא

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

  1. מסירים את הצהרות הייבוא הבאות של App Engine עבור App Engine Datastore com.google.appengine.api.datastore.*:

      import com.google.appengine.api.datastore.DatastoreService;
  import com.google.appengine.api.datastore.DatastoreServiceFactory;
  import com.google.appengine.api.datastore.Entity;
  import com.google.appengine.api.datastore.FetchOptions;
  import com.google.appengine.api.datastore.Query;

  2. מוסיפים את הייבוא הבא של Firestore במצב Datastore:‏ com.google.cloud.datastore.*:

      import com.google.cloud.Timestamp;
  import com.google.cloud.datastore.Datastore;
  import com.google.cloud.datastore.DatastoreOptions;
  import com.google.cloud.datastore.Entity;
  import com.google.cloud.datastore.Key;
  import com.google.cloud.datastore.FullEntity;
  import com.google.cloud.datastore.KeyFactory;
  import com.google.cloud.datastore.Query;
  import com.google.cloud.datastore.QueryResults;
  import com.google.cloud.datastore.StructuredQuery;

שינוי אופן הגישה של האפליקציה לשירות Datastore

‫Firestore במצב Datastore משתמש במחלקה Datastore במקום ב-DatastoreService. כדי לשנות את אופן הגישה של האפליקציה לשירות Datastore:

  1. מחפשים את השורות שבהן נעשה שימוש בשיטה DatastoreServiceFactory.getDatastoreService() כמו בדוגמה הבאה:

    // Initialize a client
DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();

  2. מחליפים את DatastoreServiceFactory.getDatastoreService() בשיטה DatastoreOptions.getDefaultInstance().getService(), כמו בדוגמה הבאה:

    // Initialize a client
Datastore datastore = DatastoreOptions.getDefaultInstance().getService();

קבלת מפתח שנוצר על ידי Datastore

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

  1. יצירת newKeyFactory.

  2. קוראים ל-method‏ setKind() כדי לקבוע את kind של הישות שמשמשת לסיווג שאילתות.

  3. מוסיפים את method‏ newKey() כדי ליצור מפתח Datastore:

    //Prepare a new entity
String kind = "visit";
Key key = datastore.allocateId(datastore.newKeyFactory().setKind(kind).newKey());

שינוי של יצירת ישויות

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

  1. משתמשים ב-Entity.newBuilder ומעבירים את המפתח שנוצר על ידי Datastore.

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

    Entity visit = new Entity(kind);

    מחליפים את הקריאה לבונה Entity בקריאה לבונה Entity.newBuilder, כמו בדוגמה הבאה:

    Entity visit = Entity.newBuilder(key);

  2. משתמשים בשיטה set כדי להגדיר מאפיינים של ישויות.

    הפרמטר הראשון הוא הנכס המיועד, והפרמטר השני הוא הערך. במקרה של המאפיין timestamp, הערך הוא Timestamp במקום Instant.toString().

    מחפשים את השורות שבהן נעשה שימוש בשיטה setProperty, כמו בדוגמה הבאה:

    visit.setProperty("user_ip", userIp);
visit.setProperty("timestamp", Instant.now().toString());

    מחליפים את השיטה setProperty בשיטה set, כמו בדוגמה הבאה:

    Entity visit = Entity.newBuilder(key).set("user_ip", userIp).set("timestamp", Timestamp.now()).build();

ביצוע העסקה

ספריית הלקוח של Firestore במצב Datastore משתמשת בשיטה add() כדי לבצע טרנזקציה. כדי לאשר את העסקה:

  1. מחפשים שורות שמשתמשות בשיטה put(), כמו השורה הבאה:

    // Save the entity
datastore.put(visit);

  2. מחליפים את השיטה put() בשיטה add(), כמו בדוגמה הבאה:

    // Save the entity
datastore.add(visit);

תוצאות השאילתה

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

  • המתודה OrderBy מציגה את התוצאות בסדר עולה או יורד.

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

השאילתה משתמשת בשיטת תבנית builder עם המשתנה kind. המשתנה kind מוגדר לערך Visit מהשלב קבלת מפתח שנוצר על ידי Datastore.

כדי לאחזר את 10 התוצאות הראשונות:

  1. מחפשים שורות שמשתמשות בשיטה addSort(), כמו השורה הבאה:

      // Retrieve the last 10 visits from the datastore, ordered by timestamp.
  Query query = new Query(kind).addSort("timestamp", Query.SortDirection.DESCENDING);
  List<Entity> results = datastore.prepare(query).asList(FetchOptions.Builder.withLimit(10));

  2. מחליפים את השיטה addSort() בשיטה setOrderBy() ומוסיפים את השיטה setLimit(), כמו בדוגמה הבאה:

    // Retrieve the last 10 visits from the datastore, ordered by timestamp.
Query<Entity> query = Query.newEntityQueryBuilder()
                        .setKind(kind)
                        .setOrderBy(StructuredQuery.OrderBy.desc("timestamp"))
                        .setLimit(10)
                        .build();

  3. אחרי שהשאילתה מוכנה, מריצים את הקוד באמצעות datastore.run() ואוספים את התוצאות באוסף QueryResultsEntity.

    אובייקט QueryResults שמתקבל הוא איטרטור עם פונקציה hasNext().

  4. בודקים אם יש קבוצת תוצאות עם אובייקט next לעיבוד, במקום להשתמש בלולאה ברשימת התוצאות. לדוגמה:

    QueryResults<Entity> results = datastore.run(query);

      resp.setContentType("text/plain");
      PrintWriter out = resp.getWriter();
      out.print("Last 10 visits:\n");
      while (results.hasNext()) {
          Entity entity = results.next();
          out.format(
                  "Time: %s Addr: %s\n", entity.getTimestamp("timestamp"), entity.getString("user_ip"));
      }

דוגמאות

כדי לראות דוגמה להעברת אפליקציית Java 8 ל-Firestore במצב Datastore, אפשר להשוות בין דוגמת הקוד של App Engine Datastore ל-Java 8 לבין דוגמת הקוד של Firestore במצב Datastore ב-GitHub.

השלב הבא