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

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

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

לפני שיוצרים העברת נתונים של Blob Storage, צריך:

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

ודאו שהענקתם את ההרשאות הבאות.

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

כדי לקבל את ההרשאות שנדרשות ליצירת העברת נתונים באמצעות שירות העברת נתונים ל-BigQuery, צריך לבקש מהאדמין להקצות לכם את תפקיד BigQuery Admin ‏ (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.

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

למידע על ההרשאות הנדרשות ב-Blob Storage כדי להפעיל את העברת הנתונים, אפשר לעיין במאמר בנושא חתימת גישה משותפת (SAS).

מגבלות

העברות נתונים ב-Blob Storage כפופות למגבלות הבאות:

הגדרת העברת נתונים מ-Blob Storage

בוחרים באחת מהאפשרויות הבאות:

המסוף

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

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

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

  3. בדף Create transfer, מבצעים את הפעולות הבאות:

    • בקטע Source type, בשדה Source, בוחרים באפשרות Azure Blob Storage & ADLS:

      סוג מקור ההעברה

    • בקטע Transfer config name (שם הגדרת ההעברה), בשדה Display name (שם מוצג), מזינים שם להעברת הנתונים.

    • בקטע אפשרויות תזמון:

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

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

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

    • בקטע Data source details (פרטים של מקור הנתונים), מבצעים את הפעולות הבאות:

      • בשדה טבלת יעד, מזינים את שם הטבלה שיצרתם לאחסון הנתונים ב-BigQuery. שמות של טבלאות יעד תומכים בפרמטרים.
      • בשדה Azure storage account name (שם חשבון אחסון ב-Azure), מזינים את שם החשבון ב-Blob Storage.
      • בשדה Container name, מזינים את שם המאגר של Blob Storage.
      • בשדה נתיב נתונים, מזינים את הנתיב לסינון הקבצים שיועברו. דוגמאות
      • בקטע SAS token (טוקן SAS), מזינים את טוקן ה-SAS של Azure.
      • בקטע פורמט קובץ, בוחרים את פורמט נתוני המקור.
      • בקטע Write disposition (אופן הכתיבה), בוחרים באפשרות WRITE_APPEND כדי להוסיף נתונים חדשים לטבלת היעד באופן מצטבר, או באפשרות WRITE_TRUNCATE כדי להחליף את הנתונים בטבלת היעד בכל הפעלה של ההעברה. ‫WRITE_APPEND הוא ערך ברירת המחדל של Write disposition.

      מידע נוסף על הטמעת נתונים באמצעות שירות העברת הנתונים ל-BigQuery באמצעות WRITE_APPEND או WRITE_TRUNCATE זמין במאמר הטמעת נתונים להעברות של Azure Blob. מידע נוסף על השדה writeDisposition זמין במאמר JobConfigurationLoad.

      הפרטים של מקור הנתונים

    • בקטע Transfer options (אפשרויות העברה), מבצעים את הפעולות הבאות:

      • בקטע מספר השגיאות המותר, מזינים ערך של מספר שלם עבור המספר המקסימלי של רשומות פגומות שאפשר להתעלם מהן. ערך ברירת המחדל הוא 0.
      • (אופציונלי) בשביל סוגי יעד עשרוניים, מזינים רשימה מופרדת בפסיקים של סוגי נתונים אפשריים ב-SQL, שאליהם יומרו ערכים עשרוניים בנתוני המקור. סוג הנתונים של SQL שנבחר להמרה תלוי בתנאים הבאים:
        • הסוג נבחר לפי הסדר NUMERIC, BIGNUMERIC ו-STRING אם הוא מופיע ברשימה שצוינה ואם הוא תומך בדיוק ובקנה מידה.
        • אם אף אחד מסוגי הנתונים שמופיעים ברשימה לא תומך בדיוק ובקנה המידה, ייבחר סוג הנתונים שתומך בטווח הרחב ביותר ברשימה שציינתם. אם ערך חורג מהטווח הנתמך במהלך קריאת נתוני המקור, מוצגת שגיאה.
        • סוג הנתונים STRING תומך בכל ערכי הדיוק והקנה מידה.
        • אם השדה הזה יישאר ריק, סוג הנתונים יהיה NUMERIC,STRING כברירת מחדל עבור ORC, ו-NUMERIC עבור פורמטים אחרים של קבצים.
        • השדה הזה לא יכול להכיל סוגי נתונים כפולים.
        • אין חשיבות לסדר שבו מופיעים סוגי הנתונים.

    • אם בחרתם בפורמט CSV או JSON, בקטע JSON, CSV, מסמנים את התיבה Ignore unknown values כדי לאשר שורות שמכילות ערכים שלא תואמים לסכימה.

    • אם בחרתם בפורמט CSV לקובץ, בקטע CSV מזינים אפשרויות נוספות של CSV לטעינת הנתונים.

      אפשרויות CSV

    • בקטע Notification options, אפשר להפעיל התראות באימייל והתראות ב-Pub/Sub.

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

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

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

BQ

משתמשים בפקודה bq mk --transfer_config כדי ליצור העברה של Blob Storage:

bq mk \
  --transfer_config \
  --project_id=PROJECT_ID \
  --data_source=DATA_SOURCE \
  --display_name=DISPLAY_NAME \
  --target_dataset=DATASET \
  --destination_kms_key=DESTINATION_KEY \
  --params=PARAMETERS

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

  • ‫PROJECT_ID: (אופציונלי) מזהה הפרויקט שמכיל את מערך הנתונים המיועד. אם לא מציינים פרויקט, המערכת משתמשת בפרויקט ברירת המחדל.
  • DATA_SOURCE: azure_blob_storage.
  • ‫DISPLAY_NAME: השם המוצג של הגדרות העברת הנתונים. שם ההעברה יכול להיות כל ערך שיעזור לכם לזהות את ההעברה אם תצטרכו לשנות אותה בהמשך.
  • ‫DATASET: מערך הנתונים של היעד להגדרת העברת הנתונים.
  • ‫DESTINATION_KEY: (אופציונלי) מזהה משאב המפתח של Cloud KMS – לדוגמה, projects/project_name/locations/us/keyRings/key_ring_name/cryptoKeys/key_name.
  • ‫PARAMETERS: הפרמטרים של הגדרת העברת הנתונים, שמופיעים בפורמט JSON. לדוגמה, --params={"param1":"value1", "param2":"value2"}. הפרמטרים להעברת נתונים ב-Blob Storage הם:
    • ‫destination_table_name_template: שדה חובה. השם של טבלת היעד.
    • ‫storage_account: שדה חובה. שם החשבון ב-Blob Storage.
    • ‫container: שדה חובה. שם מאגר Blob Storage.
    • ‫data_path: אופציונלי. הנתיב לסינון הקבצים שיועברו. דוגמאות
    • ‫sas_token: שדה חובה. טוקן SAS של Azure.
    • ‫file_format: אופציונלי. סוג הקבצים שרוצים להעביר: CSV,‏ JSON,‏ AVRO,‏ PARQUET או ORC. ערך ברירת המחדל הוא CSV.
    • ‫write_disposition: אופציונלי. בוחרים באפשרות WRITE_APPEND כדי להוסיף נתונים לטבלת היעד, או באפשרות WRITE_TRUNCATE כדי להחליף את הנתונים בטבלת היעד. ערך ברירת המחדל הוא WRITE_APPEND.
    • ‫max_bad_records: אופציונלי. מספר הרשומות הפגומות המותר. ערך ברירת המחדל הוא 0.
    • ‫decimal_target_types: אופציונלי. רשימה מופרדת בפסיקים של סוגי נתונים אפשריים ב-SQL שהערכים העשרוניים בנתוני המקור מומרים אליהם. אם לא מציינים את השדה הזה, סוג הנתונים יהיה NUMERIC,STRING בפורמט ORC ו-NUMERIC בפורמטים אחרים של קבצים.
    • ‫ignore_unknown_values: אופציונלי, ומתעלמים ממנו אם file_format הוא לא JSON או CSV. הערך true מאפשר לקבל שורות שמכילות ערכים שלא תואמים לסכימה.
    • ‫field_delimiter (לא חובה): חל רק אם הערך של file_format הוא CSV. התו שמפריד בין השדות. ערך ברירת המחדל הוא ,.
    • ‫skip_leading_rows (לא חובה): חל רק אם הערך של file_format הוא CSV. מציין את מספר שורות הכותרת שלא רוצים לייבא. ערך ברירת המחדל הוא 0.
    • ‫allow_quoted_newlines (לא חובה): חל רק אם הערך של file_format הוא CSV. מציין אם מותר להשתמש בשורות חדשות בשדות עם מרכאות.
    • ‫allow_jagged_rows (לא חובה): חל רק אם הערך של file_format הוא CSV. מציין אם לקבל שורות שחסרות בהן עמודות אופציונליות בסוף. הערכים החסרים ימולאו בערך NULL.

לדוגמה, הפקודה הבאה יוצרת העברת נתונים מ-Blob Storage בשם mytransfer:

bq mk \
  --transfer_config \
  --data_source=azure_blob_storage \
  --display_name=mytransfer \
  --target_dataset=mydataset \
  --destination_kms_key=projects/myproject/locations/us/keyRings/mykeyring/cryptoKeys/key1
  --params={"destination_table_name_template":"mytable",
      "storage_account":"myaccount",
      "container":"mycontainer",
      "data_path":"myfolder/*.csv",
      "sas_token":"my_sas_token_value",
      "file_format":"CSV",
      "max_bad_records":"1",
      "ignore_unknown_values":"true",
      "field_delimiter":"|",
      "skip_leading_rows":"1",
      "allow_quoted_newlines":"true",
      "allow_jagged_rows":"false"}

API

משתמשים בשיטה 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 azure blob storage transfer config.
public class CreateAzureBlobStorageTransfer {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    final String displayName = "MY_TRANSFER_DISPLAY_NAME";
    final String datasetId = "MY_DATASET_ID";
    String tableId = "MY_TABLE_ID";
    String storageAccount = "MY_AZURE_STORAGE_ACCOUNT_NAME";
    String containerName = "MY_AZURE_CONTAINER_NAME";
    String dataPath = "MY_AZURE_FILE_NAME_OR_PREFIX";
    String sasToken = "MY_AZURE_SAS_TOKEN";
    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("storage_account", Value.newBuilder().setStringValue(storageAccount).build());
    params.put("container", Value.newBuilder().setStringValue(containerName).build());
    params.put("data_path", Value.newBuilder().setStringValue(dataPath).build());
    params.put("sas_token", Value.newBuilder().setStringValue(sasToken).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());
    createAzureBlobStorageTransfer(projectId, displayName, datasetId, params);
  }

  public static void createAzureBlobStorageTransfer(
      String projectId, String displayName, String datasetId, Map<String, Value> params)
      throws IOException {
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName(displayName)
            .setDataSourceId("azure_blob_storage")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    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("Azure Blob Storage transfer created successfully: " + config.getName());
    } catch (ApiException ex) {
      System.out.print("Azure Blob Storage transfer was not created." + ex.toString());
    }
  }
}

הגדרת מפתח הצפנה להעברות

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

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

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

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

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

פתרון בעיות בהגדרת ההעברה

אם נתקלתם בבעיות בהגדרת העברת הנתונים, כדאי לעיין במאמר בעיות בהעברת נתונים ב-Blob Storage.

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