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

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

שדות עם פרמטרים

אפשר להגדיר פרמטרים לשדות הבאים בתבנית של תהליך העבודה Managed Service for Apache Spark:

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

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

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

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

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

התחביר של נתיב שדה דומה לזה של FieldMask. לדוגמה, נתיב שדה שמפנה לשדה האזור של בורר האשכולות בתבנית של זרימת עבודה יצוין כ-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: תבנית של תהליך עבודה לבחירת אשכול

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

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 אל values אל API‏ workflowTemplates.instantiate של Managed Service for Apache Spark.names צריך לספק את כל ערכי הפרמטרים שמוגדרים בתבנית. הערכים שצוינו יחליפו את הערכים שצוינו בתבנית.

.

לדוגמה:

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/"
  }
}