バージョン: 20 R7 BETA

データ操作

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

データのクエリ

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

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

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

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

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

{dataClass}({key}) でデータクラスのいちエンティティを取得する以外にも、エンティティセレクションやコレクションを返すクラス関数を用意することもできます。

戻り値としてセレクションを返す前に、$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 を使います。

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

エンティティを削除した場合には、エンティティセットからも削除されます。しかし、デフォルトでは、参照は undefined の値でエンティティセットに残り、エンティティセットの要素数として引き続き含まれます。エンティティセットに対して$clean を呼び出すと、undefined なエンティティ参照が含まれない、最新のエンティティセットを新規に作成できます。

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

データモデルクラス関数の呼び出し

POSTリクエストを使って、ORDAデータモデルのユーザークラス関数を呼び出すことで、ターゲットアプリケーションの公開API を活用できます。たとえば、City DataClassクラスに getCity() 関数を定義した場合、次のリクエストで呼び出すことができます:

/rest/City/getCity

データはリクエストボディに含めます: ["Paris"]

RESTサービスとして公開された 4Dプロジェクトメソッドへの呼び出しは引き続きサポートされていますが、廃止予定となっています。

取得する属性の選択

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

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

Object	シンタックス	例題
データクラス	{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 を参照ください。

BLOB属性のディスク保存

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

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

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

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

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

データのクエリ​

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

データのナビゲーション​

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

データの計算​

データモデルクラス関数の呼び出し​

取得する属性の選択​

例題​

データクラスの例​

特定エンティティの例​

エンティティセットの例​

画像属性の表示​

BLOB属性のディスク保存​

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