工作流程範本參數化

如果工作流程範本需搭配不同的值執行多次，您可以在範本中定義參數 (也就是將範本參數化)，以免每次都必須編輯工作流程。如此一來，每次執行範本時只需傳入不同的參數值即可。

可參數化的欄位

以下是可以參數化的 Dataproc 工作流程範本欄位：

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

參數屬性

工作流程範本參數是由下列必要和選用屬性所定義：

名稱 (必要)

Unix 樣式變數名稱。後續將以此名稱作為索引鍵，用於設定參數的值。

欄位 (必要)

預計由此參數所替換的欄位清單 (可參數化的欄位清單詳見「可參數化的欄位」)。每個欄位都會以「欄位路徑」加以指定 (用於指定欄位路徑的語法請參閱「欄位路徑語法」)。請注意，同一個欄位最多只能出現在一個參數的欄位路徑清單中。

說明 (選填)

關於參數的簡短說明。

驗證 (選填)

用來驗證參數值的規則，可以是下列其中一項：

一組允許值清單
值必須符合的一組規則運算式清單。

欄位路徑語法

欄位路徑的語法與 FieldMask 類似。例如，若要參照工作流程範本叢集選擇器中的可用區欄位，其欄位路徑應指定為 placement.clusterSelector.zone。

欄位路徑可依下列語法來參照欄位：

代管叢集名稱
- placement.managedCluster.clusterName
Map 中的值可使用索引鍵進行參照，例如：
- 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

系統不支援對整個 map 和重複欄位進行參數化，只能參照個別 map 值和重複欄位中的個別項目。例如，下列欄位路徑是無效的：

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 cluster-selector 工作流程範本 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

您可以將 WorkflowTemplateid 或完整範本資源 name(「projects/projectId/regions/region/workflowTemplates/template_id」) 傳遞至指令。如果已有名稱相同的範本資源，系統會覆寫 (更新) 該資源，並遞增其版本號碼。若無名稱相同的範本，則會建立新範本。

Rest API

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

以下範例是一項 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 指令

您可以透過 --parameters 旗標，將一份參數名稱與值的 map 傳遞至 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 map 傳遞至 Dataproc workflowTemplates.instantiate API。values您必須提供範本中定義的所有參數值，所提供的值會覆寫範本中指定的值。

範例：

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

工作流程範本參數化 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

可參數化的欄位

參數屬性

欄位路徑語法

將工作流程範本參數化

gcloud 指令

之前

之後

Rest API

將參數傳遞至已參數化的範本

gcloud 指令

Rest API

工作流程範本參數化