Types de paramètres et de renvois compatibles

Cette page répertorie les types de données que vous pouvez utiliser en tant que types de paramètres d'API dans les paramètres de chemin ou de requête pour vos méthodes d'API backend, ainsi que les types que vous pouvez utiliser en tant que types de renvois de méthode ou types de corps de requête.

Types acceptés pour les paramètres de chemin et de requête

Les types acceptés pour le paramètre de chemin et de requête sont les suivants :

  • java.lang.String
  • java.lang.Boolean et boolean
  • java.lang.Integer et int
  • java.lang.Long et long
  • java.lang.Float et float
  • java.lang.Double et double
  • java.util.Date
  • com.google.api.server.spi.types.DateAndTime
  • com.google.api.server.spi.types.SimpleDate
  • Toute énumération (enum)
  • Tout tableau ou collection java.util.Collection des types répertoriés ici. Les tableaux ou les collections d'autres types ne sont pas acceptés.

Pour spécifier un paramètre en tant que paramètre de chemin ou de requête, annotez-le avec @Named. Exemple :

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

Paramètres de chemin

Les paramètres de chemin sont les paramètres de méthode inclus dans la propriété path de l'annotation @ApiMethod. Si path n'est pas spécifié, tous les paramètres non annotés avec @Nullable ou @DefaultValue sont automatiquement ajoutés au chemin en tant que paramètres de chemin. Exemple :

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

Pour ajouter manuellement un paramètre à path, indiquez le nom du paramètre entre les marques {} dans le chemin. Les paramètres ajoutés manuellement à path ne peuvent pas être annotés avec @Nullable ou @DefaultValue. Exemple :

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

Paramètres de requête

Les paramètres de requête sont les paramètres de méthode non inclus dans la propriété path de l'annotation @ApiMethod. Notez que les paramètres facultatifs, à savoir ceux annotés avec @Nullable ou @DefaultValue, ne sont jamais ajoutés automatiquement à path. Ils sont donc automatiquement des paramètres de requête si aucun path n'est spécifié. Exemple :

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

Si path est spécifié, vous pouvez définir des paramètres en tant que paramètres de requête en ne les incluant pas dans le path. Exemple :

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

Types injectés

Les types injectés sont les types qui reçoivent un traitement spécial de la part de Cloud Endpoints Frameworks. Si un tel type est utilisé en tant que paramètre de méthode, il ne fait pas partie de l'API. Au lieu de cela, le paramètre est renseigné par Endpoints Frameworks.

Les types injectés sont les suivants :

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

Types d'entités

Dans la documentation Endpoints Frameworks, les types d'entités sont synonymes de composants Java Beans. Les classes que vous définissez pour une utilisation dans votre API doivent :

  • avoir un constructeur public qui n'accepte aucun argument ;
  • contrôler l'accès aux propriétés privées à l'aide de méthodes getter et setter. De plus, chaque méthode "setter" ne doit accepter qu'un paramètre.

En règle générale, les types d'entités mettent également en œuvre l'interface Serializable, mais l'utilisation d'Endpoints Frameworks n'est pas obligatoire.

N'utilisez pas l'annotation @Named pour les paramètres de type d'entité.

Corps de la requête

Lorsque vous transmettez un type d'entité en tant que paramètre dans une méthode, les propriétés du type d'entité sont mappées sur des champs JSON dans le corps de la requête. Vos méthodes ne doivent contenir qu'un seul paramètre de type d'entité. Exemple :

public Resource set(Resource resource) { … }

Vous pouvez inclure des paramètres de type non-entité et un paramètre de type entité dans une méthode. Exemple :

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

Dans l'exemple précédent, les propriétés du paramètre message sont mappées sur des champs JSON dans le corps de la requête. L'annotation @Nullable indique que le paramètre n est facultatif. Il est donc transmis en tant que paramètre de requête.

Objet réponse

La valeur de renvoi de la méthode doit être l'une des suivantes :

  • Un type d'entité.
  • Un type générique.
  • CollectionResponse (com.google.api.server.spi.response.CollectionResponse) ou une sous-classe de CollectionResponse.

Les champs JSON de l'objet réponse sont mappés à partir des propriétés dans la valeur de renvoi.

Effet de @ApiTransformer sur les types

Si vous utilisez @ApiTransformer, vous devez savoir comment le type est affecté par la transformation.

@ApiTransformer et types de paramètres

Lorsqu'un paramètre @ApiTransformer est utilisé, le fait que le paramètre de méthode résultant soit considéré ou non comme un type de paramètre dépend du résultat de la transformation et non du type d'origine. Si un type est transformé en type de paramètre, le paramètre de méthode est considéré comme un paramètre d'API et doit être annoté avec @Named.

@ApiTransformer et types d'entités

De même, le fait qu'un paramètre de méthode ou un type de renvoi soit considéré ou non comme un type d'entité dépend du résultat de la transformation et non du type d'origine. Si un type est transformé en type d'entité, il peut être utilisé comme type de renvoi. Lorsqu'il est utilisé comme un paramètre de méthode, il ne peut pas être annoté avec @Named, car il est considéré comme un type d'entité.

@ApiTransformer et types d'injections

Les types injectés ne sont pas affectés par un @ApiTransformer. Un paramètre de méthode n'est considéré comme un type injecté que si son type d'origine non transformé est un type injecté.