טעינת נתונים מייצוא מ-Firestore

מערכת BigQuery תומכת בטעינת נתונים מייצוא של Firestore שנוצר באמצעות שירות הייבוא והייצוא המנוהל של Firestore. שירות הייבוא והייצוא המנוהל מייצא מסמכי Firestore לקטגוריה של Cloud Storage. אחר כך תוכלו לטעון את הנתונים המיוצאים לטבלה ב-BigQuery.

מגבלות

כשאתם טוענים נתונים ל-BigQuery מייצוא של Firestore, חשוב לשים לב למגבלות הבאות:

  • מערך הנתונים צריך להיות באותו מיקום כמו הקטגוריה של Cloud Storage שמכילה את קובצי הייצוא.
  • אפשר לציין רק URI אחד של Cloud Storage, ואי אפשר להשתמש בתו כללי לחיפוש URI.
  • כדי שייבוא של נתונים מ-Firestore יטען בצורה תקינה, המסמכים בנתוני הייצוא צריכים להיות בעלי סכימה עקבית עם פחות מ-10,000 שמות שדות ייחודיים.
  • אפשר ליצור טבלה חדשה לאחסון הנתונים, או להחליף טבלה קיימת. אי אפשר לצרף נתונים שיוצאו מ-Firestore לטבלה קיימת.
  • פקודת הייצוא חייבת לציין מסנן collection-ids. אי אפשר לטעון ל-BigQuery נתונים שיוצאו בלי לציין מסנן של מזהה אוסף.

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

מקצים תפקידים של ניהול זהויות והרשאות גישה (IAM) שנותנים למשתמשים את ההרשאות הנדרשות לביצוע כל משימה במסמך הזה.

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

כדי לטעון נתונים ל-BigQuery, אתם צריכים הרשאות IAM להרצת משימת טעינה ולטעינת נתונים לטבלאות ולמחיצות ב-BigQuery. אם אתם טוענים נתונים מ-Cloud Storage, אתם צריכים גם הרשאות IAM כדי לגשת לקטגוריה שמכילה את הנתונים.

הרשאות לטעינת נתונים ל-BigQuery

כדי לטעון נתונים לטבלה או למחיצה חדשה ב-BigQuery, או כדי לצרף נתונים לטבלה או למחיצה קיימת או להחליף אותם, אתם צריכים את הרשאות ה-IAM הבאות:

  • bigquery.tables.create
  • bigquery.tables.updateData
  • bigquery.tables.update
  • bigquery.jobs.create

כל אחד מהתפקידים הבאים שמוגדרים מראש ב-IAM כולל את ההרשאות שנדרשות לטעינת נתונים לטבלה או למחיצה ב-BigQuery:

  • roles/bigquery.dataEditor
  • roles/bigquery.dataOwner
  • ‫roles/bigquery.admin (כולל את ההרשאה bigquery.jobs.create)
  • ‫bigquery.user (כולל את ההרשאה bigquery.jobs.create)
  • ‫bigquery.jobUser (כולל את ההרשאה bigquery.jobs.create)

בנוסף, אם יש לכם הרשאה של bigquery.datasets.create, אתם יכולים ליצור ולעדכן טבלאות באמצעות משימת טעינה במערכי הנתונים שאתם יוצרים.

במאמר תפקידים והרשאות מוגדרים מראש יש מידע נוסף על תפקידים והרשאות ב-IAM ב-BigQuery.

הרשאות לטעינת נתונים מ-Cloud Storage

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

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

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

כדי לטעון נתונים מקטגוריה של Cloud Storage, נדרשות ההרשאות הבאות:

  • storage.buckets.get
  • storage.objects.get
  • storage.objects.list (required if you are using a URI wildcard)

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

טעינת נתונים של שירות הייצוא של Firestore

אפשר לטעון נתונים מקובץ מטא-נתונים של ייצוא מ-Firestore באמצעות Google Cloud המסוף, כלי שורת הפקודה של BigQuery או ה-API.

לפעמים משתמשים בטרמינולוגיה של Datastore במסוף Google Cloud ובכלי שורת הפקודה של BigQuery, אבל התהליכים הבאים תואמים לקובצי ייצוא של Firestore. ל-Firestore ול-Datastore יש פורמט ייצוא משותף.

המסוף

  1. במסוף Google Cloud , עוברים לדף BigQuery.

    כניסה לדף BigQuery

  2. בחלונית הימנית, לוחצים על כלי הניתוחים.
  3. בחלונית Explorer, מרחיבים את הפרויקט, לוחצים על Datasets ובוחרים מערך נתונים.
  4. בקטע פרטי מערך הנתונים, לוחצים על יצירת טבלה.
  5. בחלונית Create table, מציינים את הפרטים הבאים:
    1. בקטע מקור, בוחרים באפשרות Google Cloud Storage ברשימה יצירת טבלה מ. לאחר מכן, מבצעים את הפעולות הבאות:
      1. בוחרים קובץ מתוך הקטגוריה של Cloud Storage או מזינים את ה-URI של Cloud Storage. אי אפשר לכלול כמה כתובות URI במסוף Google Cloud , אבל אפשר להשתמש בתווים כלליים לחיפוש. הקטגוריה של Cloud Storage צריכה להיות באותו מיקום כמו מערך הנתונים שמכיל את הטבלה שרוצים ליצור, להוסיף לה נתונים או להחליף אותה.
        ה-URI של קובץ הייצוא מ-Firestore צריך להסתיים ב-KIND_COLLECTION_ID.export_metadata. לדוגמה, בנתיב default_namespace_kind_Book.export_metadata, ‏Book הוא מזהה האוסף ו-default_namespace_kind_Book הוא שם הקובץ שנוצר על ידי Firestore. אם ה-URI לא מסתיים ב-KIND_COLLECTION_ID.export_metadata, מוצגת הודעת השגיאה הבאה: does not contain valid backup metadata. (קוד שגיאה: לא תקין). בוחרים קובץ מקור כדי ליצור טבלה ב-BigQuery
      2. בקטע File format (פורמט קובץ), בוחרים באפשרות Cloud Datastore Backup (גיבוי של Cloud Datastore). ‫Firestore ו-Datastore חולקים את אותו פורמט ייצוא.
    2. בקטע יעד, מציינים את הפרטים הבאים:
      1. בקטע Dataset (מערך נתונים), בוחרים את מערך הנתונים שבו רוצים ליצור את הטבלה.
      2. בשדה Table (טבלה), מזינים את השם של הטבלה שרוצים ליצור.
      3. מוודאים שהשדה Table type (סוג הטבלה) מוגדר ל-Native table (טבלה מקורית).
    3. בקטע Schema (סכימה), לא צריך לבצע פעולה כלשהי. הסכימה נגזרת מייצוא מ-Firestore.
    4. אופציונלי: מציינים הגדרות של מחיצה ושל אשכול. מידע נוסף זמין במאמרים בנושא יצירת טבלאות עם חלוקה למחיצות ויצירה ושימוש בטבלאות מקובצות.
    5. לוחצים על אפשרויות מתקדמות ומבצעים את הפעולות הבאות:
      • בקטע העדפות כתיבה, משאירים את האפשרות כתיבה אם ריק מסומנת. האפשרות הזו יוצרת טבלה חדשה וטוענת לתוכה את הנתונים.
      • אם רוצים להתעלם מערכים בשורה שלא מופיעים בסכימה של הטבלה, בוחרים באפשרות ערכים לא ידועים.
      • בקטע הצפנה, לוחצים על מפתח בניהול הלקוח כדי להשתמש במפתח של Cloud Key Management Service. אם לא משנים את ההגדרה Google-managed key,‏ BigQuery יצפין את הנתונים באחסון.
    6. לוחצים על יצירת טבלה.

BQ

משתמשים בפקודה bq load עם source_format שמוגדר ל-DATASTORE_BACKUP. מציינים את הדגל --location ומגדירים את הערך למיקום. אם מחליפים טבלה קיימת, מוסיפים את הדגל --replace.

כדי לטעון רק שדות ספציפיים, משתמשים בדגל ‎--projection_fields.

bq --location=LOCATION load \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE

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

  • ‫LOCATION: המיקום שלכם. הדגל --location הוא אופציונלי.
  • FORMAT: DATASTORE_BACKUP. האפשרות הנכונה ל-Firestore היא Datastore Backup. ‫Firestore ו-Datastore חולקים פורמט ייצוא.
  • ‫DATASET: מערך הנתונים שמכיל את הטבלה שאליה טוענים את הנתונים.
  • ‫TABLE: הטבלה שאליה טוענים את הנתונים. אם הטבלה לא קיימת, היא נוצרת.
  • ‫PATH_TO_SOURCE: ה-URI של Cloud Storage.

לדוגמה, הפקודה הבאה טוענת את קובץ הייצוא gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata של Firestore לטבלה בשם book_data. ‫mybucket ו-mydataset נוצרו במיקום US שכולל מספר אזורים.

bq --location=US load \
--source_format=DATASTORE_BACKUP \
mydataset.book_data \
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata

API

מגדירים את המאפיינים הבאים כדי לטעון נתוני ייצוא של Firestore באמצעות API.

  1. יוצרים הגדרת עבודה של load שמפנה לנתוני המקור ב-Cloud Storage.

  2. מציינים את המיקום במאפיין location בקטע jobReference של משאב המשרה.

  3. ה-sourceUris צריך להיות מוגדר במלואו, בפורמט gs://BUCKET/OBJECT בהגדרות של משימת הטעינה. שם הקובץ (האובייקט) חייב להסתיים ב-KIND_NAME.export_metadata. מותר להשתמש רק ב-URI אחד לייצוא של Firestore, ואי אפשר להשתמש בתו כללי לחיפוש.

  4. מגדירים את פורמט הנתונים על ידי הגדרת המאפיין sourceFormat לערך DATASTORE_BACKUP בהגדרות האישיות של משימת הטעינה. ‫Datastore Backup היא האפשרות הנכונה ל-Firestore. ל-Firestore ול-Datastore יש פורמט ייצוא משותף.

  5. כדי לטעון רק שדות ספציפיים, מגדירים את המאפיין projectionFields.

  6. אם מחליפים טבלה קיימת, צריך לציין את אופן הכתיבה על ידי הגדרת המאפיין writeDisposition לערך WRITE_TRUNCATE.

Python

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

כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח. 

# TODO(developer): Set table_id to the ID of the table to create.
table_id = "your-project.your_dataset.your_table_name"

# TODO(developer): Set uri to the path of the kind export metadata
uri = (
    "gs://cloud-samples-data/bigquery/us-states"
    "/2021-07-02T16:04:48_70344/all_namespaces/kind_us-states"
    "/all_namespaces_kind_us-states.export_metadata"
)

# TODO(developer): Set projection_fields to a list of document properties
#                  to import. Leave unset or set to `None` for all fields.
projection_fields = ["name", "post_abbr"]

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

job_config = bigquery.LoadJobConfig(
    source_format=bigquery.SourceFormat.DATASTORE_BACKUP,
    projection_fields=projection_fields,
)

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

אפשרויות Firestore

כדי לשנות את האופן שבו BigQuery מנתח את נתוני הייצוא של Firestore, מציינים את האפשרות הבאה:

אפשרותGoogle Cloud במסוף הדגל `bq` מאפיין BigQuery API תיאור
לא זמין --projection_fields projectionFields (Java, Python) (אופציונלי) רשימה מופרדת בפסיקים שמציינת אילו שדות במסמך לטעון מייצוא של Firestore. כברירת מחדל, כל השדות נטענים ב-BigQuery. שמות השדות הם תלויי אותיות רישיות וחייבים להופיע בייצוא. אי אפשר לציין נתיבי שדות בתוך שדה מיפוי כמו map.foo.

המרה של סוגי נתונים

‫BigQuery ממיר נתונים מכל מסמך בקובצי ייצוא של Firestore לסוגי נתונים של BigQuery. בטבלה הבאה מתואר תהליך ההמרה בין סוגי הנתונים הנתמכים.

סוג הנתונים ב-Firestore סוג נתונים ב-BigQuery
מערך רשומה
בוליאני בוליאני
חומרי עזר רשומה
תאריך ושעה TIMESTAMP
מפה רשומה
מספר בשיטת נקודה צפה FLOAT
נקודה גיאוגרפית

רשומה

[{"lat","FLOAT"},
 {"long","FLOAT"}]
מספר שלם מספר שלם
String STRING (truncated to 64 KB)

מאפייני מפתח ב-Firestore

לכל מסמך ב-Firestore יש מפתח ייחודי שמכיל מידע כמו מזהה המסמך ונתיב המסמך. ‫BigQuery יוצר סוג נתונים RECORD (שנקרא גם STRUCT) למפתח, עם שדות מקוננים לכל פריט מידע, כמו שמתואר בטבלה הבאה.

מאפיין מרכזי תיאור סוג נתונים ב-BigQuery
__key__.app שם האפליקציה ב-Firestore. מחרוזת
__key__.id מזהה המסמך, או null אם הערך של __key__.name מוגדר. מספר שלם
__key__.kind מזהה האוסף של המסמך. מחרוזת
__key__.name השם של המסמך או null אם __key__.id מוגדר. מחרוזת
__key__.namespace ‫Firestore לא תומך במרחבי שמות בהתאמה אישית. ‫ מרחב השמות שמוגדר כברירת מחדל מיוצג על ידי מחרוזת ריקה. מחרוזת
__key__.path הנתיב של המסמך: הרצף של המסמך ושל זוגות האוספים מאוסף הבסיס. לדוגמה: "Country", "USA", "PostalCode", 10011, "Route", 1234. מחרוזת