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 API di backend e i tipi che puoi utilizzare come tipi restituiti dal metodo o tipi di corpo della richiesta.

Tipi supportati per i parametri di percorso e query

I tipi supportati per il percorso e il parametro di ricerca 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 matrice o java.util.Collection dei tipi elencati qui. Array o raccolte di altri tipi non sono supportati.

Per specificare un parametro come parametro di percorso o di query, annota il parametro 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 tra i 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, quindi sono automaticamente parametri di ricerca se non viene specificato alcun path. Ad esempio:

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

Se viene specificato path, puoi fare in modo che i parametri siano parametri di ricerca non includendoli in path. Ad esempio:

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

Tipi inseriti

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

I tipi inseriti 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 sinonimi di Java Beans. Le classi che definisci per l'utilizzo nell'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 questo non è un requisito per utilizzare Endpoints Frameworks.

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

Il corpo della richiesta

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

public Resource set(Resource resource) { … }

Puoi includere parametri di tipo non entità e un parametro di tipo entità in un metodo. 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, quindi 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 risposta vengono mappati dalle proprietà nel valore restituito.

Nota: la restituzione di un tipo semplice, ad esempio String o int, di un array o di un tipo di entità con un costruttore parametrizzato non è supportata.

Effetto di @ApiTransformer sui tipi

Se utilizzi @ApiTransformer, devi essere consapevole di come il tipo viene influenzato dalla trasformazione.

@ApiTransformer e tipi di parametri

Quando viene utilizzato un @ApiTransformer, se il parametro del metodo risultante è considerato 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 del metodo viene considerato un parametro API e deve essere annotato con @Named.

@ApiTransformer e tipi di entità

Allo stesso modo, se un parametro di metodo o un tipo restituito è considerato 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 restituito e, se utilizzato come parametro di metodo, non può essere annotato con @Named perché è considerato un tipo di entità.

@ApiTransformer e tipi iniettati

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