Tipos de parâmetros e de retorno suportados

Esta página apresenta os tipos de dados que pode usar como tipos de parâmetros de API nos parâmetros de caminho ou de consulta para os métodos de API de back-end, e os tipos que pode usar como tipos de retorno de métodos ou tipos de corpo de pedido.

Tipos suportados para parâmetros de caminho e de consulta

Os tipos suportados para o parâmetro de caminho e de consulta são os seguintes:

  • 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 indicados aqui. As matrizes ou as coleções de outros tipos não são suportadas.

Para especificar um parâmetro como um parâmetro de caminho ou de consulta, anote o parâmetro com @Named. Por exemplo:

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

Parâmetros de caminho

Os parâmetros de caminho são os parâmetros do método incluídos na propriedade path da anotação @ApiMethod. Se path não for especificado, todos os parâmetros não anotados com @Nullable ou @DefaultValue são adicionados automaticamente ao caminho como parâmetros de caminho. Por 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. Não é possível anotar parâmetros adicionados manualmente a path com @Nullable ou @DefaultValue. Por exemplo:

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

Parâmetros de consulta

Os parâmetros de consulta são os parâmetros do método não incluídos na propriedade path da anotação @ApiMethod. Tenha em atenção que os parâmetros opcionais, ou seja, os parâmetros anotados com @Nullable ou @DefaultValue, nunca são adicionados automaticamente a path, pelo que são automaticamente parâmetros de consulta se não for especificado nenhum path. Por exemplo:

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

Se path for especificado, pode fazer com que os parâmetros sejam parâmetros de consulta não os incluindo em path. Por exemplo:

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

Tipos injetados

Os tipos injetados são os tipos que recebem tratamento especial pelos Frameworks do Cloud Endpoints. Se tal tipo for usado como um parâmetro de método, não é incluído na API. Em alternativa, o parâmetro é preenchido pelos 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, os tipos de entidades são sinónimos de Java Beans. As classes que definir para utilização na sua API têm de:

  • Ter um construtor público que não receba argumentos.
  • Controle o acesso a propriedades privadas através de getters e setters. Além disso, cada setter tem de aceitar apenas um parâmetro.

Normalmente, os tipos de entidades também implementam Serializable, mas isto não é um requisito para usar os frameworks de endpoints.

Não use a anotação @Named para parâmetros do tipo de entidade.

O corpo do pedido

Quando transmite um tipo de entidade como parâmetro num método, as propriedades no tipo de entidade são mapeadas para campos JSON no corpo do pedido. Os seus métodos têm de conter apenas um parâmetro do tipo de entidade. Por exemplo:

public Resource set(Resource resource) { … }

Pode incluir parâmetros de tipo não entidade e um parâmetro de tipo entidade num método. Por 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 do pedido. A anotação @Nullable indica que o parâmetro n é opcional, pelo que é transmitido como um parâmetro de consulta.

O objeto de resposta

O valor de retorno do método tem de 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 nos tipos

Se usar @ApiTransformer, tem de saber como o tipo é afetado pela transformação.

@ApiTransformer e tipos de parâmetros

Quando é usado um @ApiTransformer, se o parâmetro do método resultante é considerado um tipo de parâmetro depende do resultado da transformação e não do tipo original. Se um tipo for transformado num tipo de parâmetro, o parâmetro do método é considerado um parâmetro da API e tem de ser anotado com @Named.

@ApiTransformer e tipos de entidades

Da mesma forma, se um parâmetro de método ou um tipo de retorno é considerado um tipo de entidade depende do resultado da transformação e não do tipo original. Se um tipo for transformado num tipo de entidade, o tipo pode ser usado como um tipo de retorno e, quando usado como um parâmetro de método, não pode ser anotado com @Named, uma vez que é considerado um tipo de entidade.

@ApiTransformer e tipos injetados

Os tipos injetados não são afetados por um @ApiTransformer. Um parâmetro de método só é considerado um tipo injetado se o respetivo tipo original não transformado for um tipo injetado.