接続仕様

当ドキュメントの記述範囲

本書では、INFINI HOST-LINKシステム(以下本システム)においてINFINI内に設置されたアプリケーションサーバ(以下サーバ)とユーザ敷地内に設置されたサーバ(以下クライアント)との間のINFINI Amenity API機能利用に関するインタフェース仕様を記述する。
 なお、本書においてはプロトコル層以上について記述し、ネットワークの物理層については範囲外とする。

 

基本仕様

1.    サーバとクライアント間の通信はHTTP/1.1仕様に基づくHTTPプロトコルを用いるものとする。

2.    通信はすべてクライアントからの接続とし、サーバからの応答をもって完結する。

※ソケットの接続状態(Keep-Alive制御)についてはIISの実装に準じる。

3.    セッションの概念を持たない HTTP上においてセッション管理を実現するため、HTTPヘッダを用いたセッション管理を行う(いわゆるクッキー方式を使用する)

※セッションとは、HOST-LINKサーバを経由してのINFINIホストに対するサイン・イン(Sign in)からサイン・アウト(Sign out)までの接続状態を擬似的にHTTPプロトコル上に実現するものである。

4.    また、クッキーのみでは制御できないプロトコルを実現するために、HTTP拡張ヘッダを定義して使用する。

5.    HTTPのコンテンツは各APIのリファレンスに準拠する事とし、本資料では関知しない。

※メッセージの先頭から連続する改行までをHTTPヘッダとし、以降をコンテンツと呼ぶ。

6.    メッセージはヘッダ、コンテンツともすべてASCII文字で構成されるものとする
(現時点で本システムにおいて日本語などのマルチバイト文字は使用されしない)。

7.    本サービスは下記のURLで提供される
本番環境:
https://www.infini-hostlink.com/HostLinkService/infiniAPI.asp
テスト環境:
https://testsite.infini-hostlink.com/HostLinkService/infiniAPI.asp

8.    未承認ユーザからのアクセスについて
ユーザ登録には、ユーザ側サーバIPアドレスと利用PCCを必要とする。登録されたIPアドレスや指定されたPCC以外からのアクセスに対し、本システムは特にエラー回答はせず、HTTPメッセージのみを回答する。

 

構成

本仕様を実現するための、構成(案)を付図に示す。

※なお、クライアント側構成については想像に基づくものである。



※クライアント(Agent System)側はなんらかのアプリケーションサーバ機能により、
 サーバ(INFINI System)より付与されたCookie値を維持することを想定する。

 

セッションの管理

各セッションのフェーズに応じて、下記の拡張ヘッダを含むHTTPヘッダが送付されるものとする。

 

セッションの開始

1.    セッションの開始時にクライアントは、下記 HTTPヘッダを持つリクエストメッセージを送信する。
X-XML-Booking-Session: SESSION=START
X-XML-Booking-PCC: PCC=XXXX
X-XML-Booking-Host: HOST=RH
X-XML-Booking-Mode: MODE=AMENITY

※XXXXはエージェント旅行会社の持つ4桁のPCCコードであり、サイン・インに
使用される。また、サーバでPCCコードの末尾が"6"であることをチェックする。
※コンテンツデータはtext/*形式で送受信される。
※セッション確立中でのホスト接続先変更(HOST→RHまたはRH→HOST)は不可とする。HOSTセッション接続中にRHにセッション開始を行うと、HOSTセッションは終了しない。(RH→HOSTも同様)
※X-XML-Booking-Session: SESSION=START_ENDによるセッション開始、エントリ
実行、セッション終了の1リクエストによる実行も可能とする。

2.    上記要求に対しサーバは、サーバー内部でセッション情報を生成し、その結果を、下記HTTPヘッダを持つレスポンスメッセージによりクライアントに送信する。
X-XML-Booking-Status: STATUS=XXXX
Set-Cookie: ASPSESSIONIDYYYYY=ZZZZZ; ….

※    XXXXはソケットの確立、およびサイン・インの結果を示すステータス・コードである。このステータスが異常の場合には Set-Cookie ヘッダは送られない。
※    クライアントは通知されたクッキー情報(ASPSESSIONIDYYYYY=ZZZZZ)を記憶しておく。(YYYYY,ZZZZZは任意の長さの文字列である)
※    クッキー情報内の";"以降の文字列についてはクライアントで無視する(付かない場合もある)。
※    "Set-Cookie"という識別子を持つヘッダ情報は単一であるはないため、それぞれ取得する必要がある。
※セッションが存在する時点でクライアントよりセッション開始要求を行った場合、サーバは内部で再度セッション情報を生成する。
※HOST⇔Routehappy間の通信にセッションの概念は無いが、クライアントと本システム間でのセッションを管理するためセッションの概念を導入する。


 

セッションの維持

1.    クライアントはセッション継続中のリクエストメッセージには、下記 HTTPヘッダを付けて送信する。
(1)    X-XML-Booking-Host: HOST=RH
(2)    X-XML-Booking-Mode: MODE=AMENITY 
(3)    Cookie: ASPSESSIONIDYYYYY=ZZZZZ
(4)    X-XML-Booking-ENDPOINT:/legs?SSSS

※    Cookie情報はセッション開始時にサーバから返された情報であること。
※    SSSSSはINFINI Amenity APIへのクエリ文字列である。

2.    上記要求に対しサーバは、リクエストデータを処理し、その結果を、下記HTTPヘッダを持つレスポンスメッセージによりクライアントに送信する。
X-XML-Booking-Status: STATUS=XXXX


 

セッションの終了

1.    クライアントはセッションを終了させるために、下記 HTTPヘッダを持つリクエストメッセージを送信する。
(1) X-XML-Booking-Host: HOST=RH
X-XML-Booking-Mode: MODE=AMENITY
Cookie: ASPSESSIONIDYYYYY=ZZZZZ
X-XML-Booking-Session: SESSION=END

(2) X-XML-Booking-Host: HOST=RH
X-XML-Booking-Mode: MODE=AMENITY
X-XML-Booking-ENDPOINT:/legs?SSSS
X-XML-Booking-Session: SESSION=START_END

※    (2)の場合はセッション開始、終了を同時に行う。
※    Cookie情報はセッション開始時にサーバから返された情報であること。
※    SSSSSはINFINI Amenity APIへのクエリ文字列である。

2.    上記要求に対しサーバは、下記HTTPヘッダを持つレスポンスメッセージを送信する。
X-XML-Booking-Status: STATUS=XXXX

※    XXXXはソケットの切断、およびサイン・アウトの結果を示すステータス・コードである。


 

サーバ障害に伴うセッション終了

1.    サーバにおいてリクエスト受信後に、処理を継続できない状況が生じた場合、サーバは下記HTTPヘッダを持つレスポンスメッセージを送信する。
X-XML-Booking-Session: SESSION=END
X-XML-Booking-Status: STATUS=XXXX

※    XXXXは障害を示すステータスとする。
※    ホストのタイムアウト、対ホストソケットの切断などを想定しているため、セッションは切断されることを前提とする
※    セッション開始リクエスト受信時に障害が起きた場合、レスポンスメッセージに上記のヘッダ以外に Set-Cookie: が指定されるかもしれないが、クライアントはこれを用いたリクエストを行ってはならない。
※    クライアントより受信したリクエストのHTTPヘッダが不適当な場合はエラー応答を行い、セッションを切断する。

2.    同様にリクエスト受信後に、応答も返せない状況が生じた場合、クライアントは一定時間受信待ち後切断を切断すること。


 

クライアント障害に伴うセッションタイムアウト

1.    クライアントにおいて処理を継続できない状況が生じた場合、上記「セッションの終了」と同じ手順によりセッション終了要求を行うこと。

2.    セッション終了要求も送信できない状況が生じた場合、サーバは一定時間セッションを維持した後、セッションを終了させる。


 

HTTPメソッド、Endpointの指定

本システムのINFINI Amenity APIではクライアントからGET(POSTについては今後のバージョンUP時に対応予定)リクエストを受け付ける。
AMENITY APIではGETを利用する。
また、INFINI Amenity APIのEndpointの指定については下記HTTPリクエストヘッダーにより指定するものとする。

X-XML-Booking-ENDPOINT:/legs?SSSS

※    SSSSSはINFINI Amenity APIへのクエリ文字列である。


 

コンテンツ(クエリ文字列)

通常リクエストには、INFINI Amenity API仕様に基づく クエリ文字列が含まれるが、下記のヘッダが付いた場合には、そのメッセージのリクエストは無視するものとする(サーバ、クライアント双方において)。

※    下記ヘッダがついたメッセージのコンテンツは INFINI Amenity API仕様に含まれない独自コンテンツとする。
X-XML-Booking-Contents: CONTENTS=IGNORE

例1:    クライアントから、セッション開始/セッション終了のみ行う場合のリクエスト/レスポンスメッセージ
例2:    サーバにて障害が発生した場合のレスポンスメッセージ


 

コンテンツのGZIP圧縮

通常コンテンツは非圧縮のJSONメッセージを戻すが、下記HTTPレスポンスヘッダーが含まれる場合、コンテンツがGZIP圧縮されているためクライアント側で解凍するものとする。
Content-Encoding: gzip

クライアントからの下記HTTPリクエストヘッダーについて本システムでは受け付けない。
仮に送信されてきても無視する。
Accept-Encoding


 

通信例

上記仕様に基づいた通信例は以下のとおりである。

 

通常パターン




 

セッション開始要求のみ先行するパターン





 

セッション終了要求のみクライアントから送信するパターン




 

セッションタイムアウト終了後にクライアントから要求を送信するパターン




 

クライアントからセッション開始要求と終了要求の両方が指定されたパターン




 

クライアントからセッション開始要求と終了要求の両方(SESSION=START_END) が指定されたパターン




 

セキュリティ

1. 本システムにおいて、INFINI側LANとユーザ側LAN間の通信(WAN)については物理層 によって十分セキュリティが確保されていることを前提とし、この部分のセキュリティ対策 は本設計書では記述しない。

2. INFINI 側 LAN 内部およびユーザ側 LAN 内部におけるセキュリティ保持のため、サーバ において下記の対策を取る。 


 

リクエストメッセージ送信元の確認

1. リクエストメッセージ送信元のIPアドレスをチェックし、あらかじめ設定されたIPアドレス以 外からのリクエストはエラー応答し、該当セッションを切断する。

2. セッション開始時の送信元IPアドレスを記憶しておき、セッション途中ではそのIPアドレス 以外からの要求はエラー応答する


 

セッションのタイムアウト

1. 一定時間リクエストの無いセッションについては、サーバでこれを無効化する。

2. 無効化されたセッションを指定したリクエストメッセージについては、エラー応答する。
 この場合の HTTP ヘッダは下記のとおりとする 
 X-XML-Booking-Session: SESSION=END
 X-XML-Booking-Status: STATUS=9C00
 X-XML-Booking-Contents: CONTENTS=IGNORE

※ ただし、そのメッセージがセッション開始要求の場合は正常リクエストとみなし、新規セ ッションを開始する。
※ タイムアウト値は 5 分とする。 


 

受信コンテンツサイズの制限

ありえないサイズのリクエストを受信することによるメモリ不足や高負荷の発生を予防する ため、受信中のコンテンツサイズが 32KB を超えた時点で以降の受信を中止しエラー応答す る。 


 

特記事項

1. ステータス・コードについては、以下に一覧を記載する。
2. 本設計書のセッション管理方法は、RFC2109(HTTP State Management Mechanism) に準拠する。
3. HTTP 拡 張 ヘ ッ ダ は 、 RFC822(STANDARD FOR THE FORMAT OF ARPA INTERNET TEXT MESSAGES)に準拠し、先頭文字を "X-"とする。 4. また、RFC2616 に準拠し HTTP ヘッダ識別子(":"の左側の文字列)において大文字/ 小文字は区別されないものとする。 5. 特に断りの無い限り、サーバより送信する HTTP メッセージ仕様は IIS7.5 の実装に依存する。

<INFINI HOST-LINK XML版ステータス・コードについて>
現在のINFINI HOST-LINK XML版に基づいて返されるステータス・コード(拡張ヘッダのSTATUSに設定される値)は下記の定義に従った16進4桁数値である。



 

エラーコード

ここでは、エラー・コードの実際の値とその意味について表にしてまとめる。
 
ステータスコード 意味
0000 正常
9401 PCCエラー(末尾が6でない、または長さが8バイトより長い)
9402 不正なアクセス(途中で IP アドレスが未登録 IP アドレスに変更された)
9403 不正なアクセス(未登録 IP アドレスから受信)
9404 コンテンツが長すぎる(32KBを超えている)
9406 認識できないヘッダーがある
9408 PCCセッション上限数オーバー
9409 エンドポイント未指定
940A コマンド、モード組み合わせ指定エラー
940C 不正なクッキー
940D 接続先未指定(Routehappy接続先が指定されていない)
940E 通信遮断(契約しているトランザクション数を超過)
9C00 ホストとの接続時エラー
セッションが存在しない
9C02 ホストとの接続時エラー
接続タイムアウト
A402 ホストからの受信エラー
受信タイムアウト
A405 ホスト、サーバータイムアウト
A887 ホストへの送信エラー
送信タイムアウト
A8FF 受信したレスポンス・データが空だった
AC01
(xxx)
Routehappyホスト通信エラー
Routehappyホストへのコマンド送受信時のHTTPステータスコードが200でない
xxx はステータスコード
AC03
(xxx)
ホストビシー
通信毎にスレッド数の上限数オーバー
xxxは各通信のサブコード
FFFF 内部エラー


 

ステータス・コード

ステータスコード 説明
200 リクエストに対する情報が一つ以上存在する場合に返却されます。ボディはJSONフォーマットで返却されます。
404 リクエストに対して情報が存在しない場合に返却されます。ボディはJSONフォーマットで返却されます。
401 認証情報に誤りがあります。ボディはJSONフォーマットで返却されます。
414 URLが長すぎます。”ids”パラメータをPOSTメソッドで送信して下さい。
415 Acceptヘッダーの指定が不正です。ボディはJSONフォーマットで返却されます。
400 クライアント側のリクエストが不正です。エラー理由がボディに含まれ返却されます。
503 サーバが一時的にリクエストを処理できない状態です。
500 サーバ内部でエラーが発生しリクエストを処理できない状態です。