フローの実行方法
はじめに
フローデザイナーで作成したフローは、以下に挙げる方法で実行できます。
- フローを手動で実行：フローデザイナー上でフローをリアルタイムに手動で実行
- フローを定期的に自動実行：フローを定期的に自動で実行
- フローを外部アプリから実行：REST APIで外部アプリからフローを実行
フロー・ジョブ・ログの関係について
フロー・ジョブ・ログの関係は、料理に例えると理解しやすくなります。
- フロー：レシピ（設計図）
どのような処理を行うかの手順を定義したもの - ジョブ：料理を作る作業（実行単位）
レシピに従って実際に料理する作業そのもの - ログ：料理の記録（実行履歴）
作業の過程や結果を記録したもの
この関係を整理すると、1つのフロー（レシピ）から複数のジョブ（料理作業）を実行でき、それぞれのジョブごとにログ（料理の記録）が生成されます。同じレシピで何度も料理できるように、1つのフローから何度でもジョブを実行できるわけです。
ジョブとログは必ずセットで管理されます。ジョブが実行されると自動的にログが記録され、ジョブを削除するとログも一緒に削除される仕組みになっています。
ログは、以下の2つの場所で確認できます。
- 手動実行の場合
フローデザイナー内のログパネルでリアルタイムに確認できます。 - 定期実行や外部アプリからの実行の場合
フローデザイナー詳細画面で履歴として確認できます。
フローを手動で実行
作成したフローは、フローデザイナー上で即時実行できます。実行方法には、以下に挙げる方法があります。
「フローの開始」ブロックのプロパティから実行
フローを作成・編集後、保存を実行したときのみ、この操作ができます。
- 「フローの開始」ブロックをクリック
プロパティパネルが閉じている場合は、「フローの開始」ブロックをダブルクリックします。
- をクリック
ブロックメニューから実行
- 「フローの開始」ブロックのをクリック
- 「フローの実行」をクリック
フローを作成・編集後、保存を実行していないときは、「保存してフローを実行」をクリックします。
指定したブロックのみを実行
この機能はアルファ版です。利用にあたっては利用申請が必要です。提供している機能は完全でない場合があり、下位互換性のない変更を加える可能性もあります。このため、テスト環境での使用に適しています。利用申請／機能改善の要望／不具合の報告などは、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再実行」をクリック