§コンテンツネゴシエーション
コンテンツネゴシエーションとは、同一のリソース (URI) を複数のフォーマットで提供するためのメカニズムです。用途としては、*例えば*複数の出力フォーマット (XML, JSON など) をサポートするような Web サービスを実装する場合です。サーバ駆動のネゴシエーションは Accept*
リクエストヘッダの内容に基いて行われます。コンテンツネゴシエーションについての詳細は HTTP の仕様 を参照してください。
§言語
play.api.mvc.RequestHeader#acceptLanguages
メソッドを呼び出すと、リクエストの Accept-Language
ヘッダから、クライアント側で受付可能な言語のリストを取り出すことができます。リストは quality 値によってソートされます。Play は play.api.mvc.Controller#lang
メソッド内でこのメソッドを呼び出して、 implicit な play.api.i18n.Lang
値をアクションのスコープ内に提供しています。これによって、アクション内では常に最適な言語 (クライアントが希望している言語をあなたのアプリケーションがサポートしている場合はそれを、そうでなければアプリケーションのデフォルト言語が代わりに提供されます) を利用することができます。
§コンテンツ
同様に、 play.api.mvc.RequestHeader#acceptedTypes
メソッドを呼び出すことで、リクエストの Accept
ヘッダから、クライアント側で受付可能な MIME タイプのリストを取り出すことができます。リストは quality 値でソートされます。
実際に Accept
ヘッダに含まれているのは MIME タイプではなく メディアレンジ (*例えば* 任意のテキストを受け入れる場合は text/*
というレンジ、ありとあらゆる結果を受け入れる場合は */*
というレンジ) です。コントローラは高級な render
メソッドを提供することで、これらメディアレンジの処理を補助してくれます。例として、次のアクション定義を見てください。
val list = Action { implicit request =>
val items = Item.findAll
render {
case Accepts.Html() => Ok(views.html.list(items))
case Accepts.Json() => Ok(Json.toJson(items))
}
}
Accepts.Html()
および Accepts.Json()
は、それぞれメディアレンジが text/html
や application/json
にマッチするかをテストする抽出子です。 render
メソッドは play.api.http.MediaRange
を入力に play.api.mvc.Result
を返す PartialFunction を引数にとり、リクエストの Accept
ヘッダ内のメディアレンジに優先度順に適用します。その PartialFunction で受け入れ可能なメディアレンジが一つも存在しない場合、 NotAcceptable
という結果が返ります。
例えば、任意の型の結果を受け入れるが、 JSON を優先する、という意味である */*;q=0.5,application/json
という Accept
ヘッダを持つリクエストをクライアントが送信したとします。この場合、前述のコードは JSON
形式の結果を返します。一方、XML のみ受け付けるという意味である Accept
ヘッダ application/xml
を含むリクエストを他のクライアントが送信したとすると、 NotAcceptable
を返します。
§リクエスト抽出子
play.api.mvc.AcceptExtractors.Accepts
オブジェクトの API ドキュメントには、 Play が始めからから render
メソッドでサポートしている MIME タイプの一覧が掲載されています。さらに、 play.api.mvc.Accepting
ケースクラスを使うと、任意の MIME タイプに対応する独自の抽出子を実装することができます。例えば、メディアレンジが audo/mp3
MIME タイプにマッチするかどうかをチェックする抽出子は、次のように定義します。
val AcceptsMp3 = Accepting("audio/mp3")
...
render {
case AcceptsMp3() => ...
}
次ページ: 非同期 HTTP プログラミング
このドキュメントの翻訳は Play チームによってメンテナンスされているものではありません。 間違いを見つけた場合、このページのソースコードを ここ で確認することができます。 ドキュメントガイドライン を読んで、お気軽にプルリクエストを送ってください。