지원되는 매개변수 및 반환 유형

이 페이지에는 백엔드 API 메소드의 경로나 쿼리 매개변수에서 API 매개변수 유형으로 사용할 수 있는 데이터 유형과 메소드 반환 유형 또는 요청 본문 유형으로 사용할 수 있는 유형이 나와 있습니다.

경로 및 쿼리 매개변수에 대해 지원되는 유형

경로 및 쿼리 매개변수에 지원되는 유형은 다음과 같습니다.

  • java.lang.String
  • java.lang.Boolean 및 boolean
  • java.lang.Integer 및 int
  • java.lang.Long 및 long
  • java.lang.Float 및 float
  • java.lang.Double 및 double
  • java.util.Date
  • com.google.api.server.spi.types.DateAndTime
  • com.google.api.server.spi.types.SimpleDate
  • 모든 enum
  • 여기에 나열된 모든 배열 또는 해당 java.util.Collection. 다른 유형의 배열 또는 컬렉션은 지원되지 않습니다.

매개변수를 경로 또는 쿼리 매개변수로 지정하려면 매개변수를 @Named로 주석 처리합니다. 예를 들면 다음과 같습니다.

public Resource get(@Named("id") int id) { … }

경로 매개변수

경로 매개변수는 @ApiMethod 주석의 path 속성에 포함된 메서드 매개변수입니다. path가 지정되지 않은 경우 @Nullable 또는 @DefaultValue로 주석 처리되지 않은 모든 매개변수가 경로에 경로 매개변수로 자동 추가됩니다. 예를 들면 다음과 같습니다.

public Resource get(@Named("id") int id) { … }

매개변수를 path에 수동으로 추가하려면 경로의 {} 표시에 매개변수 이름을 포함합니다. path에 수동으로 추가된 매개변수는 @Nullable 또는 @DefaultValue로 주석 처리할 수 없습니다. 예를 들면 다음과 같습니다.

@ApiMethod(path = "resources/{id}")
public Resource get(@Named("id") int id) { … }

쿼리 매개변수

쿼리 매개변수는 @ApiMethod 주석의 path 속성에 포함되지 않은 메서드 매개변수입니다. @Nullable 또는 @DefaultValue로 주석 처리된 선택적 매개변수는 path에 자동으로 추가되지 않으므로 path를 지정하지 않으면 자동으로 쿼리 매개변수가 된다는 점에 유의하세요. 예를 들면 다음과 같습니다.

public Resource get(@Named("id") @Nullable int id) { … }

path를 지정한 경우 매개변수를 path에 포함하지 않으면 쿼리 매개변수가 됩니다. 예를 들면 다음과 같습니다.

@ApiMethod(path = "resources")
public Resource get(@Named("id") int id) { … }

삽입 유형

삽입 유형은 Cloud Endpoints Frameworks에서 특별하게 처리되는 유형입니다. 이러한 유형은 메소드 매개변수로 사용되어도 API에 포함되지 않습니다. 대신 Endpoints Frameworks가 매개변수를 채워 넣습니다.

삽입 유형은 다음과 같습니다.

  • com.google.appengine.api.users.User
  • javax.servlet.http.HttpServletRequest
  • javax.servlet.ServletContext

항목 유형

Endpoints Frameworks 문서에서 항목 유형은 자바 빈과 동의어입니다. API에서 사용하도록 정의하는 클래스는 다음과 같아야 합니다.

  • 인수를 취하지 않는 공개 생성자가 있습니다.
  • getter와 setter를 사용하여 비공개 속성에 대한 액세스를 제어합니다. 또한 각 setter는 매개변수를 하나만 취해야 합니다.

일반적으로 항목 유형은 Serializable도 구현하지만 Endpoints Frameworks를 사용하는 데 필수적이지는 않습니다.

항목 유형 매개변수에는 @Named 주석을 사용하지 마세요.

요청 본문

항목 유형을 메소드의 매개변수로 전달하면 항목 유형의 속성은 요청 본문의 JSON 필드에 매핑됩니다. 메소드는 항목 유형 매개변수 한 개만 포함해야 합니다. 예를 들면 다음과 같습니다.

public Resource set(Resource resource) { … }

메소드에 비 항목 유형 매개변수와 항목 유형 매개변수를 포함할 수 있습니다. 예를 들면 다음과 같습니다.

@ApiMethod(name = "echo")
public Message echo(Message message, @Named("n") @Nullable Integer n) { … }

위 예시에서 message 매개변수의 속성은 요청 본문의 JSON 필드에 매핑됩니다. @Nullable 주석은 n 매개변수가 선택사항이므로 쿼리 매개변수로 전달됨을 나타냅니다.

응답 객체

메소드 반환 값은 다음 중 하나여야 합니다.

  • 항목 유형
  • 일반 유형
  • CollectionResponse(com.google.api.server.spi.response.CollectionResponse) 또는 CollectionResponse의 서브클래스

응답 객체의 JSON 필드는 반환 값의 속성에서 매핑됩니다.

유형에 대한 @ApiTransformer의 영향

@ApiTransformer를 사용하는 경우 변환이 유형에 어떠한 영향을 주는지를 숙지해야 합니다.

@ApiTransformer 및 매개변수 유형

@ApiTransformer를 사용하는 경우 결과 메서드 매개변수가 매개변수 유형으로 간주되는지 여부는 원래 유형이 아닌 변환 결과에 따라 달라집니다. 유형을 매개변수 유형으로 변환하면 메서드 매개변수가 API 매개변수로 간주되며 @Named로 주석 처리되어야 합니다.

@ApiTransformer 및 항목 유형

마찬가지로 메서드 매개변수 또는 반환 유형이 항목 유형으로 간주되는지 여부는 원래 유형이 아닌 변환 결과에 따라 달라집니다. 유형을 항목 유형으로 변환하면 유형을 반환 유형으로 사용할 수 있으며, 메서드 매개변수로 사용하면 항목 유형으로 간주되므로 @Named로 주석 처리할 수 없습니다.

@ApiTransformer 및 삽입 유형

삽입 유형은 @ApiTransformer의 영향을 받지 않습니다. 메서드 매개변수는 변환되지 않은 원래 유형이 삽입 유형인 경우에만 삽입 유형으로 간주됩니다.