ネクストエンジンAPI - はじめに

ネクストエンジンAPI - はじめに

ここでは、ネクストエンジンAPIクライアントの

アクセストークンとリフレッシュトークンに関連する処理について説明いたします

ネクストエンジンAPIクライアントクラスが記述されているファイルは、

fuel/packages/nextengine/classes/nextengine以下となります

アクセストークンのリフレッシュ

リフレッシュトークンについては、APIのドキュメントの「利用方法：SDKを利用する方
」を御覧下さい

上記リンクにあるように、

ネクストエンジンAPIクライアントのアクセストークンとリフレッシュトークンは自動的に更新されるため、

それらが更新された時に、DBが持っているアクセストークンとリフレッシュトークンも更新しなければなりません

そのため、APIクライアントクラスでは以下の様な処理をapiExecuteに加えています

記述されているファイルは、fuel/packages/nextengine/classes/nextengine/client.phpです

    /**
     * ネクストエンジンAPIを叩く
     * 
     * ### 親クラスからの拡張点
     * - userプロパティがセットされており、アクセストークンが更新されたら自動でDBの値を更新する
     * - レスポンスに含まれるresultフィールドの値がsuccessでないなら、例外をスローするという処理を追加した
     *
     * @throws NextengineApiException
     * @return mixed APIのレスポンス詳しくはhttp://api.next-e.jp/request_url.phpを参照
     */
    public function apiExecute($path, $api_params = array(), $redirect_uri = NULL) {
        $before_exec_access_token = $this->_access_token;
        $response = parent::apiExecute($path, $api_params, $redirect_uri);

        // NOTE: エラーの種類については→を参照：http://api.next-e.jp/message.php
        //       エラー時の振る舞いについては、本クラスのfailoverメソッドを参照
        if($response['result'] !== self::RESULT_SUCCESS) {
            $this->failover($response['code'], $response['message']);
        }

        // APIを叩く前後でアクセストークンが変わっていたら、ユーザモデルを更新してDBに反映、セッションも更新する
        // ユーザモデルが格納されていない場合もあるため、その場合は処理しない
        if(!is_null($this->user) && ($before_exec_access_token !== $this->_access_token)) {
            $this->user->access_token  = $this->_access_token;
            $this->user->refresh_token = $this->_refresh_token;
            $this->user->save();

            $user_key = \Config::get('session.keys.ACCOUNT_USER');
            \Session::set($user_key, $this->user);
        }

        return $response;
    }

「エラー時の振る舞い」と書かれている箇所については後述します

parent::apiExecute()を実行する前にアクセストークンを保存しておき、

親クラスのapiExecuteを実行した前後でアクセストークンの値が変更されていたら、

セットされているModel_Userのインスタンスを通じて、DBに保存されているアクセストークンとリフレッシュトークンを更新します

つまり、このネクストエンジンAPIクライアントを使用している限り、

アクセストークンやリフレッシュトークンの更新について気を配る必要はありません

---

APIレスポンスのエラー処理

次に、APIからのレスポンスにエラー情報が含まれていた場合に、

それを例外へ変換する処理について説明いたします

ネクストエンジンAPIのレスポンスに含まれるエラーと原因一覧は、

APIのドキュメントを御覧下さい

これらのエラー情報がレスポンスに含まれていた場合、

ネクストエンジンAPIクライアントクラスは例外(Nextengine\Api\NextengineApiException)をスローします

その例外をキャッチし、開発者やネクストエンジンの営業へ通知メールを飛ばす必要がある例外

（料金未払いによる利用停止やシステムエラーなど）だった場合には、通知メールを送信します

まずは例外をスローしているメソッドについて説明いたします

該当ファイルは、先ほどと同じくfuel/packages/nextengine/classes/nextengine/client.phpです

    /**
     * ネクストエンジンAPIからエラーが返っていた場合の処理する
     * @param  string $code    NextengineApiExceptionに渡すエラーコード
     * @param  string $message NextengineApiExceptionに渡すエラーメッセージ
     * @return void
     * @throws NextengineApiException
     */
    protected function failover($code, $message) {
        // NOTE: ログにログレベルERRORで書き込む
        $log = '['.$code.']'.$message;
        \Log::error($log);

        // 開発者にメール送信
        $this->reportToDeveloper($code, $message);

        // 受け取ったコード、メッセージを例外としてスローする
        try {
            throw new NextengineApiException($message, $code);
        } catch(NextengineApiException $e) {
            switch($e->getCode()) {
                // 支払い等の理由で利用停止、システムエラー => 営業に問い合わせて下さい画面へリダイレクト
                case '001007':  // [xxxxx]様のネクストエンジンが、次の理由により利用停止になっています[xxxxx]
                case '002003':  // [xxxxx]様のネクストエンジンが、次の理由により利用停止になっています[xxxxx]
                case '003003':  // [xxxxx]様のメイン機能が、利用停止です
                    $this->reportToSales($code, $message);
                    break;
            }

            // NOTE: 握りつぶさずにスローしなおす
            throw $e;
        }
    }

このfailoverメソッドは、先ほどのapiExecuteメソッド内でコールされます

メソッド内部でreportToDeveloper, reportToSalesメソッドがコールされていますが、

単にメールを送信するだけのユーティリティのため、詳細は割愛します

また、このクラスを継承したクラスで更に例外処理を分岐させるために、キャッチした例外を再度スローしています

具体的な使用例は、Client_Routerクラスを御覧下さい

---

次に、通知メールの送信先の設定について説明いたします

fuel/app/config/nextengine.phpを御覧下さい

return array(
    'client_id' => '2zG7d5MjXPh4m8',
    'client_secret' => 'FTNubmlpyAgE5e3BnqWt6IHJ18voxVkMS9Yh4Zjc',
    'redirect_uri' => 'https://localhost:8443/ne-base/auth/callback',

    'debug' => array(
        // デバッグや通知メールの送信先(開発者)
        'developer'     => array(
            'xxxxxxxxxx@hamee.co.jp',
        ),

        // デバッグや通知メールの送信先(営業)
        'sales' => array(
            'xxxxxxxxxx@hamee.co.jp',
        ),

        'mail_subject' => "[NE-API] NextengineApiException"
    )
);

この設定ファイルのdebugの中に、通知メールの送信先を設定することができます

送信先は複数設定することができます

debugの中に含まれている各キーの説明をいたします

キー名	型	説明
developer	string[]	通知メールの送信先(開発者)
sales	string[]	通知メールの送信先(営業)
mail_subject	string	通知メールの件名

developerに設定されたメールアドレスには、例外が発生した時必ずメールを送信します

salesに設定されたメールアドレスには、支払い等の理由で利用停止やシステムエラーのときのみ通知メールを送信します

---

更新履歴

• 2015/02/17: ネクストエンジンAPI - はじめにページ作成