プラグイン・ガイド¶

イントロダクション¶

このプラグイン・ガイドには、Business API Ecosystem v6.4.0 の利用可能なプラグイン(デジタル・アセット型の定義)が記載されています。バグ、誤植、含まれているべきではないと思われるものを含め、この文書に対するいかなるご意見も歓迎されます。この GEiのカタログページに表示される “Contact Person” の電子メールにそれらを送信してください。または、GitHub Issues で問題を作成してください。

Basic File と Basic URL¶

Basic File と Basic URL プラグインは GitHub で入手できます。これらのプラグインは、特定の型または検証プロセスを指定する必要がなく、Business API Ecosystem におけるデジタルプロダクトの創出を可能にすることを意図しています。この点で、これらのプラグインは、任意のファイルまたは任意のURLをそれぞれデジタル・アセットとして公開することができ、簡単なファイルカタログの作成や Business API Ecosystem のテストに使用できます。

これらのプラグインはイベントハンドラを実装していません。

WireCloud コンポーネント¶

WireCloud コンポーネント のプラグインは、GitHub で入手できます。このプラグインは、特定のコンポーネントの WGT ファイルを提供するプロダクト仕様の作成を可能にすることによって、さまざまな WireCloud コンポーネント (Widgets, Operators, Mashups) を管理および収益化するためのアセット型を定義します。WireCloud プラットフォームの詳細については、ReadTheDocs のドキュメントを参照してください。

WireCloudコンポーネントのプラグインを使用すると、Business API Ecosystem でサポートされている2つの方法で WGT ファイルを提供できます。つまり、プロダクトの作成時に WGT ファイルをアップロードし、プラットフォームがファイルをダウンロードできる URL を指定します。

さらに、プラグインはメディアタイプの Mashable application component のみを許可します。それにもかかわらず、プラグインコードは、WGT metainfo を使用してWireCloudコンポーネント(Widgets, Operators, Mashups)のタイプを判断し、WireCloudプラットフォーム (wirecloud/widget, wirecloud/operator または、wirecloud/mashup) が理解している適切なメディアタイプを上書きします。

このプラグインは以下のイベントハンドラを実装しています :

on_post_product_spec_validation: このハンドラでは、プラグインが WGT ファイルを検証して、有効な WireCloud コンポーネントであることを確認します
on_post_product_spec_attachment: このハンドラでは、プラグインが WGT ファイルのメディアタイプを判断し、特定の製品仕様のメディアタイプ値を上書きします

CKAN Dataset と CKAN API Dataset¶

CKAN Dataset と CKAN API Dataset のプラグインは、GitHub で入手できます。これらのプラグインは、CKAN インスタンスで提供されるデータセットを管理および収益化するためのアセット型を定義します。特に、これらのプラグインは、データセットを検証し、提供されたデータセットを販売するプロダクト仕様を作成するセラーの権利を検証し、取得した顧客のデータセットへのアクセスを管理することができます。

両方のプラグインの違いは、CKAN Dataset のリソースとして含まれるデータの型です。特に、CKAN API Dataset は、FIWARE security framework で保護された外部 API によってデータが提供されることを期待しています。これに関して、CKAN API Dataset は、データサービス内のセラーの許可を検証し、顧客に FIWARE IdM のロールと許諾を使用してアクセスを許可します。

CKANは、デフォルトでは、データセットへのアクセス権を管理するための保護データセットまたは API を公開するメカニズムを提供していないことに注意することが重要です。これに関して、収益化する CKAN インスタンスは、次の CKAN プラグインで拡張する必要があります :

ckanext-oauth2: この拡張では、外部の OAuth2 Identity Manager を使用して CKAN ユーザを管理できます。特に、このコンテキストでは、特定の Business API Ecosystem インスタンスと同じ FIWARE IdM インスタンスを使用するユーザを認証するためにこの拡張を使用する必要があるため、両方のシステム(CKAN と Business API Ecosystem)がユーザを共有します
ckanext-privatedatasets: この拡張では、データセットの所有者が選択した一連のユーザによってのみアクセス可能な CKAN で保護されたデータセットを作成できます。さらに、この拡張機能は、承認されたユーザをデータセットに追加または削除するために使用できる API を公開しています

さらに、ckanext-baepublisher プラグインが CKAN にインストールされている場合、前述の CKAN 拡張では、プロダクト仕様を作成するためにデータセットリソースに応じてCKAN Dataset または CKAN API Dataset のアセット型が使用されるためです。CKAN Dataset または CKAN API Dataset プラグインを Business API Ecosystem にインストールする必要があります。

CKAN Dataset のプラグインでは、CKAN のdataset URL と一致する URL のみをアセットに提供できます。

このプラグインは以下のイベントハンドラを実装しています :

on_pre_product_spec_validation: このハンドラでは、プラグインは提供された URL が有効なCKAN Dataset であること、およびプロダクト仕様を作成しているユーザが所有者であることを検証します
on_product_acquisition: このハンドラでは、プラグインは CKAN instance API を使用して、データセットを取得したユーザにアクセスを許可します
on_product_suspension: このハンドラでは、プラグインは CKAN instance API を使用して、ユーザが支払いを行っていないとき、またはユーザがサブスクリプションをキャンセルしたときにデータセットへのアクセスを取り消します

一方、CKAN API Dataset では、Acquisition role も提供する必要があります。このロールは、バックエンドサービスへのアクセスを可能にするために IdM で顧客に付与されるロールであるため、ロールが存在し、データにアクセスするための適切な権限セットを定義する必要があります。

このプラグインは、次のイベントハンドラを実装しています:

on_pre_product_spec_validation: このハンドラでは、プラグインは提供された URL が有効なCKAN Dataset であること、およびプロダクト仕様を作成しているユーザが所有者であることを検証します
on_post_product_spec_validation: このハンドラでは、プラグインは、CKAN Dataset に含まれる API リソースが有効であること、そのサービスを提供するセラーの許可、および提供された取得ロールが存在し、有効であることを検証します
on_post_product_offering_validation: このハンドラでは、プラグインは、ペイ・パー・ユース・オファリング(pay-per-use offering)を作成する際に価格設定モデルがサポートされていることを検証します
on_product_acquisition: このハンドラでは、プラグインは CKAN インスタンス API を使用して、データセットを取得したユーザにアクセスを許可します
on_product_suspension: このハンドラでは、プラグインは CKAN インスタンス API を使用して、ユーザが支払いを行っていないとき、またはユーザがサブスクリプションをキャンセルしたときにデータセットへのアクセスを取り消します
get_pending_accounting: このハンドラでは、プラグインは、ペイ・パー・ユース価格モデルでデータへのアクセスが取得されたときに、保留中のアカウンティング情報を取得します

さらに、CKAN API Dataset では、いくつかの設定を展開してから展開する必要があります。この設定は、setting.py ファイルの中でできます :

AUTH_METHOD: バックエンドサービス、idm または umbrella によって使用される認証メカニズム
UMBRELLA_KEY: バックエンドサービスを保護するために使用する、API Umbrella インスタンスへのアクセスに使用されるAPIキー
UMBRELLA_ADMIN_TOKEN: バックエンドサービスを保護するために使用されるAPI Umbrella インスタンスへのアクセスに使用される管理トークン
KEYSTONE_USER: FIWARE IdM への要求の認証に使用される Keystone ユーザ
KEYSTONE_PASSWORD: FIWARE IdM への要求を認証するために使用される Keystone パスワード
KEYSTONE_HOST: 顧客の認可に使用される FIWARE IdM のキーストーンサービスのホスト

アカウンタブル・サービス¶

Accountable Service プラグインは、GitHub で入手できます。このプラグインは、ペイ・パー・ユース(pay-per-use)モデルでサービスを提供するために Accounting Proxy と共同で使用される一般的なアセット型を定義します。特に、このプラグインはサービスの URLs を検証し、セラー権限を検証し、アカウンティング・プロキシの API キーを生成し、オファリング価格モデルを検証し、提供されたサービスに対する顧客のアクセス権を管理することができます。

このプラグインがアカウンティング・プロキシのインスタンスと協調して動作することを考慮すると、Accountable Service 型を使用して登録されるすべてのアセットは、アカウンティング・プロキシのセクションで説明されているように、プロキシに登録する必要があります。

Accountable Service プラグインは、サービスに一致する必要がある URL だけをアセットに提供することを許可します。

このプラグインは以下のイベントハンドラを実装しています :

on_post_product_spec_validation: このイベントハンドラでは、プラグインは、指定された URL がアカウンティング・プロキシのインスタンスに登録されている有効なサービスに属していること、およびプロダクト仕様を作成しているユーザが所有者であることを検証します。さらに、このハンドラは、Accounting API を使用して Business API Ecosystem に課金情報を提供するときに使用される API キーを生成します
on_post_product_offering_validation: このイベントハンドラでは、プラグインは、サービスが販売される予定のプロダクト・オファリングの価格モデルを検証します。具体的には、顧客が選択できるすべての価格プランが使用モデルであり、単位(呼び出し回数、秒、MBなど)がアカウンティング・プロキシによってサポートされていることを検証します
on_product_acquisition: このイベントハンドラは、アカウント対象ユニット(選択された価格プラン)も含めて、プロキシに通知を送信してサービスを取得したユーザへのアクセスを許可するために使用されます
on_product_suspension: このイベントハンドラは、ユーザが支払をしていないとき、またはユーザがサブスクリプションをキャンセルしたときにサービスへのアクセスを取り消すために使用されます

アカウンティング・プロキシ¶

Accounting Proxy は、GitHub で入手できます。このソフトウェアは、Business API Ecosystem で提供されるサービスを管理するための NodeJs サーバです。特に、ユーザの認証、取得、URL、または使用されるHTTPメソッドに応じて特定のサービスへのアクセスを許可または拒否したり、サービスの使用量の状況を考慮したりして、ペイ・パー・ユースで料金を請求することができます。

このソフトウェアを導入することにより、サービス・オーナーは特定のサービスを変更することなく、サービスを保護し、Business API Ecosystem で提供することができます。

インストール¶

このソフトウェアは、純粋な NodeJS サーバであり、基本的な依存関係をインストールするには、次のコマンドを実行します :

$ npm install

コンフィグレーション¶

アカウンティング・プロキシの設定はすべて、プロジェクトのルートにある config.js ファイルに保存されます。

アカウンティング・プロキシを実行するには、以下の情報を入力する必要があります :

config.accounting_proxy: アカウンティング配備の基本情報
- https: HTTP 経由でサービスを開始するには、この変数を未定義に設定します
  
  enabled: このオプションを true に設定すると、HTTPS を介してサービスが開始され、一部の管理要求に対して証明書の検証が有効になります。Proxy API を参照してください
  
  certFile: PEM 形式のサーバ証明書へのパス
  
  keyFile: サーバの秘密鍵へのパス
  
  caFile: CA ファイルへのパス
- port: アカウンティング・サーバがリスニングしているポート

{
    https: {
        enabled: true,
        certFile: 'ssl/server1.pem',
        keyFile: 'ssl/server1.key',
        caFile: 'ssl/fake_ca.pem'
    },
    port: 9000
}

config.database: プロキシによって使用されるデータベース設定
- type: データベースタイプ。二つの可能なオプション : ./db (SQLiteデータベース)または、 ./db_Redis (Redisのデータベース)
- name: データベース名。データベースタイプselectがredisの場合、このフィールドはデータベース番号を選択します。0〜14です。15はテスト用に予約されています。
- redis_host: redis データベースのホスト
- redis_port: redis データベースのポート

{
    type: './db',
    name: 'accountingDB.sqlite',
    redis_host: 'localhost',
    redis_port: 6379
}

config.modules: さまざまな方法でアカウンティング用にサポートされているアカウンティング・モジュールの配列。可能なオプションは次のとおりです
- call: ユーザがリクエストを送信するたびにアカウンティングが1単位増加します
- megabyte: データのレスポンス量をメガバイト単位でカウントします
- millisecond: リクエストの継続時間をミリ秒単位でカウントします

{
    accounting: [ 'call', 'megabyte', 'millisecond']
}

他のアカウンティング・モジュールを実装してプロキシに含めることができます。Accounting modules を参照してください。

config.usageAPI: 使用量の仕様およびアカウンティング情報が送信される usage management API の情報
- host: Business API Ecosystem のホスト
- port: Business API Ecosystem のポート
- path: usage management API のパス
- schedule: アカウンティング情報を Business API Ecosystem に通知するためのデーモン・サービスのスケジュールを定義します。フォーマットは cron タブのフォーマットに似ています : “MINUTE HOUR DAY_OF_MONTH MONTH_OF_YEAR DAY_OF_WEEK YEAR (オプション)”。デフォルトでは、毎日 00:00 に使用量の通知が送信されます

{
    host: 'localhost',
    port: 8080,
    path: '/DSUsageManagement/api/usageManagement/v2',
    schedule: '00 00 * * *'
}

config.api.administration_paths: 管理パスの設定。デフォルトのアカウンティング・パスは次のとおりです :

{
    api: {
        administration_paths: {
            keys: '/accounting_proxy/keys',
            units: '/accounting_proxy/units',
            newBuy: '/accounting_proxy/newBuy',
            checkURL: '/accounting_proxy/urls',
            deleteBuy: '/accounting_proxy/deleteBuy'
        }
    }
}

アカウンティング・プロキシは、Orion Context Broker をプロキシするために使用でき、サブスクリプションのアカウンティングをサポートします。そのためには、次の設定パラメータが使用されます :

config.resources: プロキシによって占められるリソースの設定
- contextBroker: アカウントされたリソースが Orion Context Broker の場合、このオプションを true に設定します。それ以外の場合は、このオプションをfalse (デフォルト値) に設定します
- notification_port: アカウンティング・プロキシが Orion Context Broker (デフォルトでポート9002) からのサブスクリプション通知をリスンするポート

{
        contextBroker: true,
        notification_port: 9002
}

管理¶

アカウンティング・プロキシは複数のサービスを管理できます。この点で、管理者がサービスの登録、削除、および管理を行うために使用できる cli ツールが提供されています。使用可能なコマンドは次のとおりです :

./cli addService [-c | –context-broker] <publicPath> <url> <appId> <httpMethod> [otherHttpMethods…] : このコマンドは、アカウンティング・プロキシに新しいサービスを登録するために使用します。それは以下のパラメータを受け取ります
- publicPath : 外部ユーザがサービスを利用できるようにするパス。パブリック・パスの2つの有効なパターンがあります。 : (1) 単一のコンポーネント（/publicpath）でパスを指定すると、アカウンティング・プロキシは指定されたサブパスへの要求を受け入れます。つまり、/publicpath/more/path へのパブリックパス /publicpath 要求が受け入れられる。このパターンは、通常、複数のリソースを持つ API へのアクセスを提供する場合に使用されます。(2) 完全なパス (/this/is/the/final/resource/path?color=Blue&shape=rectangular) を指定すると、アカウンティング・プロキシはクエリ文字列を含む正確な登録済みパスへの要求のみを受け入れます。このパターンは、通常、Context Broker クエリーのように単一の URL を提供する場合に使用されます
- url : サービスが実際に実行されている場所とプロキシへのリクエストがリダイレクトされる URL。この場合、アカウンティング・プロキシが異なるサーバで実行されているサービスの管理を許可するため、ホストを含む、すべてのURLが提供されます
- appId : FIWARE IdM によって指定されたサービスの ID。この ID は、ユーザが提供するアクセストークンがアクセスされたサービスに対して有効であることを保証するために使用されます
- HTTP methods : 登録されたサービスにアクセスできる HTTP メソッドのリスト
- Options :
  
  -c, –context-broker: サービスは Orion Context broker サービスです。config.js では config.contextBroker を true に設定する必要があります

サービスの登録に使用できるオプションを明確にするために、次の2つの例があります :

$ ./cli addService /apacheapp http://localhost:5000/ 1111 GET PUT POST

この場合、/apacheapp パスを介して利用できるようになっているポート5000で実行されているサービスがあり、GET, PUT, POSTの HTTP 要求のみが許可されます。アカウンティング・プロキシがポート8000のホスト accounting.proxy.com で実行されていると仮定すると、次の要求が受け入れられます :

GET http://accounting.proxy.com:8000/apacheapp
GET http://accounting.proxy.com:8000/apacheapp/resource1/
POST http://accounting.proxy.com:8000/apacheapp/resource1/resource2

Note

アカウンティング・プロキシは、API または監視対象サービスのセマンティクスに配慮していないため、サービスに存在しない URL へのリクエストを受け付ける可能性があり、通常の 404 エラーが発生します

さらに、次の例のように、完全なパスを指定することもできます :

$ ./cli addService /broker/v1/contextEntities/Room2/attributes/temperature http://localhost:1026/v1/contextEntities/Room2/attributes/temperature 1111 GET

この例では、ポート1026で Context Broker が実行されており、アカウンティング・プロキシを介して特定のクエリを利用できるようになっているため、次の要求のみが受け入れられます :

GET http://accounting.proxy.com:8000/broker/v1/contextEntities/Room2/attributes/temperature

Note

完全なパスを提供するときに、外部パスと URL で同じパスを使用することは、プロキシを最終ユーザに透過的にすることを推奨します。それにもかかわらず、これは必須ではないので、クエリのエイリアスを作成することは可能です。前の例では /room2/temperature

./cli getService [-p <publicPath>]: このコマンドは、登録されているすべてのサービスのURL、アプリケーションID、およびタイプ (Context Brokerかどうか) を取得するために使用されます
- オプション:
  
  -p, –publicPath <path>: 指定されたサービスの情報のみを表示します
./cli deleteService <publicPath> : このコマンドは、パブリック・パスに関連付けられているサービスを削除するために使用します
./cli addAdmin <userId> : このコマンドは、新しい管理者を追加するために使用します
./cli deleteAdmin <userId> : このコマンドは、指定された管理者を削除するために使用されます
./cli bindAdmin <userId> <publicPath> : このコマンドは、指定された管理者をパブリック・パスで指定されたサービスに追加するために使用します
./cli unbindAdmin <userId> <publicPath> : このコマンドは、指定されたサービスの指定された管理者をパブリック・パスで削除するために使用します
./cli getAdmins <publicPath> : このコマンドは、指定したサービスのすべての管理者を表示するために使用します

cli ツールの簡単な説明を表示するには、./cli -h、または ./cli –help を使用します。さらに、特定のコマンドの情報を取得するには、./cli help [cmd] を使用します

認証と認可¶

アカウンティング・プロキシは、ユーザを認証するために FIWARE IdM に依存します。これを行うために、プロキシはすべての要求が、IdM によって与えられた有効なアクセストークンを持つヘッダ Authorization: Bearer access_token または X-Auth-Token: access_token を含むことを期待します。

さらに、認証プロセスが成功した場合、アカウンティング・プロキシは特定のサービスにアクセスするユーザのアクセス許可を検証します。これを行うために、ユーザがサービスの管理者として登録されているかどうか、またはユーザがサービスを取得したかどうかを確認します。

Business API Ecosystem は、セラーがさまざまな価格設定モデルを持つさまざまなオファリングでサービスを提供できるようにすることに注意することが重要です。これに関して、アクセストークンだけを有することは、サービスの使用を説明するために使用されなければならない課金単位(価格設定モデル)を決定するのには不十分です。有効なユーザが2つの異なるモデル(つまり呼び出し回数と秒)を持つ2つの異なるオファリングでサービスへのアクセスを取得したため、プロキシはアカウントの単位を決定するための追加情報が必要になることがあります(この例では呼び出し回数または秒) 。その問題に対処するために、アカウンティング・プロキシは、サービス、ユーザ、アカウンティング単位を識別する API キーを生成し、それをリクエストを行う際にヘッダ X-API-Key: api_key に含めることで、どの単位を考慮するか知ることとができます。

Note

X-API-Key ヘッダは、特別なレベルのセキュリティーを提供することを意図したものではありませんが、リクエストの周りの可能性のある予兆を取り除くことです

Proxy API¶

アカウンティング・プロキシはポート9000でデフォルトで実行されます。それにもかかわらず、このポートは コンフィグレーション のセクションで説明されているように設定できます。この点で、管理 cli ツールを使用して構成されたさまざまなサービスには、サービスに定義されているパブリック・パスを使用して、プロキシのルートに直接アクセスできます。

さらに、アカウンティング・プロキシには、予約パス /accounting_proxy を介してアクセスできる管理 API があります。次に、管理 API で公開されているさまざまなサービスを確認できます :

POST …/newBuy¶

このサービスは、Business API Ecosystem によって新しい購入を通知するために使用されます。アカウンティング・プロキシが HTTPS 経由で開始されている場合、これらのリクエストは Business API Ecosystem キーで署名する必要があります。さもなければ、それらは拒否されるでしょう。

{
   "orderId": "...",
   "productId": "...",
   "customer": "...",
   "productSpecification": {
       "url": "...",
       "unit": "...",
       "recordType": "..."
   }
}

orderId: オーダー ID
productId: 製品 ID
customer: 顧客 ID
url: サービスのベース URL
unit: 課金単位(メガバイト、呼び出し回数など)
recordType: アカウンティングのタイプ

POST …/deleteBuy¶

このサービスは、終了した購入を通知するために Business API Ecosystem によって使用されます。アカウンティング・プロキシが HTTPS 経由で開始されている場合、これらのリクエストは Business API Ecosystem キーで署名する必要があります。さもなければ、それは拒否されるでしょう。

{
   "orderId": "...",
   "productId": "...",
   "customer": "...",
   "productSpecification": {
      "url": "..."
   }
}

orderId: オーダー ID
productId: 製品 ID
customer: 顧客 ID
url: サービスのベース URL

POST …/urls¶

このサービスは、Business API Ecosystem が URL が有効な登録済みサービスであるかどうかをチェックするために使用されます。この要求には、IdMからの有効なアクセストークンを持つ “authorization” ヘッダーが必要であり、ユーザはサービスの管理者である必要があります。アカウンティング・プロキシが HTTPS 経由で開始された場合、これらのリクエストは Business API Ecosystem キー証明書で署名する必要があります。さもなければ、それらは拒否されるでしょう。

{
   "url": "..."
}

GET …/keys¶

JSON 内のユーザの API_KEY を取得します。この要求には、IdM からの有効なアクセストークンを持つ “authorization” ヘッダーが必要です。

[
        {
        "apiKey": "...",
        "productId": "...",
        "orderId": "...",
        "url": "..."
    },
    {
        "apiKey": "...",
        "productId": "...",
        "orderId": "...",
        "url": "..."
    }
]

GET …/units¶

サポートされている課金単位を JSON のアカウンティング・プロキシで取得します。この要求には、IdM からの有効なアクセストークンを持つ”authorization”ヘッダーが必要です。

{
        "units": ["..."]
}

アカウンティング・モジュール¶

デフォルトでは、アカウンティング・プロキシには3つの異なるアカウンティング・モジュールが含まれています。それにもかかわらず、新しいモジュールを acc_modules ディレクトリに作成することでプロキシを拡張することは可能ですが、それらのモジュールは次の構造を持たなければなりません :

/** Accounting module for unit: XXXXXX */

var count = function (countInfo, callback) {
    // Code to do the accounting goes here
    // .....

    return callback(error, amount);
}

var getSpecification = function () {
    return specification;
}

関数 count は2つのパラメータを受け取ります:

countInfo: ユーザが行ったリクエストとサービスによって返されたレスポンスの両方を含むオブジェクト

{
    request: { // Request object used by the proxy to make the request to the service.
        headers: {

        },
        body: {

        },
        ...
    },
    response: { // Response object received from the service.
        headers: {

        },
        body: {

        },
        elapsedTime: , // Response time
        ...
    }
}

callback : アカウンティング値またはエラーメッセージを取得するために使用される関数。コールバックには2つのパラメータが必要です :
- error : エラーの説明を含む文字列。そうでない場合は、null を設定してください
- amount : 現在の課金処理に追加する金額の数値

関数 getSpecification は TMF635 usage Management API に従ってアカウンティング単位の使用量の仕様を持つ javascript オブジェクトを返す必要があります

最後に、開発したアカウンティング・モジュールの名前を config.js ファイルの config.modules 配列に追加し、アカウンティング・プロキシを再起動します。アカウンティング・モジュール名はファイルの名前です(例 : megabyte と megabyte.js)。