ブログのシリーズの次のポスト （以前の記事はプラグインの UI テストを記述する方法） Piwik プラットフォームの機能を紹介します。今回は Reporting API を拡張する方法を学びます。このチュートリアルは、PHP の基本的な知識を持っている必要があります。

Piwik の Reporting API とは？

サード・パーティーアプリケーションが分析データにアクセスし、HTTP要求を通じて雑多なデータ（ユーザーやウェブサイトなどの）を処理することを可能にします。

どんな利点がありますか？

Piwik UI Reporting API を使用してレポート、ユーザー、管理を表示します。Piwik UI に機能を追加する場合は、このデータにアクセスする API メソッドを公開する必要があります。APIがHTTPを経て呼ばれると、どこからでも様々なPiwik関連データを取り出し、処理することを可能にします。これらの公開された API で大抵の要求は可能になります。例えば：

• 追加のデータによって既存のリポートを強化します
• カスタム ルールに基づいて既存のレポートのフィルター処理します
• データベースにアクセスし、カスタム レポートを生成
• 永続化および任意のデータを読み取る
• サーバーの情報を要求します

はじめに

この一連のポストにおいて、すでに開発環境を設定していたと仮定します。まだの場合は、Piwik デベロッパーゾーンへアクセスし、Piwik のセットアップチュートリアルとプラグイン開発ガイドを参照してください。

セットアップで行うことを要約すると：

• Piwikをインストール（例えば git を介して）
• 開発者モードをアクティブに: ./console development:enable
• プラグインを生成: ./console generate:plugin --name="MyApiPlugin"フォルダーを plugins/MyApiPlugin にする必要があります
• 作成したプラグインを有効にする：./console plugin:activate "MyApiPlugin"

API を作成してみましょう

まず Piwik コンソールを使用して新しい API を作成します:

./console generate:api

コマンドは作成された API に属するプラグインの名前を入力するように求められます。ここでは、上記の使用が選択したプラグインの名前”MyApiPlugin”。今すぐ簡単に開始するために、既に plugins/MyApiPlugin/API.php が置かれています:

class API extends \Piwik\Plugin\API
{
    public function getAnswerToLife($truth = true)
    {
        if ($truth) {
            return 42;
        }

        return 24;
    }

    public function getExampleReport($idSite, $period, $date, $wonderful = false)
    {
        $table = DataTable::makeFromSimpleArray(array(
            array('label' => 'My Label 1', 'nb_visits' => '1'),
            array('label' => 'My Label 2', 'nb_visits' => '5'),
        ));

        return $table;
    }
}

そのファイル内のすべてのパブリック メソッドは Reporting API を介して使用可能になります。たとえばメソッドgetAnswerToLife は、この URL 経由で呼び出すことができます：
index.php?module=API&method=MyApiPlugin.getAnswerToLife URL パラメーター Methodはプラグイン名とこのクラス内のメソッド名の組み合わせです。

メソッドにパラメーターを渡す

両方の方法の例をいくつかのパラメーターを定義します。どのような値でもあなたの方法のパラメータに手渡すことによりそれらはURLの名前によって単に指定されます。たとえば...&method=MyApiPlugin.getExampleReport&idSite=1&period=week&date=today&wonderful=1 メソッド getExampleReport のパラメーターに値を渡します。

値を返す

API メソッドに任意のブール値、数値、文字列または配列の値を返すことができます。DataTable (Piwik の analytics のデータを格納に使用されるプライマリ データ構造)、DataTable\Map (Datatable のセットを格納する) 、DataTable\Simple （DataTable のすべての行に 2 つの列：ラベルと値)など DataTableInterface を実装していない限りリソースまたはオブジェクトを返すことはできません。

ご存知ですか？パラメーター &format=JSON|XML|CSV|... への URL を追加して、API 要求の応答形式を選択できます。詳細はレポート API リファレンスをご覧ください。

ベスト・プラクティス

ユーザーのアクセス許可を確認

ユーザーが実際にデータへのアクセスまたは操作を実行するアクセス許可があるかどうかを確認することを忘れないでください。詳しくはPiwik のアクセス許可およびユーザー権限ガイドきを読んで確認してください。

API メソッドを小さく保つ

Piwikチームの目標はクリーンなコードを記述する事です。したがって、API メソッドを小さく保つためにお勧めします。（懸念の分離）APIは大抵、コントローラーのように動作します：

public function createLdapUser($idSite, $login, $password)
{
    Piwik::checkUserHasAdminAccess($idSite);
    $this->checkLogin($login);
    $this->checkPassword($password);
    
    $myModel = new LdapModel();
    $success = $myModel->createUser($idSite, $login, $password);
    
    return $success;
}

これは読みやすく、また (Piwik レイヤー全体をブートストラップすることがなく) LdapModel 用の簡単なテストを作成でき、必要な場合は他の場所で再利用することができます。

他のプラグインの Api を呼び出す

例えば、別のプラグインから既存のレポートを取得する場合は、すべてのページの Url のリストと言う、そのメソッドを直接呼び出すことによってこのレポートを要求しません。\Piwik\Plugins\Actions\API::getInstance()->getPageUrls($idSite, $period, $date);代わりに、新しい API 要求を発行しています。

$report = \Piwik\API\Request::processRequest('Actions.getPageUrls', array(
    'idSite' => $idSite,
    'period' => $period,
    'date'   => $date,
));

これはいくつかの利点があります。

• 要求されたプラグインが Piwik のインストールで使用できない場合、致命的なエラーを回避します。
• 他のプラグインはイベント（追加のレポート データをレポートに追加する、追加のアクセス許可チェックを行う） を介して呼び出された API メソッドを拡張できますが、それらのイベントとして推奨されるレポートを要求するときのみトリガーされます。
• メソッドのパラメーターを変更する場合、あなたの要求は恐らくまだ働くでしょう

マーケットプ レースでプラグインを公開

GitHub のリポジトリにプラグインをプッシュしてタグの作成することで、他の Piwik のユーザーとページを共有できます。とても簡単です。プラグインを配布する方法については、こちらをご覧ください。

APIの作成は難しいですか？私たちも、ファイルを作成したことはありません！API または Piwik デベロッパーゾーンの手順に関してのフィードバックもお気軽にお寄せ下さい。

Thomas Steur