טעינת נתונים מ-Amazon S3 ל-BigQuery

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

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

לפני שיוצרים העברת נתונים מ-Amazon S3:

מגבלות

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

  • אי אפשר להגדיר פרמטרים לחלק של הקטגוריה ב-URI של Amazon S3.
  • העברות נתונים מ-Amazon S3 עם הפרמטר Write disposition שמוגדר לערך WRITE_TRUNCATE יעבירו את כל הקבצים התואמים אל Google Cloud במהלך כל הפעלה. יכול להיות שבעקבות זאת יחולו עלויות נוספות על העברת נתונים יוצאים ב-Amazon S3. מידע נוסף על הקבצים שמועברים במהלך הרצה זמין במאמר ההשפעה של התאמת קידומות לעומת התאמת תווים כלליים.
  • אין תמיכה בהעברות נתונים מאזורים של AWS GovCloud‏ (us-gov).
  • אין תמיכה בהעברות נתונים אל מיקומים ב-BigQuery Omni.

  • יכול להיות שיש מגבלות נוספות, בהתאם לפורמט של נתוני המקור ב-Amazon S3. למידע נוסף:

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

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

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

התפקידים הנדרשים ב-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.

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

כדאי לעיין במסמכי התיעוד של Amazon S3 כדי לוודא שהגדרתם את כל ההרשאות שנדרשות להפעלת העברת הנתונים. לפחות, צריך להחיל על נתוני המקור ב-Amazon S3 את המדיניות המנוהלת של AWS‏ AmazonS3ReadOnlyAccess.

הגדרת העברת נתונים מ-Amazon S3

כדי ליצור העברת נתונים מ-Amazon S3:

המסוף

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

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

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

  3. בדף Create Transfer:

    • בקטע Source type, בוחרים באפשרות Amazon S3 בשדה Source.

      מקור ההעברה

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

      שם ההעברה

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

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

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

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

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

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

      • בשדה טבלת יעד, מזינים את השם של הטבלה שיצרתם כדי לאחסן את הנתונים ב-BigQuery. שמות הטבלאות ביעד תומכים בפרמטרים.
      • בשדה Amazon S3 URI, מזינים את ה-URI בפורמט s3://mybucket/myfolder/.... מזהי URI תומכים גם בפרמטרים.
      • בשדה Access key ID (מזהה מפתח הגישה), מזינים את מזהה מפתח הגישה.
      • בקטע מפתח גישה סודי, מזינים את מפתח הגישה הסודי.
      • בקטע פורמט קובץ בוחרים את פורמט הנתונים (JSON עם תווי שורה, CSV,‏ Avro,‏ Parquet או ORC).
      • בקטע Write Disposition (הגדרת כתיבה), בוחרים אחת מהאפשרויות הבאות:
        • ‫WRITE_APPEND כדי להוסיף נתונים חדשים לטבלת היעד הקיימת. ‫WRITE_APPEND הוא ערך ברירת המחדל של העדפת הכתיבה.
        • ‫WRITE_TRUNCATE כדי להחליף את הנתונים בטבלת היעד במהלך כל הרצה של העברת הנתונים.

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

      פרטי המקור ב-S3

    • בקטע אפשרויות העברה – כל הפורמטים:

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

      אפשרויות העברה בכל הפורמטים

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

      התעלמות מערכים לא ידועים

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

      אפשרויות CSV

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

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

    • (אופציונלי) בקטע אפשרויות להתראות:

      • לוחצים על המתג כדי להפעיל התראות באימייל. אם תפעילו את האפשרות הזו, האדמין של ההעברה יקבל התראה באימייל אם העברת הנתונים תיכשל.
      • בקטע Select a Pub/Sub topic, בוחרים את שם הנושא או לוחצים על Create a topic כדי ליצור נושא. האפשרות הזו מגדירה התראות על הפעלת Pub/Sub להעברת הנתונים.

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

BQ

מזינים את הפקודה bq mk ומספקים את האפשרות ליצירת העברה – --transfer_config.

bq mk \
--transfer_config \
--project_id=project_id \
--data_source=data_source \
--display_name=name \
--target_dataset=dataset \
--service_account_name=service_account \
--params='parameters'

כאשר:

  • ‫project_id: אופציונלי. מזהה הפרויקט ב- Google Cloud . אם לא מציינים את --project_id כדי לציין פרויקט מסוים, המערכת משתמשת בפרויקט ברירת המחדל.
  • ‫data_source: חובה. מקור הנתונים – amazon_s3.
  • ‫display_name: חובה. השם המוצג של הגדרת העברת הנתונים. שם ההעברה יכול להיות כל ערך שיעזור לכם לזהות את ההעברה אם תצטרכו לשנות אותה בהמשך.
  • ‫dataset: חובה. מערך נתוני היעד להגדרת העברת הנתונים.
  • ‫service_account: השם של חשבון השירות שמשמש לאימות העברת הנתונים. חשבון השירות צריך להיות בבעלות אותו project_id ששימש ליצירת העברת הנתונים, וצריכות להיות לו כל ההרשאות הנדרשות.

  • ‫parameters: חובה. הפרמטרים של הגדרת ההעברה שנוצרה בפורמט JSON. לדוגמה: --params='{"param":"param_value"}'. אלה הפרמטרים להעברה מ-Amazon S3:

    • ‫destination_table_name_template: חובה. השם של טבלת היעד.

    • ‫data_path: חובה. כתובת ה-URI של Amazon S3, בפורמט הבא:

      s3://mybucket/myfolder/...

      מזהי URI תומכים גם בפרמטרים.

    • ‫access_key_id: חובה. המזהה של מפתח הגישה.

    • ‫secret_access_key: חובה. מפתח הגישה הסודי.

    • ‫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. האם להתעלם מערכים לא ידועים בנתונים.

    • ‫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.

לדוגמה, הפקודה הבאה יוצרת העברת נתונים ב-Amazon S3 בשם My Transfer עם ערך data_path של s3://mybucket/myfile/*.csv, מערך נתונים של יעד mydataset ו-file_format CSV. בדוגמה הזו מופיעים ערכים לא ברירת מחדל לפרמטרים האופציונליים שמשויכים ל-CSV file_format.

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

bq mk --transfer_config \
--target_dataset=mydataset \
--display_name='My Transfer' \
--params='{"data_path":"s3://mybucket/myfile/*.csv",
"destination_table_name_template":"MyTable",
"file_format":"CSV",
"write_disposition":"WRITE_APPEND",
"max_bad_records":"1",
"ignore_unknown_values":"true",
"field_delimiter":"|",
"skip_leading_rows":"1",
"allow_quoted_newlines":"true",
"allow_jagged_rows":"false"}' \
--data_source=amazon_s3

אחרי הרצת הפקודה, תקבלו הודעה כמו זו:

[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

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי 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 amazon s3 transfer config.
public class CreateAmazonS3Transfer {

  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";
    // Amazon S3 Bucket Uri with read role permission
    String sourceUri = "s3://your-bucket-name/*";
    String awsAccessKeyId = "MY_AWS_ACCESS_KEY_ID";
    String awsSecretAccessId = "AWS_SECRET_ACCESS_ID";
    String sourceFormat = "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", Value.newBuilder().setStringValue(sourceUri).build());
    params.put("access_key_id", Value.newBuilder().setStringValue(awsAccessKeyId).build());
    params.put("secret_access_key", Value.newBuilder().setStringValue(awsSecretAccessId).build());
    params.put("source_format", Value.newBuilder().setStringValue(sourceFormat).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 Aws S3 Config Name")
            .setDataSourceId("amazon_s3")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createAmazonS3Transfer(projectId, transferConfig);
  }

  public static void createAmazonS3Transfer(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("Amazon s3 transfer created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("Amazon s3 transfer was not created." + ex.toString());
    }
  }
}

ההשפעה של התאמת תחילית לעומת התאמה של תווים כלליים לחיפוש

‫Amazon S3 API תומך בהתאמה של קידומות, אבל לא בהתאמה של תווים כלליים לחיפוש. כל הקבצים ב-Amazon S3 שתואמים לקידומת יועברו אל Google Cloud. עם זאת, רק נתונים שתואמים ל-URI של Amazon S3 בהגדרת ההעברה ייטענו בפועל ל-BigQuery. התוצאה יכולה להיות עלויות גבוהות מדי של העברת נתונים יוצאים מ-Amazon S3 לקבצים שמועברים אבל לא נטענים ל-BigQuery.

לדוגמה, נתיב הנתונים הזה:

s3://bucket/folder/*/subfolder/*.csv

בנוסף לקבצים האלה במיקום המקור:

s3://bucket/folder/any/subfolder/file1.csv
s3://bucket/folder/file2.csv

כתוצאה מכך, כל הקבצים ב-Amazon S3 עם הקידומת s3://bucket/folder/ יועברו אל Google Cloud. בדוגמה הזו, גם file1.csv וגם file2.csv יועברו.

עם זאת, רק קבצים שתואמים ל-s3://bucket/folder/*/subfolder/*.csv ייטענו בפועל ל-BigQuery. בדוגמה הזו, רק file1.csv ייטען ל-BigQuery.

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

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

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