工作流程範本參數化

如果工作流程範本會以不同值多次執行，您可以在範本中定義參數 (將範本參數化)，避免每次都需要編輯工作流程。這樣一來，您每次執行範本時，就可以傳遞不同的參數值。

可參數化的欄位

下列 Dataproc 工作流程範本欄位可參數化：

  • 標籤
  • 檔案 URI
  • 代管叢集名稱。Dataproc 會使用使用者提供的名稱做為名稱前置字串，並附加隨機字元，建立不重複的叢集名稱。系統會在工作流程結束時刪除叢集。
  • 工作屬性
  • 工作引數
  • 指令碼變數 (在 HiveJob、SparkSqlJob 和 PigJob 中)
  • 主要類別 (在 HadoopJob 和 SparkJob 中)
  • 可用區 (在 ClusterSelector 中)
  • 主控台或工作站執行個體群組中的執行個體數量 (numInstances)。

參數屬性

工作流程範本參數的定義包含下列必要和選用屬性：

name (必要)
Unix 樣式的變數名稱。稍後提供參數值時，系統會將此名稱用作鍵。
欄位 (必填)
這個參數會取代哪些欄位 (請參閱「可設定參數的欄位」，瞭解可設定參數的欄位清單)。每個欄位都會指定為「欄位路徑」(如要瞭解如何使用語法指定欄位路徑，請參閱「欄位路徑語法」)。請注意，一個欄位最多只能出現在一個參數的欄位路徑清單中。
description (選填)
參數的簡短說明。
驗證 (選填)
用於驗證參數值的規則，參數值可以是下列任一項：
  1. 允許值清單
  2. 值必須符合的規則運算式清單。

欄位路徑語法

欄位路徑的語法與 FieldMask 相似。舉例來說，如果欄位路徑參照工作流程範本叢集選取器的區域欄位，就會指定為 placement.clusterSelector.zone。

欄位路徑可使用下列語法參照欄位：

  • 代管叢集名稱：

    • placement.managedCluster.clusterName

  • 地圖中的值可透過鍵參照，例如：

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

  • 工作清單中的各項工作可透過步驟 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：參數化管理叢集範本範例

以下是 teragen-terasort 範例 受管理叢集工作流程範本 YAML 檔案，其中包含四個定義參數：CLUSTER、NUM_ROWS、GEN_OUT 和 SORT_OUT。系統會列出兩個版本：一個是前參數化，另一個是後參數化。

早於

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 叢集選取器工作流程範本 YAML 檔案，其中包含三個定義參數：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") 傳遞至指令。如果有同名的範本資源，系統會覆寫 (更新) 該資源，並將其版本編號加 1。如果沒有名稱相同的範本，系統會建立該範本。

Rest API

您可以在 workflowTemplates.create 或 workflowTemplates.update API 要求中定義一或多個 WorkflowTemplate.parameters。

以下是建立 teragen-terasort 工作流程範本的 workflowTemplates.create 要求範例，其中包含四個定義參數：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 指令

您可以使用 --parameters 標記，將參數名稱與值的對應項目傳遞至 gcloud dataproc workflow-templates instantiate 指令。必須提供範本中定義的所有參數值。提供的值會覆寫範本中指定的值。

參數化受管理叢集範本範例

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

您可以將參數 names 的 parameters 對應項目傳遞至 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/"
  }
}