Power Automate ワークフロー式関数 parameters, action関数他 まとめ＋環境変数について

はじめに

Microsoft Power Automate で登場する ワークフロー式関数の意味、パラメータ、戻り値、記述例をまとめました。
全部網羅するのは困難ですので、
Power Automate function [関数名] でググった結果、ヒット件数ランキング 15 位まで順に書いていこうと思います。

日本語のブラウザ、日本の Google 検索でググった結果です。一般的な言葉だからヒット数が多いというのも考えられますが、そういったことは考慮しませんでした。

【 Power Automate 】

Power Automate は、よく使うアプリやサービスとの間に自動化されたワークフローを作成し、ファイルの同期、通知の受信、データの収集などを行うことができるようにするためのサービスです。

ノーコード／ローコードで自動化処理が作成できます。

【 ノーコード／ローコード 】

ノーコード＝クリック、ドラッグ＆ドロップするだけで自動化処理を作成し、プログラムの記述が無い。ローコード＝自分で書いたプログラムの記述が少しだけある。の意味です。

Power Automateでは、クリックするだけで自動的に関数が使われていたりします。今回は、その関数について把握するためのまとめです。

当初は、もっと多く書くつもりでしたが、式についてのうんちく の話と、parameters 関数（環境変数）、action 関数 の説明が大きくなってきて、15個だけにしました。

● ヒット件数順
掲載関数一覧（ページ内リンク）
↓
and 関数
parameters 関数
or 関数
not 関数
if 関数
take 関数
addHours 関数
first 関数
add 関数
last 関数
actions 関数
action 関数
less 関数
greater 関数
range 関数

全関数の検索ヒット数一覧は、以下です。ダウンロードするか、クリックして拡大してください。

↓

式についてのうんちく

今回は、変数を初期化 とか、Microsoft 365 の エクセルで以下のようにテーブルを作成したりして、検証しました。

Excel Online (Business) コネクタのアクション 表内に存在する行を一覧表示
↓
コントロールコネクタのアクション Apply to each（それぞれに適用する）
↓
Excel Online (Business) コネクタのアクション 行の更新
と実行し、行の更新のスコアのところにいろいろ関数を適用していきます。

記事中に出てくる各々の関数の使用例は、無理やり適用していて、深い意味は無いです。

スコアのところの 動的なコンテンツの追加 をクリック
↓
動的なコンテンツ
↓
スコア

を選択すると、スコアのところに 四角い スコア が入力されます。
このまま保存して動作させると、スコア列の各々の行=元々のスコアの値で更新するため、更新処理は走りますが、値が変わらない結果になります。

四角い スコア にマウスを当てると、
items('Apply_to_each')?['スコア']
になります。

これは、見た目が 四角い スコア の実際の式です。
一つずつ、意味を紐解きます。

items
引数にループ名を指定すると、そのループの現在の現在の項目が返ります。
ループ名とは、「Apply to each」の部分です。

スペースはアンダーバーにしないといけない決まりです。
items('Apply_to_each')
で、「Apply to each」ループの現在の項目を返します。

現在の項目とは、ここでは、エクセルの一行に相当します。

items('Apply_to_each')?
?（クエスチョンマーク） は、この後指定する項目名が存在しない場合、エラーにならずに、null を返すという意味です。

今回の場合、items('Apply_to_each')?['スコ']のようにわざと項目名を間違えてみましたが、スコアを null で更新しようとして、値の変化はありませんでした。

items('Apply_to_each')?['スコア']
['スコア'] の部分は、
items('Apply_to_each')? の中のスコアの項目を指定して、値を取り出すという意味になります。
ドットを使って、
items('Apply_to_each')?.スコア
でも同じ意味ですが、スペースがある場合、ドットを使う書き方は許されません。
例えば、
items('Apply_to_each')?.score data は、ＮＧで、items('Apply_to_each')?['score data'] と書かないといけないです。

ところで、四角い スコア をクリックして CTRL + C でコピーすると、
@{items('Apply_to_each')?['スコア']}
という文字列がコピーされています。

この @（アットマーク）ですが、式を意味しています。@{...} でくくられているため、... 部分はただの文字ではなく、式ですという意味になります。
例えば、aaa@{items('Apply_to_each')?['スコア']}bbb とした場合、「aaa[items('Apply_to_each')?['スコア']を実行した値]bbb」 という文字列が得られます。
最初から関数で始まる場合は、@{...} でくくる必要はなく、@関数... で構いません。

ただし、@ が不要な場面があります。
@{items('Apply_to_each')?['スコア']}
を式入力欄に入力すると、「式が無効です。」となります。

式入力欄は、入力内容が式であることは分かり切っているため、
items('Apply_to_each')?['スコア'] で良いのです。

内部処理的には、@items('Apply_to_each')?['スコア'] が入力されたことになります。

スコア入力欄に
@{items('Apply_to_each')?['スコア']}
をペーストすると、視覚的に分かる 四角い スコア マークに変わります。

↓

ただし、@{items('Apply_to_each')?['スコア']} と一文字ずつ入力していくと、最初から文字列を入力していると認識されて、スコア マークに変わらず、式ではなく、文字列として扱われます。
（このまま動作させると、「@{items('Apply_to_each')?['スコア']}」とエクセルのセルに入力されます。）

なぜ、文字列として扱われるかというと、コードビューを見ると分かるのですが、実際の入力値が
"item/スコア": "@@{items('Apply_to_each')?['スコア']}"
となっていて、内部的には、@ が２つ連続＝@ 一文字の意味 になっているからです。

and 関数

すべての式が true かどうかを調べます。

種類

論理比較関数

構文

and(<調べる式１>, <調べる式２>, ...)

戻り値

使用例

if(and(equals(items('Apply_to_each')?['id'],'2'),equals(items('Apply_to_each')?['スコア'],'50')),'500',null)

parameters 関数

一般的な言葉のため、検索ヒット数上位に来たと思われます。

ワークフローの定義で記述されているパラメーターの値を返します。
・・・と公式ドキュメントの説明にあるのですが、この説明では分かりません！
parameters 関数は、ソリューションの環境変数を読み込む関数です。

ソリューションの環境変数

環境変数は、ソリューションのリソースです。したがって、ソリューションの中にフローがあることが前提となります。
トップ画面からいきなり「＋作成」で作成したフローは、ソリューションのフローではありません。

parameters 関数を利用するためには、まず、ソリューションの作成から行う必要があります。

ソリューションとは何かについては、省略します。

ソリューション作成

左側から ソリューション を選択して、＋新しいソリューション を選択します。

表示名：testsolution
名前：testsolution
と入力し、
公開元：＋新しい公開元 を選択します。

ソリューションには、公開元（Publisher）を設定する必要がありますので、公開元を登録します。

CDS Default Publisher (Crcabcd)

org123abcde における既定の発行者(D...

のようにデフォルトの公開元が選択できますが、選ばない方が良いようです。

表示名：testpublisher
名前：testpublisher
接頭辞：setto
選択する値の接頭辞：51229
とし、保存 ボタンをクリックします。

接頭辞、選択する値の接頭辞（ 10000 から 99999 の数字で、接頭辞入力時に自動的に入力されます。）の正確な用途は不明ですが、コマンドラインで何かするときにオプションに指定が必要になります。（暗証番号的なもの？）

接頭辞は、環境変数など作成物の名前に反映されます。今回の場合、testenv という環境変数を登録すると、setto_testenv になります。

選択する値の接頭辞（Choice value prefix）は、表向きどこにも反映されないようです。

ソリューション作成画面に戻って、
公開元：testpublisher (testpublisher)
選択後、作成 ボタンをクリックします。

環境変数作成

このソリューション内で、環境変数を作成します。

ソリューション → testsolution → ＋新規 → その他 → 環境変数
をクリックします。

表示名：testenv
名前：testenv
データ側：JSON
設定値：{"fullName":"Sophia Owen"}
とし、 保存 をクリックします。

ソリューションに環境変数が登録されました。

フロー作成

ソリューション → testsolution → ＋新規 → 自動化 → クラウドフロー → すぐに
をクリックします。

最後の選択肢（分かりにくい！）は、以下の意味です。

自動：自動化したクラウドフロー（トリガーで実行するフロー）を作成

すぐに：インスタントクラウドフロー（手動実行するフロー）を作成

スケジュール済み：スケジュール済みクラウドフローを作成

このフローで環境変数を入力値として使えます。

種類

ワークフロー関数

構文

parameters('<環境変数名>')

戻り値

使用例

・式

parameters('testenv (setto_testenv)')['fullName']

・戻り値の例

"Sophia Owen"

or 関数

少なくとも 1 つの式が true かどうかを調べます。 少なくとも 1 つの式が true の場合は true を返し、すべての式が false の場合は false を返します。

種類

論理比較関数

構文

or(<調べる式1>, <調べる式2>, ...)

戻り値

使用例

if(or(equals(items('Apply_to_each')?['id'],'2'),equals(items('Apply_to_each')?['スコア'],'50')),'500',null)

not 関数

式が false かどうかを調べます。 式が false の場合は true を返し、true の場合は false を返します。

種類

論理比較関数

構文

not(<調べる式>)

戻り値

使用例

if(not(equals(items('Apply_to_each')?['id'],'2')),'500',null)

if 関数

式が true か false かを調べます。 結果に基づき、指定された値を返します。 パラメーターは左から右へ評価されます。

種類

論理比較関数

構文

if(<調べる式>, <式がtrueのときの値>, <式がfalseのときの値>)

戻り値

使用例

if(not(equals(items('Apply_to_each')?['id'],'2')),'500',null)

take 関数

コレクション（配列）の先頭から項目を返します。

種類

コレクション関数

構文

take('<文字列>', <先頭から取得する項目の数を示す正の整数>)
take([<配列>], <先頭から取得する項目の数を示す正の整数>)

戻り値

使用例

文字列

・式

take('12345', 3)

・戻り値の例
"123"

配列

・式

take(createArray(100, 200, 300, 400, 500), 3)[0]

・戻り値の例
100
注意：[0]が無い場合、[100, 200, 300] の配列です。

addHours 関数

タイムスタンプに時間を加算します。

種類

日付または時刻の関数

構文

addHours('<タイムスタンプ>', <加算または減算する時間数>, '<書式>'?)
'<書式>'? の ? は、'<書式>' の指定が必須ではないことを意味します。
指定しない場合、"o" (yyyy-MM-ddTHH:mm:ss.fffffffK) です

戻り値

使用例

・式

addHours('2022-03-15T15:00:00Z',5,'yyyy/MM/dd hh:mm:ss')

・戻り値の例
"2022/03/15 20:00:00"

first 関数

文字列または配列から最初の項目を返します。

種類

コレクション関数

構文

first('<文字列>')
first([<配列>])

戻り値

使用例

文字列

・式

first('abcde')

・戻り値の例

"a"

配列

・式

first(createArray(100, 200, 300))

・戻り値の例

100

add 関数

2 つの数値を加算した結果を返します。

種類

算術関数

構文

add(<数値1>, <数値2>)

戻り値

使用例

・式

add(int(items('Apply_to_each')?['スコア']),10)

・戻り値の例

80

last 関数

2 つの数値を加算した結果を返します。

種類

算術関数

構文

last(<数値1>, <数値2>)

戻り値

使用例

・式

last(int(items('Apply_to_each')?['スコア']),10)

・戻り値の例

80

actions 関数

実行時のアクションの出力を返すか、または式に割り当てることができる他の JSON の名前と値のペアの値を返します。

種類

ワークフロー関数

構文

actions('<アクション名>')

戻り値

使用例

・式

actions('行の更新')

・戻り値の例

{
  "name": "行の更新",
  "inputs": {
    "host": {
略
      "operationId": "PatchItem"
    },
    "parameters": {
      "source": "me",
略
      "id": "1"
    }
  },
  "outputs": {
    "statusCode": 200,
    "headers": {
      "Pragma": "no-cache",
      "Transfer-Encoding": "chunked",
略
      "Expires": "-1",
      "Content-Length": "400"
    },
    "body": {
略
      "id": "1",
      "名前": "テスト太郎",
      "スコア": "80"
    }
  },
略
  "code": "OK",
  "status": "Succeeded"
}

action 関数

実行時のアクションの出力を返すか、または式に割り当てることができる他の JSON の名前と値のペアの値を返します。
action() 関数は、次の場所でのみ使うことができます。
・元の subscribe 要求の結果にアクセスできるように、webhook アクションの unsubscribe プロパティ
・アクションの trackedProperties プロパティ
・アクションの do-until ループ条件

ここでは、「アクションの trackedProperties プロパティ」の場合のみ書きます。

trackedProperties

・・・ → 設定 をクリックします。

追跡対象プロパティに
TrackedValue："@action()?['inputs']"
を入力します。
ここでの action()?['inputs']" は、自分自身（今回の場合、変数を初期化する アクション）に対する入力値という意味になります。すなわち、

{
    "xxx": "aaa",
    "yyy": "bbb"
}

のことです。

追跡対象プロパティ ですが、英語では、Tracked Properties と表記されています。

"@action()?['inputs']" の @ が無いと、ただの文字列として認識されますので、式として認識させるために @ は必要です。

actions('変数を初期化する')?['trackedProperties']
のように後で参照できます。

actions('変数を初期化する')?['trackedProperties'] の内容は、以下のような内容です。

{
  "TrackedValue": {
    "variables": [
      {
        "name": "オブジェクトテスト",
        "type": "Object",
        "value": {
          "xxx": "aaa",
          "yyy": "bbb"
        }
      }
    ]
  }
}

種類

ワークフロー関数

構文

action()

戻り値

使用例

上記の trackedProperties セクションの説明の通りです。

less 関数

1 番目の値が 2 番目の値より小さいかどうかを調べます。 1 番目の値の方が小さい場合は true を返し、小さくないい場合は false を返します。

種類

論理比較関数

構文

less(<2番目の値より小さいかどうかを調べる値>, <比較する値>)
less('<2番目の値より小さいかどうかを調べる文字列>', '<比較する文字列>')

戻り値

使用例

数値

・式

less(5, 10)

・戻り値の例

true

文字列

・式

less('banana', 'apple')

・戻り値の例

false

ソートした時、'banana' が 'apple' より下に来るから、'banana' は 'apple' より大きい＝false です。

greater 関数

1 番目の値が 2 番目の値より大きいかどうかを調べます。 1 番目の値の方が大きい場合は true を返し、大きくない場合は false を返します。

種類

論理比較関数

構文

greater(<2番目の値より大きいかどうかを調べる値>, <比較する値>)
greater('<2番目の値より大きいかどうかを調べる文字列>', '<比較する文字列>')

戻り値

使用例

数値

・式

greater(5, 10)

・戻り値の例

false

文字列

・式

greater('banana', 'apple')

・戻り値の例

true

ソートした時、'banana' が 'apple' より下に来るから、'banana' は 'apple' より大きい＝true です。

range 関数

指定した整数から始まる整数の配列を返します。

種類

論理比較関数

構文

range(<配列を開始する整数値>, <配列内の整数の数>)

<配列内の整数の数> は、10 万を超えない正の整数である必要があります。

<配列を開始する整数値> と <配列内の整数の数> の合計は、2,147,483,647 以下である必要があります。

戻り値

使用例

数値

・式

range(1, 4)

・戻り値の例

[1, 2, 3, 4]