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

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

במאמר מבוא להעברות נתונים מ-Blob Storage מוסבר איך פועלת העברה מ-Blob Storage.

מגבלות

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

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

לפני שיוצרים העברת נתונים מ-Blob 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.

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

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

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

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

המסוף

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

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

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

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

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

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

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

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

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

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

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

    • בקטע Data source details:

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

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

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

    • בקטע Transfer options:

      • בשדה Number of errors allowed, מזינים מספר שלם שמייצג את המספר המקסימלי של רשומות לא תקינות שאפשר להתעלם מהן. ערך ברירת המחדל הוא 0.
      • ‫(אופציונלי) בשדה Decimal target types, מזינים רשימה מופרדת בפסיקים של סוגי נתונים אפשריים ב-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, בוחרים שם של נושא לפרסום או לוחצים על Create a topic כדי ליצור נושא.

    • אם אתם משתמשים ב-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: שדה חובה. הטוקן של Azure SAS.
    • ‫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

משתמשים ב-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 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 לטבלאות היעד בהפעלה הבאה של ההעברה, ומחליף את כל מפתחות ה-CMEK המיושנים במפתח ה-CMEK החדש במהלך ההעברה. מידע נוסף זמין במאמר עדכון העברה.

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

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

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

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