Annotazioni e sintassi di Cloud Endpoints Frameworks

Le annotazioni di Endpoints Frameworks descrivono la configurazione, i metodi, i parametri e altri dettagli essenziali dell'API 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. Maven Gli artefatti di App Engine Cloud Endpoints vengono forniti per creare e compilare un'API di backend e generare una libreria client da questa.

L'annotazione che specifica la configurazione e il comportamento dell'intera API (interessando 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 sono esposti nell'API pubblica.

Se hai bisogno di una configurazione API speciale per un metodo specifico, puoi utilizzare facoltativamente @ApiMethod per impostare la configurazione in base al metodo. Configura 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 un'annotazione @Api specifica per una classe specifica all'interno di un'API, consulta @ApiClass e @ApiReference.

Importazioni richieste

Per utilizzare questa funzionalità, devi importare quanto segue:

import com.google.api.server.spi.config.Api;

Attributi

Attributi @Api Descrizione Esempio
audiences Obbligatorio se l'API richiede l'autenticazione e se supporti i client Android. Per saperne di più, vedi ID client 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 l'API esegue l'autenticazione utilizzando Firebase, Auth0 o service account. Questo attributo non è obbligatorio se l'API esegue l'autenticazione utilizzando i token ID Google. Puoi impostarlo a livello di API o di singolo metodo. Impostalo su {EspAuthenticator.class} oppure puoi scrivere un autenticatore personalizzato, come descritto in Interfaccia Authenticator. authenticators = {EspAuthenticator.class}
backendRoot Deprecato. Per pubblicare l'API da un percorso diverso, nel file web.xml, modifica 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 la tua API ha name impostato su dfaanalytics, puoi utilizzare questa proprietà per specificare un nome canonico di DFA Group Analytics; le classi client generate conterranno quindi il nome DfaGroupAnalytics.

Devi includere gli spazi pertinenti tra i nomi, che vengono sostituiti dalle maiuscole e minuscole appropriate o dai trattini bassi.		 canonicalName = "DFA Analytics:"n
clientIds Obbligatorio se l'API utilizza l'autenticazione. Elenco degli ID client per i client autorizzati a richiedere token. Per saperne di più, vedi ID client e segmenti di pubblico. clientIds = {"1-web-apps.apps.googleusercontent.com", "2-android-apps.apps.googleusercontent.com"}
defaultVersion Specifica se viene utilizzata una versione predefinita se non ne viene fornita alcuna nell'attributo version. defaultVersion = AnnotationBoolean.TRUE
description Una breve descrizione dell'API. Questo valore viene esposto nel servizio di rilevamento per descrivere l'API e può essere utilizzato anche per generare la documentazione. description = "Sample API for a simple game"
documentationLink L'URL in cui gli utenti possono trovare la documentazione relativa a questa versione dell'API. Queste informazioni vengono visualizzate nella sezione "Scopri di più" di API Explorer nella parte superiore della pagina di API Explorer per consentire agli utenti di scoprire di più 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 singoli emittenti. issuerAudiences = { @ApiIssuerAudience(name = "auth0", audiences = {"aud-1.auth0.com", "aud-2.auth0.com"}) }
limitDefinitions Facoltativo. Utilizzato per definire le quote 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 i percorsi dell'API. Valore name:
  • Deve iniziare con una lettera minuscola
  • Must (Deve) corrispondere all'espressione regolare [a-z]+[A-Za-z0-9]*
Se non specifichi name, viene utilizzato il valore predefinito myapi.		 name = "foosBall"
namespace Configura lo spazio dei nomi per i client generati. Vedi @ApiNamespace. namespace=@ApiNamespace(ownerDomain="your-company.com", ownerName="YourCo", packagePath="cloud/platform"
root Deprecato. Per pubblicare l'API da un percorso diverso, nel file web.xml, modifica url-pattern nella sezione EndpointsServlet. <url-pattern>/example-api/*</url-pattern>
scopes Se non viene fornito, il valore predefinito è l'ambito email (https://www.googleapis.com/auth/userinfo.email), che è obbligatorio per OAuth. Se vuoi, puoi ignorare 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 viene creato per uno qualsiasi degli ambiti specificati. Per richiedere più ambiti, deve essere specificato un singolo String con uno spazio tra un ambito e l'altro. Per ignorare gli ambiti specificati qui per un determinato 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 discovery e directory. title = "My Backend API"
transformers Specifica un elenco di trasformatori personalizzati. Tieni presente che esiste un'annotazione alternativa (@ApiTransformer) preferibile. Questo attributo è sostituito da @ApiTransformer. transformers = {BazTransformer.class}
version Specifica la versione dell'endpoint. Se non lo fornisci, viene utilizzato il valore predefinito v1. version = "v2"

Esempio di annotazione @Api

Questa annotazione viene inserita prima della definizione della classe:

/** An endpoint class we are exposing. */
@Api(name = "myApi",
    version = "v1",
    namespace = @ApiNamespace(ownerDomain = "helloworld.example.com",
        ownerName = "helloworld.example.com",
        packagePath = ""))

ID client e segmenti di pubblico

Per l'autenticazione OAuth2, viene emesso un token OAuth2 per 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 Google Cloud console, crei un ID client. Questo ID client è quello che richiede un token OAuth2 a Google a scopo di autenticazione. Quando l'API di backend è protetta dall'autenticazione, viene inviato e aperto un token di accesso OAuth2 da Endpoints, l'ID client viene estratto dal token e poi 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 autorizzati a richiedere token. Questo elenco deve essere composto da tutti gli ID client che hai ottenuto tramite Google Cloud console per i tuoi 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 può 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 di 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 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 della console, viene creato automaticamente un ID client predefinito e denominato per l'utilizzo da parte del progetto. Google Cloud Quando carichi l'API di backend in App Engine, viene utilizzato questo ID client. Si tratta dell'ID client web menzionato in Autenticazione API.

@ApiMethod: Annotazioni con ambito del metodo

L'annotazione @ApiMethod viene utilizzata per fornire una configurazione API diversa da quella predefinita fornita dalle annotazioni @Api o @ApiClass. Tieni presente che questa operazione è facoltativa: tutti i metodi pubblici, non statici e non bridge in una classe con un'annotazione @Api sono esposti nell'API, indipendentemente dal fatto che abbiano o meno un'annotazione @ApiMethod.

Gli attributi all'interno di questa annotazione ti consentono di configurare i dettagli di un singolo metodo API. Se lo stesso attributo è specificato in @Api e @ApiMethod, @ApiMethod ha la precedenza.

Importazioni richieste

Per utilizzare questa funzionalità, devi importare quanto segue:

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 ignorare la configurazione in @API. Per saperne di più, vedi ID client e segmenti di pubblico. audiences = {"1-web-apps.apps.googleusercontent.com", "2-web-apps.apps.googleusercontent.com"}
authenticators Obbligatorio se l'API esegue l'autenticazione utilizzando Firebase, Auth0 o service account e non hai impostato questo attributo a livello di API. Questo attributo non è obbligatorio se l'API esegue l'autenticazione utilizzando i token ID Google. Impostalo su {EspAuthenticator.class} oppure scrivi un autenticatore personalizzato, come descritto in Interfaccia Authenticator. authenticators = {EspAuthenticator.class}
clientIds Elenco degli 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 lo imposti, viene scelto un valore predefinito in base al nome del metodo. httpMethod = HttpMethod.GET
issuerAudiences Fornisci questo valore se vuoi ignorare 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 anche specificare l'attributo limitDefinitions per definire la quota nell'annotazione @Api. L'annotazione @ApiMetricCost prevede i seguenti attributi:
  • name: un nome specificato nell'annotazione ApiLimitMetric.
  • costo : un numero intero che specifica il costo per ogni richiesta. Il costo consente ai metodi di consumare a tariffe diverse dalla stessa quota. Ad esempio, se una quota ha un limite di 1000 e un costo di 1, l'applicazione chiamante può effettuare 1000 richieste al minuto prima di superare il limite. Con un costo di 2 per la stessa quota, un'applicazione chiamante può effettuare solo 500 richieste al minuto prima di superare il limite.
 metricCosts = { @ApiMetricCost(name = read-requests", cost = 1) }
name Il nome di questo metodo nella libreria client generata. A questo viene aggiunto automaticamente il prefisso del nome dell'API per creare un nome univoco per il metodo. Valore name:
  • Deve iniziare con una lettera minuscola
  • Must (Deve) corrispondere all'espressione regolare [a-z]+[A-Za-z0-9]*
Se non specifichi name, viene utilizzato il valore predefinito myapi.		 name = "foosBall.list"
path Il percorso URI da utilizzare per accedere a questo metodo. Se non lo imposti, viene utilizzato un percorso predefinito in base al nome del metodo Java. Se prevedi di aggiungere la gestione 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, questa impostazione sostituisce quella nell'annotazione @Api. Se definisci più di un ambito, tieni presente che il controllo dell'ambito viene superato se il token viene 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:

/** A simple endpoint method that takes a name and says Hi back. */
@ApiMethod(
    name = "sayHiUser",
    httpMethod = ApiMethod.HttpMethod.GET)
public MyBean sayHiUser(@Named("name") String name, User user)
    throws OAuthRequestException, IOException {
  MyBean response = new MyBean();
  response.setData("Hi, " + name + "(" + user.getEmail() + ")");

  return response;
}

I metodi che accettano un'entità come parametro devono utilizzare HttpMethod.POST (per le operazioni di inserimento) o HttpMethod.PUT (per le operazioni di aggiornamento):

@ApiMethod(
    name = "mybean.insert",
    path = "mybean",
    httpMethod = ApiMethod.HttpMethod.POST
)
public void insertFoo(MyBean foo) {
}

@Named

L'annotazione @Named è obbligatoria per tutti i parametri di tipo non entità passati 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 richieste

Per utilizzare questa funzionalità, devi importare quanto segue:

import javax.inject.Named;

Questo esempio mostra l'utilizzo di @Named:

/** A simple endpoint method that takes a name and says Hi back. */
@ApiMethod(name = "sayHi")
public MyBean sayHi(@Named("name") String name) {
  MyBean response = new MyBean();
  response.setData("Hi, " + name);

  return response;
}

dove @Named specifica che nella richiesta viene inserito solo il parametro id.

@ApiLimitMetric

Questa sezione descrive le annotazioni necessarie per definire le quote per la tua API. Consulta la sezione Configurazione delle quote per tutti i passaggi necessari per configurare una quota.

Assegna l'annotazione @ApiLimitMetric all'attributo limitDefinitions delle annotazioni con ambito API. Devi anche aggiungere @ApiMetricCost alle annotazioni @ApiMethod per ogni metodo a cui vuoi applicare una quota.

Importazioni richieste

Per utilizzare questa funzionalità, devi importare quanto segue:

import com.google.api.server.spi.config.ApiLimitMetric;

Attributi

Attributi @ApiLimitMetric

Descrizione
nome Il nome della quota. In genere, si tratta del tipo di richiesta (ad esempio, "read-requests" o "write-requests") che identifica in modo univoco la quota
displayName Il testo visualizzato per identificare la quota nella scheda Quote nella pagina Endpoint > Servizi della console Google Cloud . Questo testo viene visualizzato anche dai consumer 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 che vedono i consumatori della tua API, ti consigliamo quanto segue per il nome visualizzato:
  • Utilizza "Richieste" quando hai una sola metrica.
  • Quando hai più metriche, ognuna deve descrivere il tipo di richiesta e contenere la parola "richieste" (ad esempio "Richieste di lettura" o "Richieste di scrittura").
  • Utilizza "unità di quota" anziché "richieste" quando uno dei costi per questa quota è superiore a 1.
limite Un valore intero che rappresenta il 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 che specifichi, anziché uno spazio dei nomi predefinito creato durante la generazione della libreria client.

Per impostazione predefinita, se non utilizzi questa annotazione, lo spazio dei nomi utilizzato è l'inverso di your-project-id.appspot.com. ovvero 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:

/** An endpoint class we are exposing. */
@Api(name = "myApi",
    version = "v1",
    namespace = @ApiNamespace(ownerDomain = "helloworld.example.com",
        ownerName = "helloworld.example.com",
        packagePath = ""))

Imposta l'attributo ownerDomain sul dominio della tua azienda e ownerName sul nome della tua azienda, ad esempio your-company.com. L'inverso di ownerDomain viene utilizzato per il percorso del pacchetto: com.your-company.yourApi.

Se vuoi, puoi utilizzare l'attributo packagePath per fornire un ambito più specifico. Ad esempio, impostando 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 multiclasse, puoi utilizzare @ApiClass per specificare proprietà diverse per una determinata classe, sostituendo le proprietà equivalenti nella configurazione @Api. Consulta Utilizzo di @ApiClass per le proprietà che possono variare tra le classi per una descrizione completa di questa annotazione.

@ApiReference

In un'API multiclasse, puoi utilizzare @ApiReference per fornire un metodo alternativo di ereditarietà delle annotazioni. Consulta Utilizzo dell'ereditarietà @ApiReference per una descrizione completa di questa annotazione.

@ApiResourceProperty

@ApiResourceProperty fornisce il controllo su come le proprietà delle risorse vengono esposte nell'API. Puoi utilizzarlo in un getter o setter di proprietà per omettere la proprietà da una risorsa API. Puoi utilizzarlo anche sul campo stesso, se il campo è privato, per esporlo nell'API. Puoi utilizzare questa annotazione anche per modificare il nome di una proprietà in una risorsa API.

Importazioni richieste

Per utilizzare questa funzionalità, devi importare quanto segue:

import com.google.api.server.spi.config.ApiResourceProperty;
import com.google.api.server.spi.config.AnnotationBoolean;

Attributi

Attributi @ApiResourceProperty Descrizione Esempio
ignored Se impostata su AnnotationBoolean.TRUE, la proprietà viene omessa. Se non specificata o impostata su AnnotationBoolean.FALSE, la proprietà non viene omessa. @ApiResourceProperty(ignored = AnnotationBoolean.TRUE)
name Se fornito, specifica il nome della proprietà da esporre nell'API. @ApiResourceProperty(name = "baz")

Corso di esempio con @ApiResourceProperty

Il seguente snippet mostra una classe con getter di proprietà annotati con @ApiResourceProperty:


class Resp {
  private String foobar = "foobar";
  private String bin = "bin";

  @ApiResourceProperty
  private String visible = "nothidden";

  @ApiResourceProperty(ignored = AnnotationBoolean.TRUE)
  public String getBin() {
    return bin;
  }

  public void setBin(String bin) {
    this.bin = bin;
  }

  @ApiResourceProperty(name = "baz")
  public String getFoobar() {
    return foobar;
  }

  public void setFoobar(String foobar) {
    this.foobar = foobar;
  }
}

public Resp getResp() {
  return new Resp();
}

Nello snippet di codice precedente, @ApiResourceProperty viene applicato al getter getBin per la proprietà bin, con l'impostazione dell'attributo ignored che 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 della 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à rimane invariato.

Nello snippet di esempio precedente, la rappresentazione JSON di un oggetto Resp è 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 preferito per specificare un transformer. Tuttavia, puoi specificare il tuo trasformatore personalizzato nell'attributo transformer dell'annotazione @Api.

Importazioni richieste

Per utilizzare questa funzionalità, devi importare quanto segue:

import com.google.api.server.spi.config.ApiTransformer;

Corso di esempio con @ApiTransformer

Il seguente snippet mostra una classe annotata con @ApiTransformer:


@ApiTransformer(BarTransformer.class)
public class Bar {
  private final int x;
  private final int y;

  public Bar(int x, int y) {
    this.x = x;
    this.y = y;
  }

  public int getX() {
    return x;
  }

  public int getY() {
    return y;
  }
}

Questo corso viene trasformato dal corso BarTransformer.

Classe di trasformazione degli endpoint di esempio

Il seguente snippet mostra una classe di trasformazione di esempio denominata BarTransformer. Questo è il trasformatore a cui fa riferimento @ApiTransformer nello snippet precedente:

public class BarTransformer implements Transformer<Bar, String> {
  public String transformTo(Bar in) {
    return in.getX() + "," + in.getY();
  }

  public Bar transformFrom(String in) {
    String[] xy = in.split(",");
    return new Bar(Integer.parseInt(xy[0]), Integer.parseInt(xy[1]));
  }
}

Supponendo che esista un oggetto con una proprietà bar di tipo Bar, senza il trasformatore precedente, l'oggetto è rappresentato come segue:

{"bar": {"x": 1, "y": 2}}

Con il trasformatore, l'oggetto viene rappresentato come:

{"bar": "1,2"}