Search

スキーマのカスタマイズ

Version 22.0.8500

スキーマのカスタマイズ

Version 22.0.8500

API のリソースは、テキストベースのスキーマを書くことで定義されます。スキーマは、リソースのカラムを定義するシンプルなAPI Script コンフィギュレーション言語にて書かれています。さらに、データベース、ファイル、およびバックエンドサービスを読み書きすることを実現するビルトインオペレーションがあります。

これらのデータ処理構造に加えて、API Script は、条件分岐やループなどに対応して構成されているフル機能の言語です。ただし、スキーマの例に示されているように、大抵のリソース定義にはこれらの機能を使う必要はありません。

次のセクションは、SQLite データベース内のテーブルへの双方向アクセスを可能にするフル機能のスキーマについて説明します。［設定］->［リソース］タブのウィザードからデータベーステーブルおよびストアドプロシージャの類似したスキーマを生成することができます。スキーマの脇の編集ボタンをクリックしてスキーマを編集することもできます。

このセクションでは、自分でスキーマを書くことで、他のデータソースに読み書きを行うために必要なコンポーネントの詳細な説明をします。リソースのためのスキーマは、.rsd ファイルで書かれており、アクションのためのスキーマは.rsb ファイルに書かれています。ウィザードは、これらのファイルをアプリケーションルートのapi サブフォルダに配置します。作成するカスタムスキーマも同じフォルダに格納します。

リソースカラムのマークアップ

データベースに接続するときに、リソースのカラムは次の基本属性を持ちます。

  • カラム名
  • データ型
  • カラムが主キーかどうか

スキーマのapi:info ブロック内では、リソースのカラムをこれらの属性やその他でマークアップできます。

<api:info title="NorthwindOData" desc="Access the Cars database through REST APIs." connection="SQLiteCars">
  <attr name="ID"           key="true" xs:type="int"      />
  <attr name="Make"         xs:type="string"   />
  <attr name="Model"        xs:type="string"   />
  <attr name="Cost"         xs:type="double"   />
  <attr name="CreatedDate"  xs:type="datetime" />
  <attr name="InStock"      xs:type="boolean"  />
</api:info>

データの取得

HTTP GET リクエストが受信されると、API Server は、スキーマのGET メソッドを実行します。このメソッドにおいて、API Server のビルトインオペレーションを使って、データ取得リクエストを処理することができます。次にHTTP GET を使った検索リクエストの例を示します。

GET api.rsc/Cars?$filter=Make eq 'Honda'

次のリクエストは、下のSQL クエリに対応します：

SELECT * FROM Cars WHERE Make = 'Honda'

対応するGET メソッドでは、データベースクエリの結果はAPI Server のHTTP レスポンスにapi:push キーワードによって追加されます。データベースに対する検索、ソート、サマリー、および他のデータ取得クエリ実行には、apiSelect オペレーションを使うことができます。

<api:script method="GET" >
  <api:push op="apiSelect"/>
</api:script>

データのPost

POST リクエストが受信されると、API Server は、スキーマのPOST メソッドを呼び出し、挿入のようなデータ操作オペレーションを設定できます。

例として、次のHTTP POST リクエストを考えましょう：

POST api.rsc/Cars
{
  "Model":"Civic",
  "Make":"Honda"
}

次のリクエストは、下のSQL クエリに対応します：

INSERT INTO (Model, Make) VALUES ('Civic', 'Honda')

対応するPOST メソッドにおいて、apiInsert オペレーションを使って、データベースに挿入を実行できます。

<api:script method="POST">
  <api:push op="apiInsert"/>
</api:script>

いくつかのデータベースではINSERT 構文からデータを返します。例えば、新しいレコードからの発行されたId です。挿入から返された値にアクセスしたい場合には、GET の際にapi:push キーワードを使います。

データのPut

PUT リクエストが受信されると、API Server は、スキーマのPOST メソッドを呼び出し、更新のようなデータ操作オペレーションを設定できます。

例として、次のPUT リクエストを考えましょう：

PUT http://localhost:8065/api.rsc/Cars('1000')
{
  "Model":"Civic"
}

次のリクエストは、下のSQL クエリに対応します：

UPDATE Cars SET Model = 'Civic' WHERE Id = '1000'

下の対応するPUT メソッドにおいて、オペレーションが呼び出される前に必須入力である主キーがまず検証されます。インプットが提供されたかをチェックし、api:validate キーワードを伴わない場合には、ユーザーにアラートを出すことができます。スクリプトに複数のHTTP メソッドを扱わせることを指定することもできます。 さらに、更新は通常戻り値がないため、api:call キーワードがオペレーションを起こすために使われます。データベースに対する挿入の実行には、apiUpdate オペレーションを呼び出すことができます。

<api:script method="PUT,MERGE,PATCH">
  <api:validate attr="Id" desc="更新にはId が必須です。" />
  <api:call op="apiUpdate"/>
</api:script>

データのDelete

DELETE リクエストが受信されると、API Server は、スキーマのDELETE メソッドを実行し、削除オペレーションを呼び出します。例として、次のHTTP DELETE リクエストを考えましょう：

DELETE api.rsc/Cars('1000')

次のリクエストは、下のSQL クエリに対応します：

DELETE FROM Cars WHERE Id = '1000'

DELETE メソッドでは、データベースに対する削除実行には、apiDelete オペレーションを呼び出すことができます。

<api:script method="DELETE">
  <api:validate attr="Id" desc="削除にはId が必須です。" />
  <api:call op="apiDelete"/>
</api:script>

サンプルスキーマ

次のスキーマは、SQLite データベースのCars テーブルにアクセスし、データの読み書きを実行することができます。これには、HTTP を通じでデータベースにアクセスするために必要なすべてのコンポーネントが含まれています。

<api:script xmlns:api="http://www.rssbus.com/ns/rsbscript/2">
 
  <!-- Define columns and the database connection in the api:info block -->
  <api:info title="case" description="Create, Update, Query, and Delete Cars." connection="SQLiteCars">
    <attr name="Id"             key="true" xs:type="string"   />
    <attr name="Year"                      xs:type="int"      />
    <attr name="Make"                      xs:type="string"   />
    <attr name="Model"                     xs:type="string"   />
    <attr name="DatePurchased"             xs:type="datetime" />
  </api:info>
 
  <!-- The GET method is executed when an HTTP GET is received.You can configure data retrieval operations here.The results of processing are pushed to the schema's output. -->
  <api:script method="GET">
    <api:push op="apiSelect"/>
  </api:script>
 
  <!-- The POST method is executed when an HTTP POST is received.You can configure insert operations here.Use api:push to return the Id of the new record. -->
  <api:script method="POST">
  <api:validate attr="Make" desc="Make and Model are required to insert a Car."/>
  <api:validate attr="Model" desc="Make and Model are required to insert a Car."/>
    <api:push op="apiInsert"/>
  </api:script>
 
  <!-- The PUT method is executed when an HTTP PUT is received.You can configure update operations here.Within the script block, the primary key is used to update the record.Updates typically do not return data, so api:call is used to invoke the operation. -->
  <api:script method="PUT,MERGE,PATCH">
    <api:validate attr="Id" desc="更新にはId が必須です。"/>
    <api:call op="apiUpdate"/>
  </api:script>
 
  <!-- The DELETE method is executed when an HTTP DELETE is received.You can configure delete operations here.Within the script block, the primary key is used to delete the record. -->
  <api:script method="DELETE">
    <api:validate attr="Id" desc="削除にはId が必須です。"/>
    <api:call op="apiDelete"/>
  </api:script>
 
</api:script>

キーワードリファレンス

このセクションで使われているキーワードの詳細情報は、API Script を参照してください。