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

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

מידע על העברות ב-Cloud Storage

מגבלות

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

• כל הקבצים שתואמים לתבניות שהוגדרו על ידי תו כללי לחיפוש או על ידי פרמטרים של זמן ריצה להעברת הנתונים חייבים להיות בעלי אותה סכימה שהגדרתם לטבלת היעד, אחרת ההעברה תיכשל. גם שינויים בסכימת הטבלה בין הרצות יגרמו לכישלון ההעברה.
• חשוב לדעת שאפשר ליצור גרסאות של אובייקטים ב-Cloud Storage, אבל אי אפשר להשתמש באובייקטים מאורכבים ב-Cloud Storage להעברת נתונים ל-BigQuery. כדי להעביר אובייקטים, הם צריכים להיות פעילים.
• בניגוד לטעינות נתונים נפרדות מ-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, בוחרים באפשרות Google Cloud Storage בשדה Source.

   

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

   

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

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

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

   • אם בוחרים באפשרות 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. (אופציונלי) בשביל סוגי יעד עשרוניים, מזינים רשימה מופרדת בפסיקים של סוגי נתונים אפשריים ב-SQL שאפשר להמיר אליהם את הערכים העשרוניים במקור. סוג הנתונים של SQL שנבחר להמרה תלוי בתנאים הבאים:
            • סוג הנתונים שנבחר להמרה יהיה סוג הנתונים הראשון ברשימה הבאה שתומך ברמת הדיוק ובקנה המידה של נתוני המקור, בסדר הזה: NUMERIC,‏ BIGNUMERIC ו-STRING.
            • אם אף אחד מסוגי הנתונים שמופיעים ברשימה לא תומך בדיוק ובקנה המידה, ייבחר סוג הנתונים שתומך בטווח הרחב ביותר ברשימה שצוינה. אם ערך חורג מהטווח הנתמך במהלך קריאת נתוני המקור, מוצגת שגיאה.
            • סוג הנתונים STRING תומך בכל ערכי הדיוק והקנה מידה.
            • אם השדה הזה נשאר ריק, סוג הנתונים יהיה NUMERIC,STRING בפורמט ORC ו-NUMERIC בפורמטים אחרים של קבצים.
            • השדה הזה לא יכול להכיל סוגי נתונים כפולים.
            • המערכת מתעלמת מהסדר של סוגי הנתונים שאתם מפרטים בשדה הזה.
      2. בקטע JSON, CSV, מסמנים את התיבה Ignore unknown values אם רוצים שהעברת הנתונים תתעלם מנתונים שלא מתאימים לסכימה של טבלת היעד.
      3. בקטע AVRO, מסמנים את התיבה Use avro logical types (שימוש בסוגים לוגיים של Avro) אם רוצים שהעברת הנתונים תמיר סוגים לוגיים של Avro לסוגי הנתונים התואמים שלהם ב-BigQuery. כברירת מחדל, המערכת מתעלמת מהמאפיין logicalType ברוב הסוגים, ומשתמשת במקום זאת בסוג Avro הבסיסי.

      4. בקטע CSV:

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

         מידע נוסף זמין במאמר אפשרויות ל-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 באמצעות הערך data_path_template של gs://mybucket/myfile/*.csv, מערך נתוני היעד 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=[e-mail] 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

משתמשים בשיטה projects.locations.transferConfigs.startManualRuns ומספקים את משאב הגדרות ההעברה באמצעות הפרמטר parent.

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

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