העברת טבלאות מנוהלות של Hive אל Google Cloud

במאמר הזה מוסבר איך להעביר טבלאות מנוהלות של Hive אל Google Cloud.

אתם יכולים להשתמש במחבר להעברת טבלאות מנוהלות של Hive בשירות העברת הנתונים ל-BigQuery כדי להעביר בצורה חלקה את הטבלאות שמנוהלות על ידי Hive metastore. המחבר תומך בפורמטים של Hive ו-Iceberg מסביבות מקומיות ומסביבות ענן אל Google Cloud. מחבר ההעברה של טבלאות מנוהלות ב-Hive תומך בקבצים שמאוחסנים במקורות הנתונים הבאים:

HDFS
Amazon S3
‫Azure Blob Storage או Azure Data Lake Storage Gen2

באמצעות מחבר ההעברה של טבלאות מנוהלות ב-Hive, אתם יכולים לרשום את הטבלאות המנוהלות ב-Hive ב-Dataproc Metastore, ב-BigLake metastore או ב-BigLake metastore Iceberg REST Catalog, תוך שימוש ב-Cloud Storage כאחסון הקבצים.

המחבר הזה תומך בהעברות מלאות ובהעברות של מטא-נתונים בלבד. העברות מלאות יעבירו גם את הנתונים וגם את המטא-נתונים מטבלאות המקור למאגר המטא-נתונים של היעד. אתם יכולים לבצע העברה של מטא-נתונים בלבד אם כבר העברתם את הנתונים שלכם ל-Cloud Storage.

בתרשים הבא מוצג תהליך העברת הטבלאות מאשכול Hadoop.

סקירה כללית על העברת טבלאות מ-Hive Data Lake ל-BigQuery.

מגבלות

העברות של טבלאות מנוהלות ב-Hive כפופות למגבלות הבאות:

כדי להעביר טבלאות Apache Iceberg, צריך לרשום את הטבלאות במאגר המטא-נתונים של BigLake כדי לאפשר גישת כתיבה למנועי קוד פתוח (כמו Apache Spark או Flink) וגישת קריאה ל-BigQuery.
כדי להעביר טבלאות מנוהלות של Hive, צריך לרשום את הטבלאות ב-Dataproc Metastore כדי לאפשר גישת כתיבה למנועי קוד פתוח וגישת קריאה ל-BigQuery.
כדי להעביר טבלאות מנוהלות של Hive ל-BigQuery, צריך להשתמש בכלי שורת הפקודה של BigQuery.

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

לפני שתקבעו מועד להעברת טבלאות מנוהלות של Hive, תצטרכו לבצע את הפעולות הבאות:

יצירת קובץ מטא-נתונים ל-Apache Hive

מריצים את dwh-migration-dumper הכלי כדי לחלץ מטא-נתונים עבור Apache Hive. הכלי יוצר קובץ בשם hive-dumper-output.zip בקטגוריה של Cloud Storage, שנקראת במסמך הזה DUMPER_BUCKET.

הפעלת ממשקי ה-API

מפעילים את ממשקי ה-API הבאים בפרויקטGoogle Cloud :

Data Transfer API
Storage Transfer API

סוכן שירות נוצר כשמפעילים את Data Transfer API.

הגדרת ההרשאות

יוצרים חשבון שירות ומעניקים לו את התפקיד BigQuery Admin (אדמין ב-BigQuery) ‏(roles/bigquery.admin). חשבון השירות הזה משמש ליצירת הגדרת ההעברה.
סוכן שירות (P4SA) נוצר כשמפעילים את Data Transfer API. מקצים לו את התפקידים הבאים:
- roles/metastore.metadataOwner
- roles/storagetransfer.admin
- roles/serviceusage.serviceUsageConsumer
- roles/storage.objectAdmin
  - אם מעבירים מטא-נתונים לטבלאות BigLake Iceberg, צריך להעניק גם את התפקיד roles/bigquery.admin.
  - אם מעבירים מטא-נתונים למאגר מטא-נתונים של BigLake Iceberg REST Catalog, צריך להעניק גם את התפקיד roles/biglake.admin.

נותנים לסוכן השירות את התפקיד roles/iam.serviceAccountTokenCreator באמצעות הפקודה הבאה:

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT --member serviceAccount:service-PROJECT_NUMBER@gcp-sa-bigquerydatatransfer.iam.gserviceaccount.com --role roles/iam.serviceAccountTokenCreator

הגדרת Storage Transfer Agent לאגמי נתונים ב-HDFS

חובה אם הקובץ מאוחסן ב-HDFS. כדי להגדיר את סוכן העברת האחסון שנדרש להעברה של אגם נתונים ב-HDFS:

מגדירים הרשאות להרצת הסוכן להעברת נתונים מהאחסון באשכול Hadoop.
מתקינים את Docker במחשבים של סוכנים מקומיים.
יוצרים מאגר סוכני שירות של Storage Transfer Service בפרויקט Google Cloud .
מתקינים סוכנים במכונות הסוכנים המקומיות.

הגדרת הרשאות ל-Storage Transfer Service עבור Amazon S3

השדה הזה נדרש אם הקובץ מאוחסן ב-Amazon S3. העברות מ-Amazon S3 הן העברות ללא סוכן, שדורשות הרשאות ספציפיות. כדי להגדיר את Storage Transfer Service להעברה מ-Amazon S3, צריך לבצע את הפעולות הבאות:

הגדרת הרשאות להעברה ללא סוכן.
הגדרת פרטי גישה ל-AWS Amazon S3
- אחרי שמגדירים את פרטי הגישה, חשוב לזכור את המזהה של מפתח הגישה ואת מפתח הגישה הסודי.
אם בפרויקט AWS שלכם מוגדרות הגבלות על כתובות IP, צריך להוסיף את טווחי כתובות ה-IP שמשמשים את העובדים של Storage Transfer Service לרשימת כתובות ה-IP המותרות.

הגדרת הרשאות של Storage Transfer Service ל-Microsoft Azure Storage

חובה אם הקובץ מאוחסן ב-Azure Blob Storage או ב-Azure Data Lake Storage Gen2. העברות מ-Microsoft Azure Storage הן העברות ללא סוכן, שדורשות הרשאות ספציפיות. כדי להגדיר את Storage Transfer Service להעברה של Microsoft Azure Storage:

הגדרת הרשאות להעברה ללא סוכן.
יוצרים אסימון חתימת גישה משותפת (SAS) לחשבון האחסון שלכם ב-Microsoft Azure.
- אחרי שיוצרים את טוקן ה-SAS, חשוב לשים לב לטוקן.
אם חשבון האחסון שלכם ב-Microsoft Azure משתמש בהגבלות על כתובות IP, צריך להוסיף לרשימת כתובות ה-IP המותרות את טווחי כתובות ה-IP שמשמשים את העובדים של Storage Transfer Service.

תזמון העברה של טבלאות מנוהלות ב-Hive

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

המסוף

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

מעבר אל "העברות נתונים"
לוחצים על Create transfer (יצירת העברה).
בקטע סוג המקור, בוחרים באפשרות Hive Managed Tables (טבלאות מנוהלות של Hive) מהרשימה מקור.
בשדה Location, בוחרים סוג מיקום ואז בוחרים אזור.
בקטע Transfer config name (שם הגדרת ההעברה), בשדה Display name (שם מוצג), מזינים שם להעברת הנתונים.
בקטע Schedule options:
- ברשימה תדירות החזרה, בוחרים אפשרות כדי לציין באיזו תדירות יתבצע העברת הנתונים. כדי לציין תדירות חזרה מותאמת אישית, בוחרים באפשרות בהתאמה אישית. אם בוחרים באפשרות על פי דרישה, ההעברה הזו תתבצע כשמפעילים אותה באופן ידני.
- אם רלוונטי, בוחרים באפשרות התחלה מיידית או התחלה בשעה שנקבעה, ומזינים תאריך התחלה ומשך זמן הפעלה.
בקטע Data source details (פרטים של מקור הנתונים):
1. בקטע Transfer strategy (שיטת העברה), בוחרים באחת מהאפשרויות הבאות:
  - ‫FULL_TRANSFER: העברת כל הנתונים ורישום המטא-נתונים במאגר המטא-נתונים של היעד. זו האפשרות שמוגדרת כברירת המחדל.
  - ‫METADATA_ONLY: רישום מטא-נתונים בלבד. הנתונים צריכים להיות כבר במיקום הנכון ב-Cloud Storage שאליו מתייחסים במטא-נתונים.
2. בקטע Table name patterns (תבניות של שמות טבלאות), מציינים את הטבלאות של אגם הנתונים ב-HDFS שרוצים להעביר. אפשר לציין שמות של טבלאות או תבניות שמתאימות לטבלאות במסד הנתונים של HDFS. כדי לציין דפוסי טבלאות, צריך להשתמש בתחביר של ביטויים רגולריים ב-Java. לדוגמה:
  - ‫db1..* תואם לכל הטבלאות ב-db1.
  - ‫db1.table1;db2.table2 תואם ל-table1 ב-db1 ול-table2 ב-db2.
3. בשדה BQMS discovery dump gcs path (נתיב GCS של קובץ ה-dump של גילוי BQMS), מזינים את הנתיב לקטגוריה שמכילה את קובץ hive-dumper-output.zip שיצרתם כשיצרתם קובץ מטא-נתונים עבור Apache Hive.
4. בוחרים את סוג ה-Metastore מהרשימה הנפתחת:
  - ‫DATAPROC_METASTORE: בוחרים באפשרות הזו כדי לאחסן את המטא-נתונים ב-Dataproc Metastore. חובה לספק את כתובת ה-URL של Dataproc Metastore בכתובת ה-URL של Dataproc Metastore.
  - ‫BIGLAKE_METASTORE: בוחרים באפשרות הזו כדי לאחסן את המטא-נתונים במאגר המטא-נתונים של BigLake. צריך לציין מערך נתונים ב-BigQuery בשדה BigQuery dataset.
  - ‫BIGLAKE_REST_CATALOG: בוחרים באפשרות הזו כדי לאחסן את המטא-נתונים במאגר המטא-נתונים של BigLake, בקטלוג Iceberg REST.
5. בשדה Destination gcs path (נתיב היעד ב-GCS), מזינים נתיב לקטגוריה של Cloud Storage שבה רוצים לאחסן את הנתונים שהועברו.
6. אופציונלי: בשדה Service account, מזינים חשבון שירות לשימוש בהעברת הנתונים הזו. חשבון השירות צריך להיות שייך לאותוGoogle Cloud פרויקט שבו נוצרו הגדרות ההעברה ומערך נתוני היעד.
7. אופציונלי: אתם יכולים להפעיל את האפשרות Use translation output כדי להגדיר נתיב ייחודי ב-Cloud Storage ומסד נתונים לכל טבלה שמועברת. כדי לעשות זאת, מציינים את הנתיב לתיקייה ב-Cloud Storage שמכילה את תוצאות התרגום בשדה BQMS translation output gcs path. מידע נוסף זמין במאמר הגדרת פלט התרגום. השדה הזה זמין רק אם שיטת ההעברה מוגדרת לערך FULL_TRANSFER.
  - אם מציינים נתיב של Cloud Storage לפלט התרגום, נתיב היעד של Cloud Storage ומערך הנתונים ב-BigQuery יתבססו על הקבצים בנתיב הזה.
8. בקטע סוג אחסון, בוחרים אחת מהאפשרויות הבאות. השדה הזה זמין רק אם שיטת ההעברה מוגדרת לערך FULL_TRANSFER:
  - ‫HDFS: בוחרים באפשרות הזו אם האחסון של הקבצים הוא HDFS. בשדה STS agent pool name (שם מאגר סוכני STS), צריך לציין את השם של מאגר הסוכנים שיצרתם כשהגדרתם את Storage Transfer Agent.
  - ‫S3: בוחרים באפשרות הזו אם האחסון של הקבצים הוא Amazon S3. בשדות מזהה מפתח הגישה ומפתח הגישה הסודי, צריך לספק את מזהה מפתח הגישה ואת מפתח הגישה הסודי שיצרתם כשהגדרתם את פרטי הגישה.
  - ‫AZURE: בוחרים באפשרות הזו אם האחסון של הקבצים הוא Azure Blob Storage. בשדה SAS token, צריך לספק את אסימון ה-SAS שיצרתם כשהגדרתם את פרטי הגישה.

BQ

כדי לתזמן העברה של טבלאות מנוהלות ב-Hive, מזינים את הפקודה bq mk ומספקים את דגל יצירת ההעברה --transfer_config:

  bq mk --transfer_config
  --data_source=hadoop
  --display_name='TRANSFER_NAME'
  --service_account_name='SERVICE_ACCOUNT'
  --project_id='PROJECT_ID'
  --location='REGION'
  --params='{
    "transfer_strategy":"TRANSFER_STRATEGY",
    "table_name_patterns":"LIST_OF_TABLES",
    "table_metadata_path":"gs://DUMPER_BUCKET/hive-dumper-output.zip",
    "target_gcs_file_path":"gs://MIGRATION_BUCKET",
    "metastore":"METASTORE",
    "destination_dataproc_metastore":"DATAPROC_METASTORE_URL",
    "destination_bigquery_dataset":"BIGLAKE_METASTORE_DATASET",
    "translation_output_gcs_path":"gs://TRANSLATION_OUTPUT_BUCKET/metadata/config/default_database/",
    "storage_type":"STORAGE_TYPE",
    "agent_pool_name":"AGENT_POOL_NAME",
    "aws_access_key_id":"AWS_ACCESS_KEY_ID",
    "aws_secret_access_key":"AWS_SECRET_ACCESS_KEY",
    "azure_sas_token":"AZURE_SAS_TOKEN"
    }'

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

‫TRANSFER_NAME: השם המוצג של הגדרות ההעברה. שם ההעברה יכול להיות כל ערך שיעזור לכם לזהות את ההעברה אם תצטרכו לשנות אותה בהמשך.
‫SERVICE_ACCOUNT: השם של חשבון השירות שמשמש לאימות ההעברה. חשבון השירות צריך להיות בבעלות אותו project_idששימש ליצירת ההעברה, וצריכות להיות לו כל ההרשאות הנדרשות.
‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud . אם לא מציינים את --project_id כדי לציין פרויקט מסוים, המערכת משתמשת בפרויקט ברירת המחדל.
‫REGION: המיקום של הגדרות ההעברה האלה.
‫TRANSFER_STRATEGY: (אופציונלי) מציינים אחד מהערכים הבאים:
- ‫FULL_TRANSFER: העברת כל הנתונים ורישום המטא-נתונים במאגר המטא-נתונים של היעד. זה ערך ברירת המחדל.
- ‫METADATA_ONLY: רישום מטא-נתונים בלבד. הנתונים צריכים להיות כבר במיקום הנכון ב-Cloud Storage שאליו מתייחסים במטא-נתונים.
‫LIST_OF_TABLES: רשימה של ישויות להעברה. משתמשים במפרט שמות היררכי – database.table. השדה הזה תומך בביטויים רגולריים של RE2 כדי לציין טבלאות. לדוגמה:
- ‫db1..*: מציין את כל הטבלאות במסד הנתונים
- ‫db1.table1;db2.table2: רשימה של טבלאות
‫DUMPER_BUCKET: קטגוריית Cloud Storage שמכילה את הקובץ hive-dumper-output.zip.
‫MIGRATION_BUCKET: נתיב GCS ליעד שאליו ייטענו כל קובצי הבסיס. זמין רק אם transfer_strategy הוא FULL_TRANSFER.
‫METASTORE: סוג חנות המטא-נתונים שאליה רוצים להעביר את הנתונים. מגדירים את הערך של המאפיין הזה לאחד מהערכים הבאים:
- ‫DATAPROC_METASTORE: להעברת מטא-נתונים אל Dataproc Metastore.
- ‫BIGLAKE_METASTORE: כדי להעביר מטא-נתונים למאגר המטא-נתונים של BigLake.
- ‫BIGLAKE_REST_CATALOG: כדי להעביר מטא-נתונים ל-BigLake metastore Iceberg REST Catalog.
‫DATAPROC_METASTORE_URL: כתובת ה-URL של Dataproc Metastore. חובה אם הערך של metastore הוא DATAPROC_METASTORE.
‫BIGLAKE_METASTORE_DATASET: מערך הנתונים ב-BigQuery של מאגר המטא-נתונים של BigLake. חובה אם הערך של metastore הוא BIGLAKE_METASTORE והערך של transfer_strategy הוא FULL_TRANSFER.
‫TRANSLATION_OUTPUT_BUCKET: (אופציונלי) מציינים קטגוריה של Cloud Storage לפלט התרגום. מידע נוסף זמין במאמר שימוש בתוצאות התרגום. זמין רק אם transfer_strategy הוא FULL_TRANSFER.
‫STORAGE_TYPE: ציון האחסון הבסיסי של הקבצים בטבלאות. הסוגים הנתמכים הם HDFS,‏ S3 ו-AZURE. חובה אם הערך של transfer_strategy הוא FULL_TRANSFER.
‫AGENT_POOL_NAME: השם של מאגר הסוכנים שמשמש ליצירת סוכנים. חובה אם הערך של storage_type הוא HDFS.
‫AWS_ACCESS_KEY_ID: מזהה מפתח הגישה מפרטי הגישה. חובה אם הערך של storage_type הוא S3.
‫AWS_SECRET_ACCESS_KEY: מפתח הגישה הסודי מפרטי הגישה. חובה אם הערך של storage_type הוא S3.
‫AZURE_SAS_TOKEN: אסימון ה-SAS מפרטי הגישה. חובה אם הערך של storage_type הוא AZURE.

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

בסיום ההעברה, הטבלאות באשכול Hadoop יועברו אל MIGRATION_BUCKET.

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

בקטעים הבאים מוסבר איך להגדיר העברות של טבלאות מנוהלות ב-Hive.

העברות מצטברות

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

אפשרויות תזמון העברה

כברירת מחדל, ההעברות מתוזמנות לביצוע כל 24 שעות. כדי להגדיר את התדירות של ההעברות, מוסיפים את הדגל --schedule להגדרת ההעברה ומציינים את לוח הזמנים של ההעברה באמצעות התחביר schedule. ההעברות של טבלאות מנוהלות ב-Hive צריכות להתבצע בהפרש של 24 שעות לפחות בין ההרצות.

להעברות חד-פעמיות, אפשר להוסיף את הדגל end_time להגדרת ההעברה כדי להפעיל את ההעברה רק פעם אחת.

הגדרת פלט התרגום

אפשר להגדיר נתיב ייחודי ב-Cloud Storage ומסד נתונים לכל טבלה שמועברת. כדי לעשות זאת, מבצעים את השלבים הבאים כדי ליצור קובץ YAML למיפוי טבלאות שאפשר להשתמש בו בהגדרת ההעברה.

יוצרים קובץ YAML של הגדרות (עם הסיומת config.yaml) בתיקייה DUMPER_BUCKET שמכיל את ההגדרות הבאות:
```
    type: object_rewriter
    relation:
    - match:
        relationRegex: ".*"
      external:
        location_expression: "'gs://MIGRATION_BUCKET/' + table.schema + '/' + table.name"
```
- מחליפים את MIGRATION_BUCKET בשם של קטגוריה של Cloud Storage שמשמשת כיעד לקובצי הטבלה שהועברו. השדה location_expression הוא ביטוי של Common Expression Language ‏ (CEL).
יוצרים עוד קובץ YAML להגדרות (עם הסיומת config.yaml) בתיקייה DUMPER_BUCKET, שמכיל את ההגדרות הבאות:
```
    type: experimental_object_rewriter
    relation:
      - match:
          schema: SOURCE_DATABASE
        outputName:
          database: null
          schema: TARGET_DATABASE
```
- מחליפים את SOURCE_DATABASE ואת TARGET_DATABASE בשם של מסד הנתונים של המקור ובמסד הנתונים של Dataproc Metastore או במערך הנתונים של BigQuery, בהתאם למאגר המטא-נתונים שנבחר. אם אתם מגדירים את מסד הנתונים למאגר המטא-נתונים של BigLake, אתם צריכים לוודא שמערך הנתונים ב-BigQuery קיים.
מידע נוסף על קובץ ה-YAML של ההגדרות זמין במאמר הנחיות ליצירת קובץ YAML של הגדרות.
מריצים את הפקודה הבאה כדי ליצור קובץ YAML של מיפוי טבלאות:
```
curl -d '{
  "tasks": {
      "string": {
        "type": "HiveQL2BigQuery_Translation",
        "translation_details": {
            "target_base_uri": "TRANSLATION_OUTPUT_BUCKET",
            "source_target_mapping": {
              "source_spec": {
                  "base_uri": "DUMPER_BUCKET"
              }
            },
            "target_types": ["metadata"]
        }
      }
  }
  }' \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows
```
מחליפים את מה שכתוב בשדות הבאים:
- ‫TRANSLATION_OUTPUT_BUCKET: (אופציונלי) מציינים קטגוריה ב-Cloud Storage לפלט התרגום. מידע נוסף זמין במאמר שימוש בתוצאות התרגום.
- ‫DUMPER_BUCKET: ה-URI הבסיסי של קטגוריה של Cloud Storage שמכיל את hive-dumper-output.zip ואת קובץ ההגדרות YAML.
- ‫TOKEN: טוקן OAuth. אפשר ליצור את זה בשורת הפקודה באמצעות הפקודה gcloud auth print-access-token.
- ‫PROJECT_ID: הפרויקט שבו יתבצע התרגום.
- ‫LOCATION: המיקום שבו המשימה מעובדת. לדוגמה, eu או us.
מעקב אחרי הסטטוס של העבודה. בסיום, נוצר קובץ מיפוי לכל טבלה במסד הנתונים בנתיב מוגדר מראש ב-TRANSLATION_OUTPUT_BUCKET.

ארגון ההפעלה של כלי ה-dumper באמצעות הפקודה `cron`

אפשר להשתמש במשימה של cron כדי להריץ את הכלי dwh-migration-dumper ולהפוך את ההעברות המצטברות לאוטומטיות. באמצעות אוטומציה של חילוץ המטא-נתונים, אתם מוודאים שקובץ עדכני של נתוני Hadoop זמין להפעלות עתידיות של העברה מצטברת.

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

לפני שמשתמשים בסקריפט האוטומטי הזה, צריך להשלים את הדרישות המוקדמות להתקנת כלי ה-dumper. כדי להריץ את הסקריפט, צריך להתקין את הכלי dwh-migration-dumper ולהגדיר את הרשאות ה-IAM הנדרשות.

תזמון הפעולה האוטומטית

שומרים את הסקריפט הבא בקובץ מקומי. הסקריפט הזה מיועד להגדרה ולהפעלה על ידי דמון של cron כדי לאפשר אוטומציה של תהליך החילוץ וההעלאה של פלט הכלי dumper:

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e
# Treat unset variables as an error when substituting.
set -u
# Pipelines return the exit status of the last command to exit with a non-zero status.
set -o pipefail

# These values are used if not overridden by command-line options.
DUMPER_EXECUTABLE="DUMPER_PATH/dwh-migration-dumper"
GCS_BASE_PATH="gs://PATH_TO_DUMPER_OUTPUT"
LOCAL_BASE_DIR="LOCAL_BASE_DIRECTORY_PATH"

# Function to display usage information
usage() {
  echo "Usage: $0 [options]"
  echo ""
  echo "Runs the dwh-migration-dumper tool and uploads its output to provided GCS path."
  echo ""
  echo "Options:"
  echo "  --dumper-executable   The full path to the dumper executable. (Required)"
  echo "  --gcs-base-path       The base GCS path for output files. (Required)"
  echo "  --local-base-dir      The local base directory for logs and temp files. (Required)"
  echo "  -h, --help                  Display this help message and exit."
  exit 1
}

# This loop processes command-line options and overrides the default configuration.
while [[ "$#" -gt 0 ]]; do
  case $1 in
      --dumper-executable)
          DUMPER_EXECUTABLE="$2"
          shift # past argument
          shift # past value
          ;;
      --gcs-base-path)
          GCS_BASE_PATH="$2"
          shift
          shift
          ;;
      --local-base-dir)
          LOCAL_BASE_DIR="$2"
          shift
          shift
          ;;
      -h|--help)
          usage
          ;;
      *)
          echo "Unknown option: $1"
          usage
          ;;
  esac
done

# This runs AFTER parsing arguments to ensure no placeholder values are left.
if [[ "$DUMPER_EXECUTABLE" == "DUMPER_PATH"* || "$GCS_BASE_PATH" == "gs://PATH_TO_DUMPER_OUTPUT" || "$LOCAL_BASE_DIR" == "LOCAL_BASE_DIRECTORY_PATH" ]]; then
  echo "ERROR: One or more configuration variables have not been set. Please provide them as command-line arguments or edit the script." >&2
  echo "Run with --help for more information." >&2
  exit 1
fi

# Create unique timestamp and directories for this run
EPOCH=$(date +%s)
LOCAL_LOG_DIR="${LOCAL_BASE_DIR}/logs"
mkdir -p "${LOCAL_LOG_DIR}" # Ensures the base and logs directories exist

# Define the unique log and zip file path for this run
LOG_FILE="${LOCAL_LOG_DIR}/dumper_execution_${EPOCH}.log"
ZIP_FILE_NAME="dts-cron-dumper-output_${EPOCH}.zip"
LOCAL_ZIP_PATH="${LOCAL_BASE_DIR}/${ZIP_FILE_NAME}"

echo "Script execution started. All subsequent output will be logged to: ${LOG_FILE}"

# --- Helper Functions ---

log() { echo "$(date '+%Y-%m-%d %H:%M:%S') - $@" >> "${LOG_FILE}"; }

cleanup() {
  local path_to_remove="$1"
  log "Cleaning up local file/directory: ${path_to_remove}..."
  rm -rf "${path_to_remove}"
}

# This function is called when the script exits to ensure cleanup and logging happen reliably.
handle_exit() {
  local exit_code=$?
  # Only run the failure logic if the script is exiting with an error
  if [[ ${exit_code} -ne 0 ]]; then
      log "ERROR: Script is exiting with a failure code (${exit_code})."
      local gcs_log_path_on_failure="${GCS_BASE_PATH}/logs/$(basename "${LOG_FILE}")"
      log "Uploading log file to ${gcs_log_path_on_failure} for debugging..."
      # Attempt to upload the log file on failure, but don't let this command cause the script to exit.
      gsutil cp "${LOG_FILE}" "${gcs_log_path_on_failure}" > /dev/null 2>&1 || log "WARNING: Failed to upload log file to GCS."

  else
      # SUCCESS PATH
      log "Script finished successfully. Now cleaning up local zip file...."
      # Clean up the local zip file ONLY on success
      cleanup "${LOCAL_ZIP_PATH}"
  fi

  log "*****Script End*****"
  exit ${exit_code}
}

# Trap the EXIT signal to run the handle_exit function, ensuring cleanup always happens.
trap handle_exit EXIT

# Validates the dumper log file based on a strict set of rules.
validate_dumper_output() {
  local log_file_to_check="$1"

  # Check for the specific success message from the dumper tool.
  if grep -q "Dumper execution: SUCCEEDED" "${log_file_to_check}"; then
      log "Validation Successful: Found 'Dumper execution: SUCCEEDED' message."
      return 0 # Success
  else
      log "ERROR: Validation failed. The 'Dumper execution: SUCCEEDED' message was not found."
      return 1 # Failure
  fi
}

# --- Main Script Logic ---

log "*****Script Start*****"
log "Dumper Executable: ${DUMPER_EXECUTABLE}"
log "GCS Base Path: ${GCS_BASE_PATH}"
log "Local Base Directory: ${LOCAL_BASE_DIR}"

# Use an array to build the command safely
dumper_command_args=(
  "--connector" "hiveql"
  "--output" "${LOCAL_ZIP_PATH}"
)

log "Starting dumper tool execution..."
log "COMMAND: ${DUMPER_EXECUTABLE} ${dumper_command_args[*]}"

"${DUMPER_EXECUTABLE}" "${dumper_command_args[@]}" >> "${LOG_FILE}" 2>&1

log "Dumper process finished."

# Validate the output from the dumper execution for success or failure.
validate_dumper_output "${LOG_FILE}"

# Upload the ZIP file to GCS
gcs_zip_path="${GCS_BASE_PATH}/${ZIP_FILE_NAME}"
log "Uploading ${LOCAL_ZIP_PATH} to ${gcs_zip_path}..."

if [ ! -f "${LOCAL_ZIP_PATH}" ]; then
  log "ERROR: Expected ZIP file ${LOCAL_ZIP_PATH} not found after dumper execution."
  # The script will exit here with an error code, and the trap will run.
  exit 1
fi

gsutil cp "${LOCAL_ZIP_PATH}" "${gcs_zip_path}" >> "${LOG_FILE}" 2>&1
log "Upload to GCS successful."

# The script will now exit with code 0. The trap will call cleanup and log the script end.

מריצים את הפקודה הבאה כדי להפוך את הסקריפט לקובץ הפעלה:
```
chmod +x PATH_TO_SCRIPT
```
מתזמנים את הסקריפט באמצעות crontab ומחליפים את המשתנים בערכים המתאימים לעבודה שלכם. מוסיפים רשומה כדי לתזמן את העבודה. בדוגמה הבאה, הסקריפט מופעל כל יום בשעה 2:30:
```
# Run the Hive dumper daily at 2:30 AM for incremental BigQuery transfer.
30 2 * * * PATH_TO_SCRIPT \
  --dumper-executable PATH_TO_DUMPER_EXECUTABLE \
  --gcs-base-path GCS_PATH_TO_UPLOAD_DUMPER_OUTPUT \
  --local-base-dir LOCAL_PATH_TO_SAVE_INTERMEDIARY_FILES
```
כשיוצרים את ההעברה, מוודאים שהשדה table_metadata_path מוגדר לאותו נתיב ב-Cloud Storage שהגדרתם עבור GCS_PATH_TO_UPLOAD_DUMPER_OUTPUT. זהו הנתיב שמכיל את קובצי ה-ZIP של הפלט של הכלי dumper.

שיקולים לתזמון

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

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

מעקב אחרי העברות של טבלאות מנוהלות ב-Hive

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

מעקב אחרי סטטוס ההעברה של טבלה

אפשר גם להריץ את הכלי dwh-dts-status כדי לעקוב אחרי הסטטוס של כל הטבלאות שהועברו במסגרת הגדרות העברה או מסד נתונים מסוים. אפשר גם להשתמש בכלי dwh-dts-status כדי להציג את כל הגדרות ההעברה בפרויקט.

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

לפני שמשתמשים בכלי dwh-dts-status, צריך לבצע את הפעולות הבאות:

מורידים את חבילת dwh-migration-tool של הכלי dwh-dts-status ממאגר GitHub dwh-migration-tools.
מריצים את הפקודה הבאה כדי לאמת את החשבון ב- Google Cloud :
```
gcloud auth application-default login
```
מידע נוסף זמין במאמר הסבר על Application Default Credentials.
מוודאים שלמשתמש מוקצים התפקידים bigquery.admin ו-logging.viewer. מידע נוסף על תפקידי IAM זמין במאמר הפניה לבקרת גישה.

הצגת רשימה של כל הגדרות ההעברה בפרויקט

כדי לראות את כל הגדרות ההעברה בפרויקט, משתמשים בפקודה הבאה:

  ./dwh-dts-status --list-transfer-configs --project-id=[PROJECT_ID] --location=[LOCATION]

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

‫PROJECT_ID : מזהה הפרויקט Google Cloud שבו מתבצעות ההעברות.
‫LOCATION : המיקום שבו נוצרה הגדרת ההעברה.

הפקודה הזו מפיקה טבלה עם רשימה של שמות ומזהים של הגדרות העברה.

הצגת הסטטוסים של כל הטבלאות בהגדרה

כדי לראות את הסטטוס של כל הטבלאות שכלולות בהגדרת העברה, משתמשים בפקודה הבאה:

  ./dwh-dts-status --list-status-for-config --project-id=[PROJECT_ID] --config-id=[CONFIG_ID] --location=[LOCATION]

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

‫PROJECT_ID: מזהה הפרויקט Google Cloud שממנו מופעלות ההעברות.
‫LOCATION: המיקום שבו נוצרה הגדרת ההעברה.
‫CONFIG_ID: המזהה של הגדרות ההעברה שצוינו.

הפקודה הזו מפיקה טבלה עם רשימה של טבלאות וסטטוס ההעברה שלהן, בהגדרת ההעברה שצוינה. הסטטוס של ההעברה יכול להיות אחד מהערכים הבאים: PENDING, RUNNING, SUCCEEDED, FAILED, CANCELLED.

הצגת הסטטוסים של כל הטבלאות במסד נתונים

כדי לראות את הסטטוס של כל הטבלאות שהועברו ממסד נתונים ספציפי, משתמשים בפקודה הבאה:

  ./dwh-dts-status --list-status-for-database --project-id=[PROJECT_ID] --database=[DATABASE]

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

‫PROJECT_ID: מזהה הפרויקט Google Cloud שממנו מופעלות ההעברות.
‫DATABASE:השם של מסד הנתונים שצוין.

הפקודה הזו מוציאה טבלה עם רשימה של טבלאות וסטטוס ההעברה שלהן במסד הנתונים שצוין. הסטטוס של ההעברה יכול להיות אחד מהערכים הבאים: PENDING, RUNNING, SUCCEEDED, FAILED, CANCELLED.

העברת טבלאות מנוהלות של Hive אל Google Cloud

מגבלות

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

יצירת קובץ מטא-נתונים ל-Apache Hive

הפעלת ממשקי ה-API

הגדרת ההרשאות

הגדרת Storage Transfer Agent לאגמי נתונים ב-HDFS

הגדרת הרשאות ל-Storage Transfer Service עבור Amazon S3

הגדרת הרשאות של Storage Transfer Service ל-Microsoft Azure Storage

תזמון העברה של טבלאות מנוהלות ב-Hive

המסוף

BQ

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

העברות מצטברות

אפשרויות תזמון העברה

הגדרת פלט התרגום

ארגון ההפעלה של כלי ה-dumper באמצעות הפקודה cron

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

תזמון הפעולה האוטומטית

שיקולים לתזמון

מעקב אחרי העברות של טבלאות מנוהלות ב-Hive

מעקב אחרי סטטוס ההעברה של טבלה

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

הצגת רשימה של כל הגדרות ההעברה בפרויקט

הצגת הסטטוסים של כל הטבלאות בהגדרה

הצגת הסטטוסים של כל הטבלאות במסד נתונים

ארגון ההפעלה של כלי ה-dumper באמצעות הפקודה `cron`