1.2.4 リクエスト形式
APIでJP1/OAが提供する機能を利用するためのリクエスト形式を次に示します。リクエスト形式はURI,メソッド,リクエストライン,リクエストヘッダーから構成されます。
(1) URI
APIにリソースを指定するには,URIを使用します。次に示すURIの形式の<schema>から<version>までが基底URIとなり,<domain>以下が,相対URIとなります。リソースは<domain>以下の相対URIに指定します。
- URIの形式
<scheme>//<host>:<port>/<application>/<version>/<domain>/<object-type>[?<query-string>]
または
<scheme>//<host>:<port>/<application>/<version>/<domain>/<object-type>/actions/[<action-identifier>[/invoke]]
URIの構成内容について,次の表で説明します。
項目 |
説明 |
参照先 |
---|---|---|
<scheme> |
プロトコルを指定します。HTTPの場合は「http」,HTTPSの場合は「https」を指定します。 |
− |
<host> |
APIクライアントからアクセスするJP1/OAのホスト名またはIPアドレスを指定します。 |
− |
<port> |
APIクライアントからアクセスするJP1/OAのポート番号を指定します。デフォルトではHTTPの場合は22015,HTTPSの場合は22016です。 |
− |
<application> |
APIを提供するアプリケーション名です。固定値として「Analytics」を指定します。 |
− |
<version> |
使用するAPIのバージョンを指定します。 |
各APIの「APIのバージョン」を参照してください。 |
<domain> |
APIに指定するリソースのカテゴリを指定します。 |
|
<object-type> |
リソースまたはサービスの種類を表します。 |
|
<query-string> |
クエリパラメータ。<object-type>を絞り込んだり,ソートする条件を指定したりします。リソースごとに指定できるクエリパラメータは異なります。クエリパラメータ同士の順序は問いません。 |
|
<action-identifier> |
リソースに対するアクションを表します。 |
− |
(凡例)
−:該当しません。
URIの構成内容や詳細は,APIごとに異なるため,各APIの説明を参照してください。
(2) サポートするHTTPメソッド
HTTPが定義する操作メソッドのうち,GETメソッド,POSTメソッド,PUTメソッドおよびDELETEメソッドをサポートしています。
扱うリソースによって,使用できるメソッドは異なります。使用できるメソッドについては,各APIの説明を参照してください。
(3) リクエストライン
リクエストラインは次の項目から構成されます。
- リクエストラインの形式
メソッド△リクエストパス(URI)△クエリ△HTTPバージョン
(凡例)△:半角空白
項目
説明
例
メソッド
リクエストのメソッド
GET
リクエストパス(URI)
リソースを示すパス
/Analytics/v1/objects/Credentials
クエリ
リクエストに含めるクエリパラメータ
?$query=instanceId+eq+50 HTTPバージョン
HTTPのバージョンを示す文字列
HTTP/1.1
なお,リクエストラインの最大長は8,190バイトです。最大長を超えてリクエストラインを指定した場合,ステータスコード414(Request-URI Too Long)が返されます。
(4) リクエストヘッダー
リクエストヘッダーには,レスポンスのデータ形式およびレスポンスの言語コードなどを指定します。
ヘッダー |
説明 |
指定できる値 |
指定の要否 |
---|---|---|---|
Host |
ホストの情報として次の項目を指定します。 ホスト名またはIPアドレス:JP1/OAサーバのホスト名またはIPアドレスです。 ポート番号:APIがJP1/OAに接続する際に,利用するポート番号です。 |
ユーザーの環境を確認して指定する。 |
任意 |
Accept |
レスポンスデータに指定したいデータ形式を指定します。 |
application/json |
必須 |
Accept-Language |
レスポンスに指定したい言語の言語形式を指定します。 GETメソッド,POSTメソッドまたはPUTメソッドを指定する場合に指定します。 |
ja:日本語 en:英語 |
必須 |
Content-Type |
リクエストボディーの形式を指定します。 POSTメソッドまたはPUTメソッドを指定する場合に指定します。 |
application/json |
必須 |
Authorization |
認証情報を指定します。 |
Basic認証の場合 ユーザー情報 HSSOトークンの場合 hsso token |
必須 |
Content-Length |
リクエストボディーのサイズを10進数で指定します。 POSTメソッドまたはPUTメソッドを指定する場合に指定します。 |
リクエストボディーのサイズ(単位:バイト) |
必須 |