API公開インターフェースと利用方法

API公開インターフェースと利用方法

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を利用するソフトウェアからユーザー認証の要請を受けて、該当するユーザーの情報を収集し、その結果を出力する。
他の製品に連携するIPを登録して、許可されたIPのみ連携可能になる。
2 登録されたデバイスの一覧照会 POLESTAR Automationに登録されたデバイスの一覧を他の製品で該当するURLを経由、登録されたデバイスごとに多様な基本情報(DeviceID、エージェントバージョン、登録日付など)出力します。
3 デバイスの基本情報照会 POLESTAR Automationに登録されたデバイスの一覧を他の製品で該当するURLを経由、登録されたデバイスの中選択されたごとに多様な基本情報(DeviceID、エージェントバージョン、登録日付など)出力します。
4 デバイスの構成情報照会 POLESTAR Automationに登録されたデバイスの構成情報(CPUｓ、Memory, Operation Systemなど)を他の製品と連携で該当するURLを経由、登録されたデバイスの構成情報を出力します。
5 特定作業の実行 他の製品から発生したイベントにより、POLESTAR Automationに登録されていた特定作業(ジョブ)を、既に指定されているデバイスに実行します。
POLESTAR Automationに既に生成されているジョブの設定は変更せずに行います。
6 特定の対象デバイスとの連携に必要な作業実行 他の製品から発生したイベントにより、他の製品から提供された管理対象デバイスのID情報に通じて管理対象デバイスも指定されます。POLESTAR Automationに登録されていた特定作業(ジョブ)を実行します。
POLESTAR Automationに既に生成されているジョブの設定は変更せずに行います。

4. REST APIの利用方法

POLESTAR AutomationでのREST API連携は次のように処理されます。

REST API連携処理の概要
＜図1＞ REST API連携処理の概要

REST APIを利用するためには、 API毎に所定のパラメータを設定します。
それぞれのAPIは、HTTPレスポンスコードと一緒に処理結果を説明するXML形式データ(レスポンス結果XML)を出力します。
REST API経由のレスポンス結果は、次のように出力されます。

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)

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 OSバージョン
osVersion String デバイスの状態
reachable Boolean デバイスの状態
tempKey String Tempキー
paths String 静的グループのパース
agentKey String エージェントキー
agentPort Integer エージェントポート
agentVersion String エージェントのバージョン

Response Example(JSON)

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 URL

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 デバイス ID
liveObjectName String LiveObjectの名称
liveObjectType String LiveObjectのタイプ
simpleName String LiveObjectの別称
liveObjectAttributes Array 該当のデータ
persistedDate Long 収集日付
hasChildren Boolean 子有無

Response Example(JSON)

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)

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 Example(JSON)

Response Data

DATA TYPE VALUE
id Long デバイスID
message String 実行メッセージ

Response Example(JSON)

Response Example(JSON)