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

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

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

הרשאות

כדי לקבל את ההרשאות שנדרשות לניהול הגדרות PITR, צריך לבקש מהאדמין להקצות לכם את תפקיד ה-IAM בעלים של Cloud Datastore (roles/datastore.owner) בפרויקט שבו רוצים להפעיל את הגדרות ה-PITR. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

זהו תפקיד שמוגדר מראש וכולל את ההרשאות שנדרשות לניהול ההגדרות של PITR. כדי לראות בדיוק אילו הרשאות נדרשות, אפשר להרחיב את הקטע ההרשאות הנדרשות:

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

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

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

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

הפעלת PITR

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

כדי להפעיל 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: DATASTORE_MODE
    uid: 5230c382-dcd2-468f-8cb3-2a1acfde2b32
    updateTime: '2021-11-17T17:48:22.171180Z'
    versionRetentionPeriod: 3600s

קריאת נתוני PITR

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

  Datastore datastore = ...
  Timestamp timestamp = ...

  // lookup
  Key key = ...
  Entity entity = datastore.get(key, ReadOption.readTime(timestamp));

  // runQuery
  Query query = ...
  QueryResults queryResult = datastore.run(query, ReadOption.readTime(timestamp));

  // runAggregationQuery
  AggregationQuery countAggregationQuery = ...
  Long count = getOnlyElement(datastore.runAggregation(countAggregationQuery, ReadOption.readTime(timestamp))).get("total_count");

  from datetime import datetime, timezone

  read_time = datetime.now(tz=timezone.utc)

  key = …
  # read without PITR read time
  entity = client.get(key)

  # read with PITR read time
  entity = client.get(key, read_time=read_time)

  # PITR read using read_only transaction
  with client.transaction(read_only=True, read_time=read_time):
      entity = client.get(key)

  query = client.query…
  # run query without PITR read time
  iterator = query.fetch()

  # run query with PITR read time
  iterator = query.fetch(read_time=read_time)

  # PITR read query using read_only transaction
  with client.transaction(read_only=True, read_time=read_time):
      iterator = query.fetch()

  com.google.datastore.v1.Query query = ...
    Instant readTime = Instant.ofEpochSecond(1684098540L);

    DatastoreV1.Read read =
            DatastoreIO.v1()
                .read()
                .withProjectId(project)
                .withQuery(query)
                .withNamespace(namespace)
                .withReadTime(readTime);

    PCollection entities = pipeline.apply(read);
    ...

שכפול ממסד נתונים

אפשר לשכפל מסד נתונים קיים בנקודת זמן נבחרת למסד נתונים חדש:

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

  כדי ליצור שיבוט, Firestore משתמש בנתוני שחזור לנקודת זמן (PITR) של מסד הנתונים המקורי. מסד הנתונים המשוכפל כולל את כל הנתונים והאינדקסים.

• כברירת מחדל, מסד הנתונים המשוכפל יוצפן באותו אופן שבו מוצפן מסד הנתונים המקורי, באמצעות ההצפנה שמוגדרת כברירת מחדל ב-Google או באמצעות הצפנת CMEK. אפשר לציין סוג הצפנה אחר או להשתמש במפתח אחר להצפנת CMEK.

• חותמת הזמן היא ברמת גרנולריות של דקה אחת ומציינת נקודת זמן בעבר, בתקופה שמוגדרת על ידי חלון ה-PITR:

  • אם PITR מופעל במסד הנתונים, אפשר לבחור כל דקה ב-7 הימים האחרונים (או פחות, אם PITR הופעל לפני פחות מ-7 ימים).
  • אם PITR לא מופעל, אפשר לבחור כל דקה בשעה האחרונה.
  • אפשר לבדוק את חותמת הזמן המוקדמת ביותר שאפשר לבחור בתיאור של מסד הנתונים.

gcloud firestore databases clone \
--source-database='SOURCE_DATABASE' \
--snapshot-time='PITR_TIMESTAMP' \
--destination-database='DESTINATION_DATABASE_ID'

gcloud firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db'

gcloud firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db' \
--encryption-type='customer-managed-encryption' \
--kms-key-name='projects/example-project/locations/us-central1/keyRings/example-key-ring/cryptoKeys/example-key'

ייצוא וייבוא מנתונים של 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. ייבוא למסד נתונים.

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