15 オンラインチャージング用の Diameter Ro インタフェース API の使用

この章では、アプリケーション開発時に OWLCS の Diameter プロトコル実装に基づいて Diameter Rf インタフェースアプリケーションを使用する方法について説明します。以下の節で構成されています。

節 15.1「Ro インタフェースのサポートの概要」
節 15.2「クレジット認証モデルについて」
節 15.3「Ro アプリケーションのコンフィグレーション」
節 15.4「オンラインチャージング API の概要」
節 15.6「セッションベースチャージングの実装」
節 15.7「クレジット管理リクエストメッセージの送信」
節 15.8「障害の処理」

15.1 Ro インタフェースのサポートの概要

クレジットベースチャージングとしても知られているオンラインチャージングは、プリペイドサービスの請求に使用されます。典型的なプリペイドサービスの例としては、音声またはビデオのために購入するテレホンカードがあります。Ro プロトコルを使用することで、チャージングトリガ機能 (CTF) からオンラインチャージング機能 (CDF) へチャージングイベントを発行することが可能になります。チャージングイベントは即時、イベントベース、セッションベースのいずれかとすることができます。

OWLCS は Diameter オンラインチャージングアプリケーションを提供します。デプロイ済みのアプリケーションは、このアプリケーションを利用して Ro プロトコルに基づくチャージングイベントを生成します。これにより、デプロイ済みのアプリケーションが、コンフィグレートされた OCF に対し CTF として機能することが可能になります。Diameter オンラインチャージングアプリケーションは、Rf および Sh、どちらのアプリケーションもサポートする基本 Diameter プロトコルを使用します。

Diameter オンラインチャージングアプリケーションは、IETF RFC 4006 : Diameter クレジット管理アプリケーション (http://www.ietf.org/rfc/rfc4006.txt) に基づいています。ただし、アプリケーションがサポートするのは、「3GPP TS 32.299 : 通信管理、チャージング管理、Diameter チャージングアプリケーション (http://www.3gpp.org/ftp/Specs/html-info/32299.htm) との整合性のために必要な RFC 4006 のサブセットのみです。より明確に言うと、OWLCS Diameter オンラインチャージングアプリケーションはサービス固有の属性値ペア (AVP) を直接サポートすることはありませんが、提供される API が十分にフレキシブルなものであり、そのためにクレジット管理リクエストにカスタムサービス固有の AVP を含めることができます。

15.2 クレジット認証モデルについて

RFC 4006 は、以下のような 2 つの基本的なタイプのクレジット認証モデルを定義します。

ユニット予約方式でのクレジット認証
口座引き落とし方式でのクレジット認証

ユニット予約方式でのクレジット認証では、イベントベースまたはセッションベースのいずれにチャージングイベントでも実行することができます。口座引き落とし方式でのクレジット認証では、即時チャージングイベントを使用します。どちらのモデルでも、CTF はエンドユーザにサービスを配信する前に OCF からのクレジット認証を要求します。

以下の節では、各モデルについて詳しく説明します。

15.2.1 ユニット決定方式でのクレジット認証

RFC 4006は、ユニット予約方式でのイベントチャージング (ECUR) およびユニット予約方式でのセッションチャージング (SCUR) を定義します。これらのチャージングイベントは、どちらもセッションベースであり、CTF と OCF 間における複数のトランザクションを必要とします。ECUR では、サービスを配信する前にまずユニット数を予約するための問い合わせを行い、その後、サービスの終了時点で実際に使用されたユニット数を OCF へ報告するための問い合わせを実行します。SCUR の場合には、CTF が 1 つまたは複数の中間問い合わせを行って実際にその時点で使用されているユニット数を報告し、必要に応じて追加のユニット数を予約することもできます。いずれの場合も、セッションステートは CTF および OCF の両方に保持されます。

ECUR および SCUR、どちらの場合も、オンラインチャージングクライアントは RFC 4006 に記載されている「CLIENT, SESSION BASED」ステートマシンを実装します。

15.2.2 口座引き落とし方式でのクレジット認証

口座引き落としの場合は、即時イベントチャージング (IEC) が使用されます。IEC では、単一のトランザクションを作成し、クレジット認証の完了後に OCF が直ちにユーザの口座から一定の金額を引き落します。認証の受信後、CTF がサービスを配信します。このクレジット認証の形態は、1 回限りの (ワンタイム) イベントであり、セッションステートは保持されません。

IEC では、オンラインチャージングクライアントは、IETF RFC 4006 に記載されている「CLIENT, EVENT BASED」ステートマシンを実装します。

15.2.3 ユニットの決定とレーティング

ユニットの決定は、サービスの配信に先立って割り当てることのできる、非貨幣的な単位ユニット数 (サービスユニット、時間、イベントなど) の計算を参照します。ユニットのレーティングは、ユニット決定機能によって算出された非貨幣的なユニット数に基づいた価格決定を参照します。

ユニットの決定およびユニットレーティングは、OCF、CTF のいずれでも処理可能です。どちらで処理を行うかは、OCF に送信されるクレジット管理リクエスト内の AVP の選択を制御するクライアントアプリケーションによって決まります。

15.3 Ro アプリケーションのコンフィグレーション

RoApplication は、プロファイルデータを管理するための Sh アプリケーションと似たような Diameter アプリケーションとしてパッケージされています。Ro Diameter アプリケーションは、DOMAIN_ROOT/config/custom/diameter.xml に格納されている Diameter コンフィグレーションファイルを編集するか、Diameter コンソール拡張を使用して、コンフィグレーションおよび有効化することができます。

アプリケーションの init パラメータである ocs.host が、OCF のホスト ID を指定します。この場合、OCF ホストは、グローバル Diameter コンフィグレーションの一部としてピアテーブル内にコンフィグレーションされている必要があります。もう 1 つの方法として、init パラメータ ocs.realm を使用して、レルムベースルーティングを使用する 1 つまたは複数の OCF ホストを指定することもできます。この場合、対応するレルム定義がグローバル Diameter コンフィグレーション内にもある必要があります。

例 15-1 は、Ro を「myocs.oracle.com」という OCF ホスト名で有効化する diameter.xml から抜粋したサンプルです。

例 15-1 Ro アプリケーションコンフィグレーションのサンプル (diameter.xml)

  <application>
    <application-id>4</application-id>
    <class-name>com.bea.wcp.diameter.charging.RoApplication</class-name>
    <param>
      <name>ocs.host</name>
      <value>myocs.oracle.com</value>
    </param>
  </application>

RoApplication は Diameter クレジット管理アプリケーションに基づいているため、Diameter アプリケーション ID は 4 になります。

15.4 オンラインチャージング API の概要

OWLCS は、オンラインチャージング API を提供します。この API により、デプロイ済みの任意のアプリケーションが CTF として機能し、Ro プロトコルを介して OCS に対しオンラインチャージングイベントを発行することが可能になります。すべてのオンラインチャージングリクエストは、Diameter クレジット管理リクエスト (CCR) メッセージを使用します。使用されたチャージングのタイプは、CC-Request-Type AVP で示されます。チャージング API において、CC-Request-Type は com.bea.wcp.diameter.cc パッケージで、RequestType クラスによって表されます。表 15-1 は異なるクレジット認可モデルに関連付けられたリクエストタイプを示します。

表 15-1 クレジット管理リクエストのタイプ

タイプ	説明	com.bea.wcp.diameter.cc.RequestType 内の RequestType フィールド
IEC	即時イベントチャージング	`EVENT_REQUEST`
ECUR	ユニット予約方式でのイベントチャージング	`INITIAL` または `TERMINATION_REQUEST`
SCUR	ユニット予約方式でのセッションチャージング	`INITIAL`、`UPDATE` または `TERMINATION_REQUEST`

ECUR および SCUR では、サービスの配信前にユニットを予約し、サービスの完了時点でコミットします。ユニットの予約は INITIAL_REQUEST で行われ、TERMINATION_REQUEST でコミットされます。SCUR の場合には、UPDATE_REQUEST でユニットを更新することもできます。

基本 Diameter パッケージ com.bea.wcp.diameter には、Ro で使用される再認証リクエストをサポートするクラスが含まれています。com.bea.wcp.diameter.ccパッケージには Ro アプリケーションなど、クレジットコンロールアプリケーションをサポートするクラスが含まれています。com.bea.wcp.diameter.charging は Ro クレジットアプリケーションを直接サポートします。表 15-2 は、Ro クレジットコントロールのクラスの概略を説明します。

表 15-2 Ro クラスの概略

クラス	説明	パッケージ
`Charging`	定数定義	`com.bea.wcp.diameter.charging`
`RoApplication`	オンラインチャージングアプリケーション	`com.bea.wcp.diameter.charging`
`RoSession`	オンラインチャージングセッション	`com.bea.wcp.diameter.charging`
`CCR`	クレジット管理リクエスト	`com.bea.wcp.diameter.cc`
`CCA`	クレジット管理応答	`com.bea.wcp.diameter.cc`
ClientSession	クレジット管理クライアントセッション	`com.bea.wcp.diameter.cc`
RequestType	クレジット管理リクエストタイプ	`com.bea.wcp.diameter.cc`
RAR	再認証リクエストメッセージ	`com.bea.wcp.diameter`
RAA	再認証応答メッセージ	`com.bea.wcp.diameter`

15.5 Ro アプリケーションへのアクセス

Ro アプリケーションがアンデプロイされると、OWLCS でデプロイされたアプリケーションは Diameter ノード (com.bea.wcp.diameter.Nodeクラス) からアプリケーションのインスタンスを取得することができます。例 15-2 は Diameter Node の取得、および Ro アプリケーションへのアクセスに使用するサンプルサーブレットコードを示します。

例 15-2 Ro アプリケーションへのアクセス

private RoApplication roApp;
void init(ServletConfig conf) {
    ServletContext ctx = conf.getServletContext();
    Node node = (Node) ctx.getParameter("com.bea.wcp.diameter.Node");
    roApp = node.getApplication(Charging.RO_APPLICATION_ID);
  }

このコード例では、RoApplication をインスタンス変数としてサーブレットで使用できるようにします。RoApplication のインスタンスは、複数の同時スレッドで使用する場合に安全です。

15.6 セッションベースチャージングの実装

RoApplication を使用して、セッションベースクレジット認証のための新しいセッションを作成することができます。RoSession クラスは、クレジット管理タイプが ECUR (ユニット予約方式でのイベントベースチャージング) または SCUR (ユニット予約方式でのセッションベースチャージング) のいずれかに応じて、適切なステートマシンを実装します。また、RoSession クラスはシリアライズ可能なため、SIP セッション属性として格納することができます。このため、セッションを終了したり、クレジット認証を更新する必要がある場合に、セッションを復元することができます。

例 15-3 の例では、イベントベースチャージングの新しい RoSession を作成し、CCR リクエストを送信して最初の問い合わせを開始します。サービスの終了後、後で終了できるように RoSession インスタンスを保存します。

RoSession クラスはセッション ID の作成を自動で処理することに注意してください。アプリケーションでセッション ID を設定する必要はありません。

例 15-3 RoSession の作成と使用

RoSession session = roApp.createSession();
CCR ccr = session.createCCR(RequestType.INITIAL);
CCA cca = ccr.sendAndWait();
sipAppSession.setAttribute("RoSession", session);
...

15.6.1 再認証リクエストメッセージの処理

OCS が再認証リクエスト (RAR) を CTF に発行して、クレジット再認証を開始させることがあります。このタイプのリクエストを処理するために、アプリケーションはセッションリスナを登録することができます。RAR を受信すると、Diameter サブシステムは RoSession オブジェクトに対応するアプリケーション上のセッションリスナを呼び出します。RFC 4006 (http://www.ietf.org/rfc/rfc4006.txt) の節 5.5 に記載されているように、アプリケーションは適切な RAA メッセージで OCS に応答し、値 UPDATE_REQUEST を設定した CC-Request-Type AVP とともに CCR を送信して CTF に対するクレジット再認証を開始させる必要があります。

セッションリスナは、SessionListener インタフェースを実装し、シリアライズ可能である必要があります。または、SipServlet のインスタンスである必要があります。次のようにして、サーブレットがリスナを登録できます。

  RoSession session = roApp.createSession();
  session.addListener(new SessionListener() {
    public void rcvMessage(Message msg) {
      System.out.println("Got message: id = " msg.getSession().getId());
    }
  });

例 15-4 に再認証リクエストを処理する rcvMessage() コードのサンプルを示します。

例 15-4 再認証リクエストの管理

  RoSession session = roApp.createSession();
  session.addListener(new SessionListener() {
  public void rcvMessage(Message msg) {
    Request req = (Request)msg;
    if (req.getCommand() != Command.RE_AUTH_REQUEST) return;
    RoSession session = (RoSession) req.getSession();
    Answer ans = req.createAnswer();
    ans.setResultCode(ResultCode.LIMITED_SUCCESS); // Per RFC 4006 5.5
    ans.send();
    CCR ccr = session.createCCR(Ro.UPDATE_REQUEST);
    ... // リクエストされたクレジット再認証に応じて CCR AVP を設定します。
    ccr.send();
    CCA cca = (CCA) ccr.waitForAnswer();
  }

例 15-4 では、再認証リクエストを受信すると、アプリケーションは結果コード DIAMETER_LIMITED_SUCCESS とともに RAA を送信し、OCS に対して処理の完了のために追加の CCR リクエストが必要であることを知らせます。その後 CCR が送信され、クレジット再認証が開始されます。

注意 :

Diameter サブシステムは対応する RoSession にリクエストを配信する前に呼状態をロックするため、リクエストがハンドラによって処理されている間、呼状態はロックされた状態のままになります。

15.7 クレジット管理リクエストメッセージの送信

CCR クラスは Diameter クレジット管理リクエストメッセージを表し、クレジット管理リクエストを OCF に送信するために使用できます。ECUR (ユニット予約方式でのイベントベースチャージング) と SCUR (ユニット予約方式でのセッションベースチャージング)、どちらの場合でも、新しい CCR リクエストの作成には RoSession のインスタンスを使用します。RoApplication を直接使って IEC に CCR メッセージを作成することもできます。例 15-5 は CCR の作成と送信の方法を示します。

例 15-5 CCR の作成および送信

  CCR ccr = session.createCCR(RequestType.INITIAL);
  ccr.setServiceContextId("sample_id");
  CCA cca = ccr.sendAndWait();

CCR リクエストを作成した後は、どのようなアプリケーション固有またはサービス固有の AVP でも設定できます。これらの AVP は、addAvp() メソッドを使用してリクエストを送信する前に必要とされます。セッションの各新規リクエストに同じ AVP をいくつか含める必要があるため、これらの AVP をセッション自体に設定することもできます。例 15-6 は以下を設定するサンプルを示します。

Subscription-Id はセッションのユーザを特定する。
Service-Identifier はリクエスト対象のサービスを示す。
Requested-Service-Unit はリクエスト対象のユニットを指定する。

また、カスタム AVP を CCR リクエストに直接追加します。

例 15-6 CCR における AVP の設定

  session.setSubscriptionId(...);
  session.setServiceIdentifier(...);
  CCR ccr = session.createCCR(RequestType.INITIAL);
  ccr.setRequestedServiceUnit(...);
  ccr.addAvp(CUSTOM_MESSAGE, "This is a test");
  ccr.send();

この例では、セッションの各新規リクエストに、同じ Subscription-Id および Service-Identifier を追加しています。また、送信前に、メッセージに対しカスタム AVP 「Custom-Message」を追加しています。

15.8 障害の処理

アプリケーションでは、OCF から送られる CCA エラー応答内の Result-Code AVP を調べることで障害の原因を検出し、適切な対処を行うことができます。使用不可のピアや無効なルート仕様といったローカルで発生したエラーの場合は、リクエスト送信のメソッドが呼び出され、障害の内容を示す詳細メッセージとともに IOException が送出されます。

また、アプリケーションでは、Diameter タイマー Tx 値を使用して、どの時点で OCF がクレジット認証リクエストへの応答に失敗したかを突き止めることができます。タイマー Tx のデフォルト値は 10 秒ですが、RoApplication コンフィグレーション内の tx.timer init パラメータを使用してオーバーライドすることができます。タイマー Tx は、CCR が OCF に送信られた時点でスタートします。また、対応する CCA の受信後、タイマーはリセットされます。

対応する CCA の受信前に Tx が期限切れになった場合は、waitForAnswer への呼び出しが直ちに null を返し、リクエストがタイムアウトしたことを示します。そのため、アプリケーションは、リクエストの Credit-Control-Failure-Handling (CCFH) AVP の値に従って適切な対処を取ることができます。詳細については、RFC 4006 (http://www.ietf.org/rfc/rfc4006.txt) の「5.7 障害の手順」を参照してください。

例 15-7 では、CCA の受信前にタイマー Tx が期限切れになった場合、クレジット管理セッションは終了します。セッションは長めに存続するため、その後サブシステムによって CCA が受信されるとメッセージは無視されます。

例 15-7 タイマー Tx 有効期限の確認

  CCR ccr = session.createCCR(RequestType.INITIAL);
  ccr.setCreditControlFailureHandling(RequestType.TERMINATION);
  ccr.send();
  CCA cca = ccr.waitForAnswer();
  if (cca == null) {
    session.terminate();
  }

15 オンライン チャージング用の Diameter Ro インタフェース API の使用