こんにちは。
ライジングサン・システムコンサルティングの岩佐です。
この記事では、FileMaker Data API におけるレコードの取得方法について解説していきます。この記事で学習を進めるには、前回のFileMaker Data API シリーズ Authenticationの内容を理解している必要があります。
もしまだその記事を確認されていなければ、まずはこちらのリンクから、Authentication の方法を学習し、確実にログイン・ログアウトができるようにしておいてください。
また、今回の学習でもAPIクライアントでは、Postmanを利用します。
前回の記事でご紹介した環境変数の設定が、ここからの学習において極めて重要になってきますので、ぜひその部分も含めてご確認をお願いいたします。
そして、前の記事でご案内しているサンプルソリューションも、この先実際に手を動かして学習を進めていく上で必要となります。ぜひダウンロードし、ご自身の管理下にある FileMaker Server にホストしておいてください。（※この記事の一番最後にも同じくサンプルソリューションのダウンロードURL請求フォームを設置しています。）
目次
1.PostmanにおけるTokenの自動更新
この先の学習を進めるにあたって、何度もTokenをリフレッシュ（再取得・再ログイン）する機会が出てきます。取得したTokenは、JSON形式で返ってくるので、その値をコピー＆ペーストして環境変数にセットすればよいのですが、Postmanでは、この退屈な操作を自動化することができます。
1-1. Tokenの自動更新設定
それでは実際に、Tokenの自動更新の設定をしてみましょう。
先のAuthenticationの学習で、ログインとログアウトの設定をPostmanのコレクションに保存していると思います。そこからログインの設定をロードし、リクエストURLを設定するテキストボックスの下部にあるTestsタブをクリックしてください。
そうすると、簡単なテストコードを書くことができるエディタが表示されます。
そちらに、以下のコードをコピー＆ペーストしてください。
let ok = responseCode.code === 200;
tests["Successful request"] = ok;
if(ok) {
let jsonData = JSON.parse(responseBody);
pm.environment.set("token",jsonData.response.token);
}
こちらは、もしAuthenticationのログインメソッドが成功（responseCode.code=200）したら、環境変数のtokenに レスポンスされたJSONのキーtokenに設定されている値をセットしてねという意味のJavaScriptです。
1-2. 自動設定の動作確認
設定が完了したら実際にTokenを取得して、環境変数に取得した値が自動設定できることを確認してください。
Sendボタンをクリックして、正しくレスポンスが返ってきたら、ウインドウ右上にある環境変数値を確認できるポップオーバーを開いてください。tokenの環境変数が正しく設定されていれば、レスポンスJSONのtokenの値が自動設定されているはずです。
2.レコードの取得
ここからは、実際に FileMaker Data API を使って、サンプルソリューションのデータベースにセットされている値を取得する方法について学習を進めていきたいと思います。
FileMaker Data API で用意されているデータの取得を目的としたメソッドは、以下の３つになります。
| メソッド | リクエストタイプ | 説明 |
| Get Record | Get | レコードIDを指定して目的の１件のレコードを取得 |
| Get Records | Get | レコードIDを指定せずターゲットテーブルの全レコードを取得 |
| Find | Post | 検索条件を指定して目的のレコードセットを取得 |
この記事では、最も基本となる Get リクエストを使った上記２つの方法について解説します。
Find メソッドについては、APIを実行するときに設定するクエリパラメータがかなり多岐にわたり、また同時にスクリプトを実行できるなど、かなり複雑な機能も実装可能なため、独立した別記事でお伝えできればと思います。
2-1. Get Record
このメソッドは、あるテーブルの特定のレコードIDを引数に、目的のレコードを１件だけ取得するというとてもシンプルなメソッドです。
Getリクエストということもあって、複雑なパラメータ設定も必要なく、手軽にAPIの動きを確認することができます。
2-1-1. 環境変数設定
それではまず最初に、レコードの取得元となるデータベースとテーブルを、環境変数に設定します。
ウインドウ右上の環境変数設定ボタンをクリックし、開いたポップオーバーの右上にある editボタンをクリックしてください。
先の学習で設定した環境変数の中にlayoutNameという変数が設定されていると思います。こちらに T01_PRODUCTITEMという値を設定してください。こちらは、FileMakerで言うところのレイアウト名になります。
次にPostmanで、新しいタブを追加し、そちらに下記のリクエストURLを入力してください。
https://{{serverAddress}}/fmi/data/v1/databases/{{databaseName}}//layouts/{{layoutName}}/records/6238
最後に、Httpヘッダに認証情報を設定します。
リクエストURLの下部にあるタブのHeadersをクリックしていただき、そちらに１つのキーバリューセットを設定します。
キーにはAuthorization、バリューにはBearer {{token}} を入力してください。
この {{token}} の部分には、ログインメソッドで取得したトークンが自動的に代入されます。
以上で設定は完了です。
2-1-2. レコードの取得
それでは実際にAPIを実行してみましょう。
以下のようなレスポンスが返されると思います。
{
"response": {
"data": [
{
"fieldData": {
"jan_code": "4901861099898",
"name": "信州ハム つるしベーコンロング ４８５ｇ",
"unit_price": 256,
"launch_date": "08/12/2013",
"T01_productItem_MAKER::name": "信州ハム",
"__id": "D2EDDD18-954E-4B91-A0BF-2EA0AEF54ACD",
"comment": "",
"_fk_maker_id": "B3934125-CE6E-4350-84A0-0D9403D7F35A"
},
"portalData": {},
"recordId": "6238",
"modId": "6"
}
]
},
"messages": [
{
"code": "0",
"message": "OK"
}
]
}いかがでしょうか？
うまくレスポンスを取得することができたでしょうか。
もし何らかのエラーが起きた場合は、再度作業の過程を丁寧に見直してみましょう。
また以下のようなレスポンスが返ってくる場合は、セッションのタイムオーバーで強制的にログアウトされている可能性があります。
{
"messages": [
{
"code": "952",
"message": "Invalid FileMaker Data API token (*)"
}
],
"response": {}
}その場合は、再度ログインメソッドを実行して、Token をリフレッシュしてください。
2-1-3. FileMaker Data API とレイアウト
FileMaker Data API は、一般的にRESTfulと呼ばれる考え方に基づいて設計されています。
RESTful な思想とは、様々な定義があると思いますが、私の個人的な理解で説明するとなると、APIで提供するサービスと、それを享受するクライアント間の高い独立性を保つための連携手法と説明します。
…まぁこのあたりは、よくも悪くも各技術者の思想に関する方向性であったり、スキルであったり、抽象度によって大きく表現が事ある部分なので、あえて深掘りしないでおきましょう（笑）
ここで大切なのは、普段FileMakerプラットフォーム以外で開発をしている技術者に対しても RESTful な API であることを伝えることで、共通言語ができることです。
さて、FileMaker Data API では、データ取得元のテーブルを指定する場合、FileMaker用語で言うところのBaseTableではなく、レイアウトを設定します。（このあたりもFileMaker Data API を設計した「中の人」に拍手を送りたいです！）そしてそのレイアウトに配置されているフィールドの値がレスポンスとして返ってきます。
よって、先程指定したT01_PRODUCTITEMを実際に確認すると、つぎのようなレイアウトになっています。
ちなみに、レイアウトにレコードIDが表示されていますが、こちらはマージフィールドです。マージフィールドは、レスポンスされるデータには反映されないので注意が必要と同時に、デバッグ目的などで便利に浸かることができるコントロールでもあります。
またレスポンスされるJSONのキーは、フィールド名がそのまま反映されます。これはプログラミングの手間を省くことができる半面、よく考えてフィールド名を設定する必要性の裏返しでもあります。
また、レイアウトに配置されているすべてのフィールドがレスポンスの対象となるので、日本人好みの（？）幕の内弁当的な、あらゆる関連テーブルのフィールドが配置されたヘビーなレイアウトは好ましくありません。実際の開発シーンでは、目的に応じて、それぞれのAPI用のレイアウトを作ることが現実的な解になります。
2-2. Get Records
次にもう一つのGetリクエストである Get Records の動作を確認しましょう。
こちらはリファレンスを読むと次のように書いてあります。
Get all records or a subset of records in the specified layout.
指定したレイアウトに紐付いているテーブルオカレンスの全レコード、もしくはサブセットをすべて取得とありますので、事前に検索を実行してFindsetを作っていなければ、該当テーブルの全レコードが返されるという動きになります。
恐らく Findset を取得してからのレコード取得は、この後別の記事で説明する find メソッドを使うことになります。
よって、こちらのメソッドは、レコード件数が数件から数十件レベルの限られたテーブルの値をまとめて取得したい場合に使うことが前提となりそうです。
今回は、サンプルソリューションにセットしている、store テーブル。論理名称だと「店舗マスター」を獲得して見ます。今回のサンプルソリューションに登録している店舗マスターは５件のみです。この程度であれば、全県取得をしてもそれほど高コストにはならないでしょう。
以下が、レスポンスとして取得できるJSONになります。
{
"response": {
"data": [
{
"fieldData": {
"name": "にこにこマーケット・１号店",
"shopCode": 1003,
"__id": "20C5C17F-DB4E-40AF-A4E4-0C23143F7B1F",
"za_accountCreated": "Administrator",
"za_accountModified": "Administrator",
"za_timestampCreated": "12/02/2018 10:52:19",
"za_timestampModified": "12/02/2018 10:52:29"
},
"portalData": {},
"recordId": "3",
"modId": "0"
},
{
"fieldData": {
"name": "にこにこマーケット・２号店",
"shopCode": 1004,
"__id": "F04C443A-4B2A-4946-B057-89603A117D40",
"za_accountCreated": "Administrator",
"za_accountModified": "Administrator",
"za_timestampCreated": "12/04/2018 09:26:35",
"za_timestampModified": "12/04/2018 09:26:39"
},
"portalData": {},
"recordId": "4",
"modId": "0"
},
{
"fieldData": {
"name": "にこにこマーケット・３号店",
"shopCode": 1005,
"__id": "24C4D119-2B15-4698-B18F-DB5258F1BBA5",
"za_accountCreated": "Administrator",
"za_accountModified": "Administrator",
"za_timestampCreated": "12/04/2018 09:26:39",
"za_timestampModified": "12/04/2018 09:26:43"
},
"portalData": {},
"recordId": "5",
"modId": "0"
},
{
"fieldData": {
"name": "にこにこマーケット・４号店",
"shopCode": 1006,
"__id": "AEA64395-6AFE-47C5-AE80-4D3C96C8EC03",
"za_accountCreated": "Administrator",
"za_accountModified": "Administrator",
"za_timestampCreated": "12/04/2018 09:26:43",
"za_timestampModified": "12/04/2018 09:26:47"
},
"portalData": {},
"recordId": "6",
"modId": "0"
},
{
"fieldData": {
"name": "にこにこマーケット・５号店",
"shopCode": 1007,
"__id": "0DB01B77-2ED7-4435-83D9-B572F74E1445",
"za_accountCreated": "Administrator",
"za_accountModified": "Administrator",
"za_timestampCreated": "12/04/2018 09:26:48",
"za_timestampModified": "12/04/2018 09:26:53"
},
"portalData": {},
"recordId": "7",
"modId": "0"
}
]
},
"messages": [
{
"code": "0",
"message": "OK"
}
]
}3.まとめ
この記事では、FileMaker Data API の Get系 API である Get Record と Get Records メソッドについて解説してきました。
引数としてレコードIDを設定したり、もしくテーブルに登録されているすべてのレコードを取得できたりと、実際のソリューション構築のシーンでは、利用するケースが限られるAPIかと思われますが、Get系ということもあって手軽に試すことのできる基本となるリクエストでもあります。
ぜひ、しっかりと基本をマスターして、次に進むようにしましょう。
次は、様々な検索条件を設定したレコードセットの獲得方法について学習していきます。
3-1. サンプルソリューションのダウンロード
サンプルソリューションはこちらからリクエストしてください。いただいたメールアドレスにダウンロードURLと、APIを実行するために必要なアカウント名とパスワードをお送りします。
※認証の記事にあるサンプルソリューションと同じものなので、すでにダウンロード済みの方は必要ありません。
※サンプルソリューションを動かすには、FileMakerのVer17以降が必要です。
サンプルソリューションはロックフリーになっています。
ダウンロードURLには、完全アクセス権のアカウント名とパスワードを記述しています。こちらでサンプルソリューションを開いていただければ、全ての中身を確認いただくことが可能です。
そして、サンプルソリューションで使われているカスタム関数やスクリプトは自由にあなたのソリューションにコピーして使っていただくことができます。
ただし、それに伴って発生したあらゆる障害に関しては責任を追いかねることをご了承ください。
最後までお読みいただきありがとうございました。
この記事にご興味を持たれた方には、こちらの記事もおすすめです。
