リモートメソッド

概要

リモートメソッド は、独自のRESTエンドポイントを通じて公開される、モデルのメソッドです。 LoopBackの標準モデルREST APIで提供されていない操作を行うには、リモートメソッドを使います。

モデルにリモートメソッドを追加する方法

モデルにリモートメソッドを追加するには、以下のようにします。

1. モデル拡張ファイル に関数を作成します。メソッド名によってリモートメソッドが静的メソッドかインスタンスメソッドか決まります。メソッド名がprototype.で始まるものは、インスタンスメソッドになります。さもなくば、静的メソッドになります。注：既定では、リモートメソッドは静的です。インスタンスメソッドを作るには、メソッド名の先頭にprototype.を指定しなければなりません。

2. 以下の方法のいずれかで、リモートメソッドを登録します。

   • モデル定義JSONファイルで、JSONを使って登録する。 詳しくは JSONにリモートメソッドを登録するを参照してください。
   • モデル拡張ファイル で、JavaScriptを使って remoteMethod() を呼出して登録する。 詳しくは、リモートメソッドをコードで登録する を参照してください。

例

Perosonモデルが既に存在し、/greet というエンドポイントを追加して、リクエストで与えられた名前に対して挨拶を返すようにしたいとします。 /common/models/person.jsに以下のようなコードを追加してください。

module.exports = function(Person){

    Person.greet = function(msg, cb) {
      cb(null, 'Greetings... ' + msg);
    }

    Person.remoteMethod('greet', {
          accepts: {arg: 'msg', type: 'string'},
          returns: {arg: 'greeting', type: 'string'}
    });
};

そして、例えば、以下のURLに対して、

POST /api/people/greet

{"msg": "John"} というデータを送信すると、以下のような応答が得られるはずです。

Greetings... John!

リモートメソッドを登録する

リモートメソッドを登録する方法は２つあります。

• モデル拡張ファイル (modelName.js) に コードで。
• モデル定義JSONファイル (modelName.json) にJSONで。

コードでリモートメソッドを登録する

LoopBack のモデルはremoteMethod() という、リモートメソッドを登録する静的メソッドを持っています。

Model.remoteMethod(requestHandlerFunctionName, [options])

ここで、

• model は、リモートメソッドを追加したいモデルオブジェクトです。例えば Person などです。
• requestHandlerFunctionName はリモートメソッドの名前を指定する文字列です。例えば 'greet' などです。
• options は、RESTエンドポイントを設定するパラメータを指定するオブジェクトです。以下の オプション を参照してください。

JSONでリモートメソッドを登録する

モデル定義JSONファイル でリモートメソッドを登録するには、 methods キーの下にメソッド名を追加します。インスタンスメソッドを定義するには、メソッド名の前にprototype.をつけてください。

"methods": {
    "prototype.getProfile": {
      "accepts": [],
      "returns": { "arg": "data", "type": "User", "root": true},
      "http": {"verb": "get", "path": "/profile"},
      "accessScopes": ["read", "read:profile"]
    },
    "someStaticMethod" : { ... }

methodsのは以下にあるそれぞれのキーの値は、以下で説明するオプションオブジェクトです。

オプション

オプション引数は、リモートメソッドがどのように動作するかを定義するJavaScriptオブジェクトです。

Person.greet(name, age, callback)...

{  ...
accepts: [
 {arg: 'name', type: 'string'},
 {arg: 'age',  type: 'number'},
 ...],
... }

accessScopes: [
  'read',
  'read:user'
]

returns: {arg: 'greeting',
          type: 'string'}

[
 "Lorem ipsum dolor sit amet, consectetur adipiscing elit,",
 "sed do eiusmod tempor incididunt ut labore et dolore",
 "magna aliqua."
]

http プロパティ

http プロパティは、リモートメソッドが公開されるHTTPルートについての情報を提供します。

http: {path: '/sayhi'}

http: {path: '/sayhi',
       verb: 'get'}

http: {status: 201}

http: {errorStatus: 400}

引数の説明

acceptsと returnsオプションのプロパティは、単一の引数をオブジェクトとして、または順序付けされた引数のセットを配列として定義します。 次の表は、個々の引数のプロパティを示しています。

例えば、単一の引数はオブジェクトで以下のように指定できる。

{arg: 'myArg', type: 'number'}

複数の引数は、配列で指定する。

[
  {arg: 'arg1', type: 'number', required: true},
  {arg: 'arg2', type: 'array'}
]

ファイル(ストリーム)レスポンスを返す。

コールバック引数として、{ type: 'file', root: true }を指定すると、レスポンスボディを直接送信できる。 ファイル引数は以下のいずれかの値に設定できる。

• String
• Buffer
• ReadableStream (.pipe() メソッドがあるものなら何でも可)

例：

module.exports = function(MyModel) {
  MyModel.download = function(cb) {
    // getTheStreamBody() can be implemented by calling http.request() or fs.readFile() for example
    getTheStreamBody(function(err, stream) {
      if (err) return cb(err);
      // stream can be any of: string, buffer, ReadableStream (e.g. http.IncomingMessage)
      cb(null, stream, 'application/octet-stream');
    });
  };

  MyModel.remoteMethod('download', {
    returns: [
      {arg: 'body', type: 'file', root: true},
      {arg: 'Content-Type', type: 'string', http: { target: 'header' }}
    ]
  });
};

入力引数と HTTP の紐付け

There are two ways to specify HTTP mapping for input parameters (what the method accepts): HTTPと（メソッドが受け付ける）入力パラメータの紐付けを指定する方法が２つあります。

• source プロパティを持つオブジェクトを提供する。
• 独自のマッピング関数を指定する。

sourceプロパティを持つオブジェクトを指定する

入力パラメータとHTTPの紐付けに最初の方法を使うには、以下の表に示す値の一つを持つsourceプロパティのあるオブジェクトを提供します。

例えば、リクエストボディ全体を受け取る引数は以下のように指定します。

{ arg: 'data', type: 'object', http: { source: 'body' } }

ExpressのHTTPリクエストとレスポンスオブジェクトを使用する例は以下のとおりです。

[
 {arg: 'req', type: 'object', 'http': {source: 'req'}},
 {arg: 'res', type: 'object', 'http': {source: 'res'}}
]

独自のマッピング関数を使う

入力パラメータとHTTPの紐付けを指定する２つ目の方法は、独自のマッピング関数を指定するものです。例えば、以下のようにします。

{
  arg: 'custom',
  type: 'number',
  http: function(ctx) {
    // ctx is LoopBack Context object

    // 1\. Get the HTTP request object as provided by Express
    var req = ctx.req;

    // 2\. Get 'a' and 'b' from query string or form data and return their sum.
    return -req.param('a') - req.param('b');
  }
}

マッピングを指定しない場合、LoopBackは値を以下のようにさばきます。（nameは、解決すべき入力パラメータに名前とします）

1. HTTPリクエストパラメータ args がJSONの中にある場合、それは、args['name'] として扱います。
2. さもなくば、req.param('name')として使います。

JSONフィールドにないデータを返す。

arg プロパティのある return 引数を指定すると、自動的に 同じ名前のフィールドにデータが格納されたJSONオブジェクトを返します。

メインのレスポンスとして、例えば配列のようなデータを返したい場合、 root プロパティを持つオブジェクトを設定し、arg を消去することで可能です。

returns: {type: 'array', root: true}

リモートメソッドルートを指定する

既定では、リモートメソッドは以下のURLで公開されます。

POST http://apiRoot/modelName/methodName

ここで、

• apiRoot  はアプリケーションのAPI最上位パスです。
• modelName はモデル名の複数形です。
• methodName は関数の名前です。

上の例に従うと、リモートメソッドは以下のように公開されます。

POST /api/people/greet

ルートを変更するには、remoteMethod() に渡すオプションの http.path と http.verb プロパティを使います。例えば以下のようにします。

Person.remoteMethod('greet',{
  accepts: {arg: 'msg', type: 'string'},
  returns: {arg: 'greeting', type: 'string'},
  http: {path: '/sayhi', verb: 'get'}
});

こうすることで、ルートが以下のように変更されます。

GET /api/people/sayhi

すると、 http://localhost:3000/api/people/sayhi?msg=LoopBack%20developer への GETリクエストは、以下のような値を返します。

{"greeting": "Greetings... LoopBack developer"}

リモートメソッドにACLを追加する

独自のリモートメソッドへのアクセスを制限するには、他のAPIへのアクセス制御と同様に、ACL生成ツールを使います。 独自のリモートメソッドをアクセス種別は「Execute」です。

基本的な使い方

たとえば、上の例で使った greet メソッドの呼出しを禁止する場合、以下のようにします。

$ lb acl
[?] Select the model to apply the ACL entry to: Person
[?] Select the ACL scope: A single method
[?] Enter the method name: greet
[?] Select the access type: Execute
[?] Select the role: All users
[?] Select the permission to apply: Explicitly deny access

これで、以下のようなアクセス制御設定が作成されます。

...
"acls": [{
  "principalType": "ROLE",
  "principalId": "$everyone",  // 全員にACLを適用する
  "permission": "DENY",        // メソッド呼び出しを拒否する
  "property": "greet"          // greet() メソッドにアクセス制御を適用する
}],
...

進んだ使い方

他の例として、リモートメソッドの呼出しをモデルの $owner に限定するには以下のようにします。

module.exports = function(YourModel) {
  //...
  YourModel.remoteMethod(
    'someRemoteMethod',
    {
      accepts: [
        {arg: 'id', type: 'number', required: true}
      ],
      // ':id' を RESTのURLに入れることで、 $owner を判断してアクセス制御が行えるようにする
      http: {path: '/:id/some-remote-method', verb: 'get'}
    }
  );
};

リモートメソッドのレスポンスを整形する

起動スクリプトにapp.remotes()が 返すオブジェクトを修正する処理を追加することで、全てのリモートメソッドの戻り値を整形することができます。

module.exports = function(app) {
  var remotes = app.remotes();
  // 全ての戻り値を修正する
  remotes.after('**', function (ctx, next) {
    ctx.result = {
      data: ctx.result
    };

    next();
  });
};

リモートメソッドを無効化する

リモートメソッドを無効化するには、Model.disableRemoteMethod(name, isStatic) と Model.disableRemoteMethodByName(name) を使います。詳細は以下を参照してください。

• Model.disableRemoteMethod
• Model.disableRemoteMethodByName