Tipos compatíveis de parâmetros e retornos

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 e boolean
• java.lang.Integer e int
• java.lang.Long e long
• java.lang.Float e float
• java.lang.Double e double
• 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.

Observação :não é possível retornar um tipo simples, como String ou int, uma matriz ou um tipo de entidade com um construtor parametrizado.

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.