こんにちは。
ライジングサン・システムコンサルティングの岩佐です。
この記事では、FileMaker Data API におけるレコードの検索方法について解説していきます。この記事で学習を進めるには、前々回のFileMaker Data API シリーズ・認証、そしてレコード取得の内容を理解している必要があります。
また、今回の学習でもPostmanを利用します。前回のレコード取得の記事で、Postmanに token 環境変数の自動更新を設定していますので、そちらも確実にできるようにしておくと、学習がよりスムーズに進みます。
そして、前の記事でご案内しているサンプルソリューションも、この先実際に手を動かして学習を進めていく上で必要となります。ぜひダウンロードし、ご自身の管理下にある FileMaker Server にホストしておいてください。（※この記事の最後にも、サンプルソリューションのダウンロードURLリクエストフォームをご用意しています。）
目次
1. find メソッドによる検索の仕組み
先の学習で解説したレコードの取得は、レコードIDを指定して、もしくはAPIを実行するターゲットテーブルの全レコードを取得するといった内容でした。
しかし実際にソリューションを構築するとなると、当然ですがこれだけでは不十分で、多くのケースでは今回解説するfindメソッドを使う機会が多くを占めると思います。
1-1. findメソッドのエンドポイント
findメソッドを実行するときのリクエストURIは以下のとおりです。
https://{{serverAddress}}/fmi/data/v1/databases/{{databaseName}}//layouts/{{layoutName}}/_find
{{serverAddress}} には、ソリューションをホストしているFileMakerServerのホスト名をします。
{{databaseName}} には、検索を実行したいデータが格納されているfmp12ファイル名をしています。
{{layoutName}} には、検索対象の BaseTable が関連付けられ、かつレスポンスとして取得したいフィールドが配置されたレイアウト名をしています。
また、リクエストタイプはPOSTになります。
2. findメソッドに設定可能なパラメータ
findメソッドには、大きく以下のようなパラメータを設定可能です。
・検索条件
・ソート条件
・レコード件数の上限値とオフセット
・スクリプト
2-1.検索条件
検索条件はターゲットのテーブルに対する検索条件を設定するパラメータで、JSONによる指定となります。このあと、サンプルソリューションと postman を用いて、実際に検索APIを実行します。
2-2ソート条件
ソート条件は、検索結果として返されるレコードのソート順を設定するパラメータです。同じくJSONで指定します。
2-3. レコード件数の上限値とオフセット
１回のリクエストで返される検索結果のレコード件数の上限値と、返してほしいレコードセット内におけるレコード開始位置を設定します。
2-4. スクリプト
検索メソッドの実行時に動かしたいスクリプトを指定します。スクリプトを実行できるタイミングは、検索処理の実行前、検索処理の実行後、検索処理が実行され、かつソート処理が実行された後の３つのタイミングで実行可能です。
3. Postmanを使ったfindメソッドの実行
ここからは、Postmanとサンプルソリューションを使って、実際にfindメソッドをハンズオンで動かしてみたいと思います。
Postmanを起動して、ログインメソッドを実行し、Postmanの環境変数に token がセットされた状態にしておいてください。
3-1. queryパラメータ
query パラメータには、検索条件を設定します。
例えば、今回のサンプルソリューションにテストデータとして登録されているPOSの売上データから、2018年4月1日から、2018年4月3日の売上で、売上金額が12,000円を超えるデータを取得する場合は、以下のようなパラメータを設定します。
{
"query":[{"date": "04/01/2018...04/03/2018","totalAmount": ">=12000" }]
}
ここで特筆すべきことは、検索条件の設定書式で、FileMaker の標準インタフェースを通して指定できる検索条件がサポートされている点です。
例えば、上記の例ですと、日付の範囲は 04/01/2018...04/03/2018 で指定されています。これはFileMaker開発者にとって非常にありがたい仕様だと思います。実際にAPIを実行するのは、普段他の開発プラットフォームで開発をしている技術者かもしれませんが、この検索条件の設定方法は極めて直感的なので、特に抵抗は無いと思います。
3-1-1. サポートされている比較演算子
find API でサポートされている比較演算子は以下のとおりです。
| =, ==, !, <, ≤ or <=, >, ≥ or >=, …, //, ?, @, #, *, \, “”, ~ |
ご覧の通り、FileMaker の標準UIでサポートされている比較演算子はすべてサポートされています。
パラメータを設定するときの注意点はいくつかあるのですが、まず我々日本の開発者として気をつけるべきことは、日付書式の設定です。 FileMaker の標準インタフェースを使った場合は、OSのロケールに合わせた検索が可能ですが、APIの実行では mm/dd/yyyy 書式での設定が必要です。
こちらの動画は、Postmanを使って、実際にqueryパラメータを設定して、findメソッドを実行する手順を解説しています。
それ以外にも、危険なクエリを実行される可能性があるなど、APIを公開する開発者としていくつか留意すべき点があります。これらの件については、この記事の最後にまとめて記述したいと思います。
3-1-2. and検索とor検索
実際のソリューションを構築するときの検索機能では、and条件とor条件を柔軟に組み合わせて、必要なレコードセットを取り出します。そしてAPIでも、この and条件とor条件での検索は可能です。
例えば、先程の検索条件では、日付と売上金額の and 条件で検索をしましたが、次はこれらをor演算でつなぐような検索をしてみます。
{
"query":[
{"date": "04/01/2018","totalAmount": ">=12000" },
{"date": "05/01/2018","totalAmount": ">=12000" },
{"date": "06/01/2018","totalAmount": ">=12000" }
]
}
上記のクエリパラメータは、売上日が2018年4月1日、5月1日、6月1日で、それぞれの売上日において売上金額が12,000円以上の売上データを検索するクエリです。
日付と金額の組み合わせは and条件ですが、日付をまたぐ条件は or 演算です。
and条件で検索をしたい場合は、query 配列配下の、１つのJSONオブジェクトに、key&value の組み合わせをカンマで区切って指定します。
一方、or条件での検索条件指定は、JSONオブジェクトを複数設定することで対応が可能です。
こちらの動画は、AND条件・OR条件を組み合わせたfindメソッドを実行する手順を解説しています。
3-2. sort パラメータ
JSONでレスポンスされるデータは、sort パラメータを設定することで、予め指定のソートキーで並び替えされた状態で取得することが可能です。
先のqueryパラメータに、sortパラメータを追加設定した状態がこちらです。
{
"query":[
{"date": "04/01/2018","totalAmount": ">12000" },
{"date": "05/01/2018","totalAmount": ">12000" },
{"date": "06/01/2018","totalAmount": ">12000" }
],
"sort": [
{"fieldName": "date","sortOrder": "ascend" },
{"fieldName": "totalAmount","sortOrder": "descend" }
]
}
sortパラメータは、{ “fieldName” : “hoge” , “sortOrder”: “ascend” } というJSONオブジェクトで表現します。sortOrderには、昇順条件である ascend と 降順条件である descend が設定可能です。
また、複数のソートキーを設定したい場合は、queryパラメータの or検索と同じように、複数のJSONオブジェクトを並列指定することで実現可能です。
上記の例では、取得したレコードセットに対して、売上日の昇順、かつ売上金額の降順でソートした結果をJSONで受け取ります。
こちらの動画では、Sortパラメータの設定方法について解説しています。
3-3. limitパラメータとoffset パラメータ
limitパラメータは、１回のリクエストでレスポンスされるレコード件数の条件値。そしてoffsetパラメータ、レスポンスされるレコードの開始位置を指定します。
Webアプリケーションではよく見かけるユーザインタフェースですが、一定以上の大きさのレコードを１ページに表示するのではなく、複数ページに分割して表示をしたい場合があります。この場合、１回のリクエストで100レコードすべてを受け取るのではなく、ページ切り替えボタンを押すたびに、表示に必要な情報だけをレスポンスとして受け取ることで、応答性能の改善が期待できます。
例えば、１度のリクエストで受け取りたいレコード件数が10件で、21件目から30件目までのレコードをリクエストする場合は、以下のようなパラメータを設定します。
{
"query":[
{"date": "04/01/2018","totalAmount": ">12000" },
{"date": "05/01/2018","totalAmount": ">12000" },
{"date": "06/01/2018","totalAmount": ">12000" }
],
"sort": [
{"fieldName": "date","sortOrder": "ascend" },
{"fieldName": "totalAmount","sortOrder": "descend" }
],
"limit" : 10,
"offset" : 21
}3-4. スクリプト
findメソッドは、スクリプトも同時に実行することができます。
スクリプトの実行タイミングは次の３つで、それぞれに対して個別のスクリプト、そしてスクリプトパラメータを設定することが可能です。
3-4-1. 実行タイミング1:検索実行前
検索実行前にスクリプトを実行したい場合は、以下２つのパラメータを設定します。
script.prerequest : スクリプト名
script.prerequest.param : スクリプトパラメータ
3-4-2. 実行タイミング1:検索実行後・ソート実行前
検索実行後、かつソート実行前に実行したいスクリプトがある場合は、以下２つのパラメータを設定します。
script.presort : スクリプト名
script.presort.param : スクリプトパラメータ
3-4-3. 実行タイミング1:検索実行後・ソート実行後
検索が実行され、指定したソート条件での並び替えも終了した後に実行したいスクリプトがある場合は、以下２つのパラメータを設定します。
script.param : スクリプト名
script.param : スクリプトパラメータ
これだけのタイミングでスクリプトを実行することができるので、FileMaker内部で実行しているビジネスロジックはほぼすべてAPIを通じて、他システムに提供可能ということになります。
スクリプトの実行は、様々なノウハウや注意点があるので、別記事にてまとめてお伝えしたいとお見おます。
4.まとめ
この記事では、FileMaker Data API の findメソッドについて解説をしてきました。恐らくご自身のソリューションをAPIを使って公開するときに、最も利用頻度が高いメソッドになるのではないかと思います。
学習してきたとおり、AND条件とOR条件を柔軟に組み合わせできたり、APIの戻り値として返すJSONのソート順を設定できたり、Webアプリケーションではよく見かけるページネーションを意識したLIMITとOFFSETが設定できたり、更には任意のタイミングでスクリプトが実行できたりと、一般的に考えられる要求仕様に対してはほぼ対応できるかなり充実した機能が提供されています。
この次の記事では、レコードの追加・編集・削除について解説をしていきます。
4-1. サンプルソリューションのダウンロード
サンプルソリューションはこちらからリクエストしてください。いただいたメールアドレスにダウンロードURLと、APIを実行するために必要なアカウント名とパスワードをお送りします。
※認証の記事にあるサンプルソリューションと同じものなので、すでにダウンロード済みの方は必要ありません。
※サンプルソリューションを動かすには、FileMakerのVer17以降が必要です。
サンプルソリューションはロックフリーになっています。
ダウンロードURLには、完全アクセス権のアカウント名とパスワードを記述しています。こちらでサンプルソリューションを開いていただければ、全ての中身を確認いただくことが可能です。
そして、サンプルソリューションで使われているカスタム関数やスクリプトは自由にあなたのソリューションにコピーして使っていただくことができます。
ただし、それに伴って発生したあらゆる障害に関しては責任を追いかねることをご了承ください。
最後までお読みいただきありがとうございました。
この記事にご興味を持たれた方には、こちらの記事もおすすめです。
