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

המסוף

1. עוברים לדף 'העברות נתונים' במסוף Cloud de Confiance .

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

2. לוחצים על add Create transfer (יצירת העברה).

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

   

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

   

5. בקטע אפשרויות תזמון, בוחרים תדירות חזרה:

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

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

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

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

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

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

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

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

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

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

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

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

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

      4. בקטע CSV:

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

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

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

   • אם נכנסתם באמצעות זהות מאוחדת, תצטרכו חשבון שירות כדי ליצור העברת נתונים. אם נכנסתם באמצעות חשבון 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, התצורה של ההעברה מוגדרת באמצעות ערך ברירת המחדל של לוח זמנים (כל 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. מידע על האופן שבו שירות העברת הנתונים ל-BigQuery מוסיף נתונים או משכפל אותם בהעברות של Cloud Storage זמין במאמר הוספת נתונים להעברות של 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 ולא BYTES (ברירת המחדל).STRING
  • ‫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 file_format.

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

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.s3ns.iam.gserviceaccount.com 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

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

Java

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

המסוף

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

   לדף BigQuery

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

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

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

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

     

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

     

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.