この製品のマニュアルセットは、偏向のない言語を使用するように配慮されています。このマニュアルセットでの偏向のない言語とは、年齢、障害、性別、人種的アイデンティティ、民族的アイデンティティ、性的指向、社会経済的地位、およびインターセクショナリティに基づく差別を意味しない言語として定義されています。製品ソフトウェアのユーザーインターフェイスにハードコードされている言語、RFP のドキュメントに基づいて使用されている言語、または参照されているサードパーティ製品で使用されている言語によりドキュメントに例外が存在する場合があります。シスコのインクルーシブランゲージに対する取り組みの詳細は、こちらをご覧ください。
このドキュメントは、米国シスコ発行ドキュメントの参考和訳です。リンク情報につきましては、日本語版掲載時点で、英語版にアップデートがあり、リンク先のページが移動/変更されている場合がありますことをご了承ください。あくまでも参考和訳となりますので、正式な内容については米国サイトのドキュメントを参照ください。
この章では、外部Quota Provisioning(QP)APIについて説明します。
• 「制限事項」
外部クォータ プロビジョニングは、Service Controlパートナーがアプリケーション認識能力のあるクォータ ベースおよびボリューム ベース サービスを作成するための、クォータ(割り当て量)実施メカニズムです。このメカニズムは、外部エンティティによるサブスクライバ レベルでのクォータ プロビジョニングを可能にし、各ベンダー製のサブスクライバ管理プラットフォームとの統合を実現します。
外部クォータ プロビジョニングについての詳細は、『 Service Control Application Suite for Broadband User Guide 』を参照してください。
Quota Provisioning API(QP API)はService Control SM APIの拡張機能であり、C/C++およびJavaの両方のバージョンが用意されています。QP APIは、SMへの接続およびサブスクライバの追加と設定に関してはSM APIの機能に依存します。QP APIは、クォータの設定(setSubscriberQuota)、クォータの追加(addSubscriberQuota)、およびサブスクライバのクォータ バケットにあるクォータ残量の読み取り(getRemainingSubscriberQuota)といった機能を追加します。
SM APIの詳細については、『 C/C++ API for SM Guide』および『Java API for SM Guide 』を参照してください。
これらの機能により、OSSシステムで、このようなサービス モデルをプリペイド形式やクォータに基づく消費量で使用するアプリケーション/サービスに関して、サブスクライバのトラフィック使用状況を制御するためのロジックを開発できます。
システムに適用するSCAS BBサービス コンフィギュレーション(PQB)を作成するとき、QP APIを有効に活用するためのいくつかのガイドラインがあります。
–Package Quota Management Mode(パッケージ クォータ管理モード)を「External」に設定する必要があります。
–バケットを設定するとき、適切なバケット タイプを設定する必要があります。使用可能なタイプは、「Volume(容量、L3 KB)」または「Number of Sessions(セッション数)」です。
–サービス ルールにおける使用量制限の定義では、適切なバケットを選択する必要があります。サービス トラフィックは、選択したバケットからクォータを消費します。ルールの違反処理アクションを使用して、バケットの使用中にトラフィックに割り当てるサービス レベルを設定できます。
• RDR: 関連するRDRの生成をアクティブにするには、RDR Settingsで次のRDRをイネーブルにする必要があります。
–Quota Threshold(クォータ スレッシュホールド)RDR
パッケージ、ルール、およびRDRの設定についての詳細は、『Service Control Application Suite for Broadband User Guide』を参照してください。
ここでは、サブスクライバがクォータ バケットからクォータを消費するとき、およびQP APIによって追加のクォータをプロビジョニングするときの、クォータ バケットのさまざまな状態について説明します。
• スレッシュホールドより上: バケットが スレッシュホールドより上 の場合、クォータは消費されており、クォータ残量がRemaining Quota RDRでレポートされます。
• スレッシュホールドより下: クォータの残量が スレッシュホールドより下 になると、Quota Threshold RDRが生成されます。このRDRに対応して、クォータの追加または設定を行えば、バケットを再びスレッシュホールドより上にして、枯渇を未然に防げる可能性があります。クォータの残量は、クォータの消費に応じてRemaining Quota RDRでレポートされます。
• 枯渇(Depleted) :クォータが0未満になると、バケットは 枯渇 します。この場合、バケットはクォータの欠損すなわち「マイナス」のクォータ残量を維持し、これがRemaining Quota RDRでレポートされます。「枯渇」の状態になると、Quota Breach RDRが生成され、ルールの違反処理アクション(定義されている場合)がトラフィックに適用されます。この時点でクォータの追加または設定を行えば、バケットの枯渇状態を解除できる可能性があります。
ここでは、クォータ プロビジョニング処理と、サブスクライバがログインおよびログアウトし、ネットワーク トラフィックを発生させる各段階でのサブスクライバのクォータ状態について、そのライフサイクルを説明します。
クォータ プロビジョニング処理に関して理解しておくべき重要な点は、QP APIの関連するメソッドによって要求したAddまたはSetなどの処理が、キューに格納されて即時に結果が返されるとしても、実際にクォータが変更されるのは、サブスクライバがトラフィックを生成したとき、すなわち、サブスクライバが何らかのネットワーク アクティビティを実行したとき だけ であるという点です。したがって、外部のプロビジョニング システムがクォータの変更を要求してから、その変更が実際に行われるまでの間、サブスクライバの状態はクォータ変更を反映しません。そのため、この中間的な時点でサブスクライバのクォータ残量を読み取っても、表示される値には、最新の変更が組み込まれていません。
次の図で、クォータ プロビジョニング処理およびサブスクライバのネットワーク アクティビティの結果、クォータが変化する例を示します。
ステップ 1 外部クォータ プロビジョニング システムがクォータの変更(この例ではset-quota)を実行すると、その変更はキューに格納され、まだ処理されません(図中1)。
ステップ 2 したがって、外部クォータ プロビジョニング システムがクォータ残量を読み取ると、変更前の古い値が表示されます(図中2)。
ステップ 3 サブスクライバがトラフィックを発生させて初めて、変更が行われます(図中3)。
ステップ 4 このとき、外部クォータ プロビジョニング システムがクォータ残量を読み取ると、更新済みの値が表示されます(図中4)。
• プラスのクォータ残量は、バケットごとに256 GB という上限があります。
この256 GBという限界を超えてサブスクライバのクォータを増やそうとすると、エラーにはなりませんが、結果のクォータ残量がマイナスに変わります。したがって、add-quotaコマンドを使用するときは注意が必要です。
同様に、サブスクライバのクォータ欠損は、バケットごとに最大で256 GBです。サブスクライバのいずれかのバケットが欠損しているとき、そのバケットの残量はマイナスの値(-256 GBまで)です。このマイナスの値をさらに超過すると、システムは過剰消費されたバケットへの課金を停止し、残量は-256 GBのままになります。
これも上記の問題と同様ですが、サブスクライバがログオフしているときや非アクティブのときは、set-quotaコマンドによるクォータ残量の設定を頻繁に行うべきではありません。正確には、サブスクライバが非アクティブのときにset-quotaコマンドで256回連続してクォータ バケットを更新すると、エラーにはなりませんが、バケットの残量が不正確になります。
CおよびJavaに対応するQP APIは、それぞれ別のファイルでパッケージ化されています。このファイルの内容は次のとおりです。
インストールするには、最初にSM APIをインストールしたあと、QP APIを同じ手順でインストールします。
コンパイルして実行するには、SM APIのコンパイルおよび実行手順に従い、QP APIファイルも PATH/Class-path に追加します。Java APIを使用する場合は、classpathに um_core.jar をインクルードします。 um_core.jar は、SCAS BBパッケージに含まれています。
ここでは、Java用のブロッキングQP APIのメソッドを示します。各メソッドのシグニチャに続き、入力パラメータおよび戻り値を説明します。
void addSubscriberQuota(String subscriberName,
int[] quota)
throws QPApiException, ConnectionDownException
quota:
特定のサブスクライバのクォータ バケットの現在のクォータに追加する、16のクォータ値(L3 KBまたはセッション数)の配列
void addSubscriberQuota(String subscriberName,
int bucketNum
int[] quota)
quota
:特定のサブスクライバのクォータ バケットの現在のクォータに追加するクォータ値(L3 KBまたはセッション数)
int[] getSubscriberQuota(String subscriberN
ame)
throws QPApiException, ConnectionDownException
void setSubscriberQuota(String subscriberName,
int[] quota)
throws QPApiException, ConnectionDownException
quota:
特定のサブスクライバのクォータ バケットに設定する、16のクォータ値(L3 KBまたはセッション数)の配列
ここでは、QP API(Java)を使用したコード例を示します。
ここでは、Cに対応するブロッキングQP APIのメソッドを示します。各メソッドのシグニチャに続き、入力パラメータおよび戻り値を説明します。
(注) QP API C関数名には「QPB_」というプレフィクスが付きます。すべてのQP API C関数で、最初のパラメータは、argApiHandle
(init
関数をコールして作成されるAPIハンドル)です。
ReturnCode* QPB_addQuota (QPB_HANDLE argApiHandle, char* argName, int* argQuotas)
argQuotas:
特定のサブスクライバのクォータ バケットの現在のクォータに追加する、16のクォータ値(L3 KBまたはセッション数)の配列
ReturnCode* QPB_getRemainingQuota (QPB_HANDLE argApiHandle, char* argName)
特定のサブスクライバの各クォータ バケットにあるクォータ残量の値(L3 KBまたはセッション数)の整数配列を格納した ReturnCode 構造体のポインタ
ReturnCode* QPB_setQuota (QPB_HANDLE argApiHandle, char* argName, int* argQuotas)
argQuotas:
特定のサブスクライバのクォータ バケットに設定する、16のクォータ値(L3 KBまたはセッション数)の配列
• サブスクライバのクォータの設定、クォータの追加、およびクォータ残量の取得
次の表に、Quota Provisioning APIで発生する可能性のあるエラー コードを示します。Quota Provisioning APIをSM APIと併用する場合は、後者のエラー コードが表示されることもあります。そのようなエラー コードの詳細は、『 smartSUB Programmer's Guide 』の 付録A を参照してください。
|
|
|
非アクティブなサブスクライバに関する例外:サブスクライバのコンテキストが予想外に見つからない場合に発生します(内部エラー)。 |
• ConnectionDownException :SMへの確立済みの接続が、処理の途中で切断された場合に発生します。
• IllegalStateException :SMへの接続が突発的に切断された場合に発生することがあります。
• QPApiException :その他のすべてのエラー。
QPApiExceptionが発生した場合は、qpApiException.getCode()を使用し、上記の(またはSMのマニュアルの 付録A にある)表の「エラー コード」欄と比較してください。qpApiException.getMessage()を使用して、ストリング エラー メッセージを受信します。
関数コールが失敗すると、エラー コードが返されます。そのエラー コードを、上記の(またはSMのマニュアルの 付録 A にある)表の「エラー コード」欄と比較してください。