Tipi di parametri e tipi restituiti supportati

Questa pagina elenca i tipi di dati che puoi utilizzare come tipi di parametri API nel percorso o nei parametri di ricerca per i metodi dell'API di backend e i tipi che puoi utilizzare come tipi di ritorno del metodo o tipi di corpo della richiesta.

Tipi supportati per i parametri path e query

I tipi supportati per il parametro path e query sono i seguenti:

  • 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
  • Qualsiasi enum
  • Qualsiasi array o java.util.Collection dei tipi elencati qui. Gli array o le raccolte di altri tipi non sono supportati.

Per specificare un parametro come parametro di percorso o di query, annotalo con @Named. Ad esempio:

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

Parametri del percorso

I parametri di percorso sono i parametri del metodo inclusi nella proprietà path dell'annotazione @ApiMethod. Se path non è specificato, tutti i parametri non annotati con @Nullable o @DefaultValue vengono aggiunti automaticamente al percorso come parametri del percorso. Ad esempio:

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

Per aggiungere manualmente un parametro a path, includi il nome del parametro nei segni {} nel percorso. I parametri aggiunti manualmente a path non possono essere annotati con @Nullable o @DefaultValue. Ad esempio:

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

Parametri di query

I parametri di query sono i parametri del metodo non inclusi nella proprietà path dell'annotazione @ApiMethod. Tieni presente che i parametri facoltativi, ovvero quelli annotati con @Nullable o @DefaultValue, non vengono mai aggiunti automaticamente a path, pertanto sono automaticamente parametri di ricerca se non viene specificato path. Ad esempio:

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

Se è specificato path, puoi impostare i parametri come parametri di ricerca non includendoli in path. Ad esempio:

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

Tipi iniettati

I tipi iniettati sono quelli che ricevono un trattamento speciale da Cloud Endpoints Frameworks. Se un tipo di questo tipo viene utilizzato come parametro di metodo, non fa parte dell'API. Il parametro viene invece inserito da Endpoints Frameworks.

I tipi iniettati sono i seguenti:

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

Tipi di entità

Nella documentazione di Endpoints Frameworks, i tipi di entità sono synonymi di Java Beans. Le classi che definisci per l'utilizzo nella tua API devono:

  • Avere un costruttore pubblico che non accetta argomenti.
  • Controlla l'accesso alle proprietà private utilizzando getter e setter. Inoltre, ogni setter deve accettare un solo parametro.

In genere, i tipi di entità implementano anche Serializable, ma non è un requisito per l'utilizzo dei framework di endpoint.

Non utilizzare l'annotazione @Named per i parametri di tipo di entità.

Il corpo della richiesta

Quando passi un tipo di entità come parametro in un metodo, le proprietà nel tipo di entità vengono mappate ai campi JSON nel corpo della richiesta. I metodi devono contenere un solo parametro di tipo di entità. Ad esempio:

public Resource set(Resource resource) { … }

In un metodo puoi includere parametri di tipo non entità e un parametro di tipo entità. Ad esempio:

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

Nell'esempio precedente, le proprietà nel parametro message vengono mappate ai campi JSON nel corpo della richiesta. L'annotazione @Nullable indica che il parametro n è facoltativo, pertanto viene passato come parametro di query.

L'oggetto di risposta

Il valore restituito dal metodo deve essere uno dei seguenti:

  • Un tipo di entità
  • Un tipo generico
  • CollectionResponse (com.google.api.server.spi.response.CollectionResponse) o una sottoclasse di CollectionResponse

I campi JSON nell'oggetto response vengono mappati dalle proprietà nel valore di ritorno.

Effetto di @ApiTransformer sui tipi

Se utilizzi @ApiTransformer, devi essere consapevole dell'impatto della trasformazione sul tipo.

@ApiTransformer e tipi di parametri

Quando viene utilizzato un @ApiTransformer, il fatto che il parametro del metodo risultante sia considerato o meno un tipo di parametro dipende dal risultato della trasformazione, non dal tipo originale. Se un tipo viene trasformato in un tipo di parametro, il parametro metodo è considerato un parametro API e deve essere annotato con @Named.

@ApiTransformer e tipi di entità

Analogamente, il fatto che un parametro di metodo o un tipo di ritorno sia considerato o meno un tipo di entità dipende dal risultato della trasformazione, non dal tipo originale. Se un tipo viene trasformato in un tipo di entità, può essere utilizzato come tipo di ritorno e, se utilizzato come parametro di metodo, non può essere annotato con @Named in quanto considerato un tipo di entità.

@ApiTransformer e tipi di elementi inseriti

I tipi iniettati non sono interessati da un @ApiTransformer. Un parametro di metodo viene considerato un tipo iniettato solo se il suo tipo non trasformato originale è un tipo iniettato.