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

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

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

הרשאות

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

• בעלים של Cloud Datastore (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 project. רק בפרויקטים ב-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/(default)
    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. אם הנתונים כבר לא קיימים בטווח שצוין timestamp, נוצרת שגיאה. חותמת הזמן חייבת להיות דקה שלמה, גם אם השעה שצוינה היא בשעה האחרונה.
   • לא נחייב אתכם על ייצוא PITR שנכשל.

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

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