Nesta página, listamos os tipos de dados que podem ser usados como tipos de parâmetros de caminho ou de consulta para métodos de API do back-end, além daqueles que podem ser usados como tipos de retorno de método ou de corpo de solicitação.
Tipos compatíveis para parâmetros de caminho e de consulta
Os tipos compatíveis para parâmetros de caminho e de consulta são estes:
java.lang.String
java.lang.Boolean
eboolean
java.lang.Integer
eint
java.lang.Long
elong
java.lang.Float
efloat
java.lang.Double
edouble
java.util.Date
com.google.api.server.spi.types.DateAndTime
com.google.api.server.spi.types.SimpleDate
- Qualquer
enum
- Qualquer matriz ou
java.util.Collection
dos tipos listados aqui. (matrizes ou coleções de outros tipos não são compatíveis)
Para especificar um parâmetro como de caminho ou de consulta, anote-o com @Named
.
Exemplo:
public Resource get(@Named("id") int id) { … }
Parâmetros de caminho
Os parâmetros de caminho são os parâmetros de método incluídos na propriedade path
da anotação @ApiMethod
. Se path
não é especificado, os parâmetros não anotados com @Nullable
ou @DefaultValue
são automaticamente adicionadas ao caminho como parâmetros de caminho. Exemplo:
public Resource get(@Named("id") int id) { … }
Para adicionar manualmente um parâmetro a path
, inclua o nome do parâmetro em {}
marcas no caminho. Os parâmetros adicionados manualmente a path
não podem ser anotados com @Nullable
ou @DefaultValue
. Exemplo:
@ApiMethod(path = "resources/{id}")
public Resource get(@Named("id") int id) { … }
Parâmetros de consulta
Parâmetros de consulta são os parâmetros de método não incluídos na propriedade path
da anotação @ApiMethod
. Os parâmetros opcionais, ou seja, aqueles anotados com @Nullable
ou @DefaultValue
, nunca são automaticamente adicionados a path
. Portanto, eles são parâmetros de consulta automaticamente se nenhum path
for especificado.
Exemplo:
public Resource get(@Named("id") @Nullable int id) { … }
Se path
for especificado, você poderá fazer com que parâmetros sejam parâmetros de consulta por não incluí-los em path
. Exemplo:
@ApiMethod(path = "resources")
public Resource get(@Named("id") int id) { … }
Tipos injetados
Os tipos injetados são os que recebem tratamento especial do Cloud Endpoints Frameworks. Se for usado como um parâmetro de método, esse tipo não fará parte da API. Em vez disso, o parâmetro é preenchido pelo Endpoints Frameworks.
Os tipos injetados são os seguintes:
com.google.appengine.api.users.User
javax.servlet.http.HttpServletRequest
javax.servlet.ServletContext
Tipos de entidade
Na documentação do Endpoints Frameworks, tipos de entidade são sinônimos de Java Beans. As classes definidas para serem usadas na API precisam:
- ter um construtor público que não aceita argumentos;
- controlar o acesso a propriedades privadas usando getters e setters. Além disso, é necessário que cada setter tenha apenas um parâmetro.
Normalmente, os tipos de entidade também implementam Serializable, mas isso não é um requisito para usar o Endpoints Frameworks.
Não use a anotação @Named
para os parâmetros de tipo de entidade.
O corpo da solicitação
Quando você passa um tipo de entidade como um parâmetro em um método, as propriedades nesse tipo são mapeadas para campos JSON no corpo da solicitação. Seus métodos precisam conter apenas um parâmetro de tipo de entidade. Exemplo:
public Resource set(Resource resource) { … }
É possível incluir parâmetros de tipo não entidade e um parâmetro de tipo de entidade em um método. Exemplo:
@ApiMethod(name = "echo")
public Message echo(Message message, @Named("n") @Nullable Integer n) { … }
No exemplo anterior, as propriedades no parâmetro message
são mapeadas para campos JSON no corpo da solicitação. O @Nullable
anotação indica que o n
parâmetro é opcional, por isso é passado como um parâmetro de consulta.
O objeto de resposta
O valor de retorno do método precisa ser um dos seguintes:
- um tipo de entidade
- um tipo genérico
- CollectionResponse (
com.google.api.server.spi.response.CollectionResponse
) ou uma subclasse de CollectionResponse
Os campos JSON no objeto de resposta são mapeados a partir das propriedades no valor de retorno.
Efeito de @ApiTransformer
em tipos
Se você usa @ApiTransformer
, precisa saber como o tipo é afetado pela transformação.
@ApiTransformer
e tipos de parâmetros
Quando um @ApiTransformer
é usado, mesmo que o parâmetro do método resultante seja considerado um tipo de parâmetro depende do resultado da transformação, não no tipo original. Se um tipo for transformado em um tipo de parâmetro, o parâmetro do método será considerado um parâmetro da API e deverá ser anotado com @Named
.
@ApiTransformer
e tipos de entidade
Da mesma forma, é o resultado da transformação, e não o tipo original, que determina se um tipo de retorno ou de parâmetro de método é considerado um tipo de entidade ou não. Se um tipo for transformado em um tipo de entidade, o tipo poderá ser usado como um tipo de retorno e, quando usado como um parâmetro de método, não poderá ser anotado com @Named
, porque é considerado um tipo de entidade.
@ApiTransformer
e tipos injetados
Os tipos injetados não são afetados por @ApiTransformer
. Um parâmetro de método só é considerado um tipo injetado se o respectivo tipo original não transformado for injetado.