העברה מ-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 להעברה מ-App Engine bundled Datastore ל-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);

    מחליפים את הקריאה ל-constructor‏ Entity בקריאה ל-constructor‏ 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 מהשלב קבלת מפתח שנוצר במאגר נתונים.

כדי לאחזר את 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.

השלב הבא