製品情報 >
API公開
API公開インターフェースと利用方法
2020年6月改訂
POLESTAR Automation V3 では、REST-APIを使って他の製品との連携が可能になりました。ここでは、外部連携インターフェースの仕様について記載しています。
開発者の方々が開発にあたって遵守すべきプロトコルやREST APIの仕様、外部ライブラリ状況についてご紹介します。
それぞれのコンポーネントが通信する方法を、プロトコルとREST API仕様に関してインターフェース定義として定めています。
1. プロトコル
■ 外部システムとの通信は、簡単に連携がしやすいREST APIを利用し、収集された構成や特定の作業を実行できるようにします。
■ クライアント(ウェブブラウザ)と収集サーバ間の通信には、HTTP v1.1の通信プロトコルを利用します。
2. REST API仕様
外部との連携に関し、REST APIのフォーマット(スキーマ)を定義しています。ここで定義するメッセージフォーマットは、REST APIのインターフェースについて、それぞれのメッセージフォーマットを提供します。 提供されるAPIのリクエストとレスポンスに必要な内容を定義しています。
2.1 概要
外部との連携に関し、REST APIのフォーマット(スキーマ)を定義します。この文書で定義するメッセージフォーマット(Message Format)は、REST APIのインターフェースについてそれぞれのメッセージフォーマットを提供します。 提供されるAPIのリクエストとレスポンスに必要な内容を定義します。
2.2 REST API共通JSON規約
POLESTAR Automationは、REST APIで外部連携するシステム(ソフトウェアやツール)に構成情報収集及び特定作業実行の機能を提供し、JSON形式のデータ規約を利用します。
＜表1＞ 共通JSON規約
data |
全てのJSONデータのROOTはdataである |
id |
全てのJSONデータのdata内には、id(URL method Key)が存在する |
date |
全てのJSONデータのdata内には、date(リクエスト時間)が存在する |
※ 該当する共通JSON規約は、必ず守る必要があります。
※ 入力された日付($from, $to)のタイプは、long typeを基本とします。
※ ‘$’表示は変数を意味します。
3. REST API一覧
POLESTAR Automationで提供するREST APIは、利用用途に応じた以下のAPIから構成されます。
＜表2＞ API 一覧
No. |
API |
概要 |
|---|---|---|
1 |
ユーザ認証 |
POLESTAR AutomationのAPIを利用するソフトウェアからユーザー認証の要請を受けて、該当するユーザーの情報を収集し、その結果を出力する。 |
2 |
登録されたデバイスの一覧照会 |
POLESTAR Automationに登録されたデバイスの一覧を他の製品で該当するURLを経由、登録されたデバイスごとに多様な基本情報(DeviceID、エージェントバージョン、登録日付など)出力します。 |
3 |
デバイスの基本情報照会 |
POLESTAR Automationに登録されたデバイスの一覧を他の製品で該当するURLを経由、登録されたデバイスの中選択されたごとに多様な基本情報(DeviceID、エージェントバージョン、登録日付など)出力します。 |
4 |
デバイスの構成情報照会 |
POLESTAR Automationに登録されたデバイスの構成情報(CPUｓ、Memory, Operation Systemなど)を他の製品と連携で該当するURLを経由、登録されたデバイスの構成情報を出力します。 |
5 |
特定作業の実行 |
他の製品から発生したイベントにより、POLESTAR Automationに登録されていた特定作業(ジョブ)を、既に指定されているデバイスに実行します。 |
6 |
特定の対象デバイスとの連携に必要な作業実行 |
他の製品から発生したイベントにより、他の製品から提供された管理対象デバイスのID情報に通じて管理対象デバイスも指定されます。POLESTAR Automationに登録されていた特定作業(ジョブ)を実行します。 |
4. REST APIの利用方法
POLESTAR AutomationでのREST API連携は次のように処理されます。
＜図1＞ REST API連携処理の概要
REST APIを利用するためには、 API毎に所定のパラメータを設定します。
それぞれのAPIは、HTTPレスポンスコードと一緒に処理結果を説明するXML形式データ(レスポンス結果XML)を出力します。
REST API経由のレスポンス結果は、次のように出力されます。
＜図2＞ API経由のレスポンス結果
結果を表現するURLは次のようになります。
URLは、POLESTAR AutomationのURLとURLの提供されたRESTのバージョン、また結果として確認する内容を入力します。RESTのバージョンは、「v1、v2、v3…」のように入力します。
次の例は、登録されているデバイス一覧の照会です。
＜図3＞ デバイス照会のリクエスト例
詳細な内容は、次のように処理されます。
4.1 ユーザ認証
(※以降実装及び開発必要)
POLESTAR Automationの画面から他の製品と連携するIPを登録することで、許可されたIPのみ連携することができるようにします。
4.2 登録されたデバイスの一覧照会
他の製品と連携するため、次のURL経由、登録されたデバイスの一覧を出力します。
URL: host/rest/v1/server/list
RESTバージョン：v1、v2、v3…（URLに提供されたRESTバージョンを入力）
デバイスの種類：server, network, agentless(URLにデバイスの種類を入力)
■Request URL
Method Type |
URL |
|---|---|
GET |
/rest/v1/server/list |
■Request Example(URL)
http://192.168.0.1:8080/rest/v1/server/list |
http://192.168.0.1:8080/rest/v1/network/list |
http://192.168.0.1:8080/rest/v1/agentless/list |
■Response Data
Data |
Type |
Value |
|---|---|---|
objectID |
Integer |
デバイス ID |
roles |
Array |
ロール情報 |
uuid |
String |
汎用一意識別子 |
version |
Integer |
バージョン |
classification |
String |
分類 |
createdDate |
Long |
登録日付 |
createdUserID |
String |
登録したユーザーID |
deletedDate |
Long |
削除日付 |
deletedUserID |
String |
削除したユーザーID |
description |
String |
説明 |
modifiedDate |
Long |
修正日付 |
modifiedUserID |
String |
修正したユーザーID |
name |
String |
デバイス名 |
osType |
String |
OSタイプ |
propertyInstances |
Array |
プロパティリスト |
starred |
Boolean |
お気に入り状態 |
systemObjectType |
String |
SystemObjectタイプ |
hostname |
String |
ホスト名 |
ipAddress |
String |
IP |
osVersion |
String |
OSバージョン |
reachable |
Boolean |
デバイスの状態 |
tempKey |
String |
Tempキー |
paths |
String |
静的グループのパース |
agentKey |
String |
エージェントキー |
agentPort |
Integer |
エージェントポート |
agentVersion |
String |
エージェントのバージョン |
■Response Example(JSON)
4.3 デバイスの基本情報照会
他の製品と連携するため、次のURL経由登録されたデバイスから選択されたデバイス毎の基本情報を出力します。
URL: host/rest/v1/server/{$deviceID}/info
RESTバージョン：v1、v2、v3…（URLに提供されたRESTバージョンを入力）
デバイスの種類：server, network, agentless(URLにデバイスの種類を入力)
デバイスのID：デバイスのdeviceIDを入力します。
■Request URL
Method Type |
URL |
|---|---|
GET |
/rest/v1/server/{$deviceID}/info |
■Request Example(URL)
http://192.168.0.1:8080/rest/v1/server/10486/info |
http://192.168.0.1:8080/rest/v1/network/10486/info |
http://192.168.0.1:8080/rest/v1/agentless/10486/info |
■Response Data
Data |
Type |
Value |
|---|---|---|
objectID |
Integer |
デバイス ID |
roles |
Array |
ロール情報 |
uuid |
String |
汎用一意識別子 |
version |
Integer |
バージョン |
classification |
String |
分類 |
createdDate |
Long |
登録日付 |
createdUserID |
String |
登録したユーザーID |
deletedDate |
Long |
削除日付 |
deletedUserID |
String |
削除したユーザーID |
description |
String |
説明 |
modifiedDate |
Long |
修正日付 |
modifiedUserID |
String |
修正したユーザーID |
name |
String |
デバイス名 |
osType |
String |
OSタイプ |
propertyInstances |
Array |
プロパティリスト |
starred |
Boolean |
お気に入り状態 |
systemObjectType |
String |
SystemObjectタイプ |
hostname |
String |
ホスト名 |
ipAddress |
String |
IP |
osVersion |
String |
OSバージョン |
reachable |
Boolean |
デバイスの状態 |
tempKey |
String |
Tempキー |
paths |
String |
静的グループのパース |
agentKey |
String |
エージェントキー |
agentPort |
Integer |
エージェントポート |
agentVersion |
String |
エージェントのバージョン |
■Response Example(JSON)
4.4 デバイスの構成情報照会
他の製品と連携するため、次のURL経由、登録されたデバイスの構成情報を出力します。
URL: host/rest/v1/server/{$deviceID}/system-information/agent
RESTバージョン：v1、v2、v3…（URLに提供されたRESTバージョンを入力）
デバイスの種類：server, network, agentless(URLにデバイスの種類を入力)
デバイスのID：デバイスのdeviceIDを入力します。
構成項目：Agent, CPUs, Disks, File Systems, Memory, Network Interfaces,Operation Systemなど（URLに構成項目を入力します。）
■Request Data
Method Type |
URL |
|---|---|
GET |
/rest/v1/server/{$deviceID}/system-information/agent |
■Request Example(URL)
http://192.168.0.1:8080/rest/v1/server/10486/system-information/agent |
http://192.168.0.1:8080/rest/v1/server/10486/system-information/cpus |
http://192.168.0.1:8080/rest/v1/server/10486/system-information/disks |
http://192.168.0.1:8080/rest/v1/server/10486/system-information/file-systems |
http://192.168.0.1:8080/rest/v1/server/10486/system-information/memory |
http://192.168.0.1:8080/rest/v1/server/10486/system-information/network-interfaces |
http://192.168.0.1:8080/rest/v1/server/10486/system-information/operating-system |
http://192.168.0.1:8080/rest/v1/network/10486/system-information |
http://192.168.0.1:8080/rest/v1/network/10486/network-interfaces |
http://192.168.0.1:8080/rest/v1/agentless/10486/system-information/cpus |
http://192.168.0.1:8080/rest/v1/agentless/10486/system-information/disks |
http://192.168.0.1:8080/rest/v1/agentless/10486/system-information/file-systems |
http://192.168.0.1:8080/rest/v1/agentless/10486/system-information/memory |
http://192.168.0.1:8080/rest/v1/agentless/10486/system-information/network-interfaces |
http://192.168.0.1:8080/rest/v1/agentless/10486/system-information/operating-system |
■Response Data
Data |
Type |
Value |
|---|---|---|
objectID |
Integer |
Device ID |
liveObjectName |
String |
LiveObjectの名称 |
liveObjectType |
String |
LiveObjectのタイプ |
simpleName |
String |
LiveObjectの別称 |
liveObjectAttributes |
Array |
該当のデータ |
persistedDate |
Long |
収集日付 |
hasChildren |
Boolean |
子有無 |
■Response Example(JSON)
4.5 特定作業の実行
他の製品から次のURL経由、登録された特定作業を実行します。POLESTAR Automationで作成された作業(ジョブ)設定を変更せず実行します。
URL: host/rest/v1/job/{$jobID}/execute
RESTバージョン：v1、v2、v3…（URLに提供されたRESTバージョンを入力）
ジョブID：POLESTAR Automationに登録されたJOB ID(System ID)を入力します。
■Request URL
Method Type |
URL |
|---|---|
GET |
/rest/v1/job/{$jobID}/execute |
■Request Example(URL)
http://192.168.0.1:8080/rest/v1/job/1004/execute |
■Response Data
Data |
Type |
Value |
|---|---|---|
message |
String |
実行メッセージ |
■Response Example(JSON)
4.6 特定の対象デバイスとの連携に必要な作業
他のデバイスから、次のURL経由登録された特定作業を実行します。他のデバイスから提供された管理対象のデバイスID情報を提供して、POLESTAR Automationで作成されたジョブ設定を変更せず実行します。
URL: host/rest/v1/job/{$jobID}/target/execute
RESTバージョン：v1、v2、v3…（URLに提供されたRESTバージョンを入力）
ジョブID：POLESTAR Automationに登録されたJOB ID(System ID)を入力します。
■Request URL
Method Type |
URL |
|---|---|
POST |
/rest/v1/job/{$jobID}/target/execute |
■Request Example(URL)
http://192.168.0.1:8080/rest/v1/job/1004/target/execute |
■Response Data
Data |
Type |
Value |
|---|---|---|
Target_device_id |
JSON |
ジョブ実行の対象デバイスのIDリスト |
■Response Example(JSON)
■Response Data
Data |
Type |
Value |
|---|---|---|
id |
Long |
デバイスID |
message |
String |
実行メッセージ |
■Response Example(JSON)
