JSONで渡すスクリプト引数と戻り値の基本
スクリプト

JSONで渡すスクリプト引数と戻り値の基本

2026年3月7日 admin スクリプト

FileMakerでスクリプトを作っていると、「引数が増えてきて分かりにくい」「どこで何を渡しているのか追えない」「戻り値の仕様がバラバラ」という悩みが出てきます。これをすっきり整理する方法として、JSON形式でスクリプト引数や戻り値を扱うやり方がよく使われるようになってきました。

この記事では、JSONでスクリプト引数と戻り値を渡すときの「基本の考え方」と「よく使う書き方」を、できるだけ専門用語を減らして解説します。

JSONで渡すと何がうれしいのか

まずは「なぜJSONなのか」を押さえておきましょう。

  • 引数が増えても1つの引数にまとめられる
    通常のスクリプト引数だと、値を区切り文字（改行など）でつないで渡すことが多いですが、順番が変わると壊れたり、後から見て意味が分かりにくくなります。JSONなら「名前：値」のセットで渡せるので、順番に依存しません。
  • 中身が見やすく、変更しやすい
    JSON形式のテキストは、人間が読んでも構造が分かりやすく、あとから項目を追加したり削除したりもしやすいです。
  • サブスクリプトとのやりとりが安定する
    複数のスクリプト間で同じJSON形式を使っておけば、「何を渡して、何が返ってくるか」が共通のルールで管理できます。

基本：JSON形式のスクリプト引数を作る

まずは呼び出し元のスクリプトで、スクリプト引数をJSONで組み立てる方法です。よく使う関数は JSONSetElement です。

例：顧客IDと処理モードをサブスクリプトに渡したい場合

// スクリプト引数（JSON）を作成
Set Variable [ $json ; 
    JSONSetElement ( "{}" ; 
        [ "customerID" ; 顧客::顧客ID ; JSONNumber ] ;
        [ "mode"       ; "update"     ; JSONString ]
    )
]

// サブスクリプトを呼び出し
Perform Script [ "顧客処理_サブ" ; Parameter: $json ]

ポイントは次の2つです。

  • "{}" をベースに JSONSetElement で項目を追加していく
  • 各項目に「名前」をつけているので、後から見ても意味が分かりやすい

サブスクリプト側でJSON引数を取り出す

サブスクリプトでは、受け取ったJSONテキストから必要な値を取り出します。よく使う関数は JSONGetElement です。

例：さきほどの引数を受け取る側

// スクリプト引数を受け取る
Set Variable [ $param ; Get ( ScriptParameter ) ]

// JSONから値を取り出す
Set Variable [ $customerID ; JSONGetElement ( $param ; "customerID" ) ]
Set Variable [ $mode       ; JSONGetElement ( $param ; "mode" ) ]

ここでも「キー名（customerID, mode）」で取り出すので、あとから項目が増えても順番に振り回されにくいのが利点です。

戻り値もJSONで返すと便利

サブスクリプトから呼び出し元へ結果を戻したい場合も、JSONで返すと管理しやすくなります。

サブスクリプト側：

// 処理結果（例：成功・失敗、メッセージ、件数など）
Set Variable [ $resultJSON ;
    JSONSetElement ( "{}" ;
        [ "status"  ; "success"          ; JSONString ] ;
        [ "message" ; "処理が完了しました" ; JSONString ] ;
        [ "count"   ; $processedCount    ; JSONNumber ]
    )
]

// 戻り値として返す
Exit Script [ Result: $resultJSON ]

呼び出し元のスクリプトでは、Perform Script の結果を変数に受け取り、同じく JSONGetElement で中身を取り出します。

呼び出し元：

// サブスクリプトを実行し、戻り値を受け取る
Perform Script [ "顧客処理_サブ" ; Parameter: $json ]
Set Variable [ $result ; Get ( ScriptResult ) ]

// JSONから必要な情報を取り出す
Set Variable [ $status  ; JSONGetElement ( $result ; "status" ) ]
Set Variable [ $message ; JSONGetElement ( $result ; "message" ) ]
Set Variable [ $count   ; JSONGetElement ( $result ; "count" ) ]

このように「引数も戻り値もJSONにする」と、スクリプトのやりとりがすっきりと一元化できます。

よくあるパターンと簡単なルール

JSONで引数・戻り値を扱うとき、あらかじめルールを決めておくとプロジェクト全体が整理されます。例えば：

  • status … “success” / “error” など、結果の状態
  • message … ユーザーに見せるメッセージ
  • data … 実際の結果データ（IDや件数など）
  • errorCode … 失敗時のエラーコード

こうした共通キー名をチームで揃えておくと、別の人が作ったスクリプトも理解しやすくなります。

また、次のような簡単なルールもおすすめです。

  • 引数用と戻り値用で、キー名や構造をできるだけ統一する
  • 数値は JSONNumber、真偽値は JSONBoolean など、型を意識して設定する
  • JSON文字列を変数に入れるときは、$param や $result など、名前から用途が分かるようにする

まとめ：まずは小さなスクリプトからJSON化してみる

JSONでスクリプト引数や戻り値を扱うと、最初は「少し面倒そう」に見えるかもしれません。しかし、引数が3つ4つと増えてくると、その効果ははっきりしてきます。構造がはっきりし、あとから見直したときにも「何を渡して、何が返ってくるのか」がすぐに分かるようになります。

まずは、シンプルなサブスクリプト1本だけでも構いません。これまで改行区切りで渡していた引数を、JSONSetElement / JSONGetElement に置き換えてみてください。その小さな一歩が、スクリプト全体の整理への大きな一歩になります。

※ 本稿は、生成AIを使用して執筆しています。重要な内容については、必ずご自身でマニュアル等をご確認ください。
#FileMaker Pro