Unterstützte Parameter und Rückgabetypen

Auf dieser Seite finden Sie die Datentypen, die Sie als API-Parametertypen im Pfad oder in den Abfrageparametern für Ihre Back-End-API-Methoden verwenden können. Auch die Typen, die Sie als Methodenrückgabe- oder Anfragetexttypen verwenden können, sind aufgeführt.

Unterstützte Typen für Pfad- und Abfrageparameter

Für Pfad- und Abfrageparameter werden die folgenden Typen unterstützt:

  • java.lang.String
  • java.lang.Boolean und boolean
  • java.lang.Integer und int
  • java.lang.Long und long
  • java.lang.Float und float
  • java.lang.Double und double
  • java.util.Date
  • com.google.api.server.spi.types.DateAndTime
  • com.google.api.server.spi.types.SimpleDate
  • Alle enum-Typen
  • Alle Arrays oder java.util.Collection der hier aufgeführten Typen. Arrays oder Sammlungen anderer Typen werden nicht unterstützt.

Wenn Sie einen Parameter als Pfad- oder Abfrageparameter angeben möchten, annotieren Sie diesen mit @Named. Beispiel:

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

Pfadparameter

Pfadparameter sind die im Attribut path der Annotation @ApiMethod enthaltenen Methodenparameter. Wenn path nicht angegeben ist, werden alle mit @Nullable oder @DefaultValue nicht annotierten Parameter dem Pfad automatisch als Pfadparameter hinzugefügt. Beispiel:

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

Wenn Sie path manuell einen Parameter hinzufügen möchten, fügen Sie den Parameternamen zwischen geschweiften Klammern ({}) in den Pfad ein. Parameter, die dem path manuell hinzugefügt wurden, können nicht mit @Nullable oder @DefaultValue annotiert werden. Beispiel:

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

Suchparameter

Abfrageparameter sind die Methodenparameter, die nicht im Attribut path der Annotation @ApiMethod enthalten sind. Optionale Parameter, d. h. mit @Nullable oder @DefaultValue annotierte Parameter, werden path nicht automatisch hinzugefügt. Sie sind also automatisch Abfrageparameter, wenn kein path angegeben ist. , um die Option zu aktivieren. Beispiel:

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

Wenn ein path angegeben ist, können Sie Parameter zu Abfrageparametern machen, indem Sie sie nicht in den path einbeziehen. Beispiel:

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

Injizierte Typen

Injizierte Typen werden von Cloud Endpoints Frameworks gesondert behandelt. Wird ein solcher Typ als Methodenparameter verwendet, ist er nicht Teil der API. Stattdessen wird der Parameter vom Framework ausgefüllt.

Folgende injizierte Typen stehen zur Verfügung:

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

Entitätstypen

In der Dokumentation zu Endpoints Frameworks sind Entitätstypen gleichbedeutend mit Java Beans. Die Klassen, die Sie für die Verwendung in der API definieren, müssen die folgenden Voraussetzungen erfüllen:

  • Sie haben einen öffentlichen Konstruktor, der keine Argumente annimmt.
  • Sie steuern den Zugriff auf private Attribute mithilfe von Getter- und Setter-Methoden. Jeder Setter darf darüber hinaus nur einen Parameter annehmen.

In der Regel implementieren Entitätstypen auch Serializable. Das ist jedoch keine Voraussetzung für die Verwendung von Endpoints Frameworks.

Verwenden Sie die Annotation @Named nicht für Entitätstyp-Parameter.

Anfragetext

Wenn Sie in einer Methode einen Entitätstyp als Parameter übergeben, werden die Attribute im Entitätstyp den JSON-Feldern im Anfragetext zugeordnet. Ihre Methoden dürfen nur einen Entitätstyp-Parameter enthalten. Beispiel:

public Resource set(Resource resource) { … }

Methoden können einen Entitätstyp-Parameter und andere Parameter, die keine Entitätstyp-Parameter sind, enthalten. Beispiel:

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

Im vorherigen Beispiel werden die Attribute im Parameter message den JSON-Feldern im Anfragetext zugeordnet. Die Annotation @Nullable gibt an, dass der Parameter n optional ist, daher wird er als Abfrageparameter übergeben.

Antwortobjekt

Die Methode muss einen der folgenden Werte zurückgeben:

  • Einen Entitätstyp
  • Einen generischen Typ
  • CollectionResponse (com.google.api.server.spi.response.CollectionResponse) oder eine Unterklasse von CollectionResponse

Die JSON-Felder im Antwortobjekt werden aus den Attributen im Rückgabewert zugeordnet.

Auswirkungen von @ApiTransformer auf Typen

Wenn Sie @ApiTransformer nutzen, müssen Sie wissen, wie sich die Umwandlung auf den Typ auswirkt.

@ApiTransformer und Parametertypen

Ob der resultierende Methodenparameter bei Verwendung eines @ApiTransformer als Parametertyp angesehen wird, hängt vom Ergebnis der Transformation und nicht vom ursprünglichen Typ ab. Wenn ein Typ in einen Parametertyp transformiert wird, gilt der Methodenparameter als API-Parameter und muss mit @Named annotiert werden.

@ApiTransformer und Entitätstypen

Ob ein Methodenparameter oder Rückgabetyp als Entitätstyp gilt, hängt ebenfalls vom Ergebnis der Transformation und nicht vom ursprünglichen Typ ab. Wenn ein Typ in einen Entitätstyp transformiert wird, kann er als Rückgabetyp verwendet werden. Bei Verwendung als Methodenparameter kann er nicht mit @Named annotiert werden, da es als Entitätstyp gilt.

@ApiTransformer und injizierte Typen

Injizierte Typen sind von einem @ApiTransformer nicht betroffen. Ein Methodenparameter gilt nur als injizierter Typ, wenn der ursprüngliche, nicht transformierte Typ ein injizierter Typ ist.