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

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

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

מגבלות

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

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

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

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

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

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

המסוף

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

      • בשדה Number of errors allowed, מזינים מספר שלם שמייצג את המספר המקסימלי של רשומות לא תקינות שאפשר להתעלם מהן. ערך ברירת המחדל הוא 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, בוחרים שם של נושא לפרסום או לוחצים על 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

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

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