טעינת נתונים מ-Cloud Storage ל-BigQuery

אתם יכולים לטעון נתונים מ-Cloud Storage ל-BigQuery באמצעות שירות העברת הנתונים ל-BigQuery דרך החיבור ל-Cloud Storage. בעזרת שירות העברת הנתונים ל-BigQuery, אתם יכולים לתזמן משימות העברה חוזרות שמוסיפות את הנתונים העדכניים ביותר מ-Cloud Storage ל-BigQuery.

איך פועלת העברת נתונים ב-Cloud Storage

מגבלות

העברות נתונים חוזרות מ-Cloud Storage ל-BigQuery כפופות למגבלות הבאות:

• כל הקבצים שתואמים לתבניות שהוגדרו על ידי תו כללי לחיפוש או על ידי פרמטרים של זמן ריצה להעברת הנתונים חייבים להיות בעלי אותה סכימה שהגדרתם לטבלת היעד, אחרת ההעברה תיכשל. שינויים בסכימה של הטבלה בין הפעלות גם גורמים להעברה להיכשל.
• בגלל שלאובייקטים ב-Cloud Storage יכולות להיות גרסאות, חשוב לציין שאין תמיכה בהעברת נתונים ל-BigQuery מאובייקטים שהועברו לארכיון ב-Cloud Storage. כדי להעביר אובייקטים, הם צריכים להיות פעילים.
• בניגוד לטעינות נתונים נפרדות מ-Cloud Storage ל-BigQuery, בהעברות נתונים מתמשכות צריך ליצור את טבלת היעד לפני שמגדירים את ההעברה. בקובצי CSV ו-JSON, צריך גם להגדיר מראש את סכימת הטבלה. ‫BigQuery לא יכול ליצור את הטבלה כחלק מתהליך העברת הנתונים החוזר.
• בהעברות נתונים מ-Cloud Storage, הפרמטר Write preference מוגדר כברירת מחדל לערך APPEND. במצב הזה, אפשר לטעון קובץ שלא השתנה ל-BigQuery רק פעם אחת. אם המאפיין last modification time של הקובץ מתעדכן, הקובץ נטען מחדש.
• אם קובצי Cloud Storage משתנים במהלך העברת נתונים, שירות העברת הנתונים ל-BigQuery לא מבטיח שכל הקבצים יועברו או שיועברו רק פעם אחת.

• כשאתם טוענים נתונים ל-BigQuery מקטגוריה של Cloud Storage, חלות המגבלות הבאות:

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

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

  • מגבלות של קובצי CSV
  • מגבלות של JSON
  • מגבלות של Parquet
  • מגבלות הייצוא של Firestore
  • מגבלות של Avro
  • מגבלות על נתונים בתצוגת עץ ונתונים חוזרים

מרווחים מינימליים

• קבצי המקור נאספים להעברת נתונים באופן מיידי, ללא גיל מינימלי לקובץ.
• מרווח הזמן המינימלי בין העברות נתונים חוזרות הוא 15 דקות. מרווח הזמן שמוגדר כברירת מחדל להעברת נתונים חוזרת הוא כל 24 שעות.
• אתם יכולים להגדיר העברה מבוססת-אירועים כדי לתזמן באופן אוטומטי העברות נתונים במרווחי זמן קצרים יותר.

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

לפני שיוצרים העברת נתונים מ-Cloud Storage, צריך לבצע את הפעולות הבאות:

• מוודאים שביצעתם את כל הפעולות שנדרשות כדי להפעיל את שירות העברת הנתונים ל-BigQuery.
• מאחזרים את ה-URI של Cloud Storage.
• יוצרים מערך נתונים ב-BigQuery כדי לאחסן את הנתונים.
• יוצרים את טבלת היעד להעברת הנתונים ומציינים את הגדרת הסכימה. אתם יכולים ליצור טבלה ב-BigQuery או ליצור טבלה מנוהלת ב-Iceberg.
• אם אתם מתכננים לציין מפתח הצפנה בניהול הלקוח (CMEK), ודאו שלחשבון השירות שלכם יש הרשאות להצפנה ולפענוח, ושיש לכם את מזהה המשאב של מפתח Cloud KMS שנדרש כדי להשתמש ב-CMEK. במאמר ציון מפתח הצפנה בהעברות מוסבר איך CMEK פועל עם שירות העברת הנתונים ל-BigQuery.

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

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

התפקידים הנדרשים ב-BigQuery

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

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

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

כדי ליצור העברת נתונים בשירות העברת הנתונים ל-BigQuery, נדרשות ההרשאות הבאות:

• הרשאות לשירות העברת נתונים ל-BigQuery:
  • bigquery.transfers.update
  • bigquery.transfers.get
• הרשאות ב-BigQuery:
  • bigquery.datasets.get
  • bigquery.datasets.getIamPolicy
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
  • bigquery.jobs.create

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

מידע נוסף זמין במאמר מתן גישה ל-bigquery.admin.

התפקידים הנדרשים ב-Cloud Storage

צריכה להיות לכם הרשאת storage.objects.get בקטגוריה הספציפית או ברמה גבוהה יותר. אם אתם משתמשים בתו כללי לחיפוש של URI, אתם צריכים הרשאות storage.objects.list. אם רוצים למחוק את קובצי המקור אחרי כל העברה שהושלמה, צריך גם הרשאות storage.objects.delete. תפקיד ה-IAM המוגדר מראש storage.objectAdmin כולל את כל ההרשאות האלה.

הגדרת העברה מ-Cloud Storage

כדי ליצור העברת נתונים מ-Cloud Storage בשירות העברת הנתונים ל-BigQuery:

המסוף

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

   מעבר אל "העברות נתונים"

2. ‫לוחצים על Create transfer.

3. בקטע Source type, בשדה Source בוחרים באפשרות Google Cloud Storage.

   

4. בקטע Transfer config name, בשדה השם המוצג מזינים שם להעברת הנתונים, למשל My Transfer. שם ההעברה יכול להיות כל ערך שמאפשר לזהות את ההעברה אם צריך לשנות אותה מאוחר יותר.

   

5. בקטע Schedule options, בוחרים באפשרות Repeat frequency:

   • אם בוחרים באפשרות שעות, ימים, שבועות או חודשים, צריך לציין גם תדירות. אפשר גם לבחור באפשרות בהתאמה אישית כדי לציין תדירות חזרה מותאמת אישית. אפשר לבחור באפשרות התחלה עכשיו או באפשרות התחלה בזמן מוגדר ולציין תאריך התחלה וזמן ריצה.

   • אם בוחרים באפשרות On-demand, העברת הנתונים תפעל כשתפעילו את ההעברה באופן ידני.

   • אם בוחרים באפשרות Event-driven, צריך גם לציין מינוי ל-Pub/Sub. בוחרים את שם המינוי או לוחצים על יצירת מינוי. האפשרות הזו מפעילה העברה מבוססת-אירועים, שמפעילה הרצות של העברות כשאירועים מגיעים למינוי ל-Pub/Sub.

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

6. בקטע הגדרות היעד:

   • בקטע Dataset, בוחרים את מערך הנתונים שיצרתם כדי לאחסן את הנתונים.
   • בוחרים באפשרות Native table אם רוצים להעביר לטבלה ב-BigQuery.
   • בוחרים באפשרות Iceberg Managed אם רוצים להעביר לטבלה מנוהלת של Iceberg.

7. בקטע פרטי מקור הנתונים:

   1. בשדה Destination table, מזינים את השם של טבלת היעד. טבלת היעד צריכה לעמוד בכללים למתן שמות לטבלאות. אפשר להשתמש בפרמטרים גם בשמות של טבלאות היעד.
   2. בשדה Cloud Storage URI, מזינים את ה-URI של Cloud Storage. יש תמיכה בתווים כלליים לחיפוש ובפרמטרים. אם ה-URI לא תואם לאף קובץ, לא יתבצע שינוי של נתונים בטבלת היעד.

   3. בקטע העדפת כתיבה, בוחרים:

      • ‫APPEND כדי להוסיף נתונים חדשים באופן מצטבר לטבלת היעד הקיימת. ‫APPEND הוא ערך ברירת המחדל של Write preference.
      • ‫MIRROR כדי להחליף את הנתונים בטבלת היעד בכל הפעלה של העברת נתונים.

      למידע נוסף על האופן שבו שירות העברת הנתונים ל-BigQuery מטמיע נתונים באמצעות APPEND או MIRROR, קראו את המאמר הטמעת נתונים להעברות של Cloud Storage. מידע נוסף על השדה writeDisposition זמין במאמר JobConfigurationLoad.

   4. אם רוצים למחוק את קובצי המקור אחרי כל העברת נתונים שהסתיימה, מסמנים את התיבה Delete source files after transfer. משימות המחיקה מתבצעות כמיטב היכולת. אם הניסיון הראשון למחוק את קובצי המקור נכשל, לא יתבצע ניסיון נוסף למחוק אותם.

   5. בקטע אפשרויות העברה:

      1. בקטע כל הפורמטים:
         1. בשדה Number of errors allowed, מזינים את המספר המקסימלי של רשומות לא תקינות ש-BigQuery יכול להתעלם מהן בזמן הרצת המשימה. אם מספר הרשומות הפגומות חורג מהערך הזה, תוחזר שגיאת invalid בתוצאת המשימה והמשימה תיכשל. ערך ברירת המחדל הוא 0.
         2. ‫(אופציונלי) בשדה Decimal target types, מזינים רשימה מופרדת בפסיקים של סוגי נתונים אפשריים ב-SQL שאליהם אפשר להמיר את הערכים העשרוניים של המקור. סוג הנתונים של SQL שנבחר להמרה תלוי בתנאים הבאים:
            • סוג הנתונים שנבחר להמרה יהיה סוג הנתונים הראשון ברשימה הבאה שתומך ברמת הדיוק ובקנה המידה של נתוני המקור, בסדר הזה: NUMERIC,‏ BIGNUMERIC ו-STRING.
            • אם אף אחד מסוגי הנתונים שברשימה לא תומך בדיוק ובקנה המידה, נבחר סוג הנתונים שתומך בטווח הרחב ביותר ברשימה שצוינה. אם ערך חורג מהטווח הנתמך כשקוראים את נתוני המקור, מתקבלת שגיאה.
            • סוג הנתונים STRING תומך בכל ערכי הדיוק והקנה מידה.
            • אם השדה הזה נשאר ריק, סוג הנתונים יהיה כברירת מחדל NUMERIC,STRING ל-ORC, ו-NUMERIC לפורמטים האחרים של הקבצים.
            • השדה הזה לא יכול להכיל סוגי נתונים כפולים.
            • המערכת מתעלמת מהסדר של סוגי הנתונים שאתם מפרטים בשדה הזה.
      2. בקטע JSON, CSV, מסמנים את התיבה Ignore unknown values אם רוצים שהעברת הנתונים תתעלם מנתונים שלא מתאימים לסכימה של טבלת היעד.
      3. בקטע AVRO, מסמנים את התיבה Use avro logical types אם רוצים שהעברת הנתונים תמיר את הסוגים הלוגיים של Avro לסוגי הנתונים התואמים ב-BigQuery. כברירת מחדל, המערכת מתעלמת מהמאפיין logicalType ברוב הסוגים, ומשתמשת במקום זאת בסוג Avro הבסיסי.

      4. בקטע CSV:

         1. בשדה Field delimiter, מזינים את התו שמפריד בין השדות. ערך ברירת המחדל הוא פסיק.
         2. בשדה Quote character, מזינים את התו שמשמש לציטוט קטעי נתונים בקובץ CSV. ערך ברירת המחדל הוא מירכאות כפולות (").
         3. בשדה שורות כותרת שצריך לדלג עליהן, מזינים את מספר שורות הכותרת בקובצי המקור אם לא רוצים לייבא אותן. ערך ברירת המחדל הוא 0.
         4. אם רוצים לאפשר שורות חדשות בשדות עם מירכאות, מסמנים את התיבה Allow quoted newlines.
         5. מסמנים את התיבה Allow jagged rows אם רוצים לאפשר העברת נתונים של שורות שחסרות בהן עמודות NULLABLE.

         מידע נוסף זמין במאמר אפשרויות ל-CSV בלבד.

8. בתפריט Service Account, בוחרים חשבון שירות מתוך חשבונות השירות שמשויכים לפרויקט ב- Google Cloud . אתם יכולים לשייך חשבון שירות להעברת הנתונים במקום להשתמש בפרטי הכניסה של המשתמש. מידע נוסף על שימוש בחשבונות שירות להעברות נתונים זמין במאמר שימוש בחשבונות שירות.

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

9. אופציונלי: בקטע אפשרויות להתראות:

   1. לוחצים על המתג כדי להפעיל את ההתראות באימייל. כשמפעילים את האפשרות הזו, הבעלים של הגדרת העברת הנתונים מקבלים התראה באימייל כשהרצת ההעברה נכשלת.
   2. בקטע Select a Pub/Sub topic, בוחרים את שם הנושא או לוחצים על Create a topic. האפשרות הזו מגדירה התראות על הפעלת Pub/Sub להעברה.

10. אופציונלי: בקטע Advanced options, אם אתם משתמשים ב-CMEK, בוחרים באפשרות Customer-managed key. תופיע רשימה של מפתחות ה-CMEK הזמינים לבחירה. במאמר ציון מפתח הצפנה בהעברות מוסבר איך מפתחות CMEK פועלים עם שירות העברת הנתונים ל-BigQuery.

11. לוחצים על Save.

BQ

מזינים את הפקודה bq mk ומציינים את הדגל ליצירת העברה – --transfer_config. צריך גם את הדגלים הבאים:

• --data_source
• --display_name
• --target_dataset
• --params

דגלים אופציונליים:

• ‫--destination_kms_key: מציין את מזהה משאב המפתח של מפתח Cloud KMS, אם משתמשים במפתח הצפנה בניהול הלקוח (CMEK) להעברת הנתונים הזו. במאמר ציון מפתח הצפנה בהעברות מוסבר איך מפתחות CMEK פועלים עם שירות העברת הנתונים ל-BigQuery.
• ‫--service_account_name: מציין חשבון שירות שבו צריך להשתמש לאימות ההעברה של Cloud Storage במקום חשבון המשתמש.

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

• אי אפשר להגדיר את לוח הזמנים של ההעברה באמצעות כלי שורת הפקודה של BigQuery. כשיוצרים העברת נתונים מ-Cloud Storage באמצעות כלי שורת הפקודה של BigQuery, הגדרות ההעברה נקבעות לפי ערך ברירת המחדל של Schedule (כל 24 שעות).

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

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

bq mk \
--transfer_config \
--project_id=PROJECT_ID \
--data_source=DATA_SOURCE \
--display_name=NAME \
--target_dataset=DATASET \
--destination_kms_key="DESTINATION_KEY" \
--params='PARAMETERS' \
--service_account_name=SERVICE_ACCOUNT_NAME

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

• ‫PROJECT_ID הוא מזהה הפרויקט. אם לא מציינים פרויקט מסוים באמצעות --project_id, המערכת משתמשת בפרויקט שמוגדר כברירת מחדל.
• ‫DATA_SOURCE הוא מקור הנתונים, לדוגמה google_cloud_storage.
• ‫NAME הוא השם המוצג של הגדרת העברת הנתונים. שם ההעברה יכול להיות כל ערך שמאפשר לכם לזהות את ההעברה אם תצטרכו לשנות אותה בהמשך.
• ‫DATASET הוא מערך הנתונים של היעד להגדרות ההעברה.
• ‫DESTINATION_KEY: מזהה המשאב של מפתח Cloud KMS, לדוגמה projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name.
• ‫PARAMETERS מכיל את הפרמטרים של הגדרת ההעברה שנוצרה בפורמט JSON. לדוגמה: --params='{"param":"param_value"}'.
  • ‫destination_table_name_template: השם של טבלת היעד ב-BigQuery.
  • ‫data_path_template: ה-URI של Cloud Storage שמכיל את הקבצים שרוצים להעביר. יש תמיכה בתווים כלליים לחיפוש ובפרמטרים.
  • ‫write_disposition: קובע אם קבצים תואמים יתווספו לטבלת היעד או ישוכפלו במלואם. הערכים הנתמכים הם APPEND או MIRROR. במאמר הטמעת נתונים להעברות מ-Cloud Storage מוסבר איך שירות העברת הנתונים ל-BigQuery מוסיף או משקף נתונים בהעברות מ-Cloud Storage.
  • ‫file_format: הפורמט של הקבצים שרוצים להעביר. הפורמט יכול להיות CSV,‏ JSON,‏ AVRO,‏ PARQUET או ORC. ערך ברירת המחדל הוא CSV.
  • ‫max_bad_records: לכל ערך של file_format, המספר המקסימלי של רשומות לא תקינות שאפשר להתעלם מהן. ערך ברירת המחדל הוא 0.
  • ‫decimal_target_types: לכל ערך של file_format, רשימה מופרדת בפסיקים של סוגי נתונים אפשריים של SQL שאפשר להמיר אליהם את הערכים העשרוניים של המקור. אם לא מציינים את השדה הזה, סוג הנתונים שמוגדר כברירת מחדל הוא "NUMERIC,STRING" ל-ORC, ו-"NUMERIC" לפורמטים האחרים של הקבצים.
  • ‫ignore_unknown_values: לכל ערך של file_format, מגדירים את הערך TRUE כדי לקבל שורות שמכילות ערכים שלא תואמים לסכימה. למידע נוסף, עיינו בפרטי השדה ignoreUnknownvalues בטבלת העזר של JobConfigurationLoad.
  • ‫use_avro_logical_types: לערכים של AVRO file_format, מגדירים את TRUE כדי לפרש סוגים לוגיים לסוגים התואמים שלהם (לדוגמה, TIMESTAMP), במקום להשתמש רק בסוגים הגולמיים שלהם (לדוגמה, INTEGER).
  • ‫parquet_enum_as_string: לערכי PARQUET file_format, מגדירים את TRUE כדי להסיק שהסוג הלוגי של PARQUET ENUM הוא STRING במקום ברירת המחדל BYTES.
  • ‫parquet_enable_list_inference: לערכי PARQUET file_format, מגדירים את TRUE כדי להשתמש בהסקת סכימה במיוחד לסוג הלוגי PARQUET LIST.
  • ‫reference_file_schema_uri: נתיב URI לקובץ רפרנס עם הסכימה של הקורא.
  • ‫field_delimiter: לערכי CSV file_format, תו שמפריד בין שדות. ערך ברירת המחדל הוא פסיק.
  • ‫quote: לערכים של CSV file_format, תו שמשמש לציטוט קטעי נתונים בקובץ CSV. ערך ברירת המחדל הוא מירכאות כפולות (").
  • ‫skip_leading_rows: בערכים CSV file_format, מציינים את מספר שורות הכותרת הראשונות שלא רוצים לייבא. ערך ברירת המחדל הוא 0.
  • ‫allow_quoted_newlines: בערכים של CSV file_format, מגדירים את TRUE כדי לאפשר שורות חדשות בשדות עם מירכאות.
  • ‫allow_jagged_rows : לערכים CSV file_format, מגדירים את הערך TRUE כדי לקבל שורות שחסרות בהן עמודות אופציונליות בסוף. הערכים החסרים ימולאו ב-NULL.
  • preserve_ascii_control_characters: לערכים של CSV file_format, מגדירים את TRUE כדי לשמור על תווי בקרה מוטמעים של ASCII.
  • ‫encoding: מציינים את סוג הקידוד של CSV. הערכים הנתמכים הם UTF8,‏ ISO_8859_1,‏ UTF16BE,‏ UTF16LE,‏ UTF32BE ו-UTF32LE.
  • ‫delete_source_files: מגדירים את הערך TRUE כדי למחוק את קובצי המקור אחרי כל העברה שמסתיימת בהצלחה. משימות מחיקה לא מופעלות מחדש אם הניסיון הראשון למחוק את קובץ המקור נכשל. ערך ברירת המחדל הוא FALSE.
• ‫SERVICE_ACCOUNT_NAME הוא השם של חשבון השירות שמשמש לאימות ההעברה. חשבון השירות צריך להיות בבעלות של אותו project_id ששימש ליצירת ההעברה, וצריכות להיות לו כל ההרשאות הנדרשות.

לדוגמה, הפקודה הבאה יוצרת העברת נתונים מ-Cloud Storage בשם My Transfer, באמצעות הערך gs://mybucket/myfile/*.csv של data_path_template, מערך הנתונים של היעד mydataset ו-file_format CSV. הדוגמה הזו כוללת ערכים שאינם ערכי ברירת המחדל של הפרמטרים האופציונליים שמשויכים לפורמט הקובץ CSV.

העברת הנתונים נוצרת בפרויקט ברירת המחדל:

bq mk --transfer_config \
--target_dataset=mydataset \
--project_id=myProject \
--display_name='My Transfer' \
--destination_kms_key=projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey \
--params='{"data_path_template":"gs://mybucket/myfile/*.csv",
"destination_table_name_template":"MyTable",
"file_format":"CSV",
"max_bad_records":"1",
"ignore_unknown_values":"true",
"field_delimiter":"|",
"quote":";",
"skip_leading_rows":"1",
"allow_quoted_newlines":"true",
"allow_jagged_rows":"false",
"delete_source_files":"true"}' \
--data_source=google_cloud_storage \
--service_account_name=abcdef-test-sa@abcdef-test. projects/862514376110/locations/us/transferConfigs/ 5dd12f26-0000-262f-bc38-089e0820fe38

אחרי הרצת הפקודה, תתקבל הודעה כמו זו:

[URL omitted] Please copy and paste the above URL into your web browser and follow the instructions to retrieve an authentication code.

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

API

משתמשים ב-method‏ projects.locations.transferConfigs.create ומספקים מופע של המשאב TransferConfig.

Java

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

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

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to create google cloud storage transfer config
public class CreateCloudStorageTransfer {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    String datasetId = "MY_DATASET_ID";
    String tableId = "MY_TABLE_ID";
    // GCS Uri
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv";
    String fileFormat = "CSV";
    String fieldDelimiter = ",";
    String skipLeadingRows = "1";
    Map<String, Value> params = new HashMap<>();
    params.put(
        "destination_table_name_template", Value.newBuilder().setStringValue(tableId).build());
    params.put("data_path_template", Value.newBuilder().setStringValue(sourceUri).build());
    params.put("write_disposition", Value.newBuilder().setStringValue("APPEND").build());
    params.put("file_format", Value.newBuilder().setStringValue(fileFormat).build());
    params.put("field_delimiter", Value.newBuilder().setStringValue(fieldDelimiter).build());
    params.put("skip_leading_rows", Value.newBuilder().setStringValue(skipLeadingRows).build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Google Cloud Storage Config Name")
            .setDataSourceId("google_cloud_storage")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createCloudStorageTransfer(projectId, transferConfig);
  }

  public static void createCloudStorageTransfer(String projectId, TransferConfig transferConfig)
      throws IOException {
    try (DataTransferServiceClient client = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .build();
      TransferConfig config = client.createTransferConfig(request);
      System.out.println("Cloud storage transfer created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("Cloud storage transfer was not created." + ex.toString());
    }
  }
}

ציון מפתח הצפנה בהעברות

אתם יכולים לציין מפתחות הצפנה בניהול הלקוח (CMEK) כדי להצפין נתונים להרצת העברה. אתם יכולים להשתמש ב-CMEK כדי לתמוך בהעברות מ-Cloud Storage.

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

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

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

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

הפעלה ידנית של העברה

בנוסף להעברות נתונים מתוזמנות אוטומטית מ-Cloud Storage, אתם יכולים להפעיל העברה באופן ידני כדי לטעון קובצי נתונים נוספים.

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

כדי להפעיל העברת נתונים:

המסוף

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

   כניסה לדף BigQuery

2. לוחצים על העברות נתונים.

3. בוחרים את העברת הנתונים מהרשימה.

4. לוחצים על Run transfer now או על Schedule backfill (להגדרות העברה עם פרמטרים של זמן ריצה).

   • אם לחצתם על Run transfer now, בוחרים באפשרות Run one time transfer או באפשרות Run for specific date, לפי הצורך. אם בחרתם באפשרות Run for specific date, בוחרים תאריך ושעה ספציפיים:

     

   • אם לחצתם על Schedule backfill, בוחרים באפשרות Run one time transfer או Run for a date range, לפי הצורך. אם בחרתם באפשרות Run for a date range, בוחרים תאריך ושעה להתחלה ולסיום:

     

5. לוחצים על אישור.

BQ

מזינים את הפקודה bq mk ומציינים את הדגל --transfer_run. אפשר להשתמש בדגל --run_time או בדגלים --start_time ו---end_time.

bq mk \
--transfer_run \
--start_time='START_TIME' \
--end_time='END_TIME' \
RESOURCE_NAME

bq mk \
--transfer_run \
--run_time='RUN_TIME' \
RESOURCE_NAME

כאשר:

• ‫START_TIME ו-END_TIME הן חותמות זמן שמסתיימות ב-Z או מכילות היסט תקין של אזור זמן. לדוגמה:

  • 2017-08-19T12:11:35.00Z
  • 2017-05-25T00:00:00+00:00

• ‫RUN_TIME היא חותמת זמן שמציינת את הזמן שבו צריך לתזמן את הפעלת העברת הנתונים. אם רוצים להריץ העברה חד-פעמית לזמן הנוכחי, אפשר להשתמש בדגל --run_time.

• ‫RESOURCE_NAME הוא שם המשאב של ההעברה (שנקרא גם הגדרת ההעברה), לדוגמה projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7. אם אתם לא יודעים את שם המשאב של ההעברה, הריצו את הפקודה bq ls --transfer_config --transfer_location=LOCATION כדי למצוא את שם המשאב.

API

משתמשים ב-method‏ projects.locations.transferConfigs.startManualRuns ומציינים את משאב הגדרות ההעברה באמצעות הפרמטר parent.

המאמרים הבאים

• מידע על פרמטרים של זמן ריצה בהעברות של Cloud Storage
• מידע נוסף על שירות העברת הנתונים ל-BigQuery