プログラマ・ガイド¶

イントロダクション¶

このプログラマ・ガイドは、FIWARE release 6 に対応する Business API Ecosystemversion 6.4.0 をカバーしています。バグ、タイプミス、または含まれてはいけないと思われる事柄を含め、このドキュメントに対するフィードバックは非常に歓迎されます。この GEi のカタログページに表示される”担当者”の電子メールにそれらを送信してください。または、GitHub Issues で問題を作成してください。

Business API Ecosystem では、あらゆる種類のデジタル・アセットを提供できます。これに関して、ある種のデジタル・アセットは、アセットのフォーマットを知ることを必要とする特定のアクションおよび検証を実行する必要がありえます。この問題に対処するために、Business API Ecosystem では、プラグインを作成してアセットの種類を登録することができます。このセクションでは、これらのプラグインの作成方法について説明します。

さらに、Business API Ecosystem は、独自のソリューションで提供される収益化機能を統合するために、開発者が使用できる API を公開しています。この API の完全な説明は、次の場所にあります :

プラグイン・パッケージ¶

Business API Ecosystem プラグインは、zip 形式でパッケージ化する必要があります。このファイルには、プラグインのすべてのソースと、zip のルートにある package.json という設定ファイルが含まれます。この設定ファイルでは、プラグインの動作のいくつかの側面を指定することができ、次のフィールドがあります :

name: リソース型に与えられた名前。これはプロバイダに表示されるフィールドです
author: プラグインの作者
formats: 指定された型のアセットを提供するために許可されるさまざまなフォーマットを指定するリスト。このリストには、”URL” および “FILE” という値を含めることができます
module: このフィールドは、プラグインのメインクラスを指定するために使用されます
version: プラグインの現在のバージョン
media_types: 指定された型のアセットを提供するときに選択できる許可されたメディア型のリスト
pull_accounting (オプション): このフラグは、プラグインによって定義されたサービスが Business API Ecosystem の使用 API に課金情報をプッシュしていないことを示すために使用されますが、この情報を取得するために照会する必要がある API を公開します
form (オプション): このフィールドは、アセット固有のメタデータを取得するために表示されるカスタムフォームを定義するために使用されます。このフィールドはオブジェクトとして定義され、キーはメタデータプロパティの名前であり、値は次の情報を定義します
- type: 特定のメタデータ・プロパティーのタイプ。指定できる値は、データを取得するために表示されるフォームの入力タイプをマッピングする text, textarea, checkbox と select です
- label: フォーム入力と一緒に表示されるラベル
- default: プロパティに値が指定されていない場合に使用されるデフォルト値
- placeholder (テキストとテキストエリア): フォーム入力に含めるプレースホルダ
- options (選択): 入力が選択の場合に有効なオプションのリスト。各エントリの テキスト と値が含まれます

次は、package.json ファイルの例です :

{
    "name": "Test Resource",
    "author": "fdelavega",
    "formats": ["FILE"],
    "module": "plugin.TestPlugin",
    "version": "1.0",
    "media_types": ["application/zip"],
    "form": {
        "auth_type": {
            "type": "select",
            "label": "Auth type",
            "options": [{
                "text": "OAuth2",
                "value": "oauth2"
            }, {
                "text": "API Key",
                "value": "key"
            }]
        },
        "token_required": {
            "type": "checkbox",
            "label": "Token required?",
            "default": true
        },
        "auth_server": {
            "type": "text",
            "label": "Auth Server",
            "placeholder": "https://authservice.com/auth"
        }
    }
}

プラグインのソースコードは Python で記述する必要があり、Business API Ecosystem の Charging Backend で定義されている Plugin クラスの子クラスになるメインクラスを含まなければなりません。プラグインのメインクラスの例を次に示します

from wstore.asset_manager.resource_plugins.plugin import Plugin

class TestPlugin(Plugin):
    def on_pre_product_spec_validation(self, provider, asset_t, media_type, url):
        pass

    def on_post_product_spec_validation(self, provider, asset):
        pass

    def on_pre_product_spec_attachment(self, asset, asset_t, product_spec):
        pass

    def on_post_product_spec_attachment(self, asset, asset_t, product_spec):
        pass

    def on_pre_product_spec_upgrade(self, asset, asset_t, product_spec):
        pass

    def on_post_product_spec_upgrade(self, asset, asset_t, product_spec):
        pass

    def on_pre_product_offering_validation(self, asset, product_offering):
        pass

    def on_post_product_offering_validation(self, asset, product_offering):
        pass

    def on_product_acquisition(self, asset, contract, order):
        pass

    def on_product_suspension(self, asset, contract, order):
        pass

    def get_usage_specs(self):
        return []

    def get_pending_accounting(self, asset, contract, order):
        return [], Date()

イベントハンドラの実装¶

前のセクションでは、プラグインのメインクラスが、Charging Backend Plugin クラスから継承されたいくつかのメソッドを実装できることが分かりました。このメソッドは、アセットを含むプロダクトのライフサイクルのさまざまなイベントのハンドラを実装するために使用できます。具体的には、以下のイベントが定義されています

on_pre_product_spec_validation: このメソッドは、指定された型のアセットを含む新しいデジタルプロダクトを作成するとき、プロダクト仕様の内容を検証し、アセット情報をデータベースに保存する前に実行されます。このメソッドは、アセットを販売するためのアセット形式またはセラー権限を検証するために使用できます
on_post_product_spec_validation: このメソッドは、指定された型のアセットを含む新しいデジタルプロダクトを作成するときに、プロダクト仕様を検証し、アセット情報をデータベースに保存した後に実行されます。このメソッドは、プラグインがアセットモデルの特定の情報を知る必要がある場合に使用できます
on_pre_product_spec_attachment: このメソッドは、プロダクト仕様を catalog APIデータベースに保存した後、プロダクト仕様 ID をアセットモデルに添付する前に、指定された型のアセットを含む新しいデジタルプロダクトを作成するときに実行されます。このメソッドは、プラグインがプロダクト仕様のカタログ内の ID を知る必要がある場合に使用できます
on_post_product_spec_attachment: このメソッドは、指定された型のアセットを含む新しいデジタルプロダクトを catalog APIデータベースに保存した後で、プロダクト仕様 ID をアセットモデルに添付した後に、実行されます。このメソッドは、プラグインがプロダクト仕様のカタログ内の ID を知る必要がある場合に使用できます
on_pre_product_spec_upgrade: このメソッドは、デジタルプロダクトがアップグレードされているときに実行されます(新しいバージョンのアセットが提供されています)。この方法は、アップグレードを保存する前に新しいデジタルアセットを検証するために使用できます
on_post_product_spec_upgrade: このメソッドは、デジタルプロダクトがアップグレードされたときに実行されます。このメソッドを使用すると、通知を送信したり、プロダクト仕様の新しい情報を取得したりすることができます
on_pre_product_offering_validation: このメソッドは、プライスモデルを検証する前に、指定された型のアセットを含む新しいプロダクトのオファリングを作成するときに実行されます。この方法を使用して、プライスモデルで追加の検証を行うことができます。たとえば、使用モデルのユニットが特定のアセットによってサポートされているかどうかを確認できます
on_post_product_offering_validation: このメソッドは、プライスモデルを検証した後に、指定された型のアセットを含む新しいプロダクトのオファリングを作成するときに実行されます。この方法を使用して、プライスモデルで追加の検証を行うことができます。たとえば、使用モデルのユニットが特定のアセットによってサポートされているかどうかを確認できます
on_product_acquisition: このメソッドは、指定された型のアセットを含むプロダクトが取得されたときに呼び出されます。このメソッドを使用して、顧客のサービスをアクティブ化し、アクセス権を与えることができます
on_product_suspension: このメソッドは、指定された型のアセットを含むプロダクトが顧客に対して中断された場合(例えば、支払っていない場合など)に呼び出されます。Tjis メソッドを使用して、顧客のサービスを一時停止し、アクセス権を削除することができます
get_usage_specs: このメソッドは、pull_accounting フラグが true に設定されている場合に実装し、サービスが監視できる使用量の仕様のリストを返す必要があります。各使用量の仕様について、名前と説明を提供する必要があります(例、名前 : API Call、説明 : 呼び出し回数…)
get_pending_accounting: このメソッドは、pull_accounting フラグが true に設定されている場合に実装する必要があります。このメソッドは、提供する契約の保留中のアカウンティング情報を取得するために、プラグインが定義しているサービスにアクセスできるクライアントを実装する必要があります。次のような保留中のアカウンティングのリストを返さなければなりません :
- date: 会計記録のタイムスタンプ
- unit: 監視対象ユニット
- value: 顧客の実際の使用量

Plugin の例で分かるように、さまざまなハンドラメソッドは、関連する情報とオブジェクトとともにいくつかのパラメータを受け取ります。特に :

on_pre_product_spec_validation¶

provider: プロダクト仕様を作成しているユーザを含むユーザオブジェクト。ユーザオブジェクトについては後で説明します
asset_t: アセット型を含む文字列。package.jsonに定義されているものと等しくなければなりません
media_type: 作成されるプロダクトに含まれるアセットのメディアタイプを含む文字列
url: 作成されるプロダクトに含まれるアセットの URL を含む文字列

on_post_product_spec_validation¶

provider: プロダクト仕様を作成しているユーザを含むユーザオブジェクト。ユーザオブジェクトについては後で説明します
asset: 最近作成されたアセットを持つアセットオブジェクト。アセットオブジェクトについては後で説明します

on_pre_product_spec_attachment¶

asset: 作成されたプロダクト仕様 ID がアタッチされるアセットオブジェクト
asset_t: アセット型を含む文字列。package.json に定義されているものと等しくなければなりません
product_spec: 添付ファイルに使用される未処理のプロダクト仕様情報を含む JSON。この JSON オブジェクトの構造は Open Api のドキュメントにあります

on_post_product_spec_attachment¶

asset: 作成されたプロダクト仕様 ID がアタッチされているアセットオブジェクト
asset_t: アセット型を含む文字列。package.json に定義されているものと等しくなければなりません
product_spec: 添付ファイルに使用された未処理のプロダクト仕様情報を含む JSON。この JSON オブジェクトの構造は Open Api のドキュメントにあります

on_pre_product_spec_upgrade¶

asset: アップグレードされたアセットオブジェクト
asset_t: アセット型を含む文字列。package.json に定義されているものと等しくなければなりません
product_spec: アップグレードに使用される未処理のプロダクト仕様情報を含む JSON。この JSON オブジェクトの構造は Open Api のドキュメントにあります

on_post_product_spec_upgrade¶

asset: アップグレードされたアセットオブジェクト
asset_t: アセット型を含む文字列。package.json に定義されているものと等しくなければなりません
product_spec: アップグレードに使用された未処理のプロダクト仕様情報を含む JSON。この JSON オブジェクトの構造は Open Api のドキュメントにあります

on_pre_product_offering_validation¶

asset: 作成されるオファリングに含まれるアセットオブジェクト
product_offering: 有効なプロダクト情報を提供する JSON。この JSON オブジェクトの構造はOpen Api のドキュメントにあります

on_post_product_offering_validation¶

asset: 作成されるオファリングに含まれるアセットオブジェクト
product_offering: 検証された未処理のプロダクト情報を提供する JSON。この JSON オブジェクトの構造は Open Api のドキュメントにあります

on_product_acquisition¶

asset: 取得されたアセットオブジェクト
contract: アセットを含む取得したオファリングの情報を含む契約オブジェクト。契約オブジェクトについては後で説明します
order: アセットが取得された注文の情報を含む注文オブジェクト。注文オブジェクトについては後で説明します

on_product_suspension¶

asset: 中断されたアセットオブジェクト
contract: アセットを含む取得したオファリングの情報を含む契約オブジェクト
order: アセットが取得されたオーダーの情報を含むオーダーオブジェクト

get_pending_accounting¶

asset: 使用量の情報を取得する必要があるアセットオブジェクト
contract: アセットを含む取得したオファリングの情報を含む契約オブジェクト
order: アセットが取得されたオーダーの情報を含むオーダーオブジェクト

ハンドラ・オブジェクト¶

次に、プラグインハンドラで使用されるさまざまなオブジェクトに関する情報を見つけることができます

User: 次のフィールドを持つ Django モデルオブジェクト
- username: ユーザのユーザ名
- email: ユーザの電子メール
- complete_name: ユーザの完全な名前
Asset: 次のフィールドを持つ Django モデルオブジェクト
- product_id: アセットを含むプロダクト仕様の Id
- version: アセットを含むプロダクト仕様のバージョン
- provider: アセットを作成したユーザのユーザオブジェクト
- content_type: アセットのメディアタイプ
- download_link: 外部サーバのサービスである場合のアセットの URL
- resource_path: アセットファイルがサーバにアップロードされている場合のアセットファイルへのパス
- resource_type: 関連するプラグインの package.json ファイルで定義されているアセットのタイプ
- is_public: true の場合、アセットを取得することなく任意のユーザがアセットをダウンロードできます
- meta_info: 関連情報を含む JSON。このフィールドは、プラグインコードの特定の情報を含めるのに便利です

さらに、以下のメソッドが含まれています :

get_url: アセットにアクセスできる URL を返します
get_uri: アセット情報にアクセスできる URL を返します
Contract: 次のフィールドを持つ Django モデル
- item_id: 現在の契約を生成した注文アイテムの Id
- offering: 現契約で取得したオファリングの情報をオブジェクトに提供します。オファリングオブジェクトについては後で説明します
- product_id: 指定されたオファリングの取得が結果として作成されたインベントリ・プロダクトの Id
- pricing_model: 提供されたオファリングを取得した顧客に課金するために現在の契約で使用されている価格モデルの JSON
- last_charge: 顧客に最後に請求された日付と時刻の日時オブジェクト
- charges: 現在の契約のコンテキストでチャージされたさまざまな時間の情報を含むチャージオブジェクトのリスト
- correlation_number: 使用量のドキュメントの次の相関関係番号。このフィールドは、プライス設定モデルが使用量である場合にのみ使用されます
- last_usage: 受け取った最後の使用量のドキュメントの日付と時刻を持つ日時オブジェクト。このフィールドは、プライス設定モデルが使用量である場合にのみ使用されます
- revenue_class: 収益分配のための関連商品のプロダクトクラス
- terminated: 契約が終了したかどうかを指定します。顧客は取得したアセットにアクセスできなくなりました
Offering: 次のフィールドを持つ Django モデル
- off_id: プロダクト・オファリングの Id
- name: オファリングの名前
- version: オファリングのバージョン
- description: オファリングの説明
- asset: オファリングで提供されるアセット
Charge: 次のフィールドを持つ Django のモデル
- date: 日付と時刻を指定した日時オブジェクト
- cost: 請求総額
- duty_free: 税金なしで請求される金額
- currency: チャージの通貨
- concept: 料金の概念 (initial, renovation, usage)
- invoice: 請求書を含む PDF ファイルへのパス
Order: 次のフィールドを持つ Django モデル
- order_id: 商品注文の Id
- customer: 注文の顧客のユーザオブジェクト
- date: 注文作成日時の日時オブジェクト
- tax_address: 顧客が注文した請求先住所の JSON
- contracts: 契約オブジェクトのリスト、注文で取得された各オファリングに1つ

さらに、以下のメソッドが含まれています:

get_item_contract: item_id が与えられた契約を返します
get_product_contract: product_id が指定された契約を返します

プラグインの管理¶

プラグインが zip ファイルにパッケージされると、Business API Ecosystem のバックエンドには、プラグインの管理に使用できる管理コマンドがいくつか用意されています。

新しいプラグインが登録されると、Business API Ecosystem によって、そのプラグインを管理するために使用されるプラグインの ID が自動的に生成されます。新しいプラグインを登録するには、次のコマンドを使用します :

python manage.py loadplugin TestPlugin.zip

生成された ID を取得するために、既存のプラグインをリストすることもできます :

python manage.py listplugins

プラグインを削除するには、プラグイン ID を指定する必要があります。これは、次のコマンドを使用して実行できます :

python manage.py removeplugin test-plugin