תבנית Datastream to BigQuery (Stream)

התבנית Datastream to BigQuery היא פייפליין זורם שקורא נתונים מ-Datastream ומשכפל אותם ב-BigQuery. התבנית קוראת נתונים מ-Cloud Storage באמצעות התראות Pub/Sub ומשכפלת אותם לטבלת BigQuery זמנית שמחולקת לפי זמן. אחרי הרפליקציה, התבנית מריצה MERGE ב-BigQuery כדי לעדכן או להוסיף (upsert) את כל השינויים של סימון נתונים שהשתנו (CDC) לרפליקה של טבלת המקור. צריך לציין את הפרמטר gcsPubSubSubscription כדי לקרוא נתונים מהתראות Pub/Sub, או לציין את הפרמטר inputFilePattern כדי לקרוא נתונים ישירות מקבצים ב-Cloud Storage.

התבנית מטפלת ביצירה ובעדכון של הטבלאות ב-BigQuery שמנוהלות על ידי הרפליקציה. כשנדרשת שפת הגדרת נתונים (DDL), קריאה חוזרת (callback) ל-Datastream מחלצת את הסכימה של טבלת המקור ומתרגמת אותה לסוגי נתונים של BigQuery. הפעולות הנתמכות כוללות:

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

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

דרישות לגבי צינור עיבוד הנתונים

  • סטרימינג של Datastream שמוכן לשכפול נתונים או שכבר משכפל נתונים.
  • התראות Pub/Sub של Cloud Storage מופעלות לנתוני Datastream.
  • נוצרים מערכי נתונים של יעדים ב-BigQuery, ולחשבון השירות של Compute Engine ניתנת גישת אדמין אליהם.
  • כדי ליצור את טבלת הרפליקה של היעד, צריך מפתח ראשי בטבלת המקור.
  • מסד נתונים של MySQL או Oracle כמקור. אין תמיכה במסדי נתונים של PostgreSQL ו-SQL Server.

פרמטרים של תבניות

פרמטרים נדרשים

  • inputFileFormat: הפורמט של קובצי הפלט שנוצרו על ידי Datastream. הערכים המותרים הם avro ו-json. ברירת המחדל היא avro.
  • ‫outputStagingDatasetTemplate: השם של מערך הנתונים שמכיל טבלאות ביניים. הפרמטר הזה תומך בתבניות, למשל {_metadata_dataset}_log או my_dataset_log. בדרך כלל, הפרמטר הזה הוא שם של קבוצת נתונים. ברירת המחדל היא {_metadata_dataset}. הערה: במקורות MySQL, שם מסד הנתונים ממופה ל-{_metadata_schema} במקום ל-{_metadata_dataset}.
  • ‫outputDatasetTemplate: השם של מערך הנתונים שמכיל את טבלאות הרפליקה. הפרמטר הזה תומך בתבניות, למשל {_metadata_dataset} או my_dataset. בדרך כלל, הפרמטר הזה הוא שם של קבוצת נתונים. ברירת המחדל היא {_metadata_dataset}. הערה: במקורות MySQL, שם מסד הנתונים ממופה ל-{_metadata_schema} במקום ל-{_metadata_dataset}.
  • ‫deadLetterQueueDirectory: הנתיב שבו Dataflow משתמש כדי לכתוב את הפלט של התור להודעות שלא טופלו. הנתיב הזה לא יכול להיות באותו נתיב של פלט הקובץ של Datastream. ברירת המחדל היא empty.

פרמטרים אופציונליים

  • ‫inputFilePattern: מיקום הקובץ של פלט הקובץ של Datastream ב-Cloud Storage, בפורמט gs://<BUCKET_NAME>/<ROOT_PATH>/.
  • ‫gcsPubSubSubscription: המינוי ל-Pub/Sub שמשמש את Cloud Storage כדי להודיע ל-Dataflow על קבצים חדשים שזמינים לעיבוד, בפורמט: projects/<PROJECT_ID>/subscriptions/<SUBSCRIPTION_NAME>.
  • ‫streamName: השם או התבנית של מקור הנתונים שרוצים לדגום כדי לקבל מידע על הסכימה. ברירת המחדל היא: {_metadata_stream}. ערך ברירת המחדל בדרך כלל מספיק.
  • ‫rfcStartDateTime: התאריך והשעה שמהם רוצים לאחזר נתונים מ-Cloud Storage (https://tools.ietf.org/html/rfc3339). ברירת המחדל: 1970-01-01T00:00:00.00Z.
  • ‫fileReadConcurrency: מספר הקבצים של Datastream לקריאה בו-זמנית. ברירת המחדל היא 10.
  • ‫outputProjectId: המזהה של הפרויקט ב-Google Cloud שמכיל את מערכי הנתונים ב-BigQuery שאליהם רוצים להוציא את הנתונים. כברירת מחדל, הפרמטר הזה הוא הפרויקט שבו פועל צינור עיבוד הנתונים של Dataflow.
  • ‫outputStagingTableNameTemplate: התבנית שמשמשת למתן שמות לטבלאות ה-staging. לדוגמה, {_metadata_table}. ברירת המחדל היא {_metadata_table}_log.
  • ‫outputTableNameTemplate: התבנית שבה משתמשים לשם של טבלאות הרפליקה, לדוגמה {_metadata_table}. ברירת המחדל היא {_metadata_table}.
  • ignoreFields: שדות שמופרדים בפסיקים שצריך להתעלם מהם ב-BigQuery. ברירת המחדל: _metadata_stream,_metadata_schema,_metadata_table,_metadata_source,_metadata_tx_id,_metadata_dlq_reconsumed,_metadata_primary_keys,_metadata_error,_metadata_retry_count. לדוגמה, _metadata_stream,_metadata_schema.
  • ‫mergeFrequencyMinutes: מספר הדקות בין מיזוגים בטבלה נתונה. ברירת המחדל היא 5.
  • ‫dlqRetryMinutes: מספר הדקות בין ניסיונות חוזרים של DLQ. ברירת המחדל היא 10.
  • ‫dataStreamRootUrl: כתובת ה-URL הבסיסית של Datastream API. ברירת המחדל היא: https://datastream.googleapis.com/.
  • ‫applyMerge: אם להשבית שאילתות MERGE במשימה. ברירת המחדל היא true.
  • ‫mergeConcurrency: מספר השאילתות בו-זמניות של BigQuery MERGE. האפשרות הזו רלוונטית רק אם applyMerge מוגדר כ-true. ברירת המחדל היא 30.
  • ‫partitionRetentionDays: מספר הימים שבהם המחיצה תישמר בזמן הרצת מיזוגים ב-BigQuery. ברירת המחדל היא 1.
  • ‫useStorageWriteApiAtLeastOnce: הפרמטר הזה נכנס לתוקף רק אם Use BigQuery Storage Write API מופעל. אם הערך הוא true, המערכת משתמשת בסמנטיקה של "לפחות פעם אחת" ב-Storage Write API. אחרת, נעשה שימוש בסמנטיקה של פעם אחת בדיוק. ברירת המחדל היא false.
  • ‫datastreamSourceType: שינוי הזיהוי של סוג המקור לנתוני Datastream CDC. אם מציינים את הערך הזה, המערכת תשתמש בו במקום להסיק את סוג המקור מהשדה read_method. הערכים התקינים כוללים את mysql,‏ postgresql,‏ oracle,‏ sqlserver וכו'. הפרמטר הזה שימושי כשהשדה read_method מכיל את הערך cdc ואי אפשר לקבוע באופן אוטומטי את סוג המקור בפועל.
  • ‫javascriptTextTransformGcsPath: ה-URI של Cloud Storage של קובץ ה-‎ .js שמגדיר את הפונקציה בהגדרת המשתמש (UDF) ב-JavaScript שבה רוצים להשתמש. לדוגמה, gs://my-bucket/my-udfs/my_file.js.
  • ‫javascriptTextTransformFunctionName: השם של הפונקציה בהגדרת המשתמש (UDF) ב-JavaScript שבה רוצים להשתמש. לדוגמה, אם קוד הפונקציה של JavaScript הוא myTransform(inJson) { /*...do stuff...*/ }, שם הפונקציה הוא myTransform. בקישור הבא תוכלו למצוא דוגמאות לפונקציות UDF ב-JavaScript‏ (https://github.com/GoogleCloudPlatform/DataflowTemplates#udf-examples).
  • ‫javascriptTextTransformReloadIntervalMinutes: מציין את התדירות שבה צריך לטעון מחדש את ה-UDF, בדקות. אם הערך גדול מ-0, ‏Dataflow בודק מדי פעם את קובץ ה-UDF ב-Cloud Storage, וטוען מחדש את ה-UDF אם הקובץ השתנה. הפרמטר הזה מאפשר לעדכן את ה-UDF בזמן שהצינור פועל, בלי להפעיל מחדש את המשימה. אם הערך הוא 0, הטעינה מחדש של פונקציות מוגדרות-משתמש מושבתת. ערך ברירת המחדל הוא 0.
  • ‫pythonTextTransformGcsPath: תבנית הנתיב ב-Cloud Storage לקוד Python שמכיל את הפונקציות בהגדרת המשתמש. לדוגמה, gs://your-bucket/your-transforms/*.py.
  • ‫pythonRuntimeVersion: גרסת סביבת זמן הריצה שבה משתמשים ב-UDF הזה ב-Python.
  • ‫pythonTextTransformFunctionName: שם הפונקציה שצריך לקרוא לה מקובץ ה-JavaScript. אפשר להשתמש רק באותיות, בספרות ובקווים תחתונים. לדוגמה, transform_udf1.
  • ‫runtimeRetries: מספר הפעמים שבהן המערכת תנסה להפעיל את סביבת זמן הריצה לפני שהיא תיכשל. ברירת המחדל: 5.
  • ‫useStorageWriteApi: אם הערך הוא true, צינור עיבוד הנתונים משתמש ב-BigQuery Storage Write API‏ (https://cloud.google.com/bigquery/docs/write-api). ערך ברירת המחדל הוא false. מידע נוסף זמין במאמר "שימוש ב-Storage Write API"‏ (https://beam.apache.org/documentation/io/built-in/google-bigquery/#storage-write-api).
  • ‫numStorageWriteApiStreams: כשמשתמשים ב-Storage Write API, מציין את מספר הסטרימינג לכתיבה. אם הערך של useStorageWriteApi הוא true והערך של useStorageWriteApiAtLeastOnce הוא false, חובה להגדיר את הפרמטר הזה. ברירת המחדל: 0.
  • ‫storageWriteApiTriggeringFrequencySec: כשמשתמשים ב-Storage Write API, מציין את תדירות ההפעלה בשניות. אם הערך של useStorageWriteApi הוא true והערך של useStorageWriteApiAtLeastOnce הוא false, חובה להגדיר את הפרמטר הזה.

פונקציה בהגדרת המשתמש (UDF)

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

מפרט הפונקציה

המפרט של ה-UDF הוא:

  • קלט: נתוני ה-CDC, שעברו סריאליזציה כמחרוזת JSON.
  • פלט: מחרוזת JSON שתואמת לסכימה של טבלת היעד ב-BigQuery.
  • הפעלת התבנית

    המסוף

    1. נכנסים לדף Create job from template ב-Dataflow.
    2. כניסה לדף Create job from template
    3. בשדה Job name, מזינים שם ייחודי למשימה.
    4. אופציונלי: בשדה Regional endpoint, בוחרים ערך מהתפריט הנפתח. אזור ברירת המחדל הוא us-central1.

      רשימה של אזורים שבהם אפשר להריץ משימת Dataflow מופיעה במאמר מיקומי Dataflow.

    5. בתפריט הנפתח Dataflow template, בוחרים את התבנית Datastream to BigQuery.
    6. בשדות הפרמטרים שמופיעים, מזינים את ערכי הפרמטרים.
    7. אופציונלי: כדי לעבור מעיבוד של פעם אחת בדיוק למצב סטרימינג של פעם אחת לפחות, בוחרים באפשרות At Least Once.
    8. לוחצים על Run job.

    gcloud

    במעטפת או בטרמינל, מריצים את התבנית:

    gcloud dataflow flex-template run JOB_NAME \
        --project=PROJECT_ID \
        --region=REGION_NAME \
        --enable-streaming-engine \
        --template-file-gcs-location=gs://dataflow-templates/VERSION/flex/Cloud_Datastream_to_BigQuery \
        --parameters \
    inputFilePattern=GCS_FILE_PATH,\
    gcsPubSubSubscription=GCS_SUBSCRIPTION_NAME,\
    outputStagingDatasetTemplate=BIGQUERY_DATASET,\
    outputDatasetTemplate=BIGQUERY_DATASET,\
    outputStagingTableNameTemplate=BIGQUERY_TABLE,\
    outputTableNameTemplate=BIGQUERY_TABLE_log
      

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

    • ‫PROJECT_ID: Google Cloud מזהה הפרויקט שבו רוצים להריץ את משימת Dataflow
    • ‫JOB_NAME: שם ייחודי למשימה, לפי בחירתכם
    • ‫REGION_NAME: האזור שבו רוצים לפרוס את משימת Dataflow, לדוגמה us-central1
    • VERSION: the version of the template that you want to use

      You can use the following values:

      • latest to use the latest version of the template, which is available in the non-dated parent folder in the bucket— gs://dataflow-templates/latest/
      • the version name, like 2023-09-12-00_RC00, to use a specific version of the template, which can be found nested in the respective dated parent folder in the bucket— gs://dataflow-templates/
    • ‫GCS_FILE_PATH: הנתיב ב-Cloud Storage לנתוני Datastream. לדוגמה: gs://bucket/path/to/data/
    • ‫GCS_SUBSCRIPTION_NAME: המינוי ל-Pub/Sub שממנו ייקראו הקבצים שהשתנו. לדוגמה: projects/my-project-id/subscriptions/my-subscription-id.
    • ‫BIGQUERY_DATASET: השם של מערך הנתונים ב-BigQuery.
    • ‫BIGQUERY_TABLE: תבנית הטבלה ב-BigQuery. לדוגמה, {_metadata_schema}_{_metadata_table}_log.

    API

    כדי להריץ את התבנית באמצעות ה-API ל-REST, שולחים בקשת HTTP POST. למידע נוסף על ה-API ועל היקפי ההרשאות שלו, קראו את המאמר projects.templates.launch.

    POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/flexTemplates:launch
    {
       "launch_parameter": {
          "jobName": "JOB_NAME",
          "parameters": {
    
              "inputFilePattern": "GCS_FILE_PATH",
              "gcsPubSubSubscription": "GCS_SUBSCRIPTION_NAME",
              "outputStagingDatasetTemplate": "BIGQUERY_DATASET",
              "outputDatasetTemplate": "BIGQUERY_DATASET",
              "outputStagingTableNameTemplate": "BIGQUERY_TABLE",
              "outputTableNameTemplate": "BIGQUERY_TABLE_log"
          },
          "containerSpecGcsPath": "gs://dataflow-templates/VERSION/flex/Cloud_Datastream_to_BigQuery",
       }
    }
      

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

    • ‫PROJECT_ID: Google Cloud מזהה הפרויקט שבו רוצים להריץ את משימת Dataflow
    • ‫JOB_NAME: שם ייחודי למשימה, לפי בחירתכם
    • ‫LOCATION: האזור שבו רוצים לפרוס את משימת Dataflow, לדוגמה us-central1
    • VERSION: the version of the template that you want to use

      You can use the following values:

      • latest to use the latest version of the template, which is available in the non-dated parent folder in the bucket— gs://dataflow-templates/latest/
      • the version name, like 2023-09-12-00_RC00, to use a specific version of the template, which can be found nested in the respective dated parent folder in the bucket— gs://dataflow-templates/
    • ‫GCS_FILE_PATH: הנתיב ב-Cloud Storage לנתוני Datastream. לדוגמה: gs://bucket/path/to/data/
    • ‫GCS_SUBSCRIPTION_NAME: המינוי ל-Pub/Sub שממנו ייקראו הקבצים שהשתנו. לדוגמה: projects/my-project-id/subscriptions/my-subscription-id.
    • ‫BIGQUERY_DATASET: השם של מערך הנתונים ב-BigQuery.
    • ‫BIGQUERY_TABLE: תבנית הטבלה ב-BigQuery. לדוגמה, {_metadata_schema}_{_metadata_table}_log.

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