RESTful 애플리케이션에서 자원에 대한 요청 표시 매개변수 정의
매개변수는 추가 정보를 요청에 전달하고 추가하는 데 사용됩니다. 매개변수는 URL의 일부로 또는 헤더에 사용할 수 있습니다. 경로 매개변수, 매트릭스 매개변수, 조회 매개변수, 헤더 매개변수, 쿠키 매개변수는 요청에 추가 정보를 전달하는 데 유용합니다.
이 태스크 정보
여러 가지 매개변수 유형이 존재합니다. JAX-RS(Java™ API for RESTful Web Services)에서는 어노테이션이 있는 삽입된 매개변수를 사용하여 모든 유형의 매개변수에 쉽게 액세스할 수 있습니다.
java.lang.String을 포함하여 기초적인 Java 기본 유형을 매개변수로 사용할 뿐만 아니라, 단일 문자열 또는 valueOf(문자열) 정적 메소드를 사용하는 생성자를 포함하는 Java 유형을 사용할 수 있습니다. 매개변수에 다중 값이 있는 경우 Set과 같이, 일반 유형이 이전에 언급된 유형 중 하나인 List, SortedSet, Set 인터페이스를 사용할 수 있습니다. 요청을 구문 분석해야 하는 경우 매개변수 유형으로 문자열을 사용하여 오류 경로 응답의 기본 검사 및 사용자 정의를 완료할 수 있습니다.
JAX-RS에서는 자원 메소드를 올바른 매개변수값으로 호출할 수 있도록 지정하기 위해 자원 메소드 매개변수에서 사용할 다음 어노테이션을 제공합니다.
- javax.ws.rs.PathParam 어노테이션
경로 매개변수는 URL의 일부입니다. 예를 들어, URL은 /collection/{item}을 포함할 수 있습니다. 여기서, {item}은 콜렉션에서 항목을 식별하는 경로 매개변수입니다. 경로 매개변수가 URL의 일부이기 때문에 요청 식별에 매우 중요합니다.
URL의 일부가 매개변수이면 @javax.ws.rs.PathParam 어노테이션이 있는 매개변수를 사용할 수 있습니다. 예를 들어, 다음과 같습니다.
이 예제에서 /bookstore/books/12345에 대한 요청은 12345의 값을 theBookId 변수에 지정합니다.@javax.ws.rs.Path(“/bookstore/books/{bookId}”) public class BooksCollection { @javax.ws.rs.GET public String getSpecificBookInfo(@javax.ws.rs.PathParam(“bookId”) String theBookId) { /* theBookId would contain the next path segment after /bookstore/books/ */ } }
- javax.ws.rs.MatrixParam 어노테이션
매트릭스 매개변수는 URL의 일부입니다. 예를 들어, URL에 경로 세그먼트, /collection;itemID=itemIDValue를 포함하는 경우 매트릭스 매개변수 이름은 itemID이고 itemIDValue가 값입니다.
@javax.ws.rs.MatrixParam 어노테이션이 있는 매개변수로 매트릭스 매개변수를 읽을 수 있습니다. 예를 들어, 다음과 같습니다.
이 예제에서 /bookstore/books;page=25;filter=test에 대한 요청은 getBookCollectionInfo 매개변수를 호출하므로 page 변수의 값은 25로 설정되고 filter 변수의 값은 test로 설정됩니다.@javax.ws.rs.Path(“/bookstore/books”) public class BooksCollection { @javax.ws.rs.GET public String getBookCollectionInfo(@javax.ws.rs.MatrixParam(“page”) int page, @javax.ws.rs.MatrixParam(“filter”) String filter) { /* This statement uses the page and filter parameters. */ } }
- javax.ws.rs.QueryParam 어노테이션
조회 매개변수는 URL에서 이름-값 쌍으로 "?" 뒤에 추가됩니다. 예를 들어, URL이 http://example.com/collection?itemID=itemIDValue인 경우 조회 매개변수 이름은 itemID이고 itemIDValue가 값입니다. 조회 매개변수는 종종 HTTP GET 요청을 통해 페이징하거나 필터링하는 경우에 사용됩니다.
@javax.ws.rs.QueryParam 어노테이션이 있는 매개변수로 조회 매개변수를 읽을 수 있습니다. 예를 들어, 다음과 같습니다.
이 예제에서 /bookstore/books;page=25;filter=test에 대한 요청은 getBookCollectionInfo 매개변수를 호출하므로 page 변수의 값은 25로 설정되고 filter 변수의 값은 test로 설정됩니다.@javax.ws.rs.Path(“/bookstore/books”) public class BooksCollection { @javax.ws.rs.GET public String getBookCollectionInfo(@javax.ws.rs.QueryParam(“page”) int page, @javax.ws.rs.QueryParam(“filter”) String filter) { /* This statement uses the page and filter parameters. */ } }
- javax.ws.rs.HeaderParam 어노테이션
헤더 매개변수는 HTTP 헤더입니다. 미리 정의된 HTTP 헤더가 있으면 사용자 정의 헤더도 사용할 수 있습니다. 헤더는 종종 클라이언트, 매개체 또는 서버에 대한 제어 메타데이터 정보를 포함합니다.
HTTP 요청 헤더를 읽어야 하는 경우 @javax.ws.rs.HeaderParam 어노테이션을 사용하십시오. 예를 들어, 다음과 같습니다.@javax.ws.rs.Path(“/bookstore/books/”) public class BooksCollection { @javax.ws.rs.GET public String getBookCollectionInfo(@javax.ws.rs.HeaderParam(“Range”) String rangeValue) { /* The rangeValue variable contains the value of the HTTP request header "Range" */ } }
이 예제에서 Range HTTP 요청 헤더 값이 bytes=0-499인 /bookstore/books/에 대한 요청은 rangeValue 변수의 값으로 bytes=0-499의 메소드를 호출합니다.
- javax.ws.rs.CookieParam 어노테이션
쿠키 매개변수는 특별 HTTP 헤더입니다. 쿠키가 저장 세션 ID 또는 RESTful로 허용되지 않는 stateful 데이터와 연관된 경우 쿠키는 Stateless 정보를 포함할 수 있습니다.
HTTP 쿠키를 전송한 경우(예: mycustomid=customvalue123) 다음 예제를 사용하여 mycustomid 변수의 값을 검색할 수 있습니다.@javax.ws.rs.Path(“/bookstore/books/”) public class BooksCollection { @javax.ws.rs.GET public String getBookCollectionInfo(@javax.ws.rs.CookieParam(“mycustomid”) String mycustomid) { /* The cookie value is passed to the mycustomid variable. */ } }
- javax.ws.rs.FormParam 어노테이션
양식 매개변수는 매체 유형이 application/x-www-form-urlencoded인 브라우저에서 HTML 양식을 제출할 때 사용됩니다. 양식 매개변수 및 값은 다음과 같은 양식으로 요청 메시지 본문에서 인코딩됩니다. firstParameter=firstValue&secondParameter=secondValue. javax.ws.rs.FormParam 어노테이션에서는 개별 양식 매개변수값에 쉽게 액세스할 수 있습니다.
양식을 제출하고 엔티티 값이 firstName=Bob&lastName=Smith인 경우 다음 예제를 사용하여 양식 매개변수값을 검색할 수 있습니다.@javax.ws.rs.Path(“/customer”) public class Custommer { @javax.ws.rs.POST public String postCustomerInfo(@javax.ws.rs.FormParam(“firstName”) String firstName, @javax.ws.rs.FormParam("lastName") String lastName) { /* firstName would be "Bob" and secondName would be "Smith" */ } }
문제점 방지: 어노테이션이 없는 단일 매개변수를 사용해 메시지 본문을 나타내거나 다중 FormParam 어노테이션이 있는 매개변수를 사용하거나 둘 다 사용하지 않을 수 있습니다. FormParam에서는 요청 메시지 본문을 읽어야 하고 메시지 본문이 바이트 스트림으로 표시되기 때문에 메시지 본문을 다시 읽을 수 없습니다. 다음 코드는 유효하지 않습니다.
gotcha@javax.ws.rs.Path(“/bookstore/books”) public class BooksCollection { @javax.ws.rs.POST public String postSpecificBookInfo(@javax.ws.rs.FormParam(“bookId”) String theBookId, String theRequestEntity) { /* This code is invalid. Can only use FormParam or a request entity parameter like "String theRequestEntity" and not both */ } }
다음 방법 중 하나를 사용하여 변수를 정의해 매개변수를 읽으십시오.
프로시저
결과
적절한 매개변수값으로 호출될 수 있도록 자원 메소드가 정의됩니다.