$resource

概要

RESTfulによるサーバサイドとのデータ受け渡しを行うresourceオブジェクトを作成するファクトリーです。

返されたresourceオブジェクトは、低階層の$httpサービスによる受け渡しを必要としない、 高階層の振る舞いを提供するアクションメソッドを持ちます。

使用するには、ngResourceモジュールのインストールが必要になります。

依存関係

使用方法

$resource(url[, paramDefaults][, actions]);
引数 説明
url

型:string

/user/:usernameのような:プレフィックス付きのURLテンプレートを指定します。 もし、ポート番号付きのURL(http://example.com:8080/api)を使用する場合は、それを尊重します。

もし、接尾辞付きのURLを使用する場合、
$resource('http://example.com/resource.json')
$resource('http://example.com/:id.json')
$resource('http://example.com/resource/
:resource_id.:format')のように接頭辞を追加します。 もし、接頭辞の前がパラメータが空の場合(このケースでは:resource_id)、 /.は単一の.(ドット)に崩れてしまいます...(翻訳に自信なし) もし、この状況が発生してしまうが崩さないことが必要とされる場合は、 /\..としてエスケープすることが出来ます。

paramDefaults
(任意)

型:Object

URLのパラメータのデフォルトの値を指定します。 これらは、アクションメソッドで上書きする事が可能です。 もし、パラメータのいずれかが関数であれば、 パラメータ値がリクエストの取得を必要とする度に実行されます。 (パラメータが上書きされない限り)

パラメータオブジェクトの各キーの値は、最初のURLテンプレートへバインドされ、 もし提供されたキーに余るキーがあれば、URLの検索クエリーとして?の後ろに追加されます。

テンプレート/path/:verbと、パラメータ{verb:'greet', salutation:'Hello'}が与えられると、 URLは閣下的に、/path/greet?salutation=Helloになります。

もしパラメータの値に接頭辞として@が付いていた場合、 そのパラメータの値は、データオブジェクトから抽出されます。(GETを使用しない操作で便利です。)

actions
(任意)

型:Object.<Object>

resourceのデフォルトに設定されているアクションを拡張する、カスタムアクションの宣言付きのハッシュです。 この宣言は$http.configのフォーマットで作られているべきです。

{action1: {method:?, params:?, isArray:?, headers:?, ...},
 action2: {method:?, params:?, isArray:?, headers:?, ...},
 ...}
action – {string}
アクション名を指定します。 この名前は、resourceオブジェクト上のメソッド名になります。
method – {string}
HTTPリクエストメソッドを指定します。 有効なメソッドは、GETPOSTPUTDELETEJSONPです。
params – {Object=}
このアクションのために、事前にバインドされたパラメータオプションのセットです。 もし、パラメータ値のいずれかが関数の場合、 パラメータ値がリクエストの取得が必要になる度に、実行されます。 (パラメータが上書きされない限り)
url – {string}
指定されたアクションURLを上書きします。 このURLテンプレートは、resource層のURLのようにサポートされます。
isArray – {boolean=}
もし、trueが指定されると、このアクションのために返されるオブジェクトが配列になります。 詳細は、このページの戻り値の項目を確認してください。
transformRequest – {function(data, headersGetter)|Array.<function(data, headersGetter)>}
変換関数、またはそのような関数の配列を指定します。 変換関数はhttpリクエストボディとヘッダーを取得し、 それらを変換した(通常はシリアライズ)ものを返します。
transformResponse – {function(data, headersGetter)|Array.<function(data, headersGetter)>}
変換関数、またはそのような関数の配列を指定します。 変換関数はhttpレスポンスボディとヘッダーを取得し、 それらを変換した(通常はシリアライズ)ものを返します。
cache – {boolean|Cache}
もしtrueが設定されると、デフォルトで$httpのキャッシュはGETリクエストをキャッシュするのに使用され、 そうでなければ、もしキャッシュのインスタンスが$cacheFactoryで作られれば、このキャッシュが使用されます。
timeout – {number|Promise}
タイムアウトをミリ秒で、またはresolve時にリクエストを中止するpromiseを指定します。
withCredentials - {boolean}
XHRオブジェクトのwithCredentialsフラグを設定するか否かを指定します。 詳細は、requests with credentialsを確認してください。
responseType - {string}
responseTypeを確認してください。
interceptor - {Object=}
インターセプター(interceptor)オブジェクトは、2つの任意のメソッドresponseresponseErrorを持ちます。 どちらのメソッドのインターセプターも、httpのresponseオブジェクトで呼び出されます。 $httpのinterceptorを確認してください。
戻り値 説明
 

型:Object

resourceのアクションが設定された、デフォルトのresource"クラス"(オブジェクト志向としての意味の)のオブジェクトが返ります。 resourceのアクションは任意でカスタムアクションで拡張することが出来ます。 デフォルトで設定されているアクションは、下記の通りです。

{ 'get':    {method:'GET'},
  'save':   {method:'POST'},
  'query':  {method:'GET', isArray:true},
  'remove': {method:'DELETE'},
  'delete': {method:'DELETE'} };

これらのメソッドの呼び出しは、指定したhttpメソッド、遷移先、パラメータを踏まえて、ng.$httpを実行します。 データがサーバから返されるオブジェクトは、resourceクラスのインスタンスになります。 save、remove、deleteは$接頭辞付きのメソッドとして利用することが出来ます。 これは、サーバ側と連携した下記のようなCRUD(create、read、update、delete)を簡単に実装出来るようにしてくれます。

var User = $resource('/user/:userId', {userId:'@id'});
var user = User.get({userId:123}, function() {
  user.abc = true;
  user.$save();
});

$resourceオブジェクトのメソッドの実行は、すぐに空の参照(isArrayによるとオブジェクト、または配列)を返すことを理解しておくことは重要です。 サーバからデータが返されると、参照先に実際のデータが入ります。 これは、通常resourceはビューに描画されているモデルに割り当てられているため、便利です。 空のオブジェクトであれば結果的に描画はされず、サーバからデータが取得されると、 オブジェクトにそのデータが入り、ビューは自動的にその新しいデータを表示するための再描画を行います。 これは、ほとんどの場合、アクションメソッドのためのコールバック関数を書く必要が無いことを意味します。

クラスオブジェクト、またはインスタンスオブジェクトのアクションメソッドは、 下記のパラメータ付きで実行することが可能です。

  • HTTP GET "class" actions: Resource.action([parameters], [success], [error])
  • non-GET "class" actions: Resource.action([parameters], postData, [success], [error])
  • non-GET instance actions: instance.$action([parameters], [success], [error])

successコールバックは、(value, responseHeaders)引数付きで呼び出されます。 errorコールバックは、(httpResponse)引数付きで呼び出されます。

クラスのアクションは、空のインスタンス(下記の追加プロパティを持つ)を返します。 インスタンスのアクションは、アクションのpromiseを返します。

resourceのインスタンスとコレクションは、下記の追加のプロパティを持ちます。

$promise

このインスタンスまたはコレクションを作成した、元々のサーバとの受け渡しをした$promiseです。

successの場合、promiseは同じresourceインスタンスまたはコレクションオブジェクトでresolveされ、 サーバからのデータで更新されます。 これは、resourceが読み込まれるまでビューの描画を延期するための$routeProvider.when()のresolveを容易にしてくれます。

失敗すると、promiseはhttpレスポンスオブジェクト有り、resourceプロパティ無しでresolveされます。

$resolved
trueなら最初のサーバとの受け渡しが完了(successでもrejectでも)した後、 falseならその前になります。 resourceが解決された否かを知ることは、データバインディングにおいて有用なことです。

サンプル

resourceを使用したクレジットカードの例

// クレジットカードクラスを定義
var CreditCard = $resource('/user/:userId/card/:cardId',
 {userId:123, cardId:'@id'}, {
  charge: {method:'POST', params:{charge:true}}
 });

// サーバから情報を取得
var cards = CreditCard.query(function() {
  // GET: /user/123/card
  // server returns: [ {id:456, number:'1234', name:'Smith'} ];

  var card = cards[0];
  // 各項目は、CreditCardのインスタンス
  expect(card instanceof CreditCard).toEqual(true);
  card.name = "J. Smith";
  // GETではないメソッドが、インスタンスにマッピングされます
  card.$save();
  // POST: /user/123/card/456 {id:456, number:'1234', name:'J. Smith'}
  // サーバから返される値: {id:456, number:'1234', name: 'J. Smith'};

  // 同様にカスタムメソッドをマッピング。
  card.$charge({amount:9.99});
  // POST: /user/123/card/456?amount=9.99&charge=true {id:456, number:'1234', name:'J. Smith'}
});

// 同じ様にインスタンスを作成することが出来ます。
var newCard = new CreditCard({number:'0123'});
newCard.name = "Mike Smith";
newCard.$save();
// POST: /user/123/card {number:'0123', name:'Mike Smith'}
// サーバから返される値: {id:789, number:'01234', name: 'Mike Smith'};
expect(newCard.id).toEqual(789);

この関数による実行から返されたオブジェクトは、 各アクションを定義するための"静的な"メソッドを持つresourceの"クラス"です。

これらのメソッドの呼び出しは、与えられたメソッド、パラメータ、ヘッダーでURLテンプレート上の$httpを実行します。 サーバからデータが返ると、そのオブジェクトはresource型のインスタンスであり、 non-GETメソッドの全てが$接頭辞付きで利用可能になります。 これは、サーバサイドのデータのCRUD操作(create、read、update、delete)を簡易的に行えるようにサポートしてくれます。

var User = $resource('/user/:userId', {userId:'@id'});
var user = User.get({userId:123}, function() {
  user.abc = true;
  user.$save();
});

get、queryとその他のサーバからのレスポンス内で渡されたものを取得するメソッドのためのsuccessコールバックは、 $httpヘッダーのgetter関数と同様であるため、上記のサンプルを下記のように書き換えることが可能で、 getでhttpヘッダーにアクセスしてます。(翻訳に自信なし) このことを覚えておくと良いかもしれません。

var User = $resource('/user/:userId', {userId:'@id'});
User.get({userId:123}, function(u, getResponseHeaders){
  u.abc = true;
  u.$save(function(u, putResponseHeaders) {
    //u => 保存したuserオブジェクト
    //putResponseHeaders => $http header getter
  });
});

 Back to top

© 2017 Google
Licensed under the Creative Commons Attribution License 3.0.

このページは、ページトップのリンク先のAngularJS公式ドキュメント内のページを翻訳した内容を基に構成されています。 下記の項目を確認し、必要に応じて公式のドキュメントをご確認ください。 もし、誤訳などの間違いを見つけましたら、 @tomofまで教えていただければ幸いです。

  • AngularJSの更新頻度が高いため、元のコンテンツと比べてドキュメントの情報が古くなっている可能性があります。
  • "訳注:"などの断わりを入れた上で、日本人向けの情報やより分かり易くするための追記を行っている事があります。