§コンテンツネゴシエーション

コンテンツネゴシエーションとは、同一のリソース (URI) を複数のフォーマットで提供するためのメカニズムです。用途としては、 例えば 複数の出力フォーマット (XML, JSON など) をサポートするような Web サービスを実装する場合です。サーバ駆動のネゴシエーションは Accept* リクエストヘッダの内容に基いて行われます。コンテンツネゴシエーションについての詳細は HTTP の仕様を参照してください。

§言語

play.api.mvc.RequestHeader#acceptLanguages メソッドを呼び出すと、リクエストの Accept-Language ヘッダから、クライアント側で受付可能な言語のリストを取り出すことができます。リストは quality 値によってソートされます。Play は play.api.mvc.Controller#lang メソッド内でこのメソッドを呼び出して、暗黙の値 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 という結果が返ります。

例えば、クライアントが */*;q=0.5,application/json という Accept ヘッダを持つリクエストを送信したとします。これは、任意の型の結果を受け入れるが JSON を優先する、という意味で、この場合、上記のコードは JSON 形式の結果を返します。同様に、クライアントが application/xml という Accept ヘッダを持つリクエストを送信したとします。これは、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() => ???
  }
}

Next: エラーハンドリング

このドキュメントの翻訳は Play チームによってメンテナンスされているものではありません。間違いを見つけた場合、このページのソースコードをここで確認することができます。ドキュメントガイドラインを読んで、お気軽にプルリクエストを送ってください。