f:id:sugimomoto:20220118222012p:plain

こんにちは。CData Software Japanリードエンジニアの杉本です。

CData API ServerはRDBやExcel・CSVファイルなどから自動でREST ful な Web APIを生成してくれるサービスです。

www.cdata.com

シンプルなAPIであれば手軽に作ることができますが、やはりAPIを活用するにあたっては、もう少し細かなカスタマイズ、挙動・バリデーションの制御をしたいということがあるでしょう。

そんな場合に、API Serverではカスタムスクリプトをスキーマ定義に加えることによって、様々な追加機能を付加することができるようになっています。

f:id:sugimomoto:20220118221622p:plain

今回はそんなAPI Serverで利用できるカスタムスクリプトの一例を紹介したいと思います。

API Server のカスタムスクリプトでできることの一例

まず、ざっくりとカスタムスクリプトでできることを紹介したいと思います。

cdn.cdata.com

API Serverは様々なパラメータ・メソッドを提供しているのが一つの特徴です。

f:id:sugimomoto:20220118221629p:plain

これらのパラメータの設定値を事前にチェックして、バリデーションを行ったり、強制的にフィルターや取得条件を追加するといったような操作

もしくはPOSTリクエストやPUTリクエストなどで渡ってきた値を検証し、フォーマットチェックを行ったり、値を追加・削除したりすることが可能です。

f:id:sugimomoto:20220118221633p:plain

カスタムスクリプトのカスタマイズ方法

カスタムスクリプトはリソースを定義した後に、以下の編集ボタンをクリックすることでカスタマイズできます。

f:id:sugimomoto:20220118221638p:plain

f:id:sugimomoto:20220118221643p:plain

APIリクエストの検証例

それでは今回はGETを対象として、いくつかシンプルな検証例を紹介します。

例えば、API Serverではデータの取得件数を上位N件で絞り込むことができる「$top」というパラメータが存在します。

GET /api.rsc/sakila_actor/?$top=10

DBの負荷などを考慮して、必ずこの上位N件を必須にしたい、といった要望もあるでしょう。そこで、この「$top」が設定されていなければ、エラーメッセージを出力するというスクリプトを書いてみます。

スクリプトはXMLベースでカラムの定義とオペレーションの定義の２種類に分かれています。

f:id:sugimomoto:20220118221648p:plain

オペレーション定義はさらにメソッド毎に定義が分かれており、「<api:script method="GET">」の部分に追記することで、GETリクエストの追加処理やチェックを行うことができるようになっています。

<!-- オペレーション定義 -->
  <api:script method="GET">
      <!-- 基本的にここにカスタムスクリプトの処理を追加する -->
    <api:push op="apiSelect" />
  </api:script>

値のチェック方法はいくつか方法がありますが、シンプルなアプローチは以下の「api:validate」を使う方法です。

cdn.cdata.com

「$top」は「_meta.odata:top」という変数に存在するので、この変数の存在チェックでエラーを発生させるように処理することができます。

例えば以下のような形です。

<!-- オペレーション定義 -->
  <api:script method="GET">
      <api:validate attr="_meta.odata:top" desc="$topは必須パラメータです。" />
    <api:push op="apiSelect" />
  </api:script>

この状態で「$top」が存在しないAPIをリクエストを行うと、以下のようにエラーメッセージが出力されます。

f:id:sugimomoto:20220118221655p:plain

「$top」をつけると正常に値が取得できました。

f:id:sugimomoto:20220118221659p:plain

せっかくなのでもう少し細かい定義を追加してみましょう。

このままでは「$top」でいくらでも大きい値を指定できてしまうので、10以下の値でなければ指定できないようにします。

「_meta.odata:top」からは指定された数値が取得できるので、それを別な変数に格納して、if文でチェック。条件に一致したらエラーをthrowするようなスクリプトにしてみました。

 <!-- オペレーション定義 -->
  <api:script method="GET">
      <api:validate attr="_meta.odata:top" desc="$topは必須パラメータです。" />
      
      <!-- $top の値を取り出す -->>
      <api:set attr="number" value="[_meta.odata:top]" />

      <!-- 値を比較する -->>
      <api:if exp="[number] > 10">
        <!-- 値を比較する -->>
        <api:throw code="validate" desc="$top には 10 以下の値を指定してください。" />
      </api:if>
      
    <api:push op="apiSelect" />
  </api:script>