Slim フレームワークの REST による FileMaker データベースへのアクセス

　FileMaker では API for PHP、FX.php、XML、ODBC を介して Webプログラミングを行うのが通常ですが、昨今巷で REST なる言葉を聞くようになりました。　そこで今回は REST を使用した FileMaker DB アクセスにトライしてみました。

　開発環境は以下のとおりです。

Slim フレームワークを使った REST 構成で FileMaker Server にアクセス

　ご覧のように、Microsoft IIS Web サーバに FileMaker Server 15 と PHP をインストールしたうえで、 Slim フレームワークをインストールしています。

REST についてモヤモヤっとしがちなところ

　REST （REpresentational State Transfer）とは、サーバ上の情報（リソース）に対し、一意の URI を提供するためのアーキテクチャ（仕組み）です。
　この一意の URI と、Web クライアントから渡ってきた HTTP メソッドの組み合わせにより、リソースを操作します。

メソッド	処理
GET	取得。idempotent
POST	新規作成。not idempotent
PUT	更新。idempotent
DELETE	削除。idempotent (限定的)

　表中の idempotent は冪等（べきとう）性を指します。これは、何度操作しても同じ結果が返ってくるという意味です。これはステートレスという、REST の特徴になっています（ステートレスについては後述します）。

　idempotent について例を簡単に示します。

　GET メソッド --- Amazon でたとえば PlayStation 4 Pro という商品の情報を得るためのGET リクエストは、https://www.amazon.co.jp/dp/B01LRHPUZ4/　です。

　これは固有の URI として一般公開されているため、Web ユーザがこの URI に何度アクセスしても、このリンクが存在するかぎりは同じ商品にたどりつくことを意味します。よって、この処理は idempotent （冪等性がある）となります。

　POST メソッド --- Amazon の例でたとえると、出品者が Amazon に商品情報を追加したいときの URI は専用のものを使いますが、その URI だけでは、追加された商品（リソース）にたどりつくことができません。
このため、この URI そのものはリソースの一意性を保障できないため、not idempotent （冪等性がない）となります。

　PUT メソッド --- 特定のリソースを更新しますので、この URI は idempotent （冪等性がある）となります。

　DELETE メソッド --- 削除処理が完了するまでの間はリソースの URI は有効なため、 idempotent （冪等性がある）ですが、削除が完了するとそのリソース自体が消滅するため、not idempotent （冪等性がない）になります。これが限定的に idempotent とな理由です。

　アクション部分は HTTP メソッドで指定し、URI 各項目を名詞で表現するというルールを実装することによって、URI の一意性がもたらされます。
　また、実際の操作を実行するファイル名や引数名の隠匿性も高くなります。

ステートレスとステートフル

　REST の特徴としてステートレスな通信であることが挙げられます。
　しかし、Web アプリケーションの目的によっては、ステートレスですべての要求がまかなえない、つまり REST だけではシステム設計に無理が出てくることもあります。

　以下に例を示します。

　ニュースサイトでニュースを見るとき、見たいニュースのリンクをクリックすると、ニュースの内容が表示されたら処理は完結します。ユーザが今の時点までどんなニュースを見てきたかという処理の流れについてはサーバは関知しません。このような通信はステートレスであるといいます。

　ユーザが条件を指定するというパターンでは、Google Map サービスが良い例となるでしょう。
　住所を入力すれば、その住所の地図が即座に表示されますが、Web サーバはユーザとのやり取りを保持しません。しがたって、この通信もステートレスです。

　それでは、オンラインでショッピングカートに入れた商品を買う場合はどうでしょうか？
　ユーザは購入内容の確認からクレジットカード決済の処理にいたるまでの一連の処理をサーバと対話形式で行っていく必要がありますね。処理が完了するまで、サーバはユーザとのやりとりを保持しますので、この通信はステートフルになります。

REST に関する参考リンク：

REST [WikiPedia]
CHAPTER 5 Representational State Transfer (REST) [REST を提唱したロイ・フィールディングの博士論文] 英語

Slim フレームワークを使った REST 環境の構築

　Slim フレームワークは、REST 対応の軽量 PHP フレームワークです。
　HTTP メソッド別の処理のルーティングがあらかじめ想定されているため、比較的少ないコード量でデータベースアクセスルールと応答処理の実装ができます。

　インストール方法は公式サイトをご覧ください。

　Slim フレームワーク公式サイト[英語]

Microsoft IIS 向け REST 構成のためのルート URL 書き換え

　Apache の .httaccess 書き換え方法は割といろいろなところで見つかりますが、IIS 向けの情報があまりないようですので、まとめてみました。
　
　たとえば、Web アプリケーションのルートディレクトリが inventory のとき、出庫ID=123 の商品を照会するための index.php へのアクセスはこのようになるでしょう。

　http://hostname/inventory/index.php?act=outgoing&id=123

　REST 構成の URI は、スラッシュで文字列を区切った形式となります。
　このため、GET リクエストを発行するユーザに提供する URI は以下のようになります。

　http://hostname/inventory/outgoing/123

上記の赤色の URI は、本来は http://hostname/inventory/index.php ですが、これを http://www.hostname/inventory/ と書き換えることによって、ユーザに index.php ファイルを通知しないようにするとともに、後続のスラッシュで区切られた文字列をそのまま index.php に通知するように URLを書き換える必要があります。

　 http://hostname/inventory/index.php
　↓
　 http://hostname/inventory/

【操作手順】

あらかじめ、ユーザに公開する inventory ディレクトリを wwwroot 配下に作成しておきます。
Windows Server のインターネットインフォメーションサービス（IIS）マネージャを起動します。
左ペインで、ユーザに公開する inventory までディレクトリを展開し、「URL書き換え」アイコンをダブルクリックします。

inventory ディレクトリの「URL書き換え」アイコンをダブルクリック

　「URL 書き換え」ペインが表示されますので、右ペインのメニュー項目より「規則の追加...」リンクをクリックし、「受信規則と送信規則」のセクションの中から[ユーザフレンドリ URL]を選択して“OK”ボタンをクリックします。

ユーザーフレンドリ URL を選択
「ユーザーフレンドリ URL を有効にする規則の追加」ダイアログが表示されますので、[動的 Web アプリケーションで使用される内部 URL の例を入力してください]のボックスに、index.php への URL をフルで入力します。
たとえば、下図のように入力します。

[Web サイト訪問者のブラウザーに表示される、タイプするパブリック URL の例を選択してください]の項目は、ここでは無視してください。
受信規則の URL 書き換えリストに、前述の規則が追加されます。この規則をダブルクリックします。

今追加した規則をダブルクリック

URL 書き換えの詳細ペインが表示されます。
[パターン(T)]のボックスには、^inventory/index.$ という記述になっていますが、これを ^(.*) という記述に書き換えます。

受信規則のパターンの書き換え

　つぎに、画面下部の「アクション」のセクションで、URL書き換えの不要な文字列を取り除きます。現在、inventory/index.php という記述になっていますが、これを index.php という記述に変更します。

アクション URL の書き換え

ここまで終わったら、右ペインの「適用」リンクをクリックすることによって、修正を反映させます。
この規則は、inventory ディレクトリの中に、web.config という xml 形式のファイルで保存されます（ Apache でいう .htaccess ファイルに相当するファイルです）。
アクセステストしてみましょう。

ためしに、Hello World! と記述した html ファイルを index.php という名前で保存し、inventory ディレクトリに配置します。

このファイルに、以下のリンクパターンでアクセスしてみましょう。

http://hostname/inventory/
http://hostname/inventory/outgoing/
http://hostname/inventory/outgoing/123

このように、各パラメータを渡したときにも、ページが見つからないというエラーが返ってこなければ、URL 書き換えは成功です。

パラメータ別に所定の処理が動作するようにするには、Slim フレームワーク側でそれぞれのパラメータを受け取るようにコード記述を行います。

Slim フレームワークで FileMaker に接続するためのコード記述例

　ここでは、Slim フレームワークから FileMaker データベースに PDO(ODBC) 接続し、GET 要求されたデータを返すためのコード記述例を簡単に説明します。

　ユーザに公開するための出庫データ取得用 URI の形式は以下を想定します。

　 http://hostname/inventory/outgoing/123

　赤で示した部分は、URL 書き換え設定を行った URI です。つまり内部的には http://hostname/inventory/index.php にアクセスすることになります。

　outgoing/123 は　パラメータ1/パラメータ2 という並びになりますので、ここではoutgoing（出庫）と123(ID)という、2つのパラメータを取ることになります。

　
【コードの記述】

　ここでは、Slim フレームワーク公式サイトにあるコード記述方法にできるだけ沿った形でコード例をご紹介します。

接続情報の事前設定をします。

　以下は、ローカルホストの FileMaker Server 15 で公開中のデータベースファイルへの接続情報となります。
　将来的にこの接続設定を複数のファイルで使いまわしたい場合は、以下の部分を外部ファイル化（ config.php など）しておいて、実装時にインクルードするとよいでしょう。

<?php

    $config['displayErrorDetails'] = true;
    $config['addContentLengthHeader'] = false;
    $config['db']['host']   = "localhost";         //ホスト名
    $config['db']['user']   = "webuser";          //ユーザ名
    $config['db']['pass']   = "password";             //パスワード
    $config['db']['dbname'] = "testdatabase";   //データベース名

?>
Slim フレームワークオブジェクトのインスタンスを生成します。

　いよいよ、 Slim REST API の本体となる index.php ファイルを書いていきます。ユーザへのURI を提供するのがこのファイルとなります。

　$app = new \SlimApp(); で $app という名前の Slim オブジェクトのインスタンスが生成されますが、あらかじめ接続情報を読み込ませておく場合は、$app = new \Slim\App( ['settings' => $config] ); のように記述します。

<?php

    use \Psr\Http\Message\ServerRequestInterface as Request;    //要求インタフェース
    use \Psr\Http\Message\ResponseInterface as Response;　      //応答インタフェース

    require_once '../slim/vendor/autoload.php';    //Slim への相対パス
    require_once 'config.php';                            //外部ファイル化された接続情報（任意）

                                                                //Slim インスタンス生成
    $app = new \Slim\App( ['settings' => $config] );

?>
データベース接続の準備をします。

$app に実装済のデータベース接続情報の取り出しは、getContainer() メソッドで行います。
そして、コンテナの db 要素に PDO オブジェクトを返すように設定しておきます。

                        //コンテナ取り出し
$container = $app->getContainer();

                        //コンテナにデータベース接続を定義しておく
$container['db'] = function ( $c ) {

    $db = $c['settings']['db'];
    $pdobj = new PDO("odbc:Driver={FileMaker ODBC};host=" . $db['host'] . ";Database=" . $db['dbname'],$db['user'], $db['pass']);
    $pdobj->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $pdobj->setAttribute(PDO::ATTR_DEFAULT_FETCH_MODE, PDO::FETCH_ASSOC);

    return $pdobj;

};
GET リクエストを受信したときの動作を記述します。

　GET リクエストを受信した場合に応答する場合は、get メソッドを使います。
　$app->get(); が原形となりますが、GET で受け取る引数と処理の記述は、たとえば以下のような形式となります。

　赤字がユーザから受け取る引数のリスト（スラッシュ区切り）、青字が処理内容です。
　引数のリストの可変部分は中カッコ{}で囲み、中にその識別名を入れておきます。
　以下の場合は、出庫ID を想定した識別名を id とし、{id} のように記述しています。

　ユーザから渡された id を取り出すには、要求オブジェクト $request から getAttribute メソッドを呼び出すことで実現します。
　以下のコードのように書くことで、ユーザから渡された id が $id にセットされます。

$app->get( '/outgoing/{id}', function ( Request $request, Response $response ) {
　　　　                        //パラメータ取り出し
        $id = $request->getAttribute( "id" );
    }
);

$app->run();

最後の $app->run(); でユーザからのリクエストを受け付けます。

上記は GET 要求に対する処理を無名関数の中で行うように記述していますが、別途名前つきの関数を作って呼び出すようにしてもかまいません。
データベースに接続し、クエリを発行します。

　データベースの接続は、$this->db; で行います。これにより、3. のデータベース接続が実行されるとともに、PDO オブジェクトが返ってきますので、それを使ってデータベース操作を行います。

　たとえば、前述の get メソッドの部分をまとめて書くと、以下のようになります。
最後に結果を return することで呼び出し元に json フォーマットのデータを返しています。

$app->get( '/outgoing/{id:[0-9]+}', function ( Request $request, Response $response ) {

                        //パラメータ取り出し
    $id = $request->getAttribute( "id" );

    try {

                        //$this->db の形で接続確立し、$pdo オブジェクトを生成
            $pdo = $this->db;

            $sql = 'SELECT * FROM "出庫" WHERE "出庫ID"='.( int )$id;
            $stmt = $pdo->prepare( mb_convert_encoding( $sql, "shift-jis" ) );
            $stmt->execute();

                            //対象レコードカウント
            $recordCount = $stmt->rowCount();

            if( $recordCount == 0 ){

                        //レコードなし
                $result = 401;

            }else{

                        //レコード取り出し
                $data = $stmt->fetchAll();

                if( isset( $data ) ){

                    mb_convert_variables( 'UTF-8','shift-jis',$data );

                    $result = json_encode( $data );


                }else{

                        //レコードなし
                    $result = 401;

                }
            }

            $pdo = null;

        } catch( PDOException $e ) {

            $result = '{"error":{"text":'. $e->getMessage() .'}}';

        }

        return $result;

    });

重要：
- PDO(ODBC) でクエリを発行する際は、文字コードは shift-jis 形式で渡さなければエラーが発生します。
- 戻りデータの文字コード shift-jis になりますので、必要に応じて文字コードを変換してから使用する必要があります。
- PDO(ODBC) では bindParamやbindValue による引数のバインドがうまくいかない模様です。このため、SQL インジェクション対策として、{id}　で受け取る引数を数値に限定するように {id:[0-9]+} と書き換えてあります。
テストしてみましょう。

Web ブラウザから、http://hostname/inventory/outgoing/任意の数字を入力して送信したときに、json 形式の結果がブラウザページに表示されれば成功です。

　応用編として、Web インタフェースを作り、出庫ID指定による一覧呼び出しを行った例が、以下のようになります。内部的に Slim アクセスへの URI を呼び出しを行い、戻ってきた json データを整形して一覧表示しています。

内部的に Slim URI を呼び出している Web インタフェースの例

　Slim は軽量とはいえ、間にフレームワークを挟めば処理速度は低下します。
　こちらの記事でパフォーマンスについてご紹介しておりますので、併せてご覧いただけると幸いです。
　Slim フレームワークの REST(PDO) および RESTfm を使って CRUD のテストをしてみた

　Slim フレームワーク以外でも FileMaker で使用できるオープンソースの REST 環境がいくつかあるようです。
　

参考リンク：
　
　RESTfm (Goya)
　RESTfmがオープンソースに (Not only FileMaker)
　fmEasyAPI 開発者はサポートやめちゃったみたい...

FileMaker って、、、あれかなぁ

メニューバー

2016-11-17