マクロ、設定、ランタイムの引数を管理する

このページでは、Cloud Data Fusion パイプラインでの環境設定、マクロ、ランタイム引数について説明します。

主な用語

マクロ
マクロは、Cloud Data Fusion プラグインの構成内のプレースホルダです。これらは、${ } で囲まれた変数（${input_file_path} など）で表されます。マクロを使用すると、プレースホルダ値を使用できるため、パイプラインに柔軟性がもたらされます。プレースホルダ値は、実行時に実際の値に置き換えられます。これにより、ファイルパスやテーブル名などのパラメータを動的に構成できます。
環境設定
環境設定は、システム自体、名前空間、アプリケーション（パイプラインを含む）、パイプライン内の個別のプログラムなど、Cloud Data Fusion 内のさまざまなレベルに適用される事前定義された構成です。環境設定を使用すると、頻繁に使用される構成のデフォルト値を設定できます。デフォルトは、下位レベルのパイプラインとプログラムに継承できるため、反復的な構成タスクを削減できます。
ランタイム引数
ランタイム引数は、マクロの値を指定する Key-Value ペアです。パイプラインをデプロイまたは実行するときに、環境設定のオーバーライドを行うこともできます。高度にカスタマイズ可能であり、基盤となるパイプラインや環境設定を変更することなく、パイプラインの実行ごとに構成を調整できます。

マクロを設定する

プラグイン プロパティ値にマクロを使用する手順は次のとおりです。

  1. Cloud Data Fusion Studio で、プラグイン ノードに移動し、[プロパティ] をクリックします。
  2. マクロを使用するフィールドに移動し、フィールドの横にある [M] をクリックします。
  3. マクロのキーを入力します。たとえば、ファイルソースのプラグイン プロパティの [形式] フィールドに ${format.type} というキーを入力します。

マクロ値を設定する

パイプラインのデータをプレビューする前とパイプラインを実行する前に、マクロの値を設定します。マクロ値は以下の場所で設定できます。

  • 引数セッター プラグイン
  • ランタイム引数
  • アプリケーションの環境設定
  • 名前空間の環境設定
  • システムの環境設定

マクロを使用してパイプラインを実行すると、次のことが行われます。

  • Cloud Data Fusion はまず、パイプラインに引数セッター プラグインが含まれているかどうかを確認します。
    • 引数セッターがある場合、Cloud Data Fusion はセッターのマクロの値を使用します。
    • 引数セッターがない場合、または引数セッターで割り当てられていないマクロがある場合、Cloud Data Fusion は代わりにパイプラインのランタイム引数の値を使用します。
  • ランタイム引数は、アプリケーションの環境設定からマクロを継承します。
  • アプリケーションの環境設定が名前空間の環境設定からマクロを継承する
  • 名前空間の環境設定は、システム環境設定からマクロを継承します。

例

マクロは、多くの場合にパスフィールドで使用されます。ハードコードされたパスを使用する代わりに、動的パスを使用できます。たとえば、Cloud Storage ソース プラグインでは、パス値を複数のマクロに置き換えることができます。gs://${bucket.name}/${folder}/${file.name} の値は、バケット、フォルダ、ファイル要素を分割します。

次の例では、静的なバケットと静的ではない名前のファイルからデータを読み込みます。バケットの名前を入力し、ファイル名にマクロ gs://<BUCKET_NAME>/${folder}/${file.name} を使用します。

環境設定を行う

次のセクションでは、環境設定の階層について説明します。ここでは、環境設定を行い、継承、またはオーバーライドします。

システムの環境設定を行う

システムの環境設定を行うことができます。マクロ名は一意であることが必要なため、各環境設定は、マクロを使用するすべてのパイプラインに適用されます。

たとえば、データベース ソースを含むパイプラインがあり、データベース名とユーザー名にマクロを使用します。データベースとユーザー名の環境設定は、システム環境設定で行うことができます。対象のインスタンス内のすべての名前空間とすべてのパイプラインは、これらの環境設定を継承します。

システムの環境設定を行う手順は次のとおりです。

  1. Cloud Data Fusion Studio で、[システム管理者] > [構成] をクリックします。
  2. [システム環境設定] > [システム環境設定を編集] をクリックします。
  3. [環境設定] ダイアログで、新しい環境設定を入力するか、既存の環境設定を編集します。
  4. [保存して閉じる] をクリックします。 これらの環境設定は、すべての名前空間、アプリケーション、パイプラインで使用できます。

名前空間の環境設定を行う

個別の名前空間の環境設定を行うことができます。

名前空間の環境設定を行うと、継承されたシステム環境設定が表示されます。名前空間の環境設定を行うときに、異なる値を設定することで、継承された環境設定をオーバーライドできます。新しい名前空間の環境設定を追加することもできます。

名前空間の環境設定を行う手順は次のとおりです。

  1. Cloud Data Fusion Studio で、[システム管理者] > [構成] をクリックします。
  2. [名前空間] をクリックし、名前空間を選択して構成ページを開きます。
  3. 継承された環境設定を編集するか、新しい環境設定を追加するには、[環境設定] タブに移動し、[編集] をクリックします。[環境設定] ダイアログが開きます。ここで、新しい環境設定を入力する、または継承されたシステム環境設定をオーバーライドすることができます。<span class="material-icons">add</span> [追加] をクリックし、マクロのキーと新しい値を入力します。
  4. [保存して閉じる] をクリックします。 名前空間の環境設定は新しい値で作成され、システムの環境設定よりも優先されます。

アプリの環境設定を設定する

名前空間にデプロイされた各パイプラインの環境設定を行うことができます。アプリケーションの環境設定を行うと、継承されたシステム環境設定と名前空間の環境設定が表示されます。アプリケーションの環境設定を行う際に、異なる値を設定することで継承された環境設定をオーバーライドできます。または、アプリケーションに新しい環境設定を追加することもできます。

  1. Cloud Data Fusion Studio で をクリックし、[名前空間] メニューをクリックして、アプリケーションの環境設定を追加する名前空間を選択します。
  2. [コントロール センター] をクリックします。
  3. 環境設定アイコン（レンチ）をクリックします。[環境設定] ページが表示され、継承されたすべての環境設定が一覧表示されます。
  4. 継承された環境設定を編集するか、新しい環境設定を追加するには、[環境設定] タブに移動し、[編集] をクリックします。[環境設定] ダイアログが開きます。ここで、新しい環境設定を入力する、または継承されたシステム環境設定をオーバーライドすることができます。<span class="material-icons">add</span> [追加] をクリックし、マクロのキーと新しい値を入力します。
  5. [保存して閉じる] をクリックします。 アプリケーションの環境設定は新しい値で作成され、システムまたは名前空間の環境設定がオーバーライドされます。デプロイされたパイプラインを実行すると、アプリケーションの環境設定がランタイム 引数として表示され、必要に応じて編集できます。

ランタイム引数を設定する

ランタイム引数を設定して、パイプラインのデプロイ時または実行時にマクロの値を指定し、必要に応じて環境設定をオーバーライドします。

データのプレビュー用のランタイム引数

Cloud Data Fusion Studio でデータをプレビューするときに、パイプラインの各マクロの値を設定するには、[リスト] > [構成] をクリックします。

デプロイされたパイプラインの実行に使用するランタイム引数

パイプラインにマクロが含まれている場合は、パイプラインをデプロイした後にランタイム引数を追加して、マクロの値を設定します。

マクロを含むパイプラインをデプロイする場合は、[実行] の横にある プルダウン メニューをクリックして [ランタイム引数] ダイアログを開き、各マクロの値を設定します。

パイプラインの環境設定を行う

パイプラインの環境設定を行う手順は次のとおりです。

  1. Cloud Data Fusion Studio で、[リスト] > [デプロイ済み] をクリックし、デプロイされたパイプラインを選択して表示します。
  2. パイプライン キャンバスで、[実行] の横にある プルダウン メニューをクリックします。[ランタイム引数] ダイアログが開きます。
  3. 開いた [ランタイム引数] ダイアログで、パイプラインの各マクロの値を指定します。

環境設定、マクロ、ランタイム引数の概要

環境設定は次のレベルで行うことができます。

  • システム環境設定: インスタンス全体のデフォルトなどの環境設定を行う最上位レベル。
  • 名前空間の環境設定: システムの環境設定から環境設定を継承します。特定の名前空間の環境設定を行うことができます。
  • アプリケーションの環境設定: 名前空間の環境設定から環境設定を継承します。パイプラインを含む個別のアプリケーションに固有に設定できます。
  • ランタイム引数: 上位レベルの環境設定をオーバーライドする Key-Value ペア。

システム環境設定レベルで環境設定を設定すると、マクロ値は名前空間の環境設定、アプリケーションの環境設定、ランタイム引数に自動的に入力されます。

名前空間レベルで設定された環境設定は、アプリケーションの環境設定の継承された環境設定のリストに表示されます。パイプラインが環境設定で定義されたマクロを使用する場合、ランタイム パラメータは環境設定で定義された Key-Value ペアを使用します。各環境設定レベルとランタイム引数で、環境設定の値をオーバーライドできます。

環境設定、マクロ、ランタイム引数は、次のユースケースで使用します。

  • パイプラインの開発。プラグイン プロパティの動的な値が必要な場所にマクロを埋め込みます。
  • 省略可: 環境設定の設定。さまざまなレベルの環境設定でマクロのデフォルト値を設定します。
  • パイプラインのデプロイと実行。パイプラインを実行すると、次のようになります。
    • システム環境設定や名前空間の環境設定など、関連するレベルの環境設定が適用されます。
    • 指定したランタイム引数は、環境設定でマクロに割り当てられた値をオーバーライドします。
    • Cloud Data Fusion は、ランタイム引数（ランタイム引数が指定されていない場合は環境設定）の値に置き換えることでマクロを解決します。

例

パイプラインに、動的に変更する必要があるテーブル名の値を持つ BigQuery シンクが存在します。設定手順は次のとおりです。

  1. マクロを設定します。シンクのプロパティの [テーブル名] フィールドで、マクロ ${output_table}. を使用します。
  2. **環境設定を設定します。**アプリの環境設定で、${output_table} の環境設定にデフォルト値 data_staging を設定します。
  3. ランタイム引数を設定します。パイプラインを実行するときに、ランタイム引数（output_table=final_analytics_data など）を指定します。

パイプラインの実行中に、マクロ ${output_table}, は final_analytics_data に置き換えられます。