תרגום שאילתות SQL באמצעות Translation API

במאמר הזה מוסבר איך להשתמש ב-BigQuery Migration API ב-BigQuery כדי לתרגם סקריפטים שנכתבו בניבי SQL אחרים לשאילתות GoogleSQL.

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

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

לפני ששולחים משימת תרגום, צריך לבצע את השלבים הבאים.

בחירת מצב תרגום

‫BigQuery Migration API תומך בשני מצבי תרגום. בשני המצבים משתמשים באותה שיטת API והם פועלים כמשימות אסינכרוניות. ההבדלים בין המצבים הם באופן שבו מספקים את ה-SQL המקורי ובאופן שבו מקבלים את ה-SQL המתורגם:

  • תרגום באצווה: ה-API קורא קובצי מקור מ-Cloud Storage וכותב את הקבצים המתורגמים ואת הדוחות ל-Cloud Storage. אתם יכולים להשתמש בתרגום באצווה כדי לתרגם הרבה קבצים בבת אחת – לדוגמה, כשאתם מעבירים בסיס קוד שלם.
  • תרגום אינטראקטיבי: מעבירים את ה-SQL כמחרוזות מילוליות בגוף הבקשה, וקוראים את ה-SQL המתורגם מהתגובה של תהליך העבודה. אתם לא צריכים לאחסן את ה-SQL או את פלט התרגום ב-Cloud Storage. אתם יכולים להשתמש בתרגום אינטראקטיבי כדי לתרגם שאילתות ספציפיות על פי דרישה – לדוגמה, כשאתם מתרגמים שאילתות מאפליקציה או מכלי למפתחים.

הפעלת התרגום

מפעילים את BigQuery Migration API הנדרש. מידע נוסף מופיע במאמר הפעלת תרגומי SQL.

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

כדי לקבל את ההרשאות שדרושות ליצירת משימות תרגום באמצעות המתרגם האינטראקטיבי, ה-Translation API או המתרגם של SQL באצווה, בקשו מהאדמין להקצות לכם את תפקידי ה-IAM הבאים במשאב parent:

  • צפייה במשימות ההעברה ומעקב אחריהן: צפייה ב-MigrationWorkflow ‏ (roles/bigquerymigration.viewer)
  • שליחת משימות העברה: עורך MigrationWorkflow (roles/bigquerymigration.editor)
  • גישה לקטגוריות של Cloud Storage לקלט ולקבצים: אדמין של אובייקטים ב-Storage‏ (roles/storage.objectAdmin) – בקטגוריית המקור והיעד של Cloud Storage.

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

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

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

כדי ליצור משימות תרגום באמצעות המתרגם האינטראקטיבי, ה-Translation API או המתרגם של SQL באצווה, נדרשות ההרשאות הבאות:

  • bigquerymigration.workflows.create
  • bigquerymigration.workflows.get
  • bigquerymigration.workflows.list
  • bigquerymigration.workflows.delete
  • bigquerymigration.subtasks.get
  • bigquerymigration.subtasks.list
  • storage.objects.get
  • storage.objects.list
  • storage.objects.create

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

העלאת קובצי קלט ל-Cloud Storage

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

מידע נוסף על יצירת קטגוריות והעלאת קבצים ל-Cloud Storage מופיע במאמרים יצירת קטגוריות והעלאת אובייקטים ממערכת קבצים.

פונקציות SQL שלא נתמכות

אם השאילתות במקור מפנות לפונקציות SQL שאין להן מקבילות ישירות ב-GoogleSQL, אתם יכולים להשתמש בפונקציות עזר בהגדרת המשתמש (UDF). למידע נוסף, קראו את המאמר טיפול בפונקציות SQL שלא נתמכות באמצעות פונקציות עזר של UDF.

שליחת משימת תרגום

כדי לשלוח משימת תרגום באמצעות BigQuery Migration API, משתמשים ב-method‏ projects.locations.workflows.create ומספקים מכונה של המשאב MigrationWorkflow עם סוג משימה נתמך.

אחרי ששולחים את המשימה, אפשר לבדוק את הסטטוס שלה.

יצירת תרגום באצווה

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

curl -d "{
  \"tasks\": {
      string: {
        \"type\": \"TYPE\",
        \"translation_details\": {
            \"target_base_uri\": \"TARGET_BASE\",
            \"source_target_mapping\": {
              \"source_spec\": {
                  \"base_uri\": \"BASE\"
              }
            },
            \"target_types\": \"TARGET_TYPES\",
        }
      }
  }
  }" \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/workflows

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

  • ‫TYPE: סוג המשימה של התרגום, שקובע את הניב של שפת המקור ושפת היעד.
  • ‫TARGET_BASE: ה-URI הבסיסי לכל פלטי התרגום.
  • ‫BASE: ה-URI הבסיסי לכל הקבצים שנקראים כמקורות לתרגום.

  • ‫TARGET_TYPES (אופציונלי): סוגי הפלט שנוצרו. אם לא מציינים את הפרמטר, נוצרת שאילתת SQL.

    • ‫sql (ברירת המחדל): קובצי שאילתות ה-SQL המתורגמים.
    • ‫suggestion: הצעות שנוצרו על ידי AI.

    הפלט נשמר בתיקיית משנה בספריית הפלט. שם תיקיית המשנה מבוסס על הערך בשדה TARGET_TYPES.

  • TOKEN: הטוקן לאימות. כדי ליצור אסימון, משתמשים בפקודה gcloud auth print-access-token או ב-OAuth 2.0 playground (משתמשים בהיקף https://www.googleapis.com/auth/cloud-platform).

  • ‫PROJECT_ID: הפרויקט שבו מתבצע עיבוד התרגום.

  • ‫LOCATION: המיקום שבו המשימה מעובדת.

הפקודה הקודמת מחזירה תשובה שכוללת מזהה של תהליך עבודה בפורמט projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID.

דוגמה לתרגום באצווה

כדי לתרגם את הסקריפטים של Teradata SQL בספרייה gs://my_data_bucket/teradata/input/ ב-Cloud Storage ולשמור את התוצאות בספרייה gs://my_data_bucket/teradata/output/ ב-Cloud Storage, אפשר להשתמש בשאילתה הבאה:

{
  "tasks": {
     "task_name": {
       "type": "Teradata2BigQuery_Translation",
       "translation_details": {
         "target_base_uri": "gs://my_data_bucket/teradata/output/",
           "source_target_mapping": {
             "source_spec": {
               "base_uri": "gs://my_data_bucket/teradata/input/"
             }
          },
       }
    }
  }
}

הקריאה הזו תחזיר הודעה שמכילה את מזהה תהליך העבודה שנוצר בשדה "name":

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "task_name": { /*...*/ }
  },
  "state": "RUNNING"
}

כדי לקבל את הסטטוס המעודכן של תהליך העבודה, מריצים שאילתת GET. המשימה שולחת פלטים ל-Cloud Storage ככל שהיא מתקדמת. הסטטוס של המשימה state משתנה ל-COMPLETED אחרי שכל ה-target_types המבוקשים נוצרים. אם המשימה מצליחה, שאילתת ה-SQL המתורגמת מופיעה ב-gs://my_data_bucket/teradata/output.

דוגמה לתרגום קבוצתי עם הצעות מבוססות-AI

בדוגמה הבאה, הסקריפטים של Teradata SQL שנמצאים בספרייה gs://my_data_bucket/teradata/input/ ב-Cloud Storage מתורגמים, והתוצאות נשמרות בספרייה gs://my_data_bucket/teradata/output/ ב-Cloud Storage עם הצעה נוספת של AI:

{
  "tasks": {
     "task_name": {
       "type": "Teradata2BigQuery_Translation",
       "translation_details": {
         "target_base_uri": "gs://my_data_bucket/teradata/output/",
           "source_target_mapping": {
             "source_spec": {
               "base_uri": "gs://my_data_bucket/teradata/input/"
             }
          },
          "target_types": "suggestion",
       }
    }
  }
}

אחרי שהמשימה תסתיים, ההצעות של ה-AI יופיעו בספרייה gs://my_data_bucket/teradata/output/suggestion ב-Cloud Storage.

יצירת תרגום אינטראקטיבי

הפקודה curl הבאה יוצרת משימת תרגום אינטראקטיבית עם קלט ופלט של מחרוזות מילוליות. השדה source_target_mapping מכיל רשימה שממפה את הרשומות של מקור ה-literal לנתיב יחסי אופציונלי של פלט היעד.

curl -d "{
  \"tasks\": {
      string: {
        \"type\": \"TYPE\",
        \"translation_details\": {
        \"source_target_mapping\": {
            \"source_spec\": {
              \"literal\": {
              \"relative_path\": \"PATH\",
              \"literal_string\": \"STRING\"
              }
            }
        },
        \"target_return_literals\": \"TARGETS\",
        }
      }
  }
  }" \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/workflows

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

  • ‫TYPE: סוג המשימה של התרגום, שקובע את הניב של שפת המקור ושפת היעד.
  • ‫PATH: המזהה של הרשומה המילולית, בדומה לשם קובץ או לנתיב.
  • STRING: מחרוזת של נתוני קלט מילוליים (לדוגמה, SQL) לתרגום.
  • ‫TARGETS: היעדים הצפויים שהמשתמש רוצה לקבל ישירות בתגובה בפורמט literal. הם צריכים להיות בפורמט של ה-URI לטירגוט (לדוגמה, GENERATED_DIR + target_spec.relative_path + source_spec.literal.relative_path). כל מה שלא נמצא ברשימה הזו לא מוחזר בתגובה. הספרייה שנוצרה, GENERATED_DIR לתרגומים כלליים של SQL היא sql/.
  • TOKEN: הטוקן לאימות. כדי ליצור אסימון, משתמשים בפקודה gcloud auth print-access-token או ב-OAuth 2.0 playground (משתמשים בהיקף https://www.googleapis.com/auth/cloud-platform).
  • ‫PROJECT_ID: הפרויקט שבו מתבצע עיבוד התרגום.
  • ‫LOCATION: המיקום שבו המשימה מעובדת.

הפקודה הקודמת מחזירה תשובה שכוללת מזהה של תהליך עבודה בפורמט projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID.

אחרי שיוצרים את תהליך העבודה, אפשר לראות את התוצאות על ידי בדיקת סטטוס המשימה.

דוגמה לתרגום אינטראקטיבי

כדי לתרגם את מחרוזת ה-SQL של Apache Hive‏ select 1 באופן אינטראקטיבי, אפשר להשתמש בשאילתה הבאה:

"tasks": {
  string: {
    "type": "HiveQL2BigQuery_Translation",
    "translation_details": {
      "source_target_mapping": {
        "source_spec": {
          "literal": {
            "relative_path": "input_file",
            "literal_string": "select 1"
          }
        }
      },
      "target_return_literals": "sql/input_file",
    }
  }
}

אפשר להשתמש בכל relative_path שרוצים עבור הליטרל, אבל הליטרל המתורגם יופיע בתוצאות רק אם כוללים את sql/$relative_path ב-target_return_literals. אפשר גם לכלול כמה ערכים מילוליים בשאילתה אחת, ובמקרה כזה צריך לכלול את כל הנתיבים היחסיים שלהם ב-target_return_literals.

הקריאה הזו תחזיר הודעה שמכילה את מזהה תהליך העבודה שנוצר בשדה "name":

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "task_name": { /*...*/ }
  },
  "state": "RUNNING"
}

כדי לקבל את הסטטוס המעודכן של תהליך העבודה, בודקים את סטטוס המשימה. המשימה מסתיימת כשהסמל "state" משתנה לסמל COMPLETED. אם המשימה תצליח, ה-SQL המתורגם יופיע בהודעת התשובה:

{
  "name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
  "tasks": {
    "string": {
      "id": "0fedba98-7654-3210-1234-56789abcdef",
      "type": "HiveQL2BigQuery_Translation",
      /* ... */
      "taskResult": {
        "translationTaskResult": {
          "translatedLiterals": [
            {
              "relativePath": "sql/input_file",
              "literalString": "-- Translation time: 2023-10-05T21:50:49.885839Z\n-- Translation job ID: projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00\n-- Source: input_file\n-- Translated from: Hive\n-- Translated to: BigQuery\n\nSELECT\n    1\n;\n"
            }
          ],
          "reportLogMessages": [
            ...
          ]
        }
      },
      /* ... */
    }
  },
  "state": "COMPLETED",
  "createTime": "2023-10-05T21:50:49.543221Z",
  "lastUpdateTime": "2023-10-05T21:50:50.462758Z"
}

בדיקת סטטוס המשימה

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

curl \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer TOKEN" \
  -X GET https://bigquerymigration.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

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

  • TOKEN: הטוקן לאימות. כדי ליצור אסימון, משתמשים בפקודה gcloud auth print-access-token או ב-OAuth 2.0 playground (משתמשים בהיקף https://www.googleapis.com/auth/cloud-platform).
  • ‫PROJECT_ID: הפרויקט שבו פועלת משימת התרגום.
  • ‫LOCATION: המיקום שבו המשימה מעובדת.
  • ‫WORKFLOW_ID: מזהה תהליך העבודה שהוחזר כשיצרתם את תהליך העבודה של התרגום.

מצבים של תהליך העבודה

התשובה כוללת את השדה state שמציין את הסטטוס הנוכחי של תהליך העבודה:

  • ‫STATE_UNSPECIFIED: מצב תהליך העבודה לא צוין.
  • ‫RUNNING: תהליך העבודה פועל. דוגמים את נקודת הקצה (endpoint) מדי פעם עד שהמצב משתנה.
  • ‫PAUSED: תהליך העבודה מושהה.
  • ‫COMPLETED: תהליך העבודה הסתיים בהצלחה. עכשיו אפשר לאחזר את התוצאות.
  • ‫FAILED: אירעו שגיאות בתהליך העבודה. כדי לראות את פרטי השגיאה, בודקים את השדות taskResult ו-reportLogMessages בתגובה.

כשתהליך העבודה state מגיע למצב COMPLETED או FAILED, אפשר להפסיק את הסקר.

אחזור תוצאות

האופן שבו מאחזרים את התוצאות תלוי בסוג התרגום ששלחתם – תרגום באצווה או תרגום אינטראקטיבי:

  • תרגומים באצווה: הקבצים המתורגמים, דוחות הסיכום והצעות ה-AI נכתבים בספריית היעד ב-Cloud Storage שציינתם ב-target_base_uri. אתם יכולים לקרוא את הקבצים האלה ישירות מ-Cloud Storage באמצעות פקודות האחסון של ה-CLI של gcloud, ספריות הלקוח של Cloud Storage או ה-API בארכיטקטורת REST:

    gcloud storage cp --recursive TARGET_URI LOCAL_DIRECTORY

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

    • ‫TARGET_URI: ה-URI הבסיסי של היעד, למשל gs://my_data_bucket/teradata/output/.
    • ‫LOCAL_DIRECTORY: הספרייה המקומית שמקבלת את הקבצים.

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

  • תרגומים אינטראקטיביים: במשימות שמוגדרות עם קלט של מחרוזות מילוליות ו-target_return_literals, השאילתה המתורגמת מוחזרת ישירות בתגובה של תהליך העבודה בשדה translatedLiterals:

    "taskResult": {
  "translationTaskResult": {
    "translatedLiterals": [
      {
        "relativePath": "sql/input_file",
        "literalString": "SELECT 1;\n"
      }
    ]
  }
}

    כדי לקבל את השאילתה המתורגמת, מחלצים את השדה literalString לכל רשומה ב-translatedLiterals.