§HTTP ルーティング

§ビルトイン HTTP ルータ

ルータとは、送られてきた HTTP リクエストをそれぞれ対応するアクションの呼び出しに変換する役割を持つコンポーネントです。

HTTP リクエストは MVC フレームワークにとってはイベントであるといえます。このイベントには、次の２つの重要データが含まれています。

• クエリストリングを含むリクエストパス (例えば、 clients/1542 、 /photos/list)
• HTTP メソッド (例えば、 GET 、 POST 、 …)

ルートは conf/routes ファイル内に定義され、コンパイルされます。したがって、ルート定義のエラーはブラウザ上ですぐ確認できます。

§ルートファイルの文法

conf/routes はルータによって利用される設定ファイルです。このファイルにはアプリケーションの全てのルートの一覧があります。各ルートは HTTP メソッドと URI パターン、そしてその２つが関連付けられた Action ジェネレータで構成されています。

ルート定義を例を見てみましょう。

GET   /clients/:id          controllers.Clients.show(id: Long)  

各ルートの先頭は HTTP メソッドで、次が URI パターンです。最後の要素は呼び出し定義 (call definition) と呼ばれます。

# から始まるコメント行を書くこともできます。

# Display a client.
GET   /clients/:id          controllers.Clients.show(id: Long)  

§HTTP メソッド

HTTP メソッドには HTTP がサポートする有効なメソッド (GET, POST, PUT, DELETE, HEAD) が全て使えます。

§URI パターン

URI パターンはルートのリクエストパスを定義します。リクエストパスの各パートはそれぞれ動的にマッチさせることができます。

§静的パス

例えば、 GET /clients/all へのリクエストだけをマッチさせたい場合、次のようなルートになります。

GET   /clients/all              controllers.Clients.list()

§動的パート

例えば、クライアント ID を受け取るようなルートを定義する場合、次のような動的パートを使うことができます。

GET   /clients/:id          controllers.Clients.show(id: Long)  

一つの URI パターンには、複数の動的パートを含められます

動的パートをマッチ方法は、デフォルトでは [^/]+ という正規表現になっています。したがって、 :id のように定義した動的パートは、ちょうど一つの URI パートにマッチします。

§複数の / をまたぐ動的パート

/ から始まる複数の URI パスセグメントをキャプチャする動的パートを定義したい場合、 *id という文法を使った動的パートが使えます。これには .* という正規表現が使われます。

GET   /files/*name          controllers.Application.download(name)  

GET /files/images/logo.png のようなリクエストについて、 name という動的パートは images/logo.png という値をキャプチャします。

§動的パーツに使う正規表現のカスタマイズ

動的パートに独自の正規表現を使うためには、$id<regex>という構文を使って次のような定義をします。

GET   /clients/$id<[0-9]+>  controllers.Clients.show(id: Long)  

§アクションジェネレータメソッドの呼び出し

ルート定義の最後の部分は、アクションの呼び出しです。この部分には play.api.mvc.Action 型の値を返すようなメソッドの有効な呼び出しを書くことになっています。通常は、コントローラのアクションメソッドを呼び出すことになるでしょう。

メソッドに一つもパラメータが存在しない場合、単にメソッドの完全修飾名を書きます。

GET   /                     controllers.Application.homePage()

アクションメソッドにパラメータが存在する場合は、全てのパラメータがリクエスト URI から検索され、 URI パス部分かクエリストリングのいずれかから抽出されることになります。

# Extract the page parameter from the path.
GET   /:page                controllers.Application.show(page)

または

# Extract the page parameter from the query string.
GET   /                     controllers.Application.show(page)

上記のルートに対応する controllers.Application コントローラの show メソッドは次のとおりです。

def show(page: String) = Action {
    loadContentFromDatabase(page).map { htmlContent =>
        Ok(htmlContent).as("text/html")
    }.getOrElse(NotFound)
}

§パラメータの型

String 型のパラメータについては、型は指定しなくても構いません。しかし、送られてきたパラメータを Play に他の型へ変換させたい場合は、パラメータの型を明記する必要があります。

GET   /client/:id           controllers.Clients.show(id: Long)

対応する controllers.Clients コントローラの show メソッドにも同様の型を定義します。

def show(id: Long) = Action {
    Client.findById(id).map { client =>
        Ok(views.html.Clients.display(client))
    }.getOrElse(NotFound)
}

§パラメータに固定値を渡す

パラメータに固定値を渡したい場合は、次のようにします。

# Extract the page parameter from the path, or fix the value for /
GET   /                     controllers.Application.show(page = "home")
GET   /:page                controllers.Application.show(page)

§パラメータにデフォルト値を設定する

送信されてきたリクエストに値が存在しない場合にデフォルト値を使うためには、次のようにします。

# Pagination links, like /clients?page=3
GET   /clients              controllers.Clients.list(page: Int ?= 1)

§省略可能なパラメータ

必ずしもリクエストに含まれていなくてもよい省略可能なパラメータを定義するためには、次のようにします。

# The version parameter is optional. E.g. /api/list-all?version=3.0
GET   /api/list-all         controllers.Api.list(Option[version])

§ルートの優先度

同じリクエストに複数のルートがマッチする可能性もあります。そのようなルートの競合が起こった場合、 (定義した順番が) 最初のルートが利用されます。

§リバースルーティング

ルータは Scala から呼び出して URL を生成させるという使い方もできます。これにより、全ての URI パターンを一つの設定ファイルに集約することができ、アプリケーションのリファクタリングをより安全に行うことができるようになります。

ルータはルートファイルで使われるそれぞれのコントローラについて routes パッケージ以下に「リバースコントローラ」を生成します。リバースコントローラにはコントローラと同じシグネチャを持つ、同名のアクションメソッド定義されていますが、それぞれ play.api.mvc.Action の代わりに play.api.mvc.Call を返すようになっています。

play.api.mvc.Call は HTTP 呼び出しを表していて、 HTTP メソッドと URI が両方とも含まれてます。

例えば、次のようなコントローラを作成した場合を考えてみます。

package controllers

import play.api._
import play.api.mvc._

object Application extends Controller {
    
  def hello(name: String) = Action {
      Ok("Hello " + name + "!")
  }
    
}

そして、 conf/routes ファイルで次のようなマッピングを行ったとします。

# Hello action
GET   /hello/:name          controllers.Application.hello(name)

すると、 controllers.routes.Application リバースコントローラを利用することで、 hello アクションメソッドの URI を逆引きすることができます。

// Redirect to /hello/Bob
def helloBob = Action {
    Redirect(routes.Application.hello("Bob"))    
}

次ページ: レスポンスの操作