Claris FileMaker 2024 では、スクリプト「 FileMaker Data API を実行」ステップでレコードへの書き込みがサポートされるようになりました。
これまで利用できたのは read（レコード内容の取得） と metaData（メタデータの取得） のみでしたが、書き込みがサポートされたことにより「 FileMaker Data API を実行」ステップの活用方法が大きく広がりました。
追加された action は、create（レコード登録） 、update（レコード編集）、delete（レコード削除）、duplicate（レコード複製） です。利用できるリクエスト内のオプションは 通常の Data API と同じものが使えるようです（※例外あり）。
このステップの実行上のポイントは次の通りです。
・ウインドウやレイアウトの切り替えをせずに実行できる
・実行結果のエラーを取得できるようになった
・レコードの登録や編集、削除は1件ずつしかできませんが、ポータルを含んだ親子関係でのレコードの登録や編集が可能（ポータル内のデータは複数件のレコード登録 / 編集が可能）
「 FileMaker Data API を実行 」の Claris のヘルプページは下記です。
https://help.claris.com/ja/pro-help/content/execute-filemaker-data-api.html
以下それぞれの action ごとに解説していきます。
レコードの追加「 create 」
レコードの追加は、例えば以下のように記述します。action オプションで create を指定し、layouts オプションで対象のレイアウト名を指定します。登録する各フィールド値は、 fieldData オプション以下にオブジェクトとしてフィールド名と値のセットで登録していきます。
FileMaker Data API を実行 [ ターゲット: $$result ;
JSONSetElement ( "{}" ;
[ "action" ; "create" ; JSONString ] ;
[ "layouts" ; "売上入力" ; JSONString ] ;
[ "dateformats" ; 1 ; JSONNumber ] ;
[ "fieldData.売上日" ; "2024/06/05" ] ;
[ "fieldData.得意先名" ; "株式会社API" ; JSONString ] ;
[ "fieldData.件名" ; "○○の件" ; JSONString ] ;
)
]これによって発行されるJSONは以下のようになります。
{
"action" : "create",
"dateformats" : 1,
"fieldData" :
{
"件名" : "○○の件",
"得意先名" : "株式会社API",
"売上日" : "2024/06/05"
},
"layouts" : "売上入力"
}実行結果として返ってくる JSON は以下のようになります。
{
"messages" :
[
{
"code" : "0",
"message" : "OK"
}
],
"response" :
{
"modId" : "0",
"recordId" : "1"
}
}実行結果のエラーコードと、作成されたレコードのレコードID（ recordID ）と編集ID（ modId ）を取得できます。
登録するフィールドに日付タイプが含まれるときは、デフォルトでは、mm/dd/yyyy 形式となっているため、このフォーマットに整形するか、 dateformats オプションで引数を 1 に設定するかの方法をとります。上記は dateformats オプションを指定しているので、売上日など日付タイプを yyyy/mm/dd など日本語環境で普段利用しているフォーマットで登録できます。
また、この「 FileMaker Data API を実行」ステップを実行した後に発生したエラーは、Get（ 最終エラー ）で取得できます。例えば、上記コマンドで dateformats を指定せずに実行した場合、エラーコードは「 500 」（日付の値が入力値の制限を満たしていません）が返ってきます。
ポータル含めたレコードの登録
そして、このレコード登録はポータルのレコードなど親子関係のデータも一緒に登録が可能です。ポータルレコードを追加していく場合は、portalData オプションにまずオブジェクトとしてポータル名または TO 名を追加し、その中に配列として各行のデータを追加していきます。これによりテーブルが親子関係のものであっても1回のコマンドで登録が可能になっています。以下のように記述します。
FileMaker Data API を実行 [ ターゲット: $$result ;
JSONSetElement ( "{}" ;
[ "action" ; "create" ; JSONString ] ;
[ "layouts" ; "売上入力" ; JSONString ] ;
[ "dateformats" ; 1 ; JSONNumber ] ;
[ "fieldData.売上日" ; "2024/06/05" ; JSONString ];
[ "fieldData.得意先名" ; "株式会社API" ; JSONString ] ;
[ "fieldData.件名" ; "○○の件" ; JSONString ] ;
[ "portalData.売上明細[0].売上明細::品名" ; "商品A" ; JSONString ] ;
[ "portalData.売上明細[0].売上明細::数量" ; "1" ; JSONNumber ] ;
[ "portalData.売上明細[0].売上明細::単価" ; "10000" ; JSONNumber ] ;
[ "portalData.売上明細[1].売上明細::品名" ; "商品B" ; JSONString ] ;
[ "portalData.売上明細[1].売上明細::数量" ; "1" ; JSONNumber ] ;
[ "portalData.売上明細[1].売上明細::単価" ; "12000" ; JSONNumber ] ;
)
]上記ではポータル行として2行分のデータを登録しています。これによって発行されるJSONは以下のようになります。
{
"action" : "create",
"dateformats" : 1,
"fieldData" :
{
"件名" : "○○の件",
"売上日" : "2024/06/05",
"得意先名" : "株式会社API"
},
"layouts" : "売上入力",
"portalData" :
{
"売上明細" :
[
{
"売上明細::単価" : 10000,
"売上明細::品名" : "商品A",
"売上明細::数量" : 1
},
{
"売上明細::単価" : 12000,
"売上明細::品名" : "商品B",
"売上明細::数量" : 1
}
]
}
}レコードの編集「 update 」
次に、レコード編集 update のコマンドを解説いたします。基本的にはレコード登録 create と似ています。異なるのは action オプションに update を指定し、必ず編集対象となるレコードのレコードID（ Get ( レコードID ) で取得できる値）を指定することです。以下のように記述します。
FileMaker Data API を実行 [ ターゲット: $$result ;
JSONSetElement ( "{}" ;
[ "action" ; "update" ; JSONString ] ;
[ "layouts" ; "売上入力" ; JSONString ] ;
[ "dateformats" ; 1 ; JSONNumber ] ;
[ "recordId" ; 1 ; JSONNumber ] ;
[ "fieldData.売上日" ; "2024/06/05" ] ;
[ "fieldData.得意先名" ; "株式会社API" ; JSONString ] ;
[ "fieldData.件名" ; "○○の件" ; JSONString ] ;
)
]fieldData オプションで指定したフィールドの値のみ更新されます。ここで指定しないフィールドは更新されません。（指定したフィールド以外のフィールドに自動入力やルックアップなど設定している場合は反映されます）
実行結果として返ってくるJSONは、 create 時と同じです。エラーコードとメッセージ、更新したレコードのレコードID（ recordId ）と編集ID（ modId ）が返ってきます。
{
"messages" :
[
{
"code" : "0",
"message" : "OK"
}
],
"response" :
{
"modId" : "1",
"recordId" : "1"
}
}ポータル含めたレコードの編集
ポータルを含めたレコードの編集時は、ポータルの各行ごとのレコードIDも指定します。この機能では、ポータル内のデータに対しては編集だけでなく追加も可能です。各ポータルでレコードIDを指定した行は編集となり、指定していない行は追加となります。例えば以下のように記述します。
FileMaker Data API を実行 [ ターゲット: $$result ;
JSONSetElement ( "{}" ;
[ "action" ; "update" ; JSONString ] ;
[ "layouts" ; "売上入力" ; JSONString ] ;
[ "dateformats" ; 1 ; JSONNumber ] ;
[ "recordId" ; 1 ; JSONNumber ] ;
[ "fieldData.売上日" ; "2024/06/05" ; JSONString ] ;
[ "fieldData.得意先名" ; "株式会社API" ; JSONString ] ;
[ "fieldData.件名" ; "○○の件" ; JSONString ] ;
[ "portalData.売上明細[0].売上明細::品名" ; "商品A" ; JSONString ] ;
[ "portalData.売上明細[0].売上明細::数量" ; "1" ; JSONNumber ] ;
[ "portalData.売上明細[0].売上明細::単価" ; "10000" ; JSONNumber ] ;
[ "portalData.売上明細[0].recordId" ; 1 ; JSONNumber ] ;
[ "portalData.売上明細[1].売上明細::品名" ; "商品B" ; JSONString ] ;
[ "portalData.売上明細[1].売上明細::数量" ; "1" ; JSONNumber ] ;
[ "portalData.売上明細[1].売上明細::単価" ; "12000" ; JSONNumber ] ;
[ "portalData.売上明細[1].recordId" ; 2 ; JSONNumber ] ;
[ "portalData.売上明細[2].売上明細::品名" ; "商品C" ; JSONString ] ;
[ "portalData.売上明細[2].売上明細::数量" ; "1" ; JSONNumber ] ;
[ "portalData.売上明細[2].売上明細::単価" ; "15000" ; JSONNumber ] ;
)
]上記で、親レコードの recordId を指定し、かつ各ポータル内のレコードにも recordId を指定しています。ポータルの3行目のデータには recordId を指定していません。この場合、1、2行目は編集され、3行目は追加する動きとなります。
また、編集時はオプションとして modId も指定することができます。この modId を指定すると、送信した modId が編集対象のレコードの modId と異なる場合にエラー（ 306 ）を返すというものです。
これは、例えばレコードの内容を取得して編集するまでの間に他のユーザーによって編集されているかどうかをチェックさせるための排他処理用のオプションとして利用できます。
ポータル含めたレコード登録・編集時にエラーが発生したとき
ポータル含めたレコード登録や編集時の重要なポイントですが、仮にポータルの中の一部のデータに不備があり登録・編集できない行があった場合（空欄不可、日付などの書式、レコードがロックされているなど）、このコマンドのすべてがキャンセルされる点です。不備のある行のレコードだけが登録・編集されないのではなく、親子関係の登録・編集すべてがキャンセルされます。
これは通常の FileMaker Pro でも用いられるトランザクション処理と同じく、レコード確定前に登録されたポータルのデータを、確定キャンセルしたことですべてなかったことにできるのと同じです。
この特性を利用してポータル内のレコードの登録や編集などがすべてエラーなしで実行できなかった場合はすべての処理をキャンセルさせたいときなどの処理を、「 FileMaker Data API を実行」を利用することでレイアウトやウインドウを切り替えることなくできるようになります。
利用できないオプションについて
通常の Data API のレコード登録や編集で利用できるオプションで、スクリプト「 FileMaker Data API を実行」で利用できないオプションは、script 関連のオプションです。通常の Data API の場合は、レコード登録や編集と合わせてスクリプトを実行させることが可能ですが、「 FileMaker Data API を実行」では利用できません。レコード登録時に合わせてスクリプトを実行させたい場合は、「 FileMaker Data API を実行」ステップ実行後に、対象のレイアウト、レコードに移動して目的のスクリプトを実行させる必要があります。この点は少し残念ですね。
他にはオブジェクトフィールドに対してデータをアップロードすることはできません。（通常の Data API でもオブジェクトフィールドへのアップロードは別のコマンドです。action の read でオブジェクトフィールドの内容は参照用の URL が返ってくるところも共通です）。これも「 FileMaker Data API を実行 」後に対象のレイアウト、レコードに移動し、通常のステップ「ファイルを挿入」などで対応する必要があります。
レコードの削除「 delete 」
レコードの削除は、action オプションを delete にして、対象のレイアウトとレコードIDを指定するだけです。以下のように記述します。
FileMaker Data API を実行 [ ターゲット: $$result ;
JSONSetElement ( "{}";
[ "action"; "delete"; JSONString ];
[ "layouts"; "売上入力"; JSONString ];
[ "recordId"; 1 ; JSONNumber ]
)
]実行結果として返ってくるJSONは以下のようにエラーコードとメッセージのみです。
{
"messages" :
[
{
"code" : "0",
"message" : "OK"
}
],
"response" : {}
}レコード削除に関してはシンプルになっています。ポータルの指定した行を削除するということはできません。ポータル内のテーブルが TO となっているレイアウトを用意しておき、そのレイアウトとレコードIDを指定することで削除することができます。
レコード複製
レコードの複製も、削除同様にアクションとレイアウト、レコードIDを指定します。以下のように記述します。
FileMaker Data API を実行 [ ターゲット: $$result ;
JSONSetElement ( "{}";
[ "action"; "duplicate"; JSONString ];
[ "layouts"; "売上入力"; JSONString ];
[ "recordId"; 1 ; JSONNumber ]
)
]実行結果として返ってくるJSONは、 create、update 時と同じです。エラーコードとメッセージ、更新したレコードのレコードID（ recordId ）と編集ID（ modId ）が返ってきます。
{
"messages" :
[
{
"code" : "0",
"message" : "OK"
}
],
"response" :
{
"modId" : "0",
"recordId" : "2"
}
}これは通常の FileMaker の複製と同じく、親子関係のレコードの一括複製はしません。また複製後に特定の項目を所定の値に変更するなども一回のコマンドではできないので注意が必要です。
まとめ
以上、Claris FileMaker 2024 で追加された「FileMaker Data API を実行」の追加オプションについて解説してきました。
主なポイントをまとめますと以下のようになります。
・ウインドウやレイアウトを切り替えることなく実行できる
・実行時のエラーコードを取得できるようになった
・ポータル含めた親子関係でのレコード登録 / 編集が可能
・ポータル内のレコード登録 / 編集エラーの場合、すべてのコマンドがキャンセルされるトランザクション的動作ができる
従来似たようなことをしたい場合は、「 ExecuteSQL 」を利用する方法がありましたが、それよりももっと細かな対応が可能になる今回の機能は、今後の FileMaker の実装方法においてたくさん活用されていくことになると思います。
新しい機能を使ってみたい方は今回の記事を是非参考ください。
本記事の注目度
本記事の注目度を測りたく、下記のクリック数を集計しております。
本ブログをご覧いただけた方は下記リンクより Claris 製品ページをご覧いただけると幸いです。
