フローの実行方法
重要なお知らせ - URLの変更について
2024年10月31日（木）のリリースより、フローデザイナーのベースURLの形式が変更されます。
- 新形式:
https://flow-designer.magellanic-clouds.com/fd/{フローデザイナー番号}/- {フローデザイナー番号}：各フローデザイナーに割り当てられる固有の数値識別子
- 旧形式:
https://{システム識別子}.magellanic-clouds.net/（非推奨）- {システム識別子}：各フローデザイナーに割り当てられる固有の文字列識別子
旧形式のURLはリリース後も当面の間利用可能ですが、早めに新形式URLへの移行をお願いいたします。
はじめに
フローデザイナーで作成したフローは、以下に挙げる方法で実行できます。
- フローを手動で実行：フローデザイナー上でフローをリアルタイムに手動で実行
- フローを定期的に自動実行：フローを定期的に自動で実行
- フローを外部アプリから実行：REST APIで外部アプリからフローを実行
ここでは、フローの実行方法について解説します。
フローを手動で実行
作成したフローは、フローデザイナー上で即時実行できます。実行方法には、以下に挙げる方法があります。
「フローの開始」ブロックのプロパティから実行
フローを作成・編集後、保存を実行したときのみ、この操作ができます。
- 「フローの開始」ブロックをクリック
プロパティパネルが閉じている場合は、「フローの開始」ブロックをダブルクリックします。
- をクリック
ブロックメニューから実行
- 「フローの開始」ブロックのをクリック
- 「フローの実行」をクリック
フローを作成・編集後、保存を実行していないときは、「保存してフローを実行」をクリックします。
指定したブロックのみを実行
この機能はアルファ版です。利用にあたっては利用申請が必要です。提供している機能は完全でない場合があり、下位互換性のない変更を加える可能性もあります。このため、テスト環境での使用に適しています。利用申請／機能改善の要望／不具合の報告などは、MAGELLAN BLOCKSのお問い合わせ機能からお願いします。
「フローの開始」と「フローの終了」を除く、指定したブロックのみを実行します。
- 実行したいブロックのをクリック
- ブロックメニューの「ブロックを実行（α）」をクリック
指定したブロック以降を実行
この機能はアルファ版です。利用にあたっては利用申請が必要です。提供している機能は完全でない場合があり、下位互換性のない変更を加える可能性もあります。このため、テスト環境での使用に適しています。利用申請／機能改善の要望／不具合の報告などは、MAGELLAN BLOCKSのお問い合わせ機能からお願いします。
「フローの開始」と「フローの終了」を除く、指定したブロック以降を実行します。
- 実行を開始したいブロックのをクリック
- ブロックメニューの「フローをここから実行（α）」をクリック
フローを実行すると、フローの実行結果がログに出力されます。ログについては、「フローデザイナーの基本的な使い方」の「ログを見る」で解説しています。
フローを定期的に自動実行
作成したフローは、「毎週日曜日の深夜に実行」や「月末深夜に実行」などのように、定期的に実行できます。
定期実行のタイミングは、「フローの開始」ブロックプロパティのフローごとの「開始時間」プロパティと「開始時間を有効にする」プロパティで決まります。
「開始時間」プロパティと「開始時間を有効にする」プロパティの詳細については「ブロックリファレンス」の「フローの開始」ブロックの解説を参照してください。
定期実行は、「開始時間」プロパティを設定しただけでは、定期実行されません。「開始時間を有効にする」プロパティを「有効」に設定すると定期実行されます（初期値は「無効」になっています）。
フローを外部アプリから実行
フローは、外部アプリからREST APIを使って、実行・ステータス確認・変数値の取得などができます。
サポートするREST APIは、以下のとおりです。
フロー実行API
REST APIを使って、特定のフローを実行します。
エンドポイント
POST [Flow Designer Base URL]/flows/[ID].json
| 項目 | 説明 |
|---|---|
| [Flow Designer Base URL] |
実行したいフローが配置されているフローデザイナーのベースURL。ウェブブラウザーのアドレスバーで確認できます。 たとえば、アドレスバーに URLの「123456」の部分は、フローデザイナーごとに割り当てられる固有のフローデザイナーIDです。 2024年10月31日移行も「https://{システム識別子}.magellanic-clouds.net/」の形式のURLも利用可能ですが、新形式への移行をお勧めします。 |
| [ID] |
実行するフローのID。フローデザイナーで事前に設定。詳細は「フローデザイナーの基本的な使い方」の「フローごとの外部実行に関する設定」を参照。 |
リクエストヘッダー
| キー名 | 値 | 説明 |
|---|---|---|
| Content-Type | application/json;charset=UTF-8 | リクエストボディのデータ形式。JSON形式のデータをUTF-8エンコーディングで送信。 |
| Authorization | Bearer [API Token] | [API Token]は、事前に[設定]の[APIトークン]で発行。 |
リクエストボディ
| キー名 | データ型 | 必須 | 説明 |
|---|---|---|---|
| api_token | string | 任意 |
APIトークンを指定。Authorizationヘッダーの使用が難しい場合にのみ使用。 |
| target_time | string | 任意 |
フローを開始する時間をISO 8601形式で指定。 たとえば、日本時間の2023年11月9日午前0時に実行させたい場合は、"2023-11-09T00:00:00+09:00"と指定。 フロー内で、この時間を取得したい場合は、「%Y/%m/%d %H:%M:%S%z」のような%形式の文字列書式で参照可能。 |
| dependent_job_id | integer | 任意 |
特定のフローが他のフローに依存する場合に使用されるID。このIDを設定すると、指定したフローが成功した場合のみ、次の依存するフローが実行される。これにより、データ処理やビジネスロジックが順序正しく、また効率的に行われることを保証する。 
たとえば、あるフローBが別のフローAの完了を待つ必要がある場合、フローBを実行する際にdependent_job_idにフローAのIDを指定。この設定により、フローAの実行が完了するまでフローBは実行されない。このIDは、このAPIを使用して、完了を待つフロー（ここでいうフローA）を起動した際のレスポンスで取得できる。 
|
| _job_name | string | 任意 |
ジョブに関連付けるラベル。
この機能を用いることで、ログからジョブを簡単に識別し、管理できます。 |
| 任意のキー名 | 任意の型 | 任意 |
任意のキーと値が渡せる。フロー内では、キー名と同名の変数名でその値を参照可能。 たとえば、
|
サンプルリクエスト
curl -X POST -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Bearer 3a1b4c2d5e8f7g6h9i0j3k2l5m8n7o6p9q0r3t2u5v8w7x6y9z0a3b2c5d8e7f6g9h0" -d '{"city": "Fukuoka,jp"}' "https://flow-designer.magellanic-clouds.com/fd/123456/flows/sample_flow.json"
レスポンス
| キー名 | データ型 | 説明 |
|---|---|---|
| result | string |
フロー起動の成否。
実行したフローの結果（ステータス）ではないことに注意。実行したフローのステータスは、「実行フローのステータス確認API」で確認。 |
| job_id | integer |
実行したフローのジョブID。ジョブIDは、フローを実行するたびに自動採番されるフローデザイナー内でユニークな番号。 |
| group_id | string |
実行したフローのグループID。グループIDは、フローを実行するたびに自動採番されるフローデザイナー内でユニークなID。 「ジョブ起動」ブロックからから起動された場合は、起動元フローのグループIDが継承される。 
|
| message | string |
フローの起動に失敗したときの理由を示すメッセージ。 |
サンプルレスポンス
- 成功例：
{"result":true,"job_id":28,"group_id":"0927debd-0fc7-4db6-a2fd-f650f41c3605"} - 失敗例：
{"result":false,"message":"Flow Alias not found"} - 不正なAPIトークンを渡した場合：
{"message":"Unauthorized"}このときのHTTPレスポンスのステータスは、401 Unauthorizedになる。
グループ情報の取得API
REST APIを使って、特定のグループの情報を取得します。
エンドポイント
GET [Flow Designer Base URL]/groups/[Group ID].json
| 項目 | 説明 |
|---|---|
| [Flow Designer Base URL] |
実行したいフローが配置されているフローデザイナーのベースURL。ウェブブラウザーのアドレスバーで確認できます。 たとえば、アドレスバーに URLの「123456」の部分は、フローデザイナーごとに割り当てられる固有のフローデザイナーIDです。 2024年10月31日移行も「https://{システム識別子}.magellanic-clouds.net/」の形式のURLも利用可能ですが、新形式への移行をお勧めします。 |
| [Group ID] |
グループID。グループIDは、フローを実行するたびに自動採番されるフローデザイナー内でユニークなID。フロー実行APIのレスポンスで取得。 「ジョブ起動」ブロックからから起動されたフローは、起動元フローのグループIDが継承される。
|
リクエストヘッダー
| キー名 | 値 | 説明 |
|---|---|---|
| Authorization | Bearer [API Token] | [API Token]は、事前に[設定]の[APIトークン]で発行。 |
サンプルリクエスト
curl -X GET -H "Authorization: Bearer 3a1b4c2d5e8f7g6h9i0j3k2l5m8n7o6p9q0r3t2u5v8w7x6y9z0a3b2c5d8e7f6g9h0" "https://flow-designer.magellanic-clouds.com/fd/123456/groups/09a73744-68b6-4681-809b-943ba1feda37.json"
レスポンス
| キー名 | データ型 | 説明 | |||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| group_id | string |
グループID |
|||||||||||||||||||||||||||||||||||||
| jobs | array |
特定グループ内のフロー情報（オブジェクト）の配列。各フロー情報の内容は、以下のとおり。
|
サンプルレスポンス
- 成功時：
{"group_id":"09a73744-68b6-4681-809b-943ba1feda37","jobs":[{"schedule_id":54,"flow_name":"REST APIサンプル（グループ ID）","job_id":14,"status":"finished","target_time":"2023-10-24T10:48:25.890+09:00","started_at":"2023-10-24T10:48:26.000+09:00","finished_at":"2023-10-24T10:48:26.000+09:00","error_messages":null},{"schedule_id":53,"flow_name":"ジョブ起動サンプル","job_id":15,"status":"finished","target_time":"2023-10-24T10:48:25.890+09:00","started_at":"2023-10-24T10:48:27.000+09:00","finished_at":"2023-10-24T10:48:27.000+09:00","error_messages":null}]} - 失敗時（グループIDを間違えた場合）：
{"group_id":"09a73744-68b6-4681-809b-943ba1feda3","jobs":[]} - 不正なAPIトークンを渡した場合：
{"message":"Unauthorized"}このときのHTTPレスポンスのステータスは、401 Unauthorizedになる。
実行フローのステータス確認API
REST APIを使って、実行フローのステータスを確認します。
エンドポイント
GET [Flow Designer Base URL]/flows/[ID]/jobs/[Job ID]/status.json GET [Flow Designer Base URL]/flows/[ID]/jobs/[Job ID]/status.txt
| 項目 | 説明 |
|---|---|
| [Flow Designer Base URL] |
実行したいフローが配置されているフローデザイナーのベースURL。ウェブブラウザーのアドレスバーで確認できます。 たとえば、アドレスバーに URLの「123456」の部分は、フローデザイナーごとに割り当てられる固有のフローデザイナーIDです。 2024年10月31日移行も「https://{システム識別子}.magellanic-clouds.net/」の形式のURLも利用可能ですが、新形式への移行をお勧めします。 |
| [ID] |
ステータスを確認するフローのID。フローデザイナーで事前に設定。詳細は「フローデザイナーの基本的な使い方」の「フローごとの外部実行に関する設定」を参照。 |
| [Job ID] | ステータスを確認するフローのジョブID。フロー実行APIのレスポンスで取得。 |
リクエストヘッダー
| キー名 | 値 | 説明 |
|---|---|---|
| Authorization | Bearer [API Token] | [API Token]は、事前に[設定]の[APIトークン]で発行。 |
リクエストパラメーター
| キー名 | 必須 | 説明 |
|---|---|---|
| api_token | 任意 |
APIトークンを指定。Authorizationヘッダーの使用が難しい場合にのみ使用。 |
サンプルリクエスト
curl -X GET -H "Authorization: Bearer 3a1b4c2d5e8f7g6h9i0j3k2l5m8n7o6p9q0r3t2u5v8w7x6y9z0a3b2c5d8e7f6g9h0" "https://flow-designer.magellanic-clouds.com/fd/123456/sample_flow/jobs/1/status.json"
レスポンス
- .jsonの場合:
キー名 データ型 説明 status string フローのステータス
"planning" フローの実行を準備している "running" フローの実行中 "finished" フローの実行が成功 "failed" フローの実行に失敗 "canceled" フローの実行がキャンセルされた - .txtの場合：
planning フローの実行を準備している running フローの実行中 finished フローの実行が成功 failed フローの実行に失敗 canceled フローの実行がキャンセルされた
サンプルレスポンス
- 成功例：
{"status":"finished"} - 失敗例：
{"message":"Job not found."} - 不正なAPIトークンを渡した場合：
{"message":"Unauthorized"}このときのHTTPレスポンスのステータスは、401 Unauthorizedになる。
変数値の取得API
REST APIを使って、実行したフローの変数値を取得します。
エンドポイント
GET [Flow Designer Base URL]/flows/[ID]/jobs/[JOB ID]/variable.json
| 項目 | 説明 |
|---|---|
| [Flow Designer Base URL] |
実行したいフローが配置されているフローデザイナーのベースURL。ウェブブラウザーのアドレスバーで確認できます。 たとえば、アドレスバーに URLの「123456」の部分は、フローデザイナーごとに割り当てられる固有のフローデザイナーIDです。 2024年10月31日移行も「https://{システム識別子}.magellanic-clouds.net/」の形式のURLも利用可能ですが、新形式への移行をお勧めします。 |
| [ID] |
ステータスを確認するフローのID。フローデザイナーで事前に設定。詳細は「フローデザイナーの基本的な使い方」の「フローごとの外部実行に関する設定」を参照。 |
| [Job ID] | ステータスを確認するフローのジョブID。フロー実行APIのレスポンスで取得。 |
リクエストヘッダー
| キー名 | 値 | 説明 |
|---|---|---|
| Authorization | Bearer [API Token] | [API Token]は、事前に[設定]の[APIトークン]で発行。 |
リクエストパラメーター
| キー名 | 必須 | 説明 |
|---|---|---|
| api_token | 任意 |
APIトークンを指定。Authorizationヘッダーの使用が難しい場合にのみ使用。 |
| variable | 任意 |
変数名を指定して変数値を取得。変数名には、オブジェクト形式や配列形式データの一部を参照する記法が使用可能。 省略した場合は、変数_の値を取得。 |
サンプルリクエスト
curl -X GET -H "Authorization: Bearer 3a1b4c2d5e8f7g6h9i0j3k2l5m8n7o6p9q0r3t2u5v8w7x6y9z0a3b2c5d8e7f6g9h0" "https://flow-designer.magellanic-clouds.com/fd/123456/flows/sample_flow/jobs/1/variable.json?variable=_.predictions"
サンプルレスポンス
- 成功例：
[{"score":[0.9999089241027832,9.108754602493718e-05],"key":"gs://my-storage-1703/blocks_ml_image_example/prediction/sample_01.jpg","label":"cat"},{"score":[0.0008647672948427498,0.9991353154182434],"key":"gs://my-storage-1703/blocks_ml_image_example/prediction/sample_02.jpg","label":"dog"}] - 失敗例（存在しない変数名を指定）：
{"status":500,"error":"Internal Server Error"} - 不正なAPIトークンを渡した場合：
{"message":"Unauthorized"}このときのHTTPレスポンスのステータスは、401 Unauthorizedになる。
ジョブをグループ単位でキャンセルAPI
REST APIを使って、特定のグループのジョブをキャンセルします。キャンセル対象は、ステータスがplanning（フローの実行を準備している）およびrunning（フローの実行中）のジョブのみです。
エンドポイント
POST [Flow Designer Base URL]/groups/[Group ID]/cancel
| 項目 | 説明 |
|---|---|
| [Flow Designer Base URL] |
実行したいフローが配置されているフローデザイナーのベースURL。ウェブブラウザーのアドレスバーで確認できます。 たとえば、アドレスバーに URLの「123456」の部分は、フローデザイナーごとに割り当てられる固有のフローデザイナーIDです。 2024年10月31日移行も「https://{システム識別子}.magellanic-clouds.net/」の形式のURLも利用可能ですが、新形式への移行をお勧めします。 |
| [Group ID] |
グループID。グループIDは、フローを実行するたびに自動採番されるフローデザイナー内でユニークなID。フロー実行APIのレスポンスで取得。 「ジョブ起動」ブロックからから起動されたフローは、起動元フローのグループIDが継承される。
|
リクエストヘッダー
| キー名 | 値 | 説明 |
|---|---|---|
| Content-Type | application/json;charset=UTF-8 | リクエストボディのデータ形式。JSON形式のデータをUTF-8エンコーディングで送信。 |
| Authorization | Bearer [API Token] | [API Token]は、事前に[設定]の[APIトークン]で発行。 |
リクエストボディ
| キー名 | データ型 | 必須 | 説明 |
|---|---|---|---|
| api_token | string | 任意 |
APIトークンを指定。Authorizationヘッダーの使用が難しい場合にのみ使用。 |
サンプルリクエスト
curl -X POST -H "Authorization: Bearer 3a1b4c2d5e8f7g6h9i0j3k2l5m8n7o6p9q0r3t2u5v8w7x6y9z0a3b2c5d8e7f6g9h0" "https://flow-designer.magellanic-clouds.com/fd/123456/groups/09a73744-68b6-4681-809b-943ba1feda37/cancel"
レスポンス
| キー名 | データ型 | 説明 |
|---|---|---|
| job_ids | array |
キャンセルしたジョブIDの一覧（配列）。 |
サンプルレスポンス
{"job_ids":[101,102,103]}
ジョブをすべて削除API
REST APIを使って、指定したフローのジョブをすべて削除します。
エンドポイント
DELETE [Flow Designer Base URL]/flows/[ID]/jobs.json
| 項目 | 説明 |
|---|---|
| [Flow Designer Base URL] |
実行したいフローが配置されているフローデザイナーのベースURL。ウェブブラウザーのアドレスバーで確認できます。 たとえば、アドレスバーに URLの「123456」の部分は、フローデザイナーごとに割り当てられる固有のフローデザイナーIDです。 2024年10月31日移行も「https://{システム識別子}.magellanic-clouds.net/」の形式のURLも利用可能ですが、新形式への移行をお勧めします。 |
| [ID] |
ステータスを確認するフローのID。フローデザイナーで事前に設定。詳細は「フローデザイナーの基本的な使い方」の「フローごとの外部実行に関する設定」を参照。 |
リクエストヘッダー
| キー名 | 値 | 説明 |
|---|---|---|
| Authorization | Bearer [API Token] | [API Token]は、事前に[設定]の[APIトークン]で発行。 |
サンプルリクエスト
curl -X DELETE -H "Authorization: Bearer 3a1b4c2d5e8f7g6h9i0j3k2l5m8n7o6p9q0r3t2u5v8w7x6y9z0a3b2c5d8e7f6g9h0" "https://flow-designer.magellanic-clouds.com/fd/123456/flows/1/jobs.json"
サンプルレスポンス
- 成功例：
{"result":true} - 失敗例：
{"result":false,"message":"Flow Alias not found"} - 不正なAPIトークンを渡した場合：
{"message":"Unauthorized"}このときのHTTPレスポンスのステータスは、401 Unauthorizedになる。
終了状態のジョブをすべて削除API
REST APIを使って、指定されたフローの終了状態のジョブをすべて削除します。ステータスが終了以外のものは削除されません。
エンドポイント
DELETE [Flow Designer Base URL]/flows/[ID]/finished_jobs.json
| 項目 | 説明 |
|---|---|
| [Flow Designer Base URL] |
実行したいフローが配置されているフローデザイナーのベースURL。ウェブブラウザーのアドレスバーで確認できます。 たとえば、アドレスバーに URLの「123456」の部分は、フローデザイナーごとに割り当てられる固有のフローデザイナーIDです。 2024年10月31日移行も「https://{システム識別子}.magellanic-clouds.net/」の形式のURLも利用可能ですが、新形式への移行をお勧めします。 |
| [ID] |
ステータスを確認するフローのID。フローデザイナーで事前に設定。詳細は「フローデザイナーの基本的な使い方」の「フローごとの外部実行に関する設定」を参照。 |
リクエストヘッダー
| キー名 | 値 | 説明 |
|---|---|---|
| Authorization | Bearer [API Token] | [API Token]は、事前に[設定]の[APIトークン]で発行。 |
サンプルリクエスト
curl -X DELETE -H "Authorization: Bearer 3a1b4c2d5e8f7g6h9i0j3k2l5m8n7o6p9q0r3t2u5v8w7x6y9z0a3b2c5d8e7f6g9h0" "https://flow-designer.magellanic-clouds.com/fd/123456/flows/1/finished_jobs.json"
サンプルレスポンス
- 成功例：
{"result":true} - 失敗例：
{"result":false,"message":"Flow Alias not found"} - 不正なAPIトークンを渡した場合：
{"message":"Unauthorized"}このときのHTTPレスポンスのステータスは、401 Unauthorizedになる。
フローのキャンセルとログの削除
実行中のフローのキャンセルやログの削除を行うには、フローデザイナーのログリスト左のチェックボックスをクリックします。
info_outlineフローの実行時間が短い場合やフローの実行が終了間際の場合は、フローの実行をキャンセルできないことがあります。
実行に失敗したフローの再実行
実行に失敗したフローは、同じ変数や開始時刻で再実行ができます。
- 実行に失敗したフローのみ再実行できます（ステータスが失敗のフローのみ）。
- 変数は、実行に失敗したフローの起動時の変数を引き継ぎます。
フロー終了時点の変数内容を引き継ぐわけではありません。 - 開始時刻は、実行に失敗したフローの開始時刻を引き継ぎます。
「開始時刻」は、定期実行・手動実行・フロー実行APIによる実行によって、異なります。- 定期実行：「フローの開始」ブロックの「開始時間」プロパティの値
- 手動実行：フローの手動実行をMAGELLAN BLOCKSが受け付けた日時
- フロー実行APIによる実行：手動実行と同じ。ただし、target_timeパラメーターが指定された場合は、そのパラメーターに指定された時刻。
- フローの内容は、再実行時点の内容で実行します。
実行失敗後に、フローを修正した場合、修正した内容で実行されます。
再実行の手順は、以下のとおりです。
- ログパネルから再実行したい、ステータスが失敗のフローをクリック
- 「replay再実行」をクリック