טעינת נתונים מ-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 אם רוצים להעביר לטבלת BigLake Iceberg ב-BigQuery.

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

      • בשדה טבלת יעד, מזינים את שם הטבלה שיצרתם לאחסון הנתונים ב-BigQuery. שמות של טבלאות יעד תומכים בפרמטרים.
      • בשדה Azure storage account name (שם חשבון אחסון ב-Azure), מזינים את שם חשבון Blob Storage.
      • בשדה Container name, מזינים את שם הקונטיינר של Blob Storage.
      • בשדה Data path (נתיב נתונים), מזינים את הנתיב לסינון הקבצים שיועברו. דוגמאות
      • בקטע טוקן 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: חובה. הטוקן של 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

משתמשים בשיטה 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.

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