5.2 制御プログラムとの連携
5.2.1 概要#
SpeeDBee Synapseの一部の操作は、APIによって外部から行うことができます。
5.2.2 APIの実行方法#
ここでは例として、curlコマンドによってAPIを実行する方法を記載します。
curlがインストールされていない場合、curlの公式サイトからcurlをダウンロードして、ご利用中のマシンへcurlをインストールして下さい。
-
curlコマンドを実行する環境を開きます。Linuxの場合はターミナルを、Windowsの場合はコマンドプロンプトを開きます。
-
「API仕様」の各APIの「curlコマンドによるリクエスト」をコピーし、curlコマンドを実行する環境にペーストします。
※「curlコマンドによるリクエスト」の一部は、置き換える必要があります。詳細は、「共通事項」をご覧ください。 -
Enterキーを押下するとAPIが実行され、レスポンスが表示されます。レスポンスの詳細は、「API仕様」の各APIの「レスポンス」をご覧ください。
「API仕様」の各APIの「curlコマンドによるリクエスト」では、次の項目が指定されています。curlコマンド以外の方法でAPIを実行する場合は、同じ項目を指定する必要があります。
| 項目 | 説明 |
|---|---|
| HTTPメソッド | -X "~~~"という形で指定されています。 |
| リクエストURL | "http:// |
| HTTPヘッダ | -H "~~~"という形で指定されています。 |
| POSTメソッドで送信するデータ | -d "~~~"という形で指定されています。 |
5.2.3 API仕様#
APIによって行うことができる操作の一覧について、その概要・リクエスト方法・レスポンスを掲載します。 API仕様を理解し、各種プログラムから同一のリクエストを送信することで、各種プログラミング言語からの利用や制御プログラムとの連携が可能となります。
API仕様のドキュメントはSpeeDBee Synapseにも含まれており、次のURLでアクセスすることができます。
http://<SpeeDBee Synapseのホスト:ポート>/ext_api/docs
5.2.3.1 共通事項#
次の一覧は、以降のリクエスト例に掲載されている内容について、共通となる事項です。
は、SpeeDBee Synapseが稼働しているホスト・ポートに置き換えてください。 - <アクセストークン>は、「アクセストークン発行」で発行したアクセストークンに置き換えてください。
- <パネルID>は、取得したいパネルのIDを指定します。そのパネルに登録されている全てのコンポーネントの実行状態を取得します。パネルIDは、「全コンポーネントの実行状態取得」によって取得することができます。
- <コンポーネントID>は、実行状態を取得したいコンポーネントのIDを指定します。コンポーネントIDは、「全コンポーネントの実行状態取得」によって取得することができます。
5.2.3.2 全コンポーネントの実行状態取得#
-
概要
SpeeDBee Synapseに登録されている全てのコンポーネントの実行状態を取得します。
-
リクエストURL
http://<SpeeDBee Synapseのホスト:ポート>/ext_api/v1/components/status -
curlコマンドによるリクエスト
$ curl -X "GET" "http://<SpeeDBee Synapseのホスト:ポート>/ext_api/v1/components/status" -H "accept: application/json" -H "X-hive-api-key: <アクセストークン>"$ curl.exe -X "GET" "http://<SpeeDBee Synapseのホスト:ポート>/ext_api/v1/components/status" -H "accept: application/json" -H "X-hive-api-key: <アクセストークン>" -
レスポンス
コード 説明 200 正常 403 認証エラー 503 SpeeDBee Synapseがリクエストを処理できない状態 正常レスポンスは、以下の形式です。
{ "status": "SpeeDBee Synapseのステータス", "components": [ { "id": "コンポーネントID", "name": "コンポーネント名", "panel_id": "コンポーネントが登録されているパネルのID", "panel_name": "コンポーネントが登録されているパネルの名前", "status": "コンポーネントのステータス", "errors": [ { "id": "エラーID", "parameter": ["エラーメッセージ"] } ] } ] }
※1 "components"には、コンポーネントの実行状態が格納されます。コンポーネントが存在しない場合は、空配列となります。
※2 "errors"には、コンポーネントのエラー情報が格納されます。エラーが発生していない場合は、空配列となります。
5.2.3.3 個別コンポーネントの実行状態取得#
-
概要
SpeeDBee Synapseに登録されている個別のコンポーネントの実行状態を取得します。
-
リクエストURL
http://<SpeeDBee Synapseのホスト:ポート>/ext_api/v1/components/status -
curlコマンドによるリクエスト
-
パネル毎
$ curl -X "POST" "http://<SpeeDBee Synapseのホスト:ポート>/ext_api/v1/components/status" -H "accept: application/json" -H "X-hive-api-key: <アクセストークン>" -H 'Content-Type: application/json' -d "{\"panel_ids\": [<パネルID>]}"$ curl.exe -X "POST" "http://<SpeeDBee Synapseのホスト:ポート>/ext_api/v1/components/status" -H "accept: application/json" -H "X-hive-api-key: <アクセストークン>" -H 'Content-Type: application/json' -d "{\"panel_ids\": [<パネルID>]}" -
コンポーネント毎
$ curl -X "POST" "http://<SpeeDBee Synapseのホスト:ポート>/ext_api/v1/components/status" -H "accept: application/json" -H "X-hive-api-key: <アクセストークン>" -H 'Content-Type: application/json' -d "{\"component_ids\": [\"<コンポーネントID>\"]}"$ curl.exe -X "POST" "http://<SpeeDBee Synapseのホスト:ポート>/ext_api/v1/components/status" -H "accept: application/json" -H "X-hive-api-key: <アクセストークン>" -H 'Content-Type: application/json' -d "{\"component_ids\": [\"<コンポーネントID>\"]}"
-
-
レスポンス
コード 説明 200 正常 403 認証エラー 422 バリデーションエラー 503 SpeeDBee Synapseがリクエストを処理できない状態 正常レスポンスは、以下の形式です。
{ "status": "SpeeDBee Synapseのステータス", "components": [ { "id": "コンポーネントID", "name": "コンポーネント名", "panel_id": "コンポーネントが登録されているパネルのID", "panel_name": "コンポーネントが登録されているパネルの名前", "status": "コンポーネントのステータス", "errors": [ { "id": "エラーID", "parameter": ["エラーメッセージ"] } ] } ] }
※1 "components"には、指定されたコンポーネントの実行状態が格納されます。指定されたコンポーネントが存在しない場合は、空配列となります。
※2 "errors"には、コンポーネントのエラー情報が格納されます。エラーが発生していない場合は、空配列となります。
5.2.3.4 コンポーネント一括実行開始#
-
概要
SpeeDBee Synapseに登録されているコンポーネントを開始します。
-
リクエストURL
http://<SpeeDBee Synapseのホスト:ポート>/ext_api/v1/components/start -
curlコマンドによるリクエスト
-
パネル毎
$ curl -X "PUT" "http://<SpeeDBee Synapseのホスト:ポート>/ext_api/v1/components/start" -H "accept: application/json" -H "x-hive-api-key: <アクセストークン>" -H "Content-Type: application/json" -d "{\"panel_ids\": [<パネルID>]}"$ curl.exe -X "PUT" "http://<SpeeDBee Synapseのホスト:ポート>/ext_api/v1/components/start" -H "accept: application/json" -H "x-hive-api-key: <アクセストークン>" -H "Content-Type: application/json" -d "{\"panel_ids\": [<パネルID>]}" -
コンポーネント毎
$ curl -X "PUT" "http://<SpeeDBee Synapseのホスト:ポート>/ext_api/v1/components/start" -H "accept: application/json" -H "x-hive-api-key: <アクセストークン>" -H "Content-Type: application/json" -d "{\"component_ids\": [\"<コンポーネントID>\"]}"$ curl.exe -X "PUT" "http://<SpeeDBee Synapseのホスト:ポート>/ext_api/v1/components/start" -H "accept: application/json" -H "x-hive-api-key: <アクセストークン>" -H "Content-Type: application/json" -d "{\"component_ids\": [\"<コンポーネントID>\"]}"
-
-
レスポンス
コード 説明 200 正常 400 ポイント不足によりコンポーネントの実行を開始できない 403 認証エラー 422 バリデーションエラー 503 SpeeDBee Synapseがリクエストを処理できない状態 正常レスポンスは、以下の形式です。
[ { "id": "コンポーネントID", "panel_id": "パネルID", "success": "コンポーネント開始の成否", "error": "エラー情報" } ]※ 正常レスポンスの配列には、リクエストで指定されたコンポーネントの一覧が格納されます。指定されたコンポーネントが存在しない場合は、空配列となります。
5.2.3.5 コンポーネント一括実行停止#
-
概要
SpeeDBee Synapseに登録されているコンポーネントを停止します。
-
リクエストURL
http://<SpeeDBee Synapseのホスト・ポート>/ext_api/v1/components/stop -
curlコマンドによるリクエスト
-
パネル毎
$ curl -X "PUT" "http://<SpeeDBee Synapseのホスト:ポート>/ext_api/v1/components/stop" -H "accept: application/json" -H "x-hive-api-key: <アクセストークン>" -H "Content-Type: application/json" -d "{\"panel_ids\": [<パネルID>]}"$ curl.exe -X "PUT" "http://<SpeeDBee Synapseのホスト:ポート>/ext_api/v1/components/stop" -H "accept: application/json" -H "x-hive-api-key: <アクセストークン>" -H "Content-Type: application/json" -d "{\"panel_ids\": [<パネルID>]}" -
コンポーネント毎
$ curl -X "PUT" "http://<SpeeDBee Synapseのホスト:ポート>/ext_api/v1/components/stop" -H "accept: application/json" -H "x-hive-api-key: <アクセストークン>" -H "Content-Type: application/json" -d "{\"component_ids\": [\"<コンポーネントID>\"]}"$ curl.exe -X "PUT" "http://<SpeeDBee Synapseのホスト:ポート>/ext_api/v1/components/stop" -H "accept: application/json" -H "x-hive-api-key: <アクセストークン>" -H "Content-Type: application/json" -d "{\"component_ids\": [\"<コンポーネントID>\"]}"
-
-
レスポンス
コード 説明 200 正常 403 認証エラー 422 バリデーションエラー 503 SpeeDBee Synapseがリクエストを処理できない状態 正常レスポンスは、以下の形式です。
[ { "id": "コンポーネントID", "panel_id": "パネルID", "success": "コンポーネント停止の成否", "error": "エラー情報" } ]※ 正常レスポンスの配列には、リクエストで指定されたコンポーネントの一覧が格納されます。指定されたコンポーネントが存在しない場合は、空配列となります。