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

製品情報 >

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を利用するソフトウェアからユーザー認証の要請を受けて、該当するユーザーの情報を収集し、その結果を出力する。
他の製品に連携するIPを登録して、許可されたIPのみ連携可能になる。

2

登録されたデバイスの一覧照会

POLESTAR Automationに登録されたデバイスの一覧を他の製品で該当するURLを経由、登録されたデバイスごとに多様な基本情報(DeviceID、エージェントバージョン、登録日付など)出力します。

3

デバイスの基本情報照会

POLESTAR Automationに登録されたデバイスの一覧を他の製品で該当するURLを経由、登録されたデバイスの中選択されたごとに多様な基本情報(DeviceID、エージェントバージョン、登録日付など)出力します。

4

デバイスの構成情報照会

POLESTAR Automationに登録されたデバイスの構成情報(CPUs、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経由のレスポンス結果は、次のように出力されます。

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)

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)

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)

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)