【Alteryx Tips】分析アプリをAPIで実行する場合の設定について

2024年8月20日 2024年10月10日 12分11秒

分析アプリをAPIで実行する場合の設定についてご紹介します

Alteyrx Serverに置かれた分析アプリをAPI(v3)で実行する場合、各質問に対する入力はどのように設定するのかについてご紹介します。なおAPIの使用方法につきましては本説明では割愛します。

全体の流れ

分析アプリの質問は、GET:/v3/workflows/{workflowId}/questions メソッドで取得できます。

取得した内容を元に、POST:/v3/workflows/{workflowId}/jobs メソッドで質問を設定してワークフローを実行します。

以下に、各ツールにおける設定方法をご紹介します。なお例として使用するワークフローでは質問で設定した内容を実行結果で確認できるようにしています。

チェックボックスツールの場合

チェックボックスツールを含むワークフローは、GET:/v3/workflows/{workflowId}/questions メソッドに対して以下のような応答を返します。

ここで得られる"name"キーの値はツールの名前、"value"キーの値は現在の状態をブーリアン型で表しています(Falseはチェックしていない意味)。これらのキーの値をPOST:/v3/workflows/{workflowId}/jobsメソッドで使用します。

使用例は以下のとおりです。

{
  "questions": [
    {
      "name": "チェックボックス (2)",
      "value": "True"
    }
  ],
  "priority": "Default"
}

"workerTag"および"credentialId"オブジェクトは省略可能です。"questions"オブジェクト内の"name"キーには先程取得したツールの名前を、"value"キーにはワークフロー実行時のチェックボックスの状態(Trueはチェックを入れる意味)を記入します。

POSTメソッドを送信後にワークフローの実行結果を確認すると、チェックボックスにチェックが入っている状態でワークフローは実行されたことが確認できます。

Dateツールの場合

Dateツールを含むワークフローは、GET:/v3/workflows/{workflowId}/questions メソッドに対して以下のような応答を返します。

ここで得られる"name"キーの値はツールの名前、"value"キーの値は現在の状態を表しています(nullは未記入の意味)。これらのキーの値をPOST:/v3/workflows/{workflowId}/jobsメソッドで使用します。

使用例は以下のとおりです。

{
  "questions": [
    {
      "name": "Date (14)",
      "value": "2024-07-07"
    }
  ],
  "priority": "Default"
}

"workerTag"および"credentialId"オブジェクトは省略可能です。"questions"オブジェクト内の"name"キーには先程取得したツールの名前を、"value"キーにはワークフロー実行時に入力したい日付(yyyy-mm-dd形式)を記入します。

POSTメソッドを送信後にワークフローの実行結果を確認すると、日付が入っている状態でワークフローは実行されたことが確認できます。

ドロップダウンツールの場合

ドロップダウンツールを含むワークフローは、GET:/v3/workflows/{workflowId}/questions メソッドに対して以下のような応答を返します。

ここで得られる"name"キーの値はツールの名前、"items"キーには項目ごとの内容、"value"キーの値はその項目の値を表しています。"name"および"value"キーの値をPOST:/v3/workflows/{workflowId}/jobsメソッドで使用します。

使用例は以下のとおりです。

{
  "questions": [
    {
      "name": "ドロップダウン (14)",
      "value": "夏"
    }
  ],
  "priority": "Default"
}

"workerTag"および"credentialId"オブジェクトは省略可能です。"questions"オブジェクト内の"name"キーには先程取得したツールの名前を、"value"キーにはワークフロー実行時に選択した項目の値を記入します。

POSTメソッドを送信後にワークフローの実行結果を確認すると、項目を選択した状態でワークフローは実行されたことが確認できます。

数値増減ツールの場合

数値増減ツールを含むワークフローは、GET:/v3/workflows/{workflowId}/questions メソッドに対して以下のような応答を返します。

ここで得られる"name"キーの値はツールの名前、"value"キーの値は規定の値を表しています。これらのキーの値をPOST:/v3/workflows/{workflowId}/jobsメソッドで使用します。なお数値増減ツールには他にも最小、最大、増分、小数位といった設定項目もありますが、API上でこれらの設定内容を確認することはできません。

使用例は以下のとおりです。

{
  "questions": [
    {
      "name": "数値増減 (16)",
      "value": "7"
    }
  ],
  "priority": "Default"
}

"workerTag"および"credentialId"オブジェクトは省略可能です。"questions"オブジェクト内の"name"キーには先程取得したツールの名前を、"value"キーにはワークフロー実行時に選択したい数値を記入します。

POSTメソッドを送信後にワークフローの実行結果を確認すると、選択された数値でワークフローは実行されたことが確認できます。

補足: 条件外の値を入力した場合

数値増減ツールで設定した入力条件と異なる値を"value"キーに設定して実行するとどうなるのか確認してみます。

上図は数値増減ツールの設定となり、値は0から10までの整数と設定しています。

設定した範囲外の値を入力した場合

上限を超える値(31.24)を入力してワークフローを実行すると、実行エラーとなりました。

値の範囲内だが設定していない桁数の小数を入力した場合

値の範囲内だが設定していない桁数の小数(1.24)を入力してワークフローを実行すると、成功しました。

まとめると次のようになります。

値の範囲外に設定した場合: ワークフローの実行は失敗
値の範囲内だが許可していない桁数の小数に設定した場合: ワークフローの実行は成功

となり、値の範囲内であれば設定と異なる値でも実行できてしまうので、注意が必要です。

ラジオボタンツールの場合

ラジオボタンツールを含むワークフローは、GET:/v3/workflows/{workflowId}/questions メソッドに対して以下のような応答を返します。

ここで得られる"name"キーの値はツールの名前、"value"キーの値は現在の状態をブーリアン型で表しています(Falseはチェックしていない意味)。"name"および"value"キーの値をPOST:/v3/workflows/{workflowId}/jobsメソッドで使用します。なおグループ情報は含まれていないため、どのラジオボタンが同一グループに属するかは"description"キーの値などから推定します。

使用例は以下のとおりです。

{
  "questions": [
    {
      "name": "ラジオボタン (14)",
      "value": "True"
    },
    {
      "name": "ラジオボタン (22)",
      "value": "True"
    }
  ],
  "priority": "Default"
}

"workerTag"および"credentialId"オブジェクトは省略可能です。"questions"オブジェクト内の"name"キーには先程取得したツールの名前を、"value"キーにはワークフロー実行時のラジオボタンの状態(Trueはチェックを入れる意味)を記入します。

補足: 同一グループ内で複数選択した、または全く選択しない場合

通常、同一グループ内のラジオボタンは必ずどれか一つだけを選択しますが、APIでは複数を選択することや全く選択しないことができてしまいます。その場合の挙動を確認してみます。

検証に使用したワークフローは下図のようなものとなり、2つのグループにそれぞれ2つのラジオボタンを配置しています。各ラジオボタンのチェック有無は異なるカラムに記録され、それらの値を出力します。

{
  "questions": [
    {
      "name": "ラジオボタン (12)",
      "value": "True"
    },
    {
      "name": "ラジオボタン (14)",
      "value": "True"
    }
  ],
  "priority": "Default"
}

ここで"name"キーの値"ラジオボタン(12)"と"ラジオボタン(14)"は同一グループのラジオボタンであるButton1とButton2を指しており、片方のグループのラジオボタンは両方ともチェックを入れ、もう片方のグループのラジオボタンには両方ともチェックしないよう設定しています。この状態で実行すると以下のような結果になりました。

ワークフローはエラーとはならず完了しました。出力ではButton1 | Button2 | Button3 | Button4の状態を出力していますが、APIの設定通りButton1とButton2がチェックされています。従って、APIを利用した場合はグループの制約を無視して実行できてしまうことが分かります。