עבודה עם שחזור בנקודת זמן (PITR)

בדף הזה נסביר איך משתמשים בשחזור לנקודת זמן מסוימת (PITR) כדי לשמור ולשחזר נתונים ב-Cloud Firestore.

במאמר שחזור מערכת מנקודה מסוימת בזמן מוסבר על המושגים של PITR.

הרשאות

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

• Cloud Datastore Owner (roles/datastore.owner)

בתפקידים בהתאמה אישית, חשוב לוודא שההרשאות הבאות ניתנות:

• כדי להפעיל את PITR כשיוצרים מסד נתונים: datastore.databases.create
• כדי לעדכן את ההגדרות של PITR במסד נתונים קיים: datastore.databases.update,datastore.databases.list
• כדי לבצע קריאות מנתוני PITR: datastore.databases.get,datastore.entities.get,datastore.entities.list
• כדי לייצא נתוני PITR: datastore.databases.export
• כדי לייבא נתוני PITR: datastore.databases.import

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

לפני שמתחילים להשתמש ב-PITR, חשוב לשים לב לנקודות הבאות:

• אי אפשר להתחיל לקרוא מ-7 ימים אחורה מיד אחרי הפעלת PITR.
• כדי להפעיל את PITR בזמן יצירת מסד נתונים, צריך להשתמש בפקודה gcloud firestore databases create. אי אפשר להפעיל את PITR בזמן יצירת מסד נתונים באמצעות מסוף Google Cloud.
• Cloud Firestore מתחיל לשמור גרסאות מהנקודה הזו ואילך אחרי הפעלת PITR.
• לא ניתן לקרוא נתוני PITR בחלון PITR אחרי השבתת PITR.
• אם תפעילו מחדש את PITR מיד אחרי השבתתו, נתוני PITR הקודמים כבר לא יהיו זמינים. כל נתוני PITR שנוצרו לפני השבתת PITR יימחקו אחרי תאריך התפוגה של PITR.
• אם מחקתם בטעות נתונים בשעה האחרונה ו-PITR מושבת, תוכלו להפעיל את PITR תוך שעה ממועד המחיקה כדי לשחזר את הנתונים.
• כל קריאה שמתבצעת בנתוני PITR שפג תוקפם נכשלת.

הפעלת PITR

לפני שמשתמשים ב-PITR, צריך להפעיל את החיוב בפרויקט ב-Google Cloud. רק בפרויקטים ב-Google Cloud שבהם החיוב מופעל אפשר להשתמש בפונקציה של PITR.

כדי להפעיל את PITR במסד הנתונים:

gcloud firestore databases create\
  --location=LOCATION\
  [--database=DATABASE_ID; default="(default)"]\
  [--type=TYPE; default="firestore-native"]\
  --enable-pitr

gcloud firestore databases update\
  [--database=DATABASE_ID; default="(default)"]\
  --no-enable-pitr

אחזור של תקופת השמירה וזמן הגרסה המוקדמת ביותר

gcloud firestore databases describe --database=DATABASE_ID

    appEngineIntegrationMode: ENABLED
    concurrencyMode: PESSIMISTIC
    createTime: '2021-03-24T17:02:35.234Z'
    deleteProtectionState: DELETE_PROTECTION_DISABLED
    earliestVersionTime: '2023-06-12T16:17:25.222474Z'
    etag: IIDayqOevv8CMNTvyNK4uv8C
    keyPrefix: s
    locationId: nam5
    name: projects/PROJECT_ID/databases/DATABASE_ID
    pointInTimeRecoveryEnablement: POINT_IN_TIME_RECOVERY_DISABLED
    type: FIRESTORE_NATIVE
    uid: 5230c382-dcd2-468f-8cb3-2a1acfde2b32
    updateTime: '2021-11-17T17:48:22.171180Z'
    versionRetentionPeriod: 3600s

קריאת נתוני PITR

אפשר לקרוא נתוני PITR באמצעות ספריות הלקוח, שיטות ה-API ל-REST או המחבר FirestoreIO Apache Beam.

  Firestore firestore = …

  TransactionOptions options =
          TransactionOptions.createReadOnlyOptionsBuilder()
              .setReadTime(
                  com.google.protobuf.Timestamp.newBuilder()
                      .setSeconds(1684098540L)
                      .setNanos(0))
              .build();

  ApiFuture<Void> futureTransaction = firestore.runTransaction(
              transaction -> {
                // Does a snapshot read document lookup
                final DocumentSnapshot documentResult =
                    transaction.get(documentReference).get();

                // Executes a snapshot read query
                final QuerySnapshot queryResult =
                  transaction.get(query).get();
              },
              options);

  // Blocks on transaction to complete
  futureTransaction.get();

  const documentSnapshot = await firestore.runTransaction(
    updateFunction => updateFunction.get(documentRef),
    {readOnly: true, readTime: new Firestore.Timestamp(1684098540, 0)}
);

  const querySnapshot = await firestore.runTransaction(
    updateFunction => updateFunction.get(query),
    {readOnly: true, readTime: new Firestore.Timestamp(1684098540, 0)}
  )

  Instant readTime = Instant.ofEpochSecond(1684098540L);

  PCollection<Document> documents =
      pipeline
          .apply(Create.of(collectionId))
          .apply(
              new FilterDocumentsQuery(
                  firestoreOptions.getProjectId(), firestoreOptions.getDatabaseId()))
          .apply(FirestoreIO.v1().read().runQuery().withReadTime(readTime).withRpcQosOptions(rpcQosOptions).build())
  ...

ייצוא וייבוא מנתוני PITR

אפשר לייצא את מסד הנתונים אל Cloud Storage מנתוני PITR באמצעות הפקודה gcloud firestore export. אפשר לייצא נתוני PITR שבהם חותמת הזמן היא חותמת זמן של דקה שלמה במהלך שבעת הימים האחרונים, אבל לא לפני earliestVersionTime. אם הנתונים כבר לא קיימים בחותמת הזמן שצוינה, פעולת הייצוא נכשלת.

פעולת הייצוא של PITR תומכת בכל המסננים, כולל ייצוא של כל המסמכים וייצוא של אוספים ספציפיים.

1. מייצאים את מסד הנתונים, מציינים את הפרמטר snapshot-time לחותמת הזמן הרצויה לשחזור.

   gcloud

   מריצים את הפקודה הבאה כדי לייצא את מסד הנתונים לקטגוריה.

   gcloud firestore export gs://BUCKET_NAME_PATH \
       --snapshot-time=PITR_TIMESTAMP \
       --collection-ids=COLLECTION_IDS \
       --namespace-ids=NAMESPACE_IDS
   

   איפה,

   • BUCKET_NAME_PATH – קטגוריה תקינה של Cloud Storage עם תחילית נתיב אופציונלית שבה נשמרים קובצי הייצוא.
   • PITR_TIMESTAMP – חותמת זמן של PITR ברמת פירוט של דקה, למשל 2023-05-26T10:20:00.00Z או 2023-10-19T10:30:00.00-07:00.
   • COLLECTION_IDS – רשימה של מזהי אוספים או מזהי קבוצות של אוספים, לדוגמה: 'specific-collection-group1','specific-collection-group2'.
   • NAMESPACE_IDS – רשימה של מזהי מרחבי שמות, לדוגמה 'customer','orders'.

   לפני שמייצאים נתוני PITR, חשוב לשים לב לנקודות הבאות:

   • חותמת הזמן צריכה להיות בפורמט RFC 3339. לדוגמה, 2023-05-26T10:20:00.00Z או 2023-10-19T10:30:00.00-07:00.
   • חשוב לוודא שחותמת הזמן שציינתם היא חותמת זמן של דקה שלמה במהלך שבעת הימים האחרונים, אבל לא לפני earliestVersionTime. אם הנתונים כבר לא קיימים בחותמת הזמן שצוינה, נוצרת שגיאה. חותמת הזמן חייבת להיות דקה שלמה, גם אם השעה שצוינה היא מהשעה האחרונה.
   • לא תחויבו על ייצוא PITR כושל.

2. ייבוא למסד נתונים.

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