תבניות Dataflow

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

יתרונות

לתבניות יש כמה יתרונות על פני פריסה ישירה של צינור עיבוד נתונים ל-Dataflow:

• התבניות מפרידות בין עיצוב צינור עיבוד הנתונים לבין הפריסה. לדוגמה, מפתח יכול ליצור תבנית, ומדען נתונים יכול לפרוס את התבנית במועד מאוחר יותר.
• לתבניות יכולים להיות פרמטרים שמאפשרים להתאים אישית את צינור עיבוד הנתונים כשפורסים את התבנית.
• אפשר לפרוס תבנית באמצעות מסוף Google Cloud , Google Cloud CLI או קריאות ל-API בארכיטקטורת REST. לא צריך סביבת פיתוח או יחסי תלות של צינור עיבוד נתונים שמותקנים במחשב המקומי.
• תבנית היא פריט קוד שאפשר לאחסן במאגר בקרת מקור ולהשתמש בו בצינורות עיבוד נתונים של אינטגרציה רציפה (CI/CD).

תבניות ש-Google מספקת

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

החל מ-4 באוגוסט 2025, משימות של תבניות בניהול Google פועלות ב-Dataflow Prime כברירת מחדל. כדי להריץ את המשימה ב-Dataflow הרגיל, צריך להשבית את Dataflow Prime. כדי להשבית את Dataflow Prime למשימות של תבניות בניהול Google, מגדירים את אפשרות השירות של Dataflow ל-enable_prime (false) כשמריצים את התבנית.enable_prime=false למידע נוסף, קראו את המאמר השבתת Dataflow Prime.

השוואה בין תבניות Flex לתבניות מותאמות אישית

ב-Dataflow יש תמיכה בשני סוגים של תבניות: תבניות Flex, שהן חדשות יותר, ותבניות קלאסיות. אם אתם יוצרים תבנית Dataflow חדשה, מומלץ ליצור אותה כתבנית Flex.

בתבנית Flex, הצינור נארז כקובץ אימג' של Docker ב-Artifact Registry, יחד עם קובץ מפרט של תבנית ב-Cloud Storage. מפרט התבנית מכיל מצביע לקובץ האימג' של Docker. כשמריצים את התבנית, שירות Dataflow מפעיל מכונה וירטואלית של מרכז האפליקציות, שולף את קובץ האימג' של Docker ומריץ את צינור עיבוד הנתונים. תרשים הביצוע נבנה באופן דינמי על סמך פרמטרים של זמן ריצה שהמשתמש מספק. כדי להשתמש ב-API להפעלת משימה שמשתמשת בתבנית Flex, משתמשים ב-method‏ projects.locations.flexTemplates.launch.

תבנית קלאסית מכילה את הסריאליזציה של JSON של תרשים משימה ב-Dataflow. הקוד של צינור עיבוד הנתונים צריך לעטוף את כל הפרמטרים של זמן הריצה בממשק ValueProvider. הממשק הזה מאפשר למשתמשים לציין ערכי פרמטרים כשהם פורסים את התבנית. כדי להשתמש ב-API לעבודה עם תבניות קלאסיות, עיינו במאמרי העזרה של projects.locations.templates API.

לתבניות Flex יש את היתרונות הבאים על פני תבניות מותאמות אישית:

• בניגוד לתבניות קלאסיות, בתבניות Flex לא צריך את הממשק ValueProvider לפרמטרים של קלט. לא כל המקורות והכיורים של Dataflow תומכים ב-ValueProvider.
• בתבניות מותאמות אישית יש תרשים משימות סטטי, אבל בתבניות Flex אפשר ליצור את תרשים המשימות באופן דינמי. לדוגמה, יכול להיות שהתבנית תבחר מחבר קלט/פלט אחר על סמך פרמטרים של קלט.
• תבנית Flex יכולה לבצע עיבוד מראש במכונה וירטואלית (VM) במהלך בניית צינור עיבוד הנתונים. לדוגמה, הוא יכול לאמת ערכי פרמטרים של קלט.

תהליך העבודה של התבנית

כדי להשתמש בתבניות Dataflow, צריך לבצע את השלבים הכלליים הבאים:

1. המפתחים מגדירים סביבת פיתוח ומפתחים את צינור עיבוד הנתונים שלהם. הסביבה כוללת את Apache Beam SDK ויחסי תלות אחרים.
2. בהתאם לסוג התבנית (Flex או קלאסית):
   • בתבניות Flex, המפתחים אורזים את צינור עיבוד הנתונים בקובץ אימג' של Docker, מעבירים את קובץ האימג' בדחיפה ל-Artifact Registry ומעלים קובץ מפרט של תבנית ל-Cloud Storage.
   • בתבניות מותאמות אישית, המפתחים מריצים את צינור עיבוד הנתונים, יוצרים קובץ תבנית ומעבירים את התבנית ל-Cloud Storage.
3. משתמשים אחרים שולחים בקשה לשירות Dataflow כדי להריץ את התבנית.
4. ‫Dataflow יוצר צינור עיבוד נתונים מהתבנית. יכול להיות שיעברו 5 עד 7 דקות עד שהצינור יתחיל לפעול.

בדיקה וביקורת של משימות בתבניות

כשאתם מבצעים ביקורת על משימות של תבניות Dataflow שפועלות או שהסתיימו באופן פרוגרמטי באמצעות ה-API בארכיטקטורת REST או Google Cloud CLI, תצוגת ברירת המחדל היא תצוגת סיכום (JOB_VIEW_SUMMARY). בתצוגת הסיכום לא מופיעים פרטי הביצוע של צינור עיבוד הנתונים, המטא-נתונים של התבנית והאפשרויות של צינור עיבוד הנתונים ב-SDK. כדי לאחזר את פרטי התבנית ואת אפשרויות הסביבה, צריך לבקש במפורש את תצוגת המשימה המלאה.

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

‫CLI של gcloud

כדי לאחזר את תיאור המשימה המלא, כולל פרטי התבנית, מריצים את הפקודה gcloud dataflow jobs describe עם הדגל --full:

לפני השימוש בנתוני הפקודה הבאים, צריך להחליף את הנתונים הבאים:

• ‫REGION: האזור ב-Dataflow שבו המשימה פועלת.
• ‫JOB_ID: מזהה המשימה ב-Dataflow.

מריצים את הפקודה הבאה:

‫Linux,‏ macOS או Cloud Shell

הערה: חשוב לוודא שהפעלתם את Google Cloud CLI עם אימות ופרויקט, על ידי הרצת הפקודה gcloud init או gcloud auth login ו- gcloud config set project.

gcloud dataflow jobs describe JOB_ID --full --region=REGION

‏Windows (PowerShell)

הערה: חשוב לוודא שהפעלתם את Google Cloud CLI עם אימות ופרויקט, על ידי הרצת הפקודה gcloud init או gcloud auth login ו- gcloud config set project.

gcloud dataflow jobs describe JOB_ID --full --region=REGION

Windows‏ (cmd.exe)

הערה: חשוב לוודא שהפעלתם את Google Cloud CLI עם אימות ופרויקט, על ידי הרצת הפקודה gcloud init או gcloud auth login ו- gcloud config set project.

gcloud dataflow jobs describe JOB_ID --full --region=REGION

אמורים לקבל תגובה שדומה לזו:

environment:
  sdkPipelineOptions:
    options:
      templateLocation: gs://BUCKET_NAME/templates/TEMPLATE_NAME
id: JOB_ID
name: JOB_NAME
type: JOB_TYPE_BATCH

REST

כדי לאחזר את משאב המשימה המלא, כולל פרטי התבנית, שולחים בקשת HTTP מסוג GET למתודה projects.locations.jobs.get עם פרמטרים של שאילתה view=JOB_VIEW_ALL:

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
• ‫REGION: האזור ב-Dataflow שבו המשימה פועלת.
• ‫JOB_ID: מזהה המשימה ב-Dataflow.

ה-method של ה-HTTP וכתובת ה-URL:

GET https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL

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

curl

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

מריצים את הפקודה הבאה:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL"

PowerShell

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

מריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "id": "JOB_ID",
  "name": "JOB_NAME",
  "type": "JOB_TYPE_BATCH",
  "environment": {
    "sdkPipelineOptions": {
      "options": {
        "templateLocation": "gs://BUCKET_NAME/templates/TEMPLATE_NAME"
      }
    }
  }
}

זיהוי סוגי תבניות

מטען הייעודי (payload) של התגובה משתנה בהתאם לשאלה אם המשימה נוצרה מתבנית שסופקה על ידי Google או מתבנית בהתאמה אישית:

• תבניות ש-Google מספקת: Dataflow מצרף באופן אוטומטי תוויות מוגדרות מראש למשאב של המשימה:
  • ‫goog-dataflow-provided-template-name: שם התבנית.
  • ‫goog-dataflow-provided-template-type: סוג התבנית, flex או legacy (קלאסית).
  • ‫goog-dataflow-provided-template-version: גרסת ההפצה של התבנית.
• תבניות בהתאמה אישית: למשימות של תבניות בהתאמה אישית אין את התוויות goog-dataflow-provided-*. גם משימות של תבניות Flex וגם משימות של תבניות קלאסיות מאכלסות את האפשרות templateLocation ב-environment.sdkPipelineOptions. כדי לקבוע את סוג התבנית של משימות ייעודיות כשאין תוויות, בודקים את השדות הבאים בתגובה המלאה של המשימה (JOB_VIEW_ALL):
  • תבניות מותאמות אישית: השדה templateLocation מפנה ישירות לקובץ ה-JSON של התבנית שהועברה לסביבת Staging ב-Cloud Storage. לדוגמה, הנתיב דומה ל-gs://BUCKET_NAME/templates/TEMPLATE_NAME. למשימות של תבניות מותאמות אישית אין הגדרות של קובצי אימג' להרצה בקונטיינר.
  • thought תבניות Flex: משימות של תבניות Flex מופעלות מקובץ אימג' של קונטיינר במרכז האפליקציות. באובייקט environment, משימות של תבניות Flex מכילות מפרטים ופרמטרים של קונטיינר מרכז האפליקציות (כמו flexResourceLimits). בנוסף, הנתיב של templateLocation ב-Cloud Storage שנוצר במהלך ההפעלה מכיל את מזהה המשימה.

שיטה מומלצת: צירוף תוויות משתמשים במהלך ההפעלה

כדי להבחין בין סוגי תבניות מותאמות אישית באופן פרוגרמטי, צריך לאחזר ולנתח את כל אפשרויות הסביבה של JOB_VIEW_ALL. לכן מומלץ לצרף תוויות תיאוריות למשתמשים כשמפעילים את משימות התבנית. לדוגמה, אפשר להוסיף תוויות כמו template-type: flex או template-type: classic.

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

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

• בתבניות Flex ב-CLI של gcloud, משתמשים בדגל --additional-user-labels בפקודה gcloud dataflow flex-template run.
• בתבניות מותאמות אישית ב-CLI של gcloud, משתמשים בדגל --labels בפקודה gcloud dataflow jobs run.
• כשמשתמשים ב-API בארכיטקטורת REST, צריך לכלול את מפת המפתח/ערך labels בגוף הבקשה להפעלה.

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

משימות Dataflow, כולל משימות שמופעלות מתבניות, משתמשות בשני חשבונות שירות של IAM:

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

חשוב לוודא שלשני חשבונות השירות האלה יש תפקידים מתאימים. מידע נוסף זמין במאמר אבטחה והרשאות ב-Dataflow.

אם בארגון שלכם משתמשים בכללי מדיניות של גבולות גישה לישויות מורשות (PAB), יכול להיות שמשתמשים או חשבונות שירות לא יוכלו לראות ולהריץ תבניות ש-Google מספקת. למידע נוסף ולפתרונות, ראו גישה לתבניות ש-Google מספקת באמצעות כללי מדיניות לקביעת גבול הגישה לחשבונות משתמשים.

דרישות לגבי גרסת Apache Beam SDK

כדי ליצור תבניות משלכם, ודאו שגרסת ה-SDK של Apache Beam תומכת ביצירת תבניות.

Java

כדי ליצור תבניות באמצעות Apache Beam SDK 2.x ל-Java, צריך להשתמש בגרסה 2.0.0-beta3 ואילך.

Python

כדי ליצור תבניות באמצעות Apache Beam SDK 2.x ל-Python, צריך להשתמש בגרסה 2.0.0 ואילך.

כדי להריץ תבניות באמצעות Google Cloud CLI, צריך להתקין את Google Cloud CLI בגרסה 138.0.0 ואילך.

הרחבת התבניות

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

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

• תבניות ש-Google מספקת
• שימוש בתבניות Flex כדי לארוז צינור עיבוד נתונים
• יצירה והרצה של תבנית Flex לדוגמה
• יצירת תבניות מותאמות אישית
• הפעלת תבניות קלאסיות
• פתרון בעיות בתבניות Flex