ワークフローテンプレートのパラメータ化

ワークフローテンプレートに別の値を指定して何度も使用できれば、その都度テンプレートのパラメータ定義を行ってワークフローを編集する必要がなくなります。これをテンプレートのパラメータ化と言います。これを行うことにより、テンプレートを使用するたびにパラメータに別の値を渡すことができます。

パラメータ化可能なフィールド

パラメータ化可能な Cloud Dataproc ワークフローテンプレートフィールドは、次のとおりです。

ラベル
ファイルの URI
マネージドクラスタ名。 Dataproc は、ユーザー指定の名前を名前の前部に使用し、その後ろにランダムな文字を追加して重複しないクラスタ名を作成します。クラスタはワークフローの最後に削除されます。
ジョブのプロパティ
ジョブの引数
スクリプトの変数（HiveJob、SparkSqlJob、PigJob）
メインクラス（HadoopJob、SparkJob）
ゾーン（ClusterSelector）
マスターインスタンスグループまたはワーカーインスタンスグループのインスタンス数（numInstances）。

パラメータ属性

ワークフローテンプレートパラメータは、次に挙げる必須の属性とオプションの属性で定義されます。

name（必須）

unix スタイルの変数名。後でパラメータの値を指定するときに、この名前がキーとして使用されます。

fields（必須）

パラメータで置き換えられるフィールドのリスト（パラメータ化できるフィールドのリストは、パラメータ化可能なフィールドをご覧ください）。各フィールドは「フィールドパス」として指定されます（フィールドパスの指定に使用する構文は、フィールドパスの構文をご覧ください）。各フィールドは、1 つのパラメータのフィールドパスリストにのみ指定できます。

description（省略可）

パラメータの簡単な説明。

validation（省略可）

パラメータ値の検証に使用するルール。次のいずれかを使用できます。

使用できる値のリスト
値が一致する必要のある正規表現のリスト。

フィールドパスの構文

フィールドパスは FieldMask の構文に似ています。たとえば、ワークフローテンプレートのクラスタセレクタの zone フィールドを参照するフィールドパスは、placement.clusterSelector.zone と指定します。

フィールドパスでは、次の構文を使用してフィールドを参照できます。

マネージドクラスタ名:
- placement.managedCluster.clusterName
マップの値は、次の例のようにキーを指定して参照できます。
- labels['キー']
- placement.clusterSelector.clusterLabels['キー']
- placement.managedCluster.labels['キー']
- jobs['step-id'].labels['キー']
ジョブリストのジョブは、次のようにステップ ID を指定して参照できます。
- jobs['ステップ ID'].hadoopJob.mainJarFileUri
- jobs['ステップ ID'].hiveJob.queryFileUri
- jobs['ステップ ID'].pySparkJob.mainPythonFileUri
- jobs['ステップ ID'].hadoopJob.jarFileUris[0]
- jobs['ステップ ID'].hadoopJob.archiveUris[0]
- jobs['ステップ ID'].hadoopJob.fileUris[0]
- jobs['ステップ ID'].pySparkJob.pythonFileUris[0]
- 繰り返しフィールドのアイテムは、次の例のようにゼロ始まりのインデックスを指定して参照できます。
- jobs['ステップ ID'].sparkJob.args[0]
- その他の例:
- jobs['ステップ ID'].hadoopJob.args[0]
- jobs['ステップ ID'].hadoopJob.mainJarFileUri
- jobs['ステップ ID'].hadoopJob.properties['キー']
- jobs['ステップ ID'].hiveJob.scriptVariables['キー']
- placement.clusterSelector.zone

マップ全体や繰り返しフィールド全体をパラメータ化することはできません。現時点で参照できるのは、個々のマップ値と、繰り返しフィールド内の個々のアイテムのみです。たとえば、以下のフィールドパスは無効です。

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

ワークフローテンプレートのパラメータ化

ワークフローテンプレートをパラメータ化するには、Dataproc API または Google Cloud CLI を使用してテンプレートパラメータを定義します。

gcloud コマンド

Google Cloud CLI を使用してワークフローテンプレートパラメータを作成またはエクスポートして定義します。次に、ワークフローテンプレート YAML ファイルを編集してから、Google Cloud CLI を使用してファイルをインポートし、テンプレートを作成または更新します。詳細については、YAML ファイルの使用をご覧ください。

例 1: パラメータ化されたマネージドクラスタテンプレートの例

定義済みの 4 つのパラメータ（CLUSTER、NUM_ROWS、GEN_OUT、SORT_OUT）を含んだ teragen-terasort マネージドクラスタワークフローテンプレート YAML ファイルの例を次に示します。パラメータ化前およびパラメータ化後の 2 つのバージョンを記載します。

これまで

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: クラスタセレクタワークフローテンプレートの例

定義済みの 3 つのパラメータ（CLUSTER、NUM_ROWS、OUTPUT_DIR）を含んだパラメータ化された teragen-terasort クラスタセレクタワークフローテンプレート YAML ファイルの例を次に示します。

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

1 つ以上の WorkflowTemplate.parameters を workflowTemplates.create または workflowTemplates.update の API リクエストで定義できます。

4 つの定義済みパラメータ（CLUSTER、NUM_ROWS、GEN_OUT、SORT_OUT）を使用して teragen-terasort ワークフローテンプレートを作成する、workflowTemplates.create リクエストの例を次に示します。

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

パラメータ names から values への parameters マップを 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/"
  }
}

ワークフロー テンプレートのパラメータ化

パラメータ化可能なフィールド

パラメータ属性

フィールドパスの構文

ワークフロー テンプレートのパラメータ化

gcloud コマンド

これまで

これから

Rest API

パラメータ化テンプレートにパラメータを渡す

gcloud コマンド

Rest API

ワークフローテンプレートのパラメータ化

ワークフローテンプレートのパラメータ化