Hitachi

JP1 Version 12 JP1/IT Desktop Management 2 運用ガイド


20.2 APIの共通仕様

JP1/IT Desktop Management 2が提供しているAPIに共通する仕様について説明します。

通信方式

APIが使用する通信プロトコルおよびポート番号について、次に示します。

通信プロトコル

APIではHTTPプロトコルおよびHTTPSプロトコルをサポートしています。バージョンは1.1をサポートしています。通信プロトコルの詳細な仕様については次の規定を参照してください。

  • HTTPプロトコルの場合:RFC2616

  • HTTPSプロトコルの場合:RFC2818

通信プロトコルにHTTPSを使用する場合、TLS 1.2およびSHA-2(SHA-256)を使用します。

重要

HTTPSを使用する場合、SSLサーバ証明書が必要です。詳細は、マニュアル「JP1/IT Desktop Management 2 構築ガイド」の外部システム連携構成でHTTPSを使用する場合の環境構築手順について説明している個所を参照してください。

ポート番号

ポート番号のデフォルトの設定は31030です。ポート番号を変更したい場合は、管理用サーバのセットアップを実行してください。

セキュリティと認証

APIのリクエストを送信してレスポンスを取得するには、ユーザー認証を受ける必要があります。

ユーザー認証を受けるためには、次のように認証情報をリクエストヘッダーで指定してください。

X-ITDM-Authorization1:ユーザーID
X-ITDM-Authorization2:パスワード
ユーザーID

ユーザーIDをBase64エンコードした文字列を指定します。指定するユーザーIDにはAPI権限を付与している必要があります。

パスワード

ユーザーIDに対応するパスワードをBase64エンコードした文字列を指定します。

入出力形式

APIのリクエストおよびレスポンスのデータ形式として、JSON形式を使用します。データ形式は次のようにリクエストヘッダーで指定してください。

Content-Type:application/json

文字コードはUTF-8を使用します。

リクエストおよびレスポンスのメッセージボディに設定する値のデータ型については、各APIの説明を参照してください。

リクエスト形式

リクエスト形式は、リクエスト行、リクエストヘッダー、およびリクエストのメッセージボディで構成されます。リクエスト行およびリクエストヘッダーはASCII文字を指定します。URLで使用できない文字を指定する場合は,URLエンコードが必要です。

形式

method△/jp1itdm/api/apiVersion/resource/other?query△HTTP/1.1
Host:host:port
Accept-Language:lang
Content-Type:application/json
Accept:application/json
X-ITDM-Authorization1:userID
X-ITDM-Authorization2:password

messageBody

項目

区分

説明

リクエスト行

method

必須

メソッドを指定します。次のどれかを指定します。

  • GET

  • POST

  • PUT

  • DELETE

指定できるメソッドはAPIによって異なります。詳細は各APIの説明を参照してください。

apiVersion

必須

APIのバージョンを指定します。詳細は各APIの説明を参照してください。

resource

必須

リソースを指定します。指定するリソースはAPIによって異なります。詳細は各APIの説明を参照してください。

other

任意

必要に応じて、リソースまたはリソースの操作を一意に識別できる値を指定します。詳細は各APIの説明を参照してください。

?query

任意

必要に応じて、クエリ文字列を指定します。詳細は各APIの説明を参照してください。

リクエストヘッダー

Host:

host

必須

管理用サーバのホスト名またはIPアドレスを指定します。

port

必須

管理用サーバのポート番号を指定します。

Accept-Language:

lang

必須

レスポンスのメッセージ文の言語コードを指定します。次のどれかを指定します。

ja

日本語

en

英語

zh

中国語(簡体字)

Content-Type:

application/json

必ず「application/json」を指定します。

Accept:

application/json

必須

必ず「application/json」を指定します。

X-ITDM-Authorization1:

userID

必須

ユーザーIDをBase64エンコードした文字列を指定します。

X-ITDM-Authorization2:

password

必須

ユーザーIDに対応するパスワードをBase64エンコードした文字列を指定します。

リクエストのメッセージボディ

messageBody

任意

必要に応じて、JSON形式で指定します。詳細は各APIの説明を参照してください。

注※

methodが「GET」の場合

指定不要

上記以外の場合

必須

重要

リクエストのメッセージボディには30MB以内のデータを指定してください。

レスポンス形式

リクエストに対するレスポンス形式は、ステータス行、レスポンスヘッダー、およびレスポンスのメッセージボディで構成されます。ステータス行およびレスポンスヘッダーはASCII文字を指定します。

形式

HTTP/1.1△statusCodestatusCodeText
Content-Type:application/json
Cache-Control:no-store, no-cache, max-age=0
X-Content-Type-Options:nosniff

messageBody

項目

説明

ステータス行

statusCode

ステータスコードが格納されます。詳細は「ステータスコード」を参照してください。

statusCodeText

ステータスコードのテキストが格納されます。詳細は「ステータスコード」を参照してください。

レスポンスヘッダー

Content-Type:

application/json

必ず「application/json」が返却されます。

Cache-Control:

no-store, no-cache, max-age=0

必ず「no-store, no-cache, max-age=0」が返却されます。

X-Content-Type-Options:

nosniff

必ず「nosniff」が返却されます。

レスポンスのメッセージボディ

messageBody

APIが呼び出された時に返却されるレスポンスデータが、JSON形式で格納されます。詳細は各APIの説明を参照してください。

また、エラーが発生した場合は、エラー情報がJSON形式で格納されます。詳細は「エラー情報」を参照してください。

ステータスコード

API実行によって返却されるレスポンスメッセージのステータスコードを次の表に示します。

ステータスコード

ステータスコードのテキスト

説明

100

Continue

クライアントは、リクエストを継続可能です。

200

OK

正常終了しました。

206

Partial Content

部分的なリソースが返却されています。

207

Multi-Status

複数のリソースの操作でエラーがありました。

300

Multiple Choices

複数ページの利用が可能です。

301

Moved Permanently

リソースが恒久的に移動しました。

302

Found

リソースが一時的に移動しました。

303

See Other

リソースが移動しました。

304

Not Modified

リクエストしたコンテンツが変更されていません。

400

Bad Request

  • 引数が不正です。

  • リクエストの形式が誤っています。

401

Unauthorized

  • IDまたはパスワードが指定されていません。

  • IDまたはパスワードが間違っています。

  • アカウントがロックされています。

403

Forbidden

  • リソースを実行する権限がありません。

  • ユーザーにAPI権限がありません。

404

Not Found

存在しないリソースにアクセスしました。

405

Method Not Allowed

認可されてないリソースへアクセスしました。

406

Not Acceptable

サポートしていないデータ形式が指定されました。

408

Request Time-out

リクエストがタイムアウトになりました。

410

Gone

リソースが恒久的に利用できません。

411

Length Required

クライアントはContent-Lengthヘッダを指定する必要があります。

412

Precondition Failed

クライアントのIf-Unmodified-SinceヘッダまたはIf-Matchedヘッダなどで指定した条件が一致しません。

413

Request Entity Too Large

リクエストのメッセージボディが長いです。

414

Request-URI Too Long

リクエスト行が長いです。

416

Requested Range Not Satisfiable

Rangeヘッダでの指定範囲は、該当リソースの範囲を超えています。

417

Expectation Failed

Expectリクエストヘッダフィールドの拡張が受け入れられませんでした。

429

Too Many Requests

リクエスト数が多すぎて拒否されました。

453

Expiration Password

パスワードの有効期限が切れています。

500

Internal Server Error

サーバ処理エラーが発生しました。

501

Method Not Implemented

サポートされていないHTTPメソッドの要求です。

502

Bad Gateway

プロキシサーバが不正な要求を受け取りました。

503

Service Unavailable

管理用サーバ上のサービス起動が完了していません。

506

Variant Also Negotiates

サーバに内部配置上のエラーがあります。

512

License Error

ライセンスが登録されていません。

513

Temporary Error

一時的なエラーが発生しました。

514

JP1/Base Error

JP1/Baseの認証サーバのエラーが発生しました。

エラー情報

APIのリクエストがエラーになった場合、エラー情報がレスポンスのメッセージボディにJSON形式で格納されて返却されます。エラー情報の形式を次に示します。

形式

{
  "errorSource":"エラーが発生したURL"
  "message":"メッセージ",
  "messageID":"メッセージID",
  "application":"jp1itdm"
}

属性

データ型

説明

errorSource

string

エラーが発生したURL

message

string

メッセージ

messageID

string

メッセージID

例:ユーザーIDが存在しない場合のレスポンス

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Cache-Control: no-store, no-cache, max-age=0
X-Content-Type-Options: nosniff

{
"errorSource": "http://example.com:31030/jp1itdm/api/v1/objects/devices",
"message": "認証に失敗しました。次の理由が考えられます。
・ユーザーIDまたはパスワードに誤りがある(大文字と小文字は区別されます)
・ユーザーアカウントがロックされている
ロックされているかどうかは、管理者に確認してください。",
"messageID": "KDEX2016-E",
"application": "jp1itdm"
}

サポートするデータ型

リクエストおよびレスポンスのメッセージボディに設定する値は、「"」(ダブルクォーテーション)で囲んだ文字列で指定します。各データ型に対応する文字列の書式を次に示します。

データ型

説明

int

-2,147,483,647〜2,147,483,647の範囲の整数です。""で囲んでください。

例:"123"

unsigneInt

0〜2,147,483,647の範囲の整数です。""で囲んでください。

例:"123"

long

-9,223,372,036,854,775,807〜9,223,372,036,854,775,807の範囲の整数です。""で囲んでください。

例:"123"

unsignedLong

0〜9,223,372,036,854,775,807の範囲の整数です。""で囲んでください。

例:"123"

string

テキストデータです。ASCIIコードの制御文字を除いた文字列を指定してください。

string型で数字を扱う場合、特に説明がなければ数字を10進数として扱います。

例:"サンプルテキスト"

dateTime

日時または日付を設定します。

日時の場合、UTCで"YYYY-MM-DDTHH:MM:SS.sssZ"形式で指定します。

YYYY

西暦の年を4桁で指定します。

MM

月を2桁で指定します。

DD

日を2桁で指定します。

HH

時間を2桁で指定します。

MM

分を2桁で指定します。

SS

秒を2桁で指定します。

sss

ミリ秒を3桁で指定します。

例(2019年5月8日 6:52:16.000の場合):"2019-05-08T06:52:16.000Z"

日付の場合、YYYY-MM-DDT00:00:00.000Z"形式で指定します。

例(2019年5月8日の場合):"2019-05-08T00:00:00.000Z"

同時実行

APIは4本まで同時に実行ができます。