Le annotazioni di Endpoints Frameworks descrivono la configurazione dell'API, i metodi, i parametri e altri dettagli essenziali che definiscono le proprietà e il comportamento dell'endpoint.
Consulta Scrittura e annotazione del codice per informazioni sull'aggiunta di annotazioni utilizzando un progetto Maven. Gli artefatti Cloud Endpoints di App Engine Maven vengono forniti per creare e creare un'API di backend e generare una libreria client da questa.
L'annotazione che specifica la configurazione e il comportamento nell'intera API
(interessa tutte le classi esposte nell'API e tutti i relativi metodi esposti) è
@Api
.
Tutti i metodi pubblici, non statici e non bridge di una classe annotata con @Api
vengono
esposti nell'API pubblica.
Se hai bisogno di una configurazione API speciale per un determinato metodo, puoi facoltativamente utilizzare @ApiMethod
per impostare la configurazione in base al metodo.
Puoi configurare queste annotazioni impostando vari attributi, come mostrato nelle tabelle seguenti.
@Api
: annotazioni con ambito API
L'annotazione @Api
configura l'intera API e si applica a tutti i metodi pubblici di una classe, a meno che non venga sostituita da @ApiMethod
.
Per eseguire l'override di una determinata annotazione @Api
per una classe specifica all'interno di un'API, consulta @ApiClass
e @ApiReference
.
Importazioni obbligatorie
Per utilizzare questa funzionalità, devi eseguire la seguente importazione:
import com.google.api.server.spi.config.Api;
Attributi
Attributi @API | Descrizione | Esempio |
---|---|---|
audiences |
Obbligatorio se la tua API richiede l'autenticazione e se supporti i client Android. Per saperne di più, consulta ID cliente e segmenti di pubblico. | audiences = {"1-web-apps.apps.googleusercontent.com", "2-web-apps.apps.googleusercontent.com"} |
apiKeyRequired |
Facoltativo. Utilizzato per limitare l'accesso alle richieste che forniscono una chiave API. | apiKeyRequired = AnnotationBoolean.TRUE |
authenticators |
Obbligatorio se la tua API viene autenticata utilizzando account Firebase, Auth0 o di servizio. Questo attributo non è obbligatorio se la tua API viene autenticata utilizzando i token ID Google. Puoi impostare questa opzione a livello di API o di singolo metodo. Impostalo su {EspAuthenticator.class} oppure puoi scrivere il tuo autenticatore personalizzato, come descritto in Interface Authenticator. |
authenticators = {EspAuthenticator.class} |
backendRoot |
Ritirato. Per pubblicare l'API da un percorso diverso, nel file web.xml modifica il valore url-pattern nella sezione EndpointsServlet . |
<url-pattern>/example-api/*</url-pattern> |
canonicalName |
Utilizzato per specificare un nome diverso o più leggibile per l'API nella libreria client. Questo nome viene utilizzato per generare i nomi nella libreria client; l'API di backend continua a utilizzare il valore specificato nella proprietà name .Ad esempio, se per l'API name è impostato su dfaanalytics, potresti utilizzare questa proprietà per specificare un nome canonico di DFA Group Analytics; le classi client generate conterranno il nome DfaGroupAnalytics .Devi includere gli spazi pertinenti tra i nomi; questi devono essere sostituiti con lettere maiuscole e minuscole appropriate o trattini bassi. |
canonicalName = "DFA Analytics:" n |
clientIds |
Obbligatorio se l'API utilizza l'autenticazione. Elenco di ID client per i client autorizzati a richiedere token. Per saperne di più, consulta ID cliente e segmenti di pubblico. | clientIds = {"1-web-apps.apps.googleusercontent.com", "2-android-apps.apps.googleusercontent.com"} |
defaultVersion |
Consente di specificare se viene utilizzata una versione predefinita se non ne viene specificata nessuna nell'attributo version . |
defaultVersion = AnnotationBoolean.TRUE |
description |
Una breve descrizione dell'API. Questo viene esposto nel servizio di rilevamento per descrivere l'API e, facoltativamente, può essere utilizzato anche per generare documentazione. | description = "Sample API for a simple game" |
documentationLink |
L'URL in cui gli utenti possono trovare la documentazione su questa versione dell'API. Questi dati vengono visualizzati nell'evidenziazione "Scopri di più" di Explorer API nella parte superiore della pagina Explorer API per consentire agli utenti di ottenere informazioni sul tuo servizio. | documentationLink = "http://link_to/docs" |
issuers |
Le configurazioni personalizzate dell'emittente JWT. | issuers = { @ApiIssuer(name = "auth0", issuer = "https://test.auth0.com/authorize", jwksUri = "https://test.auth0.com/.well-known/jwks.json") } |
issuerAudiences |
Segmenti di pubblico per i singoli emittenti. | issuerAudiences = { @ApiIssuerAudience(name = "auth0", audiences = {"aud-1.auth0.com", "aud-2.auth0.com"}) } |
limitDefinitions |
Facoltativo. Utilizzato per definire le quotas per la tua API. Vedi @ApiLimitMetric . |
limitDefinitions = { @ApiLimitMetric(name = "read-requests", displayName = "Read requests", limit = 1000)} |
name |
Il nome dell'API, che viene utilizzato come prefisso per tutti i metodi e percorsi dell'API. Il valore name :
name , viene utilizzato il valore predefinito myapi . |
name = "foosBall" |
namespace |
Configura il pacing dei nomi per i client generati. Vedi @ApiNamespace . |
namespace=@ApiNamespace(ownerDomain="your-company.com", ownerName="YourCo", packagePath="cloud/platform" ) |
root |
Ritirato. Per pubblicare l'API da un percorso diverso, nel file web.xml modifica il valore url-pattern nella sezione EndpointsServlet . |
<url-pattern>/example-api/*</url-pattern> |
scopes |
Se non viene specificato, il valore predefinito è l'ambito email (https://www.googleapis.com/auth/userinfo.email ), obbligatorio per OAuth. Se vuoi, puoi eseguire l'override di questa impostazione per specificare più ambiti OAuth 2.0. Tuttavia, se definisci più di un ambito, tieni presente che il controllo dell'ambito viene superato se il token è stato creato per uno qualsiasi degli ambiti specificati. Per richiedere più ambiti, è necessario specificare un singolo String con uno spazio tra ogni ambito. Per eseguire l'override degli ambiti specificati qui per un particolare metodo API, specifica ambiti diversi nell'annotazione @ApiMethod . |
scopes = {"ss0", "ss1 and_ss2"} |
title |
Il testo visualizzato in Explorer API come titolo dell'API ed esposto nei servizi di rilevamento e directory. | title = "My Backend API" |
transformers |
Specifica un elenco di trasformatori personalizzati. Tieni presente che è preferibile un'annotazione alternativa (@ApiTransformer ). Questo attributo è sostituito da @ApiTransformer . |
transformers = {BazTransformer.class} |
version |
Specifica la versione dell'endpoint. Se non lo specifichi, viene utilizzato il valore predefinito v1 . |
version = "v2" |
Esempio di annotazione@Api
Questa annotazione viene inserita prima della definizione del corso:
ID client e segmenti di pubblico
Per l'autenticazione OAuth2, un token OAuth2 viene inviato a un ID client specifico, il che significa che puoi utilizzare l'ID client per limitare l'accesso alle tue API.
Quando registri un'applicazione Android nella console Google Cloud,
crei un ID client per l'applicazione. Questo ID client è quello che richiede un token OAuth2
a Google per scopi di autenticazione. Quando l'API di backend è protetta tramite autenticazione, un token di accesso OAuth2 viene inviato e aperto da Endpoints, l'ID client viene estratto dal token e l'ID viene confrontato con l'elenco di ID client accettabili dichiarati dal backend (l'elenco clientIds
).
Se vuoi che l'API Endpoints autentichi i chiamanti, devi fornire un elenco di clientIds
che possono richiedere token. Questo elenco
dovrebbe essere composto da tutti gli ID client ottenuti tramite la
console Google Cloud
per i client web o Android. Ciò significa che i client devono essere noti al momento della creazione dell'API. Se specifichi un elenco vuoto, {}
, nessun client potrà accedere ai metodi protetti da Auth.
Se utilizzi l'attributo clientIds
e vuoi testare le chiamate autenticate alla tua API utilizzando Explorer API di Google, devi fornire il relativo ID client nell'elenco clientIds
: il valore da utilizzare è com.google.api.server.spi.Constant.API_EXPLORER_CLIENT_ID
.
Informazioni sui segmenti di pubblico
L'elenco clientIds
protegge l'API di backend da client non autorizzati. Tuttavia,
è necessaria un'ulteriore protezione per proteggere i client, in modo che il loro token di autenticazione funzioni
solo per l'API di backend prevista. Per i client Android, questo meccanismo è l'attributo audiences
, in cui specifichi l'ID client dell'API di backend.
Tieni presente che quando crei un progetto nella console Google Cloud, viene creato automaticamente un ID client predefinito, che viene denominato per essere utilizzato dal progetto. Quando carichi l'API di backend in App Engine, questa utilizza l'ID client. Si tratta dell'ID client web menzionato in Autenticazione API.
@ApiMethod
: annotazioni basate sul metodo
L'annotazione @ApiMethod
viene utilizzata per fornire una configurazione API diversa rispetto ai valori predefiniti forniti dalle annotazioni @Api
o @ApiClass
. Tieni presente che questo passaggio è facoltativo: tutti i metodi pubblici, non statici e non bridge in una classe con un'annotazione @Api
vengono esposti nell'API, indipendentemente dal fatto che abbiano o meno un'annotazione @ApiMethod
.
Gli attributi all'interno di questa annotazione consentono di configurare i dettagli di un singolo metodo API. Se lo stesso attributo viene specificato in @Api
e
@ApiMethod
, @ApiMethod
esegue l'override.
Importazioni obbligatorie
Per utilizzare questa funzionalità, sono necessarie le seguenti importazioni:
import com.google.api.server.spi.config.AnnotationBoolean;
import com.google.api.server.spi.config.ApiMethod;
import com.google.api.server.spi.config.ApiMethod.HttpMethod;
Attributi
Attributi @ApiMethod | Descrizione | Esempio |
---|---|---|
apiKeyRequired |
Facoltativo. Utilizzato per limitare l'accesso alle richieste che forniscono una chiave API. | apiKeyRequired = AnnotationBoolean.TRUE |
audiences |
Fornisci questo valore se vuoi sostituire la configurazione in @API . Per saperne di più, consulta ID cliente e segmenti di pubblico. |
audiences = {"1-web-apps.apps.googleusercontent.com", "2-web-apps.apps.googleusercontent.com"} |
authenticators |
Obbligatorio se la tua API viene autenticata utilizzando Firebase, Auth0 o account di servizio e non hai impostato questo attributo a livello di API. Questo attributo non è obbligatorio se la tua API viene autenticata utilizzando i token ID Google. Impostalo su {EspAuthenticator.class} oppure puoi scrivere il tuo autenticatore personalizzato, come descritto in Interface Authenticator |
authenticators = {EspAuthenticator.class} |
clientIds |
Elenco di ID client per i client autorizzati a richiedere token. Obbligatorio se l'API utilizza l'autenticazione. | clientIds = {"1-web-apps.apps.googleusercontent.com", "2-android-apps.apps.googleusercontent.com"} |
httpMethod |
Il metodo HTTP da utilizzare. Se non imposti questa opzione, viene scelto un valore predefinito in base al nome del metodo. | httpMethod = HttpMethod.GET |
issuerAudiences |
Fornisci questo valore se vuoi sostituire la configurazione in @Api . |
issuerAudiences = { @ApiIssuerAudience(name = "auth0", audiences = {"aud-1.auth0.com", "aud-2.auth0.com"}) } |
metricCosts |
Facoltativo. Indica che il metodo ha un limite di quota. Assegni l'annotazione @ApiMetricCost a metricCosts . Devi inoltre specificare l'attributo limitDefinitions per definire la quota nell'annotazione @Api . L'annotazione @ApiMetricCost utilizza i seguenti attributi:
|
metricCosts = { @ApiMetricCost(name = read-requests", cost = 1) } |
name |
Il nome di questo metodo nella libreria client generata. Questo viene preceduto automaticamente dal nome dell'API per creare un nome univoco per il metodo. Il valore name :
name , viene utilizzato il valore predefinito myapi . |
name = "foosBall.list" |
path |
Il percorso dell'URI da utilizzare per accedere a questo metodo. Se non imposti questa opzione, viene utilizzato un percorso predefinito basato sul nome del metodo Java. Se prevedi di aggiungere la gestione delle API, non includere una barra finale nel percorso. | path = "foos" |
scopes |
Specifica uno o più ambiti OAuth 2.0, uno dei quali è obbligatorio per chiamare questo metodo. Se imposti scopes per un metodo, sostituisce l'impostazione nell'annotazione @Api . Se definisci più di un ambito, tieni presente che il controllo dell'ambito viene superato se il token è stato creato per uno qualsiasi degli ambiti specificati. Per richiedere più ambiti, specifica un singolo String con uno spazio tra un ambito e l'altro. |
scopes = {"ss0", "ss1 and_ss2"} |
Esempio di annotazione @ApiMethod
Questa annotazione viene inserita prima della definizione del metodo all'interno di una classe:
I metodi che utilizzano un'entità come parametro devono utilizzare HttpMethod.POST
(per le operazioni di inserimento) o HttpMethod.PUT
(per le operazioni di aggiornamento):
@Named
L'annotazione @Named
è obbligatoria per tutti i parametri di tipo non entità trasmessi ai metodi lato server. Questa annotazione indica il nome del parametro nella richiesta che viene inserita qui. Un parametro non annotato con @Named
viene inserito con l'intero oggetto richiesta.
Importazioni obbligatorie
Per utilizzare questa funzionalità, sono necessarie le seguenti importazioni:
import javax.inject.Named;
Questo esempio mostra l'utilizzo di @Named
:
dove @Named
specifica che solo il parametro id
viene inserito
nella richiesta.
@ApiLimitMetric
Questa sezione descrive le annotazioni necessarie per definire le quotas per la tua API. Consulta la pagina relativa alla configurazione delle quote per tutti i passaggi necessari per impostare una quota.
Puoi assegnare l'annotazione @ApiLimitMetric
all'attributo limitDefinitions
delle
annotazioni con ambito API.
Devi inoltre aggiungere @ApiMetricCost
alle
@ApiMethod
annotazioni
per ciascun metodo a cui vuoi applicare una quota.
Importazioni obbligatorie
Per utilizzare questa funzionalità, devi eseguire la seguente importazione:
import com.google.api.server.spi.config.ApiLimitMetric;
Attributi
Attributi @ApiLimitMetric
|
Descrizione |
---|---|
name | Il nome della quota. In genere, questo è il tipo di richiesta (ad esempio "richieste-lettura" o "richieste-scrittura") che identifica in modo univoco la quota |
displayName | Il testo visualizzato per identificare la quota nella scheda Quote
della pagina Endpoint > Servizi della console Google Cloud. Questo testo viene mostrato anche ai consumatori della tua API nella pagina Quote di IAM e amministrazione e API e servizi. Il nome visualizzato deve contenere un massimo di 40 caratteri. Per motivi di leggibilità, il testo "al minuto per progetto" viene aggiunto automaticamente al nome visualizzato nelle pagine Quote. Per mantenere la coerenza con i nomi visualizzati dei servizi Google elencati nelle pagine Quote visualizzate dai consumatori della tua API, consigliamo di procedere come segue per il nome visualizzato:
|
limite | Un valore intero che corrisponde al numero massimo di richieste al minuto per progetto consumer per la quota. |
Esempio
limitDefinitions = {
@ApiLimitMetric(
name = "read-requests",
displayName = "Read requests",
limit = 1000),
@ApiLimitMetric(
name = "write-requests",
displayName = "Write requests",
limit = 50),
}
@ApiNamespace
L'annotazione @ApiNamespace
fa sì che le librerie client generate abbiano lo spazio dei nomi da te specificato, anziché creare uno spazio predefinito durante la generazione delle librerie client.
Per impostazione predefinita, se non utilizzi questa annotazione, lo spazio dei nomi utilizzato è l'inverso di your-project-id.appspot.com
. Ciò significa che il percorso del pacchetto è
com.appspot.your-project-id.yourApi
.
Puoi modificare lo spazio dei nomi predefinito fornendo l'annotazione @ApiNamespace
all'interno dell'annotazione @Api
:
Imposta l'attributo ownerDomain
sul dominio della tua azienda e ownerName
con il nome dell'azienda, ad esempio your-company.com
. L'inverso di ownerDomain
viene utilizzato per il percorso del pacchetto: com.your-company.yourApi
.
Facoltativamente, puoi utilizzare l'attributo packagePath
per fornire ulteriori ambiti.
Ad esempio, se imposti packagePath
su cloud
, il percorso del pacchetto utilizzato nella
libreria client è com.your-company.cloud.yourApi
. Puoi aggiungere altri valori al percorso del pacchetto fornendo il delimitatore /
: packagePath="cloud/platform"
.
@Nullable
Questa annotazione indica che un parametro di un metodo è facoltativo (e quindi un parametro di query). @Nullable
può essere utilizzato solo con i
parametri @Named
.
@ApiClass
In un'API Multiclass, puoi utilizzare @ApiClass
per specificare proprietà diverse per una determinata classe, sostituendo le proprietà equivalenti nella configurazione @Api
. Per una descrizione completa di questa annotazione, consulta
Utilizzo di @ApiClass
per le proprietà che possono variare da una classe all'altra.
@ApiReference
In un'API Multiclass, puoi utilizzare @ApiReference
per fornire un metodo alternativo di ereditarietà delle annotazioni. Per una descrizione completa di questa annotazione, consulta Utilizzo dell'ereditarietà @ApiReference
.
@ApiResourceProperty
@ApiResourceProperty
fornisce il controllo su come sono esposte le proprietà delle risorse nell'API.
Puoi utilizzarla su un getter o un setter della proprietà per omettere la proprietà da una risorsa API. Puoi anche utilizzarlo sul campo stesso, se il campo è privato, per esporlo nell'API. Puoi usare questa annotazione anche per modificare
il nome di una proprietà in una risorsa API.
Importazioni obbligatorie
Per utilizzare questa funzionalità, sono necessarie le seguenti importazioni:
import com.google.api.server.spi.config.ApiResourceProperty;
import com.google.api.server.spi.config.AnnotationBoolean;
Attributi
Attributi @ApiResourceProperty | Descrizione | Esempio |
---|---|---|
ignored |
Se impostato su AnnotationBoolean.TRUE , la proprietà viene omessa. Se non viene specificata o viene impostata su AnnotationBoolean.FALSE , la proprietà non viene omessa. |
@ApiResourceProperty(ignored = AnnotationBoolean.TRUE) |
name |
Se specificato, specifica il nome della proprietà da esporre nell'API. | @ApiResourceProperty(name = "baz") |
Classe di esempio con @ApiResourceProperty
Lo snippet seguente mostra una classe con getter di proprietà annotati con @ApiResourceProperty
:
Nello snippet di codice precedente, @ApiResourceProperty
viene applicato al getter getBin
per la proprietà bin
e l'attributo ignored
indica a Endpoints Frameworks di omettere questa proprietà nella risorsa API.
@ApiResourceProperty
viene applicato anche al campo privato visible
, che non ha getter o setter. L'utilizzo di questa annotazione espone questo campo come
proprietà nella risorsa API.
Nello stesso snippet, @ApiResourceProperty
viene applicato anche
a un getter diverso, getFoobar
, che restituisce un valore di proprietà
per la proprietà foobar
. L'attributo name
in questa
annotazione indica a Endpoints Frameworks di modificare il nome della proprietà nella
risorsa API. Il valore della proprietà è rimasto invariato.
Nello snippet di esempio precedente, la rappresentazione JSON di un oggetto Resp
appare simile a questa:
{"baz": "foobar", "visible": "nothidden"}
@ApiTransformer
L'annotazione @ApiTransformer
personalizza il modo in cui un tipo viene esposto in Endpoints tramite la trasformazione da e verso un altro tipo. (Il trasformatore specificato deve essere un'implementazione di com.google.api.server.spi.config.Transformer
.)
L'utilizzo dell'annotazione @ApiTransformer
su una classe è il modo migliore per specificare un trasformatore. Tuttavia, in alternativa, puoi specificare il trasformatore
personalizzato nell'attributo transformer
dell'annotazione
@Api
.
Importazioni obbligatorie
Per utilizzare questa funzionalità, devi eseguire la seguente importazione:
import com.google.api.server.spi.config.ApiTransformer;
Classe di esempio con @ApiTransformer
Lo snippet seguente mostra un corso annotato con @ApiTransformer
:
Questa classe viene trasformata dalla classe BarTransformer
.
Classe Transformer di Endpoints di esempio
Lo snippet seguente mostra una classe Transformer di esempio denominata BarTransformer
.
Questo è il trasformatore a cui fa riferimento @ApiTransformer
nello snippet precedente:
Supponendo che esista un oggetto con una proprietà bar
di tipo Bar
, senza il precedente Transformer, l'oggetto è rappresentato come:
{"bar": {"x": 1, "y": 2}}
Con il trasformatore, l'oggetto è rappresentato come segue:
{"bar": "1,2"}