הגדרת פרמטרים בתבניות של תהליכי עבודה

אם אתם מתכננים להריץ תבנית של תהליך עבודה כמה פעמים עם ערכים שונים, אתם יכולים להגדיר פרמטרים בתבנית (הפיכת התבנית לפרמטרית) כדי שלא תצטרכו לערוך את תהליך העבודה בכל פעם. לאחר מכן, תוכלו להעביר ערכים שונים לפרמטרים בכל פעם שתפעילו את התבנית.

שדות שאפשר להגדיר להם פרמטרים

אפשר להגדיר פרמטרים לשדות הבאים של תבנית בתהליך העבודה של Dataproc:

  • תוויות
  • מזהי URI של קבצים
  • השם של האשכול המנוהל. ‫Dataproc ישתמש בשם שהמשתמש סיפק כקידומת לשם, ויוסיף תווים אקראיים כדי ליצור שם אשכול ייחודי. האשכול נמחק בסוף תהליך העבודה.
  • מאפייני המשרה
  • ארגומנטים של משרות
  • משתני סקריפט (ב-HiveJob,‏ SparkSqlJob ו-PigJob)
  • הכיתה הראשית (ב-HadoopJob וב-SparkJob)
  • תחום (ב-ClusterSelector)
  • מספר המופעים (numInstances) בקבוצת מופעים של מאסטר או של worker.

מאפייני הפרמטרים

פרמטרים של תבנית זרימת עבודה מוגדרים באמצעות המאפיינים הנדרשים והאופציונליים הבאים:

name (חובה)
שם משתנה בסגנון Unix. השם הזה ישמש כמפתח כשמספקים ערך לפרמטר בהמשך.
שדות (חובה)
רשימה של שדות שהפרמטר הזה יחליף (כאן מפורטת רשימה של שדות שאפשר להגדיר להם פרמטרים). כל שדה מצוין כ'נתיב שדה' (במאמר תחביר של נתיב שדה מוסבר איך מציינים נתיב שדה). הערה: שדה יכול להופיע ברשימת נתיבי השדות של פרמטר אחד בלבד.
תיאור (אופציונלי)
תיאור קצר של הפרמטר.
אימות (אופציונלי)
כללים שמשמשים לאימות ערך פרמטר, שיכול להיות אחד מהערכים הבאים:
  1. רשימה של ערכים מותרים
  2. רשימה של ביטויים רגולריים שערך צריך להתאים להם.

תחביר של נתיב שדה

התחביר של נתיב שדה דומה לזה של FieldMask. לדוגמה, נתיב שדה שמפנה לשדה zone של סלקטור אשכול בתבנית של זרימת עבודה יצוין כ-placement.clusterSelector.zone.

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

  • שם האשכול המנוהל:

    • placement.managedCluster.clusterName

  • אפשר להפנות לערכים במפות באמצעות מפתח, לדוגמה:

    • labels['key']
    • placement.clusterSelector.clusterLabels['key']
    • placement.managedCluster.labels['key']
    • jobs['step-id'].labels['key']

  • אפשר להתייחס למשרות ברשימת המשרות באמצעות step-id.

    • jobs['step-id'].hadoopJob.mainJarFileUri
    • jobs['step-id'].hiveJob.queryFileUri
    • jobs['step-id'].pySparkJob.mainPythonFileUri
    • jobs['step-id'].hadoopJob.jarFileUris[0]
    • jobs['step-id'].hadoopJob.archiveUris[0]
    • jobs['step-id'].hadoopJob.fileUris[0]

    • jobs['step-id'].pySparkJob.pythonFileUris[0]

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

    • jobs['step-id'].sparkJob.args[0]

    • דוגמאות נוספות:

    • jobs['step-id'].hadoopJob.args[0]

    • jobs['step-id'].hadoopJob.mainJarFileUri

    • jobs['step-id'].hadoopJob.properties['key']

    • jobs['step-id'].hiveJob.scriptVariables['key']

    • placement.clusterSelector.zone

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

placement.clusterSelector.clusterLabels
jobs['step-id'].sparkJob.args

הגדרת פרמטרים בתבנית של תהליך עבודה

כדי להגדיר פרמטרים לתבנית של תהליך עבודה, משתמשים ב-Dataproc API או ב-Google Cloud CLI.

פקודת gcloud

כדי להגדיר פרמטרים של תבנית של תהליך עבודה, יוצרים קובץ YAML של תבנית של תהליך עבודה, או מייצאים אותו באמצעות Google Cloud CLI ועורכים אותו, ואז מייבאים את הקובץ באמצעות Google Cloud CLI כדי ליצור או לעדכן את התבנית. מידע נוסף זמין במאמר בנושא שימוש בקובצי YAML.

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

הדוגמה הבאה היא קובץ YAML של תבנית managed-cluster workflow של teragen-terasort עם ארבעה פרמטרים מוגדרים: CLUSTER,‏ NUM_ROWS,‏ GEN_OUT ו-SORT_OUT. מוצגות שתי גרסאות: אחת BEFORE ואחת AFTER פרמטריזציה.

לפני

placement:
  managedCluster:
    clusterName: my-managed-cluster
    config:
      gceClusterConfig:
        zoneUri: us-central1-a
jobs:
- hadoopJob:
    args:
    - teragen
    - '10000'
    - hdfs:///gen/
    mainJarFileUri: file:///usr/lib/hadoop-mapreduce/hadoop-mapreduce-examples.jar
  stepId: teragen
- hadoopJob:
    args:
    - terasort
    - hdfs:///gen/
    - hdfs:///sort/
    mainJarFileUri: file:///usr/lib/hadoop-mapreduce/hadoop-mapreduce-examples.jar
  prerequisiteStepIds:
  - teragen
  stepId: terasort

אחרי

placement:
  managedCluster:
    clusterName: 'to-be-determined'
    config:
      gceClusterConfig:
        zoneUri: us-central1-a
jobs:
- hadoopJob:
    args:
    - teragen
    - '10000'
    - hdfs:///gen/
    mainJarFileUri: file:///usr/lib/hadoop-mapreduce/hadoop-mapreduce-examples.jar
  stepId: teragen
- hadoopJob:
    args:
    - terasort
    - hdfs:///gen/
    - hdfs:///sort/
    mainJarFileUri: file:///usr/lib/hadoop-mapreduce/hadoop-mapreduce-examples.jar
  prerequisiteStepIds:
  - teragen
  stepId: terasort
parameters:
- description: The managed cluster name prefix
  fields:
  - placement.managedCluster.clusterName
  name: CLUSTER
- description: The number of rows to generate
  fields:
  - jobs['teragen'].hadoopJob.args[1]
  name: NUM_ROWS
  validation:
    values:
      values:
      - '1000'
      - '10000'
      - '100000'
- description: Output directory for teragen
  fields:
  - jobs['teragen'].hadoopJob.args[2]
  - jobs['terasort'].hadoopJob.args[1]
  name: GEN_OUT
  validation:
    regex:
      regexes:
      - hdfs:///.*
- description: Output directory for terasort
  fields:
  - jobs['terasort'].hadoopJob.args[2]
  name: SORT_OUT
  validation:
    regex:
      regexes:
      - hdfs:///.*

דוגמה 2: תבנית של תהליך עבודה לבחירת אשכול

הדוגמה הבאה היא קובץ תבנית YAML של תהליך עבודה של cluster-selector עם שלושה פרמטרים מוגדרים: CLUSTER,‏ NUM_ROWS ו-OUTPUT_DIR. הדוגמה כוללת גם פרמטרים של teragen-terasort:

placement:
  clusterSelector:
    clusterLabels:
      goog-dataproc-cluster-name: 'to-be-determined'
jobs:
  - stepId: teragen
    hadoopJob:
      args:
      - 'teragen'
      - 'tbd number of rows'
      - 'tbd output directory'
parameters:
- name: CLUSTER
  fields:
  - placement.clusterSelector.clusterLabels['goog-dataproc-cluster-name']
- name: NUM_ROWS
  fields:
  - jobs['teragen'].hadoopJob.args[1]
- name: OUTPUT_DIR
  fields:
  - jobs['teragen'].hadoopJob.args[2]

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

gcloud dataproc workflow-templates import template-ID or template-name \
    --region=region \
    --source=template.yaml

אפשר להעביר לפקודה את WorkflowTemplate‏ id או את משאב התבנית המוגדר במלואו name (‎"projects/projectId/regions/region/workflowTemplates/template_id"‎). אם קיים משאב תבנית עם אותו שם תבנית, הוא יוחלף (יעודכן) ומספר הגרסה שלו יוגדל. אם לא קיימת תבנית עם אותו שם, היא תיצור תבנית חדשה.

‫Rest API

אפשר להגדיר פרמטר אחד או יותר של WorkflowTemplate.parameters בבקשת API מסוג workflowTemplates.create או workflowTemplates.update.

הדוגמה הבאה היא בקשת workflowTemplates.create ליצירת תבנית של תהליך עבודה מסוג teragen-terasort עם ארבעה פרמטרים מוגדרים: CLUSTER,‏ NUM_ROWS,‏ GEN_OUT ו-SORT_OUT.

POST https://dataproc.googleapis.com/v1/projects/my-project/locations/us-central1/workflowTemplates
{
  "id": "my-template",
  "jobs": [
    {
      "stepId": "teragen",
      "hadoopJob": {
        "mainJarFileUri": "file:///usr/lib/hadoop-mapreduce/hadoop-mapreduce-examples.jar",
        "args": [
          "teragen",
          "10000",
          "hdfs:///gen/"
        ]
      }
    },
    {
      "stepId": "terasort",
      "prerequisiteStepIds": [
        "teragen"
      ],
      "hadoopJob": {
        "mainJarFileUri": "file:///usr/lib/hadoop-mapreduce/hadoop-mapreduce-examples.jar",
        "args": [
          "terasort",
          "hdfs:///gen/",
          "hdfs:///sort/"
        ]
      }
    }
  ],
  "parameters": [
    {
      "name": "CLUSTER",
      "fields": [
        "placement.managedCluster.clusterName"
      ],
      "description": "The managed cluster name prefix"
    },
    {
      "name": "NUM_ROWS",
      "fields": [
        "jobs['teragen'].hadoopJob.args[1]"
      ],
      "description": "The number of rows to generate",
      "validation": {
        "values": {
          "values": [
            "1000",
            "10000",
            "100000"
          ]
        }
      }
    },
    {
      "name": "GEN_OUT",
      "fields": [
        "jobs['teragen'].hadoopJob.args[2]",
        "jobs['terasort'].hadoopJob.args[1]"
      ],
      "description": "Output directory for teragen",
      "validation": {
        "regex": {
          "regexes": [
            "hdfs:///.*"
          ]
        }
      }
    },
    {
      "name": "SORT_OUT",
      "fields": [
        "jobs['terasort'].hadoopJob.args[2]"
      ],
      "description": "Output directory for terasort",
      "validation": {
        "regex": {
          "regexes": [
            "hdfs:///.*"
          ]
        }
      }
    }
  ],
  "placement": {
    "managedCluster": {
      "clusterName": "to-be-determined",
      "config": {
        "gceClusterConfig": {
          "zoneUri": "us-central1-a"
        }
      }
    }
  }
}

העברת פרמטרים לתבנית עם פרמטרים

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

פקודת gcloud

אפשר להעביר מיפוי של שמות פרמטרים לערכים לפקודה gcloud dataproc workflow-templates instantiate עם הדגל --parameters. צריך לספק את כל ערכי הפרמטרים שמוגדרים בתבנית. הערכים שסופקו יחליפו את הערכים שצוינו בתבנית.

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

gcloud dataproc workflow-templates instantiate my-template \
    --region=region \
    --parameters=CLUSTER=cluster,NUM_ROWS=1000,GEN_OUT=hdfs:///gen_20180601/,SORT_OUT=hdfs:///sort_20180601

דוגמה לתבנית של כלי לבחירת אשכולות עם פרמטרים

gcloud dataproc workflow-templates instantiate \
  --parameters CLUSTER=my-cluster,NUM_ROWS=10000,OUTPUT_DIR=hdfs://some/dir

‫Rest API

אפשר להעביר parametersמיפוי של פרמטר names אל values אל Dataproc workflowTemplates.instantiate API. צריך לספק את כל ערכי הפרמטרים שמוגדרים בתבנית. הערכים שסופקו יחליפו את הערכים שצוינו בתבנית.

.

לדוגמה:

POST https://dataproc.googleapis.com/v1/projects/my-project/regions/us-central1/workflowTemplates/my-template:instantiate
{
  "parameters": {
    "CLUSTER": "clusterA",
    "NUM_ROWS": "1000",
    "GEN_OUT": "hdfs:///gen_20180601/",
    "SORT_OUT": "hdfs:///sort_20180601/"
  }
}