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

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

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

הרשאות

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

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

ההרשאות הנדרשות

כדי לנהל את הגדרות ה-PITR, נדרשות ההרשאות הבאות:

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

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

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

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

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

הפעלת PITR

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

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

המסוף

1. נכנסים לדף Databases במסוף Google Cloud .

   כניסה לדף Databases

2. בוחרים את מסד הנתונים הרצוי מרשימת מסדי הנתונים.

3. בתפריט הניווט, לוחצים על תוכנית התאוששות מאסון (DR).

4. כדי לערוך את ההגדרות, לוחצים על עריכה.

5. מסמנים את התיבה Enable point-in-time recovery ולוחצים על Save.

הפעלת PITR כרוכה בעלויות אחסון. למידע נוסף, ראו תמחור.

כדי להשבית את ה-PITR, מבטלים את הסימון בתיבה Enable point-in-time recovery בדף תוכנית התאוששות מאסון (DR) במסוף Google Cloud .

gcloud

מפעילים את PITR במהלך יצירת מסד הנתונים באמצעות הפקודה gcloud firestore databases create, באופן הבא:

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

מחליפים את הערכים באופן הבא:

• ‫LOCATION: המיקום שבו רוצים ליצור את מסד הנתונים.
• ‫DATABASE_ID: מזהה מסד הנתונים או (default).
• ‫TYPE: מוגדר ל-datastore-mode.

כדי להשבית את ה-PITR, משתמשים בפקודה gcloud firestore databases update באופן הבא:

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

מחליפים את הערכים באופן הבא:

• ‫DATABASE_ID: מזהה מסד הנתונים או (default).

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

המסוף

1. נכנסים לדף Databases במסוף Google Cloud .

   כניסה לדף Databases

2. בוחרים את מסד הנתונים הרצוי מרשימת מסדי הנתונים.

3. בתפריט הניווט, לוחצים על תוכנית התאוששות מאסון (DR).

4. בקטע Settings, שימו לב לערכים של Retention period ו-Earliest version time.

   • תקופת השמירה: התקופה שבה כל גרסאות הנתונים של מסד הנתונים נשמרות במצב Datastore. הערך הוא שעה אחת כש-PITR מושבת, ושבעה ימים כש-PITR מופעל.
   • Earliest version time: חותמת הזמן המוקדמת ביותר שבה אפשר לקרוא גרסאות קודמות של הנתונים בחלון ה-PITR. הערך הזה מתעדכן כל הזמן במצב Datastore, והוא הופך למיושן ברגע ששולחים שאילתה. אם אתם משתמשים בערך הזה כדי לשחזר נתונים, חשוב להביא בחשבון את הזמן שעובר מהרגע שבו נשלחת השאילתה על הערך ועד לרגע שבו אתם מתחילים את השחזור.
   • שחזור מערכת מנקודה מסוימת בזמן (PITR): אם PITR מופעל, מוצג הערך Enabled. אם PITR מושבת, יופיע הערך Disabled.

gcloud

מריצים את הפקודה gcloud firestore databases describe באופן הבא:

gcloud firestore databases describe --database=DATABASE_ID

מחליפים את DATABASE_ID במזהה מסד הנתונים או ב-(default).

הנה הפלט:

    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

כאשר:

• ‫earliestVersionTime: חותמת הזמן של נתוני ה-PITR המוקדמים ביותר שנשמרו.
• ‫pointInTimeRecoveryEnablement: מוצג הערך POINT_IN_TIME_RECOVERY_ENABLED אם PITR מופעל. אם האפשרות PITR מושבתת, יוצג הערך POINT_IN_TIME_RECOVERY_DISABLED או שהשדה pointInTimeRecoveryEnablement לא יוצג.
• ‫versionRetentionPeriod: משך הזמן שבו נתוני ה-PITR נשמרים, באלפיות השנייה. הערך יכול להיות שעה אחת כש-PITR מושבת, או שבעה ימים כש-PITR מופעל.

קריאת נתוני PITR

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

ספריות לקוח

הערה: אפשר לקרוא מנתוני PITR בספריות הלקוח של השרת, כלומר Go,‏ Java,‏ Node.js,‏ PHP ו-Python.

Java

כדי לקרוא נתוני PITR, צריך להשתמש ב-method‏ readTime במחלקה ReadOption. אי אפשר להשתמש בעסקה ReadOnly כדי לבצע קריאות. למידע נוסף, עיינו בקוד לדוגמה של ReadOption.

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

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

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

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

לרשימה המלאה של דוגמאות ל-readTime, ראו את מאגר GitHub.

Python

כדי לקרוא נתונים ב-PITR במצב Datastore ב-Python SDK, משתמשים ב-method‏ readTime או בטרנזקציה ReadOnly עם readTime.

  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()

לרשימה המלאה של דוגמאות ל-readTime, ראו את מאגר GitHub.

‫API בארכיטקטורת REST

אפשר לקרוא נתונים ב-PITR בשיטות הקריאה של מצב Datastore V1, שהן lookup,‏ runQuery ו-runAggregationQuery.

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

1. בבקשה של ה-method לקריאה, מעבירים את הערך של readTime כחותמת זמן נתמכת של PITR ב-method ‏readOptions. חותמת הזמן של ה-PITR יכולה להיות חותמת זמן מדויקת במיקרו-שניות בשעה האחרונה, או חותמת זמן של דקה שלמה לפני השעה האחרונה, אבל לא לפני earliestVersionTime.

2. משתמשים בפרמטר readTime יחד עם השיטה BeginTransaction כחלק מטרנזקציית ReadOnly לכמה קריאות PITR.

Apache Beam

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

מציינים את ה-method‏ withReadTime(Instant readTime) באובייקט DatastoreV1.Read. כל הקריאות הבאות באמצעות האובייקט DatastoreV1.Read קוראות מאותו readTime.

Java

הקוד הבא מראה איך להשתמש ב-method‏ withReadTime לקריאות PITR.

  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<Entity> entities = pipeline.apply(read);
    ...

לרשימה מלאה של דוגמאות ל-withReadTime, עיינו במאגר GitHub.

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

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

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

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

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

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

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

הערה: כדי לשכפל מסדי נתונים, לחשבון Google שלכם צריכה להיות הרשאת ה-IAM‏ datastore.databases.clone.

המסוף

1. נכנסים לדף Databases במסוף Google Cloud .

   כניסה לדף Databases

2. לוחצים על View more בשורה של מסד הנתונים שרוצים לשכפל. לוחצים על שכפול. מופיעה תיבת הדו-שיח Create a clone.

3. בתיבת הדו-שיח Create a clone, מזינים את הפרמטרים לשיבוט מסד הנתונים:

   1. בשדה Give the clone an ID, מזינים מזהה מסד נתונים למסד הנתונים המשוכפל החדש. מזהה מסד הנתונים הזה לא יכול להיות משויך למסד נתונים קיים.

   2. בשדה Clone from, בוחרים נקודת זמן שרוצים להשתמש בה לשכפול. הזמן שנבחר תואם לחותמת זמן של PITR, ברמת פירוט של דקות.

4. לוחצים על Create clone.

הערה: למסד הנתונים המשוכפל תהיה אותה הגדרת הצפנה כמו למסד הנתונים המקורי. אם רוצים להגדיר הצפנה אחרת למסד הנתונים המשוכפל, אפשר להשתמש בפקודות של Google Cloud CLI.

gcloud

משתמשים בפקודה gcloud firestore databases clone כדי לשכפל מסד נתונים:

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

מחליפים את מה שכתוב בשדות הבאים:

• ‫SOURCE_DATABASE: שם מסד הנתונים הקיים שרוצים לשכפל. השם הוא בפורמט projects/PROJECT_ID/databases/SOURCE_DATABASE_ID.

• ‫PITR_TIMESTAMP: חותמת זמן של PITR בפורמט RFC 3339, ברמת פירוט של דקות. לדוגמה: 2025-06-01T10:20:00.00Z או 2025-06-01T10:30:00.00-07:00.

• ‫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'

שינוי הגדרות ההצפנה של מסד הנתונים המשוכפל

כברירת מחדל, למסד הנתונים המשוכפל תהיה אותה הגדרת הצפנה כמו למסד הנתונים המקורי. כדי לשנות את הגדרות ההצפנה, משתמשים בארגומנט --encryption-type:

• ‫use-source-encryption (ברירת המחדל): שימוש באותן הגדרות הצפנה כמו במסד הנתונים של המקור.
• ‫google-default-encryption: שימוש בהצפנת ברירת המחדל של Google.
• ‫customer-managed-encryption: שימוש בהצפנת CMEK. מציינים מזהה מפתח בארגומנט --kms-key-name.

בדוגמה הבאה מוסבר איך להגדיר הצפנת CMEK למסד הנתונים המשוכפל:

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, חשוב לשים לב לנקודות הבאות:

   • מפעילים את PITR במסד הנתונים. אם התכונה PITR מושבתת, הייצוא של חותמת זמן של תמונת מצב נכשל, גם אם חותמות הזמן הן מהשעה האחרונה אחרי earliestVersionTime. פעולת הייצוא מחזירה את השגיאה Point-in-Time Recovery must be enabled in order to execute exports at a snapshot timestamp.
   • צריך לציין את חותמת הזמן בפורמט RFC 3339. לדוגמה, 2023-05-26T10:20:00.00Z או 2023-10-19T10:30:00.00-07:00.
   • חשוב לוודא שחותמת הזמן שציינתם היא חותמת זמן של דקה שלמה בשבעת הימים האחרונים, אבל לא לפני earliestVersionTime. אם הנתונים כבר לא קיימים בחותמת הזמן שצוינה, תופיע הודעת שגיאה. חותמת הזמן חייבת להיות דקה שלמה, גם אם השעה שצוינה היא בשעה האחרונה.
   • לא תחויבו על ייצוא PITR שנכשל.

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

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