基本操作ガイド

Basic Guide

Big Data ボードのフローの実行

フローの外部実行

フローは、外部アプリケーションから Web API を使って、実行・ステータス確認・変数値の取得ができます。

サポートする API は、以下のとおりです。

フロー実行 API

フロー実行 API は、外部アプリケーションからフローを実行する Web API です。

この Web API へは、HTTP の POST メソッドで以下の URL にアクセスします。

[POST] ボードURL/flows/ID.json

項目 説明
ボード URL 実行するフローがある Big Data ボードの URL です。この URL は、Big Data ボードを開いて、ウェブブラウザーのアドレスバーで確認します。
ID

実行するフローの ID です。ID は、フローリストで設定します。ID の規則は、以下のとおりです。

  • 英数字(a-z、A-Z、0-9)、ハイフン(-)およびアンダースコアー(_)が使用できます。
  • 最大長は、64 文字です。

本 Web API のアクセスには、API トークンを使った認証が必要です。Web API アクセス時に、以下の Authorization ヘッダーを含めてください。

Authorization: Bearer API トークン

項目 説明
API トークン [ボード設定][API トークン] で発行したものを使います。

以下のパラメーターが HTTP リクエストのボディに指定できます(HTTP リクエストの Content-Type ヘッダーは x-www-form-urlencoded)。

パラメーター名 説明
api_token API トークンを指定します。Authorization ヘッダーの使用が難しい場合に使用します。
target_time フローを開始する時刻を指定します。
dependent_job_id 依存するフローのジョブ ID を指定します。ジョブ ID は、フロー実行 API のレスポンスに含まれています。
任意の名前 任意のパラメーターが渡せます。フロー内では、パラメーター名と同名の変数で参照できます。パラーメーターで渡す値は、すべて文字列として扱われます。

HTTP リクエストの Content-Type ヘッダーが application/json の場合は、HTTP リクエストのボディに指定された JSON テキストを解析して、BLOCKS の変数に値を設定します。

ボディに、以下の JSON テキストが指定されていたとします。

{"foo": 100, "bar": "baz"}

この場合は、変数 foo に数値の 100 を、変数 bar に文字列の "baz" をそれぞれ設定します。

このように、JSON オブジェクト値の各メンバーの名前に変数名を指定し、値に変数値を指定します。

HTTP ボディの JSON テキストの例

前述のパラメーターを使った方法だと、文字列値しか変数に設定できませんが、この方法だと数値や配列値なども設定できます。

レスポンスは、JSON 形式の文字列が返ってきます。

以下は、フローの実行に成功した例です。

{
  "result": true,
  "job_id": 1
}

フローの実行に成功した場合は、"result"true で、"job_id" に実行したフローのジョブ ID が設定されます。ジョブ ID は、フローを実行するたびに採番されるボード内でユニークな番号です。実行したフローのステータスを確認するときに必要です。

以下は、フローの実行に失敗した例です。

{
  "result": false,
  "message": "Flow Alias not found"
}

フローの実行に失敗した場合は、"result"false で、"message" に失敗した理由を示すメッセージが設定されます。

以下は、Unix 系 curl コマンドでの実行例です(青字の部分はレスポンス)。

curl -X POST -H "Authorization: Bearer 3b3d3aea17899ff7a862e8623f7d65f6c761118c7e8af0df734e8d3178563179" --data "city=Fukuoka,jp" https://magellanblocksdemoblocksboard51f4ddc4.magellanic-clouds.net/flows/example.json
{"result":true,"job_id":1}

指定情報
ボード URL https://magellanblocksdemoblocksboard51f4ddc4.magellanic-clouds.net
API トークン 3b3d3aea17899ff7a862e8623f7d65f6c761118c7e8af0df734e8d3178563179
ID example
パラメーター 説明
city Fukuoka,jp 任意のパラメーター。フロー内で、${city} で参照可。

以下は、Content-Type ヘッダーに application/json を指定して、ボディに JSON テキストを指定した例です。

curl -X POST -H 'Authorization: Bearer 3b3d3aea17899ff7a862e8623f7d65f6c761118c7e8af0df734e8d3178563179' -H 'Content-Type: application/json' --data '{"city", "Fukuoka,jp"}' https://magellanblocksdemoblocksboard51f4ddc4.magellanic-clouds.net/flows/example.json

実行フローのステータス確認 API

実行フローのステータス確認 API は、実行したフローのステータスを確認する Web API です。

この Web API へは、HTTP の GET メソッドで以下の URL にアクセスします。

[GET] ボードURL/flows/ID/jobs/ジョブ ID/status.json

もしくは

[GET] ボードURL/flows/ID/jobs/ジョブ ID/status.txt

最後の部分が、json もしくは txt と異なっています。

項目 説明
ボード URL ステータスを確認するフローがある Big Data ボードの URL です。この URL は、Big Data ボードを開いて、ウェブブラウザーのアドレスバーで確認します。
ID

ステータスを確認するフローの ID です。ID は、フローリストで設定・確認します。ID の規則は、以下のとおりです。

  • 英数字(a-z、A-Z、0-9)、ハイフン(-)およびアンダースコアー(_)が使用できます。
  • 最大長は、64 文字です。
ジョブ ID ステータスを確認したいフローのジョブ ID です。フロー実行 API のレスポンスに含まれています。

なお、本 Web API のアクセスには、API トークンを使った認証が必要です。Web API アクセス時に、以下の Authorization ヘッダーを含めてください。

Authorization: Bearer API トークン

項目 説明
API トークン [ボード設定][API トークン] で発行したものを使います。

もし、Authorization ヘッダーの使用が難しい場合は、URL クエリーで以下のパラメーターを指定します。

パラメーター名 説明
api_token API トークンを指定します。

レスポンスは、URL の最後が status.json の場合は、ステータス情報を含む JSON 形式の文字列が返ってきます。URL の最後が status.txt の場合は、ステータスを示す文字列のみが返ってきます。

以下は、フローのステータス確認に成功した例です。

{
  "status": "finished"
}

もしくは

finished

フローのステータス確認に成功した場合は、以下いずれかの文字列が返ってきます。

"status" 説明
"planning" フローの実行を準備しています。
"running" フローの実行中です。
"finished" フローの実行が成功しました。
"failed" フローの実行に失敗しました。
"canceled" フローの実行がキャンセルされました。

以下は、フローのステータス確認に失敗した例です。

{
  "message": "Job not found."
}

もしくは

Job not found.

フローのステータス確認に失敗した場合は、失敗した理由を示すメッセージが設定されます。

以下は、Unix 系 curl コマンドでの実行例です(青字の部分はレスポンス)。

curl -H "Authorization: Bearer 3b3d3aea17899ff7a862e8623f7d65f6c761118c7e8af0df734e8d3178563179" https://magellanblocksdemoblocksboard51f4ddc4.magellanic-clouds.net/flows/example/jobs/1/status.json
{"status":"finished"}

指定情報
ボード URL https://magellanblocksdemoblocksboard51f4ddc4.magellanic-clouds.net
API トークン 3b3d3aea17899ff7a862e8623f7d65f6c761118c7e8af0df734e8d3178563179
ID example
ジョブ ID 1

変数値の取得 API

実行したフローの変数値が取得できます。

この Web API へは、HTTP の GET メソッドで以下の URL にアクセスします。

[GET] ボードURL/flows/ID/jobs/ジョブ ID/variable.json

項目 説明
ボード URL ステータスを確認するフローがある Big Data ボードの URL です。この URL は、Big Data ボードを開いて、ウェブブラウザーのアドレスバーで確認します。
ID

ステータスを確認するフローの ID です。ID は、フローリストで設定・確認します。ID の規則は、以下のとおりです。

  • 英数字(a-z、A-Z、0-9)、ハイフン(-)およびアンダースコアー(_)が使用できます。
  • 最大長は、64 文字です。
ジョブ ID ステータスを確認したいフローのジョブ ID です。フロー実行 API のレスポンスに含まれています。

なお、本 Web API のアクセスには、API トークンを使った認証が必要です。Web API アクセス時に、以下の Authorization ヘッダーを含めてください。

Authorization: Bearer API トークン

項目 説明
API トークン [ボード設定][API トークン] で発行したものを使います。

もし、Authorization ヘッダーの使用が難しい場合は、URL クエリーで以下のパラメーターを指定します。

パラメーター名 説明
api_token API トークンを指定します。

variable クエリーパラメーターに変数名を指定すると、その変数値が取得できます。変数名には、ハッシュ形式や配列形式データの一部を参照する記法が使えます。

variable クエリーパラメーターを省略した場合は、変数 _ の値を取得します。

以下は、Unix 系 curl コマンドでの実行例です。

curl -H 'Authorization: Bearer f38a9f8d0b3b999e279759f68abca69c4ce73dd9b53f4a4ded52b1357a435d0f' 'https://foobarblocksboard8fec513f.magellanic-clouds.net/flows/ml-image/jobs/23/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"}]