ブロックリファレンス

BLOCKS Reference

共通

変数

フローには、「変数」機能があります。変数とは、フローの実行中に文字列や整数などのデータを格納・参照できる記憶領域のことで、固有の名称（変数名）で識別できます。

変数には、「フロー間共通変数」と「フロー実行内変数」の2種類があります。おおまかには、以下の違いがあります。

  • フロー間共通変数：複数のフロー間で共有される変数（フローデザイナー単位）

    info複数のフローデザイナー間での共有はできません。

  • フロー実行内変数：１つのフロー内でのみ有効な変数（フロー単位）

それぞれの変数の仕様については、後述します。

変数にデータを格納するには、以下に挙げるいくつかの方法があります。

フローデザイナーの「設定」の「フロー間共通変数」で変数を設定すると、フロー実行時に指定された変数名と値で変数が準備され、参照できるようになります。

上図は、変数名DATASETの変数に、文字列値stagingを格納する例です。

フロー間共通変数の設定手順については、「フローデザイナーの基本的な使い方」の「フロー間共通変数」を参照願います。

「オブジェクト生成」ブロックを使うと、変数にオブジェクト型のデータを格納できます。

上図は、「オブジェクト生成」ブロックで変数名が_の変数に、datasetという名前の値としてstagingという文字列を持つオブジェクト型のデータを格納する例です。

ブロックによっては、ブロックの処理結果を変数に格納するブロックがあります。後続のブロックでその変数を参照（変数展開）できます。

上図は、「クエリーの実行」ブロックの例です。このブロックの場合は、「結果を格納する変数」プロパティに指定された変数に対して、処理結果を格納します。

フローは、フローデザイナー外部やジョブ起動ブロックから実行できますが、その際それらから変数を引き継げます。

上図は、ワークスペースの「フローを開始パネル」からフローを起動する例です。このように、フロー外部からフローが実行される場合は、外部から変数を引き継げます。この例では、単一の変数を引き継いでいますが、複数の変数も引き継げます。

ここでは、ワークスペースの「フローを開始パネル」を例にしていますが、この部分は「ジョブ起動」ブロックやMAGELLAN BLOCKS外のアプリケーションに置き換えても同様のことができます。

フロー内での変数の使い方には、以下に挙げるいくつかの方法があります。

ブロックによっては、変数からデータを受け取って処理するもの、処理の結果を変数へ格納するものがあります。このような場合は、ブロックに変数を指定するプロパティがあるので、このプロパティに変数名を指定します。

下図は、「スプレッドシートを作成」ブロックの例です。

このブロックは、変数内のデータを受け取ってGoogleスプレッドシートを作成し、作成したGoogleスプレッドシートのURLを変数へ出力します。

上図、「出力データの変数」プロパティと「作成したファイルURLを格納する変数」プロパティがそれらに該当します（赤枠部分）。

このようなプロパティでは、変数名を指定します。この例では、共に変数名として_を指定しています。

  1. 変数_に格納されたデータを元にスプレッドシートを作成
  2. 作成したスプレッドシートのURLを変数_へ格納（以前の格納データを上書き）

info変数にはMAGELLAN BLOCKSがサポートするどのようなデータ形式のデータも自由に出し入れできるため、このようにひとつの変数を使い回すこともできます。

変数展開を使うと、ブロックのプロパティ値の全部または一部を変数の内容で置き換えられます。

以下は、変数展開の典型的な一例です。

上図では、ブロック内の「結果格納先データセット」プロパティに、${変数名}という変数展開の記法で記述しておきます。すると、フロー実行時には、その時点の変数の内容でプロパティ値が置き換えられます。

変数展開について詳しくは、「変数展開」の章を参照願います。

ブロックによっては、変数からデータを受け取って処理するもの、処理の結果を変数に格納するものがあります。変数内のデータ形式が合致する場合は、これらのブロックをつなぎ合わせることで、実現したい業務処理が簡単に作成できます。

以下は、変数を経由したブロック間のデータ受け渡しの典型的な一例です。

「クエリーの実行」ブロックは、オブジェクトの配列形式でデータを変数に格納します。一方、「スプレッドシートを作成」ブロックは、オブジェクトの配列形式のデータを変数から受け取ります。この場合、両者の入出力のデータ形式が一致するため、上図のようにつなげることで、変数を介してデータの受け渡しができ、BigQueryのデータからスプレッドシートを作成することが簡単に実現できます。

以下は、ブロックの入力もしくは出力で変数を利用するブロックをまとめたものです。これらのブロックは、変数をうまく扱うことで、業務処理を簡潔に実現可能です。

infoデータ形式が異なるブロック同士の場合は、「クエリーの実行」ブロックや「配列内のオブジェクト形式変換」ブロックなどのデータを加工するブロックを挟むことで、つなぎ合わせることが可能です。

この挟んだ「クエリーの実行」ブロックや「配列内のオブジェクト形式変換」ブロックなどでは、異なるデータ形式を合わせる変換処理を行います。

カテゴリー ブロック 入力変数のデータ形式 出力変数のデータ形式
基本 変数指定によるSlack通知 オブジェクトの配列 -
ログへ出力 フリー -
オブジェクト生成 - オブジェクト・配列
配列内のオブジェクト形式変換 配列 オブジェクト
ジョブ起動 変数名（データ形式はフリー） -
API HTTP GET - 文字列・オブジェクト
HTTP POST - 文字列・オブジェクト
HTTP PUT - 文字列・オブジェクト
HTTP DELETE - 文字列・オブジェクト
HTTP POST（JSON） - 文字列・オブジェクト
HTTP PUT（JSON） - 文字列・オブジェクト
BigQuery 変数からテーブルへロード オブジェクト -
クエリーの実行 - オブジェクトの配列
クエリーの並列実行 オブジェクトの配列 -
ストリームインサート オブジェクトの配列 -
テーブルの内容取得 - オブジェクトの配列
機械学習 モデルジェネレーター予測（オンライン） 文字列・オブジェクト・オブジェクトの配列 -
画像解析 - オブジェクト
音声認識 - オブジェクト
音声認識（音声認識モデル選択） - オブジェクト
テキスト分析（エンティティ分析） 文字列 オブジェクト
テキスト分析（感情分析） 文字列 オブジェクト
テキスト分析（構文分析） 文字列 オブジェクト
テキスト分析（コンテンツ分類） 文字列 オブジェクト
テキスト翻訳 文字列 オブジェクト
動画分析 - オブジェクト
物体検出（オンライン） 文字列 オブジェクト
Salesforce SOQLクエリーの実行 - オブジェクトの配列
レコードの追加 オブジェクトの配列 -
レコードの更新、無ければ追加 オブジェクトの配列 -
変数からAnalyticsへアップロード オブジェクトの配列 -
Einstein画像認識【ベータ版】 バイナリーデータ・文字列 オブジェクト
Google Cloud Pub/Subパブリッシュ 文字列 -
GCSから変数へロード - オブジェクト
変数からGCSへアップロード 文字列・オブジェクト・配列 -
GCSからファイルリスト取得 - 配列
GCSマルチファイルコピー 文字列・文字列の配列 -
GCSからDriveへファイルコピー - 文字列
Cloud Functionsの呼び出し オブジェクト 文字列・オブジェクト
Google Drive Googleドライブのアイテムを検索 - 文字列の配列・オブジェクトの配列
Googleドライブから変数へロード - バイナリー・文字列・オブジェクト・オブジェクトの配列
Googleドライブのアイテムをコピー - 文字列
スプレッドシートを作成 オブジェクトの配列 文字列
クエリーの結果からスプレッドシートを作成 - 文字列
スプレッドシートを更新 オブジェクトの配列 -
スプレッドシートのデータを取得 - オブジェクトの配列
スプレッドシートのワークシートコピー 文字列・文字列の配列 -
Google Maps 移動時間と距離を計算 配列の配列・オブジェクトの配列 オブジェクトの配列
住所を経緯度へ変換【アルファ版】 オブジェクト・オブジェクトの配列 オブジェクトの配列
経緯度を住所へ変換【アルファ版】 オブジェクト・オブジェクトの配列 オブジェクトの配列
経緯度のタイムゾーンを取得【アルファ版】 オブジェクト・オブジェクトの配列 オブジェクトの配列
標高を取得【アルファ版】 オブジェクト・オブジェクトの配列 オブジェクトの配列
地点間の道順を計算 配列 オブジェクトの配列
移動経路のスナップを取得【アルファ版】 オブジェクト・オブジェクトの配列 オブジェクトの配列
経緯度から近い区間を取得【アルファ版】 オブジェクト・オブジェクトの配列 オブジェクトの配列
Box Boxから変数へロード - バイナリー・文字列・オブジェクト・オブジェクトの配列
変数からBoxへアップロード バイナリー・文字列・オブジェクト・オブジェクトの配列 -
Watson 自然言語分類器の作成とトレーニング【ベータ版】 オブジェクト・オブジェクトの配列 -
テキストの分類【ベータ版】 文字列 オブジェクト

「フロー間共通変数」と「フロー実行内変数」の仕様は、以下のとおりです。

  • 複数持つことができ、それぞれに名称を付けて区別します。名称のルールは以下のとおりです。
    • 名称に使える文字は、英大文字・英小文字・数字・_（アンダースコアー）のみです。
    • 数字のみの名称は使用できません。
    • _で始まる名称は使用できません。

    infoフロー間共通変数の名称は、FOO_BARのようにすべて大文字にすると、フロー実行内変数との区別がつけやすくなります。

  • 扱えるデータの種類は以下のとおりです。
    • 文字列
    • 整数
    • 浮動小数点
    • 真偽
    • 型なし（NULL）
  • フロー内でフロー間共通変数の値は変更可能ですが、その影響範囲は変更を行った実行中のフロー内のみです。他の実行中のフローでは、変更されていない定義時の値を参照します。
    例（登場するフローAとフローBは別のフロー）：
    1. フロー間共通変数として、名称をFOO、値を1として定義します。
    2. 実行中のフローAで、FOOの値を100に変更後、FOOの値を参照すると、100という値が取得されます。
    3. 実行中のフローBで、FOOを参照すると、その参照タイミングに関わらず1という値（1.で定義した値）が取得されます（このフロー内でFOOを変更しない前提）。
    4. 新たに実行したフローAで、FOOの値を変更する前に、FOOを参照すると1という値（1.で定義した値）が取得されます。
  • 複数持つことができ、それぞれに名前を付けて区別します。名称のルールは以下のとおりです。
    • 名称に使える文字は、英大文字・英小文字・数字・_（アンダースコアー）です。
    • 数字のみの変数名は使用できません。
    • _で始まる名称は、BLOCKSが定義するフロー実行内変数として使います。現在、以下のフロー実行内変数が定義されています（今後も追加予定）。
      フロー実行内変数 説明
      _flow_aliases

      フローのIDが格納されています。
      _flow_id

      フローごとに自動採番された番号が格納されています。
      _group_id

      フローごとに自動採番されたグループ番号が格納されています。「ジョブ起動」ブロックからから起動された場合は、起動元フローのグループIDが継承される。
      _flow_name

      ［フローの開始］ブロックのブロック名が格納されています。
      _board_url

      フローデザイナーのURLが格納されています。

      ［例］https://*****.magellanic-clouds.net/のようなURLです。
      _board_id

      フローデザイナーURLのサブドメインが格納されています。

      ［例］https://*****.magellanic-clouds.net/の*****部分です。
      _execute_user_id

      フローを実行したユーザーのIDが格納されています。
      _execute_user_name

      フローを実行したユーザーの名前が格納されています。
      _gcs_all_files【1】

      「GCSファイル存在チェック」ブロックの確認対象の全GCS URLが配列形式で列挙されています。
      _gcs_not_found_files【1】

      「GCSファイル存在チェック」ブロックで見つからなかったGCS URLが配列形式で列挙されています。
      _target_time_unix_seconds

      フローの開始時間【2】が、1970年1月1日からの経過秒数を示すUNIX Time形式で格納されています。

      2023年11月30日14時00分の場合、UNIX Timeは「1669786800」となります。
      _target_time_iso8601

      フローの開始時間【2】が、年-月-日と時:分:秒を組み合わせた国際標準形式で格納されます。

      2023年11月30日14時00分の場合、形式は「2023-11-30T14:00:00+0900」となります。
      _target_time_iso8601_localtime

      フローの開始時間【2】が、_target_time_iso8601で用いられる国際標準形式で格納されています。

      2023年11月30日14時00分の場合は「2023-11-30T14:00:00+0900」となります。
      _target_time_iso8601_utc

      フローの開始時間【2】が、国際標準形式で格納されていますが、タイムゾーンは世界協定時刻（UTC）に固定され、「Z」が表示されます。

      2023年11月30日14時00分の場合、UTCに変換すると「2023-11-30T05:00:00Z」となります。

      【1】「GCSファイル存在チェック」ブロックで、存在確認するGCS URLのリストのファイルがひとつでもないときに、エラーメッセージプロパティ内でのみ使用可能です。

      【2】フローの開始時間とは以下のいずれかの日時を指します。

      • 定期実行されるフローでは、「フローの開始」ブロックの「開始時間」プロパティで設定された日時
      • 手動で実行されるフローでは、MAGELLAN BLOCKSが手動実行を受け付けた日時
      • フロー実行APIを通じて実行されるフローでは、target_timeパラメータで指定された日時。未指定の場合は、MAGELLAN BLOCKSがフロー実行APIを受け付けた日時

      info_始まりの名称でフロー実行内変数を命名すると、今後追加されるBLOCKS定義のフロー実行内変数と重複する可能性があります。名称が重複した場合、予期しない動作となる可能性があるため、_始まりの名称で命名しないことをおすすめします。

      また、FOO_BARのようなすべて大文字の名称は、フロー間共通変数での命名を推奨しているため、すべて大文字の名称で命名しないこともおすすめします。

  • フローの実行中にのみ有効です。
  • ブロックの入力や出力に使えます。

この情報は役に立ちましたか？