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 |
必須 |
メソッドを指定します。次のどれかを指定します。
指定できるメソッドはAPIによって異なります。詳細は各APIの説明を参照してください。 |
|
apiVersion |
必須 |
APIのバージョンを指定します。詳細は各APIの説明を参照してください。 |
||
resource |
必須 |
リソースを指定します。指定するリソースはAPIによって異なります。詳細は各APIの説明を参照してください。 |
||
other |
任意 |
必要に応じて、リソースまたはリソースの操作を一意に識別できる値を指定します。詳細は各APIの説明を参照してください。 |
||
?query |
任意 |
必要に応じて、クエリ文字列を指定します。詳細は各APIの説明を参照してください。 |
||
リクエストヘッダー |
Host: |
host |
必須 |
管理用サーバのホスト名またはIPアドレスを指定します。 |
port |
必須 |
管理用サーバのポート番号を指定します。 |
||
Accept-Language: |
lang |
必須 |
レスポンスのメッセージ文の言語コードを指定します。次のどれかを指定します。
|
|
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△statusCode△statusCodeText 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 |
|
403 |
Forbidden |
|
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"形式で指定します。
例(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本まで同時に実行ができます。