クラス関数の呼び出し
You can call data model class functions defined for the ORDA Data Model and singleton class functions through REST requests, so that you can benefit from the exposed API of the targeted 4D application.
Functions can be called in two ways:
- using POST requests, with data parameters passed in the body of the request.
- using GET requests, with parameters directly passed in the URL.
POST requests provide a better security level because they avoid running sensitive code through an action as simple as clicking on a link. However, GET requests can be more compliant with user experience, allowing to call functions by entering an URL in a browser (note: the developer must ensure no sensitive action is done in such functions).
関数の呼び出し
The following ORDA and singleton functions can be called in REST:
クラス関数 | シンタックス |
---|---|
DataStore クラス | /rest/$catalog/DataStoreClassFunction |
DataClass クラス | /rest/\{dataClass\}/DataClassClassFunction |
EntitySelection クラス | /rest/\{dataClass\}/EntitySelectionClassFunction |
/rest/{dataClass}/EntitySelectionClassFunction/$entityset/entitySetNumber | |
/rest/{dataClass}/EntitySelectionClassFunction/$filter | |
/rest/{dataClass}/EntitySelectionClassFunction/$orderby | |
Entity クラス | /rest/{dataClass}(key)/EntityClassFunction/ |
シングルトンクラス | /rest/$singleton/SingletonClass/SingletonClassFunction ($singleton ページ 参照) |
/rest/{dataClass}/Function
can be used to call either a dataclass or an entity selection function (/rest/{dataClass}
returns all entities of the DataClass as an entity selection). EntitySelection クラスの関数が先に探されます。 見つからない場合に、DataClassクラスを探します。 つまり、同じ名称の関数が DataClassクラスと EntitySelectionクラスの両方に定義されている場合、DataClassクラスの関数が実行されることはありません。
Functions are simply called on the appropriate ORDA interface or singleton class, without (). Parameters are passed either in the body of the POST request (POST
calls) or in the params
collection in the URL (GET
calls).
たとえば、City DataClassクラスに getCity()
関数を定義した場合、次のリクエストで呼び出すことができます:
POST request
/rest/City/getCity
POST リクエストのボディに関数に渡す引数を含めます: ["Aguada"]
GET request
/rest/City/getCity?$params='["Aguada"]'
The getCity()
function must have been declared with the onHttpGet
keyword (see Function configuration below).
この呼び出しは、4Dランゲージでは次のステートメントに相当します:
$city:=ds.City.getCity("Aguada")
Function configuration
exposed
All functions allowed to be called directly from HTTP REST requests (POST
or GET
) must be declared with the exposed
keyword. 例:
exposed Function getSomeInfo() : 4D.OutgoingMessage
See Exposed vs non-exposed functions section.
onHttpGet
Functions allowed to be called from HTTP GET
requests must also be specifically declared with the onHttpGet
keyword. 例:
//allowing GET requests
exposed onHttpGet Function getSomeInfo() : 4D.OutgoingMessage
Thread-safe
プロジェクトがコンパイル済みモードで実行される場合、RESTサーバーは常にプリエンプティブプロセスを使用するため、RESTリクエストから呼び出されるすべての 4Dコードは スレッドセーフでなければなりません (プリエンプティブプロセスを使用 の設定値 は、RESTサーバーによって無視されます)。
You can restrict calls to specific ORDA functions by configuring appropriate privileges in the roles.json file.
引数
You can send parameters to functions defined in ORDA user classes or singletons. サーバーサイドでこれらの引数は、クラス関数の 宣言されたパラメーター に受け渡されます。
次のルールが適用されます:
- In functions called through POST requests, parameters must be passed in the body of the POST request.
- In functions called through GET requests, parameters must be passed in the URL with "?$params=" syntax.
- Parameters must be enclosed within a collection (JSON format).
- JSON コレクションがサポートしているスカラーなデータ型はすべて引数として渡せます。
- エンティティやエンティティセレクションも引数として受け渡せます。 The parameter list must contain specific attributes used by the REST server to assign data to the corresponding ORDA objects:
__DATACLASS
,__ENTITY
,__ENTITIES
,__DATASET
.
エンティティを引数として受け取る例題 と エンティティセレクションを引数として受け取る例題 を参照ください。
スカラー値の引数
Scalar value parameter(s) must simply be enclosed in a collection. 引数としてサポートされるのは、JSONポインターを含むすべての JSON のデータ型です。 日付は ISO 8601形式の文字列として渡せます (例: "2020-08-22T22:00:000Z")。
For example, with a dataclass function getCities()
receiving text parameters:
POST request
/rest/City/getCities
ボディの引数: ["Aguada","Paris"]
GET request
/rest/City/getCities?$params='["Aguada","Paris"]'
エンティティ引数
引数として渡されたエンティティは、キー (__KEY プロパティ) によってサーバー上で参照されます。 If the key parameter is omitted in a request, a new entity is loaded in memory on the server. エンティティが持つ属性について、値を受け渡すことも可能です。 サーバー上でこれらの値は自動的に当該エンティティ用に使用されます。
サーバー上の既存エンティティについて変更された属性値をリクエストが送信した場合、呼び出した ORDAデータモデル関数は自動的に変更後の値で実行されます。 この機能によって、たとえばエンティティに対する処理の、すべてのビジネスルールを適用した後の結果をクライアントアプリケーションから確認することが可能です。 その結果をもとにエンティティをサーバー上で保存するかどうかを判断できます。
プロパティ | 型 | 説明 |
---|---|---|
エンティティの属性 | mixed | 任意 - 変更する値 |
__DATACLASS | String | 必須 - エンティティのデータクラスを指定します |
__ENTITY | ブール | 必須 - true は引数がエンティティであることをサーバーに通知します |
__KEY | 混合 (プライマリーキーと同じ型) | 任意 - エンティティのプライマリーキー |
- If
__KEY
is not provided, a new entity is created on the server with the given attributes. - If
__KEY
is provided, the entity corresponding to__KEY
is loaded on the server with the given attributes
See examples for creating or updating entities with POST requests. See an example of contents downloading using an entity with a GET request.
リレートエンティティ引数
エンティティ引数 と同じプロパティを持ちます。 異なる点は、リレートエンティティは存在していなければならないため、プライマリーキーを格納する __KEY を省略できません。
リレートエンティティを持つエンティティを 作成 または 更新 する例題を参照ください。
エンティティセレクション引数
引数として渡すエンティティセレクションはあらかじめ $method=entityset によって定義されている必要があります。
変更されたエンティティセレクションをリクエストがサーバーに送信した場合、呼び出した ORDAデータモデル関数は自動的に変更後のエンティティセレクションで実行されます。
プロパティ | 型 | 説明 |
---|---|---|
エンティティの属性 | mixed | 任意 - 変更する値 |
__DATASET | String | 必須 - エンティティセレクションのエンティティセットID (UUID) |
__ENTITIES | ブール | 必須 - true は引数がエンティティセレクションであることをサーバーに通知します |
See example for receiving an entity selection with a POST request. See example for getting a list built upon an entity selection with a GET request.
POST request examples
このデータベースは、localhost (ポート8111) 上でリモートデータストアーとして公開されています。
データストアークラス関数を使用する
US_Cities DataStore
クラスは API を提供しています:
// DataStore クラス
Class extends DataStoreImplementation
exposed Function getName() : Text
return "US cities and zip codes manager"
次のリクエストを実行します:
POST 127.0.0.1:8111/rest/$catalog/getName
戻り値
{
"result": "US cities and zip codes manager"
}
DataClassクラス関数を使用する
City
の DataClassクラスは、引数として受け取った名前をもとに City エンティティを返す API を提供しています:
// Cityクラス
Class extends DataClass
exposed Function getCity($city : Text ) : cs.CityEntity
return This.query("name = :1";$city).first()
次のリクエストを実行します:
POST 127.0.0.1:8111/rest/City/getCity
リクエストのボディ: ["Aguada"]
戻り値
結果は、次のエンティティです:
{
"__entityModel": "City",
"__DATACLASS": "City",
"__KEY": "1",
"__TIMESTAMP": "2020-03-09T08:03:19.923Z",
"__STAMP": 1,
"ID": 1,
"name": "Aguada",
"countyFIPS": 72003,
"county": {
"__deferred": {
"uri": "/rest/County(72003)",
"__KEY": "72003"
}
},
"zips": {
"__deferred": {
"uri": "/rest/City(1)/zips?$expand=zips"
}
}
}
Entityクラス関数を使用する
CityEntity
の Entityクラスは API を提供しています:
// CityEntityクラス
Class extends Entity
exposed Function getPopulation()
return This.zips.sum("population")
次のリクエストを実行します:
POST 127.0.0.1:8111/rest/City(2)/getPopulation
戻り値
{
"result": 48814
}
EntitySelectionクラス関数を使用する
CitySelection
の EntitySelectionクラスは API を提供しています:
// CitySelection クラス
Class extends EntitySelection
exposed Function getPopulation()
return This.zips.sum("population")
次のリクエストを実行します:
POST 127.0.0.1:8111/rest/City/getPopulation/?$filter="ID<3"
戻り値
{
"result": 87256
}
EntitySelectionクラス関数とエンティティセットを使用する
StudentsSelection
クラスは getAgeAverage
関数を持ちます:
// StudentsSelection クラス
Class extends EntitySelection
exposed Function getAgeAverage : Integer
var $sum : Integer
var $s : Object
$sum:=0
For each ($s;This)
$sum:=$sum+$s.age()
End for each
return $sum/This.length
あらかじめ作成した既存のエンティティセットを使い、次のリクエストを実行します:
POST 127.0.0.1:8044/rest/Students/getAgeAverage/$entityset/17E83633FFB54ECDBF947E5C620BB532
戻り値
{
"result": 34
}