検索

47.2.2. リクエスト URI からのデータの注入

download PDF

概要

RESTful Web サービスを設計するためのベストプラクティスの 1 つとして、各リソースに一意の URI を設定する必要があります。開発者はこの原則を使用して、基盤となるリソースの実装に適量の情報を提供できます。リソースの URI テンプレートを設計する場合には、開発者は、リソースの実装に注入できるパラメーター情報を含めるようにテンプレートを作成できます。また、開発者はクエリーおよびマトリックスパラメーターを使用して、情報をリソース実装にフィードすることもできます。

URI のパスからのデータ取得

リソースの URI テンプレートの作成に使用される変数でリソースに関する情報を取得することが一般的なメカニズムです。これは、javax.ws.rs.PathParam アノテーションを使用して実現されます。@PathParam アノテーションには、データの注入元となる URI テンプレート変数を識別する単一のパラメーターがあります。

例47.1「URI テンプレート変数からのデータの注入」 では、@PathParam アノテーションは URI テンプレート変数 color の値が itemColor フィールドにインジェクトされることを指定します。

例47.1 URI テンプレート変数からのデータの注入

import javax.ws.rs.Path;
import javax.ws.rs.PathParam
...

@Path("/boxes/{shape}/{color}")
class Box
{
  ...

  @PathParam("color")
  String itemColor;

  ...
}

@PathParam アノテーションでサポートされるデータ型は、「サポートされるデータタイプ」 で説明されているものとは異なります。@PathParam アノテーションがデータを注入するエンティティーは、以下の型のいずれかでなければなりません。

  • PathSegment

    値は、パスに一致する部分の最後のセグメントになります。

  • List<PathSegment>

    この値は、名前付きの template パラメーターに一致するパスセグメントに対応する PathSegment オブジェクトの一覧です。

  • intchar、または long などのプリミティブ
  • 単一の String 引数を受け入れるコンストラクターを持つオブジェクト
  • 単一の String 引数を受け入れる静的 valueOf() メソッドを持つオブジェクト

クエリーパラメーターの使用

Web に情報を渡す一般的な方法は、URI で クエリーパラメーター を使用することです。クエリーパラメーターは URI の最後に表示され、疑問符 (?) で URI のリソース場所部分から区切られます。これらは、名前と値が等号 (=) で区切られた 1 つ以上の名前と値のペアで設定されます。複数のクエリーパラメーターを指定すると、ペアはセミコロン (;) またはアンパサンド (&) で区切られます。例47.2「クエリー文字列のある URI」 は、クエリーパラメーターが含まれる URI の構文を示しています。

例47.2 クエリー文字列のある URI

http://fusesource.org?name=value;name2=value2;...
注記

セミコロンまたはアンパサンドの いずれか を使用してクエリーパラメーターを区切ることができますが、両方は使用できません。

javax.ws.rs.QueryParam アノテーションは、クエリーパラメーターの値を抽出し、それを JAX-RS リソースに注入します。アノテーションでは、パラメーターを 1 つ使用できます。このパラメーターをもとに、値の抽出、指定されたフィールド、Bean プロパティー、またはパラメーターにインジェクトされるクエリーパラメーターの名前が識別されます。@QueryParam アノテーションは、「サポートされるデータタイプ」で説明されている型をサポートします。

例47.3「クエリーパラメーターのデータを使用したリソースメソッド」 は、クエリーパラメーター id の値をメソッドの id パラメーターに注入するリソースメソッドを示しています。

例47.3 クエリーパラメーターのデータを使用したリソースメソッド

import javax.ws.rs.QueryParam;
import javax.ws.rs.PathParam;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
...

@Path("/monstersforhire/")
public class MonsterService
{
  ...
  @POST
  @Path("/{type}")
  public void updateMonster(@PathParam("type") String type,
                            @QueryParam("id") String id)
  {
    ...
  }
  ...
}

HTTP POST/monstersforhire/daikaiju?id=jonas に処理するには、updateMonster() メソッドの typedaikaiju に設定され、idjonas に設定されます。

マトリクスパラメーターの使用

URI クエリーパラメーターと同様に、URI マトリックスパラメーターは、リソース選択用の追加情報を提供できる名前と値のペアです。クエリーパラメーターとは異なり、マトリクスパラメーターは URI のどこにでも置くことができ、セミコロン (;) を使用して URI の階層パスセグメントから区別されます。/mostersforhire/daikaiju;id=jonas には id という 1 つのマトリクスパラメーターがあり、/monstersforhire/japan;type=daikaiju/flying;wingspan=40 には type および wingspan という 2 つのマトリクスパラメーターがあります。

注記

リソースの URI を計算するときには、マトリックスパラメーターは評価されません。そのため、要求 URI /monstersforhire/japan;type=daikaiju/flying;wingspan=40/monstersforhire/japan/flying の処理に適したリソースを見つけるために使用される URI です。

マトリクスパラメーターの値は、javax.ws.rs.MatrixParam アノテーションを使用してフィールド、パラメーター、または Bean プロパティーに注入されます。アノテーションでは、パラメーターを 1 つ使用できます。このパラメーターをもとに、値の抽出、指定されたフィールド、Bean プロパティー、またはパラメーターにインジェクトされるマトリックスパラメーターの名前が識別されます。@MatrixParam アノテーションは、「サポートされるデータタイプ」で説明されている型をサポートします。

例47.4「マトリックスパラメーターのデータを使用するリソースメソッド」 は、マトリクスパラメーター type および id の値をメソッドのパラメーターに注入するリソースメソッドを表しています。

例47.4 マトリックスパラメーターのデータを使用するリソースメソッド

import javax.ws.rs.MatrixParam;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
...

@Path("/monstersforhire/")
public class MonsterService
{
  ...
  @POST
  public void updateMonster(@MatrixParam("type") String type,
                            @MatrixParam("id") String id)
  {
    ...
  }
  ...
}

HTTP POST/monstersforhire;type=daikaiju;id=whale に処理するには、updateMonster() メソッドの typedaikaiju に設定され、idwhale に設定されます。

注記

JAX-RS は URI の全マトリックスパラメーターを一度に評価するため、URI のマトリックスパラメーターの場所に、制約を適用することはできません。たとえば、/monstersforhire/japan;type=daikaiju/flying;wingspan=40 , /monstersforhire/japan/flying;type=daikaiju;wingspan=40, and /monstersforhire/japan;type=daikaiju; wingspan=40/flying はすべて、JAX-RS API を使用して実装される RESTful Web サービスと同等のものとして処理されます。

URI のデコードの無効化

デフォルトでは、すべてのリクエスト URI がデコードされます。そのため、URI /monster/night%20stalker と URI /monster/night stalker は同等です。自動 URI デコードを使用すると、ASCII 文字セット以外の文字をパラメーターとして送信しやすくなります。

URI を自動的にデコードしたくない場合は、javax.ws.rs.Encoded アノテーションを使用して URI のデコードを非アクティブ化できます。アノテーションは、以下のレベルで URI のデコードを非アクティブにするために使用できます。

  • クラスレベル - @Encoded アノテーションでクラスをデコードすると、クラス内のすべてのパラメーター、フィールド、および Bean プロパティーの URI デコードが無効になります。
  • メソッドレベル - @Encoded アノテーションでメソッドをデコードすると、クラスのすべてのパラメーターの URI デコードが無効になります。
  • パラメーター/フィールドレベル - パラメーターまたはフィールドを @Encoded アノテーションでデコレートすると、クラスのすべてのパラメーターの URI デコードが無効になります。

例47.5「URI のデコードの無効化」は、getMonster() メソッドが URI デコードを使用しないリソースを示しています。addMonster() メソッドは、type パラメーターの URI デコードのみを無効にします。

例47.5 URI のデコードの無効化

@Path("/monstersforhire/")
public class MonsterService
{
  ...

  @GET
  @Encoded
  @Path("/{type}")
  public Monster getMonster(@PathParam("type") String type,
                            @QueryParam("id") String id)
  {
    ...
  }

  @PUT
  @Path("/{id}")
  public void addMonster(@Encoded @PathParam("type") String type,
                         @QueryParam("id") String id)
  {
    ...
  }
  ...
}

エラー処理

URI インジェクションアノテーションのいずれかを使用してデータを注入しようとすると、元の例外をラップする WebApplicationException 例外が生成されます。WebApplicationException 例外のステータスは 404 に設定されます。

Red Hat logoGithubRedditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

© 2024 Red Hat, Inc.