データ操作

REST によって、すべての 公開されているデータクラス、属性、そしてメソッドにアクセスすることができます。 データクラス、属性、およびメソッド名については、文字の大小が区別されます。クエリのデータについては、文字の大小は区別されません。

データのクエリ

データを直接クエリするには $filter 関数を使います。 たとえば、"Smith" という名前の人を検索するには:

http://127.0.0.1:8081/rest/Person/?$filter="lastName=Smith"

エンティティの追加・編集・削除

REST API を使って、4D内と同等のデータ操作をおこなうことができます。

エンティティを追加・編集するには $method=update を呼び出します。 1つ以上のエンティティを削除するには $method=delete を使用します。

{dataClass}({key}) でデータクラスのいちエンティティを取得する以外にも、DataClassクラスにメソッドを書いて {dataClass}/{method} のように使い、エンティティセレクションやコレクションを返すようにすることができます。

戻り値としてコレクションを返す前に、$orderby を使って一つ以上の属性 (リレーション属性も可) を基準に並べ替えることもできます。

データのナビゲーション

エンティティのコレクションをナビゲートするにあたっては、クエリやエンティティセレクションに次の RESTリクエストを追加することができます: $skip (開始エンティティの指定)、$top/$limit (返されるエンティティ数の指定)。

エンティティセットの作成と管理

エンティティセットとは、エンティティセレクション と同等の意味で、RESTリクエストによって取得され、4D Server のキャッシュに保存されるエンティティのコレクションのことです。 エンティティセットを利用することで、同じ結果を得るためにアプリケーションを繰り返しクエリすることが避けられます。 エンティティセットへのアクセスはクエリするよりも速いため、アプリケーション速度の向上にもつながります。

エンティティセットを作成するには、RESTリクエスト内で $method=entityset を呼び出します。 エンティティセットがタイムアウトした場合やサーバーから削除されてしまった場合への安全対策として、$filter や $orderby を呼び出す際に $savedfilter および $savedorderby を使用することで、以前と同じ ID で再取得することができます。

エンティティセットにアクセスするには、$entityset/\{entitySetID\} を使います。 例:

/rest/People/$entityset/0AF4679A5C394746BFEB68D2162A19FF

デフォルトで、エンティティセットは 2時間保存されます。$timeout に新しい値を渡すことで、タイムアウトを変更できます。 エンティティセットを使用するたびに、タイムアウトはデフォルト値または指定値にリセットされます。

4D Server のキャッシュからエンティティセットを削除したい場合には $method=release を使います。

エンティティセット内のエンティティの属性値を編集すると、それらの値が更新されます。 ただし、エンティティセットの生成に使用したクエリ条件に合致する値から合致しない値に変更したとしても、そのエンティティはエンティティセットから削除されません。 エンティティを削除した場合には、エンティティセットからも削除されます。

4D Server のキャッシュからエンティティセットが消えていた場合、10分のデフォルトタイムアウトで再作成されます。 エンティティセットが消えていた場合、再作成されるエンティティセットの内容は更新されたものです (新しくエンティティが追加されていたり、存在していたエンティティが削除されていたりする場合がありえます)。

$entityset/\{entitySetID\}?$logicOperator... &$otherCollection を使って、事前に作成した 2つのセンティティセットを統合できます。 両セットの内容を統合する (集合の和) ほか、共通のエンティティのみを返したり (集合の積) 、共通でないエンティティのみを返したり (集合の対称差) することができます。

この場合m新規のエンティティセレクションが返されます。RESTリクエストの最後に $method=entityset を追加することで新規のエンティティセットを作成することもできます。

データの計算

$compute を使って、データクラスの任意の属性について、averageや count、min、max、sum といった計算がおこなえます。 $all キーワードを使えば、全種の値を計算できます。

たとえば、一番高い給与を取得するには:

/rest/Employee/salary/?$compute=max

全種の値を計算して JSONオブジェクトとして返すには:

/rest/Employee/salary/?$compute=$all

メソッドを利用したデータ取得

RESTサービスとして公開 されている 4Dプロジェクトメソッドを呼び出すことができます。 4Dメソッドは次のものを $0 に返せます:

• オブジェクト
• コレクション

引数を受け取ってオブジェクトを返すデータクラスメソッドの例です:

// 4D findPerson メソッド
C_TEXT($1;$firstname;$2;$lastname)
$firstname:=$1
$lastname:=$2

$0:=ds.Employee.query("firstname = :1 and lastname = :2";$firstname;$lastname).first().toObject()

4Dプロジェクト側では、下図のとおりメソッドプロパティが設定されています:

この場合、次のように HTTP Request 4Dコマンドを使って REST POSTリクエストを送信できます:

C_TEXT($content)
C_OBJECT($response)

$content:="[\"Toni\",\"Dickey\"]" 

$statusCode:=HTTP Request(HTTP POST method;"127.0.0.1:8044/rest/Employee/findPerson";$content;$response)

メソッドの呼び出しについての詳細は {dataClass} を参照ください。

取得する属性の選択

RESTレスポンスにどの属性を含めて返してもらうかを指定するには、初期リクエストに属性のパスを追加します (例: Company(1)/name,revenues/)。

このフィルターは次の方法で適用できます:

オブジェクト	シンタックス	例題
データクラス	{dataClass}/{att1,att2...}	/People/firstName,lastName
エンティティのコレクション	{dataClass}/{att1,att2...}/?$filter="{filter}"	/People/firstName,lastName/?$filter="lastName='a@'"
特定のエンティティ	{dataClass}({ID})/{att1,att2...}	/People(1)/firstName,lastName
	{dataClass}:{attribute}(value)/{att1,att2...}/	/People:firstName(Larry)/firstName,lastName/
エンティティセレクション	{dataClass}/{att1,att2...}/$entityset/{entitySetID}	/People/firstName/$entityset/528BF90F10894915A4290158B4281E61

属性名はコンマ区切りで渡します (例: /Employee/firstName,lastName,salary)。 ストレージ属性およびリレーション属性を渡すことができます。

例題

エンティティを取得する際に、レスポンスに含める属性を指定する例をいくつか紹介します。

この方法は次を対象に使用できます:

• データクラス (データクラスの全エンティティまたはエンティティのコレクション)
• 特定のエンティティ
• エンティティセット

データクラスの例

次のリクエストは、People データクラス (データクラス全体または $filter の定義に応じたエンティティセレクション) から名字 (firstName) と名前 (lastName) 属性のみを取得します。

GET /rest/People/firstName,lastName/

結果:

{
    __entityModel: "People",
    __COUNT: 4,
    __SENT: 4,
    __FIRST: 0,
    __ENTITIES: [
        {
            __KEY: "1",
            __STAMP: 1,
            firstName: "John",
            lastName: "Smith"
        },
        {
            __KEY: "2",
            __STAMP: 2,
            firstName: "Susan",
            lastName: "O'Leary"
        },
        {
            __KEY: "3",
            __STAMP: 2,
            firstName: "Pete",
            lastName: "Marley"
        },
        {
            __KEY: "4",
            __STAMP: 1,
            firstName: "Beth",
            lastName: "Adams"
        }
    ]
}

GET /rest/People/firstName,lastName/?$filter="lastName='A@'"/

結果:

{
    __entityModel: "People",
    __COUNT: 1,
    __SENT: 1,
    __FIRST: 0,
    __ENTITIES: [
        {
            __KEY: "4",
            __STAMP: 4,
            firstName: "Beth",
            lastName: "Adams"
        }
    ]
}

特定エンティティの例

次のリクエストは、People データクラスの特定エンティティについて、名字 (firstName) と名前 (lastName) 属性のみを取得します。

GET /rest/People(3)/firstName,lastName/

結果:

{
    __entityModel: "People",
    __KEY: "3",
    __STAMP: 2,
    firstName: "Pete",
    lastName: "Marley"
}

GET /rest/People(3)/

結果:

{
    __entityModel: "People",
    __KEY: "3",
    __STAMP: 2,
    ID: 3,
    firstName: "Pete",
    lastName: "Marley",
    salary: 30000,
    employer: {
        __deferred: {
            uri: "http://127.0.0.1:8081/rest/Company(3)",
            __KEY: "3"
        }
    },
    fullName: "Pete Marley",
    employerName: "microsoft"

}

エンティティセットの例

エンティティセットの作成 後に、どの属性を返すかを指定して、エンティティセットの情報をフィルターできます:

GET /rest/People/firstName,employer.name/$entityset/BDCD8AABE13144118A4CF8641D5883F5?$expand=employer

画像属性の表示

画像属性の全体像を表示させるには、次のように書きます:

GET /rest/Employee(1)/photo?$imageformat=best&$version=1&$expand=photo

画像形式についての詳細は $imageformat を参照ください。 version パラメーターについての詳細は $version を参照ください。

BLOB属性のディスク保存

データクラスに保存されている BLOB をディスクに保存するには、次のように書きます:

GET /rest/Company(11)/blobAtt?$binary=true&$expand=blobAtt

1件のエンティティの取得

エンティティを 1件のみ取得したい場合には \{dataClass\}:\{attribute\}(value) シンタックスを利用できます。 これは、データクラスの主キーに基づかないリレーション検索をしたい場合に便利です。 たとえば:

GET /rest/Company:companyCode("Acme001")