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

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

www.cdata.com

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

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

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

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

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

cdn.cdata.com

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

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

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

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

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

APIリクエストの検証例

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

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

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

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

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

オペレーション定義はさらにメソッド毎に定義が分かれており、「」の部分に追記することで、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をリクエストを行うと、以下のようにエラーメッセージが出力されます。

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

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

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

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

 
  <api:script method="GET">
      <api:validate attr="_meta.odata:top" desc="$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>

これで「GET /api.rsc/sakila_actor/?$top=11」のようなリクエストを行うと、エラーが表示されるようになります。

同じように以下の変数でそれぞれのクエリパラメータの値にアクセスできるので、試してみてください。

• _meta.odata:filter
• _meta.odata:top
• _meta.odata:select
• _meta.odata:skip
• _meta.odata:orderby

おわりに

他にも様々なカスタマイズ方法があるので、随時Blogで紹介していきたいと思います。

また、もし使っていて気になる点、こんなカスタマイズはできる？　どうカスタマイズしたらいい？　みたいな疑問・質問があれば、お気軽にテクニカルサポートフォームまでお問い合わせください。

https://www.cdata.com/jp/support/submit.aspx

関連コンテンツ