Questa pagina è stata tradotta dall'API Cloud Translation.

API multiclasse

Se una singola API è particolarmente complessa, potresti volerla implementare da più classi Java. Per fare in modo che classi diverse facciano parte della stessa API, devi:

Assegna a ogni classe le stesse stringhe name e version nell'annotazione @Api.
Aggiungi le API della classe come elenco separato da virgole in web.xml.

Ad esempio, le seguenti due classi fanno parte dell'API tictactoe:

@Api(name = "tictactoe", version = "v1")
class TicTacToeA { … }

@Api(name = "tictactoe", version = "v1")
class TicTacToeB { … }

La configurazione dell'API viene specificata tramite le proprietà di annotazione @Api. Tuttavia, per più classi nella stessa API, i requisiti di @Api vanno oltre la semplice presenza delle stesse stringhe name e version nell'annotazione @Api per ogni classe. Infatti, la tua API di backend non funzionerà se ci sono differenze nelle configurazioni API specificate nelle proprietà @Api delle classi. Qualsiasi differenza nelle proprietà @Api per le classi in un'API multiclasse comporta una configurazione dell'API "ambigua", che non funzionerà in Cloud Endpoints Frameworks per App Engine.

Esistono diversi modi per creare un'API multiclasse non ambigua:

Assicurati manualmente che tutte le classi in una singola API abbiano esattamente le stesse proprietà di annotazione @Api.
Utilizza l'ereditarietà delle annotazioni tramite l'ereditarietà Java. In questa ereditarietà, tutte le classi di una singola API ereditano la stessa configurazione API da una classe base comune annotata con @Api.
Utilizza l'ereditarietà delle annotazioni tramite l'annotazione @ApiReference su tutte le classi di una singola API per fare in modo che facciano riferimento alla stessa configurazione API da una classe comune annotata con @Api.

Utilizzo di `@ApiClass` per le proprietà che possono variare tra le classi

Per utilizzare questa funzionalità, devi importare quanto segue:

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

Mentre tutte le proprietà nell'annotazione @Api devono corrispondere per tutte le classi in un'API, puoi utilizzare anche l'annotazione @ApiClass per fornire proprietà che non devono essere esattamente uguali tra le classi. Ad esempio:

// API methods implemented in this class allow only "clientIdA".
@Api(name = "tictactoe", version = "v1")
@ApiClass(clientIds = { "clientIdA" })
class TicTacToeA { … }

// API methods implemented in this class provide unauthenticated access.
@Api(name = "tictactoe", version = "v1")
class TicTacToeB { … }

dove TicTacToeA limita l'accesso utilizzando una lista consentita di ID client contenente l'ID client consentito e TicTacToeB non limita l'accesso.

Tutte le proprietà fornite dall'annotazione @ApiClass hanno una proprietà equivalente nell'annotazione @Api. Tieni presente che la proprietà equivalente @Api funge da valore predefinito a livello di API. Se esiste un valore predefinito a livello di API per la stessa proprietà, specificato in @Api, la proprietà @ApiClass specifica della classe sostituisce il valore predefinito a livello di API.

Gli esempi seguenti illustrano l'override delle proprietà @Api da parte degli equivalenti @ApiClass specifici per la classe:

// For this class "boards" overrides "games".
@Api(name = "tictactoe", version = "v1", resource = "games")
@ApiClass(resource = "boards")
class TicTacToeBoards { … }

// For this class "scores" overrides "games".
@Api(name = "tictactoe", version = "v1", resource = "games")
@ApiClass(resource = "scores")
class TicTacToeScores { … }

// For this class, the API-wide default "games" is used as the resource.
@Api(name = "tictactoe", version = "v1", resource = "games")
class TicTacToeGames { … }

Ereditarietà delle annotazioni

Le proprietà di annotazione @Api e @ApiClass possono essere ereditate da altre classi e le singole proprietà possono essere sostituite tramite ereditarietà Java o ereditarietà @ApiReference.

Utilizzo dell'ereditarietà Java

Una classe che estende un'altra classe con annotazioni @Api o @ApiClass si comporta come se fosse annotata con le stesse proprietà. Ad esempio:

@Api(name = "tictactoe", version = "v1")
class TicTacToeBase { … }

// TicTacToeA and TicTacToeB both behave as if they have the same @Api annotation as
// TicTacToeBase
class TicTacToeA extends TicTacToeBase { … }
class TicTacToeB extends TicTacToeBase { … }

Le annotazioni vengono ereditate solo tramite la creazione di sottoclassi Java, non tramite l'implementazione dell'interfaccia. Ad esempio:

@Api(name = "tictactoe", version = "v1")
interface TicTacToeBase { … }
// Does *not* behave as if annotated.
class TicTacToeA implements TicTacToeBase { … }

Di conseguenza, non è supportata alcuna forma di ereditarietà multipla delle annotazioni dei framework.

L'ereditarietà funziona anche per @ApiClass:

@ApiClass(resource = "boards")
class BoardsBase { … }

// TicTacToeBoards behaves as if annotated with the @ApiClass from BoardsBase.
// Thus, the "resource" property will be "boards".
@Api(name = "tictactoe", version = "v1", resource = "scores")
class TicTacToeBoards extends BoardsBase { … }

dove TicTacToeBoards eredita il valore della proprietà resource boards da BoardsBase, sostituendo così l'impostazione della proprietà resource (scores) nella relativa annotazione @Api. Ricorda che se una classe ha specificato la proprietà risorsa nell'annotazione @Api, tutte le classi devono specificare la stessa impostazione nell'annotazione @Api; questa tecnica di ereditarietà ti consente di ignorare la proprietà @Api.

Utilizzo dell'ereditarietà `@ApiReference`

Per utilizzare questa funzionalità, devi importare quanto segue:

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

L'annotazione @ApiReference fornisce un modo alternativo per specificare l'ereditarietà delle annotazioni. Una classe che utilizza @ApiReference per specificare un'altra classe con annotazioni @Api o @ApiClass si comporta come se fosse annotata con le stesse proprietà. Ad esempio:

@Api(name = "tictactoe", version = "v1")
class TicTacToeBase { … }

// TicTacToeA behaves as if it has the same @Api annotation as TicTacToeBase
@ApiReference(TicTacToeBase.class)
class TicTacToeA { … }

Se vengono utilizzati sia l'ereditarietà Java sia @ApiReference, le annotazioni vengono ereditate solo tramite l'annotazione @ApiReference. Le annotazioni @Api e @ApiClass nella classe ereditata tramite l'ereditarietà Java vengono ignorate. Ad esempio:

@Api(name = "tictactoe", version = "v1")
class TicTacToeBaseA { … }
@Api(name = "tictactoe", version = "v2")
class TicTacToeBaseB { … }

// TicTacToe will behave as if annotated the same as TicTacToeBaseA, not TicTacToeBaseB.
// The value of the "version" property will be "v1".
@ApiReference(TicTacToeBaseA.class)
class TicTacToe extends TicTacToeBaseB { … }

Override della configurazione ereditata

Indipendentemente dal fatto che l'ereditarietà della configurazione avvenga tramite l'ereditarietà Java o @ApiReference, puoi eseguire l'override della configurazione ereditata utilizzando una nuova annotazione @Api o @ApiClass. Vengono sostituite solo le proprietà di configurazione specificate nella nuova annotazione. Le proprietà non specificate vengono comunque ereditate. Ad esempio:

@Api(name = "tictactoe", version = "v2")
class TicTacToe { … }

// Checkers will behave as if annotated with name = "checkers" and version = "v2"
@Api(name = "checkers")
class Checkers extends TicTacToe { … }

La sostituzione dell'ereditarietà funziona anche per @ApiClass:

@Api(name = "tictactoe", version = "v1")
@ApiClass(resource = "boards", clientIds = { "c1" })
class Boards { … }

// Scores will behave as if annotated with resource = "scores" and clientIds = { "c1" }
@ApiClass(resource = "scores")
class Scores { … }

L'override funziona anche quando l'ereditarietà avviene tramite @ApiReference:

@Api(name = "tictactoe", version = "v2")
class TicTacToe { … }

// Checkers will behave as if annotated with name = "checkers" and version = "v2"
@ApiReference(TicTacToe.class)
@Api(name = "checkers")
class Checkers { … }

Ereditare le annotazioni `@ApiMethod`

L'annotazione @ApiMethod può essere ereditata dai metodi sottoposti a override. Ad esempio:

class TicTacToeBase {
  @ApiMethod(httpMethod = "POST")
  public Game setGame(Game game) { … }
}
@Api(name = "tictactoe", version = "v1")
class TicTacToe extends TicTacToeBase {
  // setGame behaves as if annotated with the @ApiMethod from TicTacToeBase.setGame.
  // Thus the "httpMethod" property will be "POST".
  @Override
  public Game setGame(Game game) { … }
}

Analogamente all'ereditarietà delle annotazioni @Api e @ApiClass, se più metodi che si sovrascrivono a vicenda hanno annotazioni @ApiMethod, è possibile sovrascrivere le singole proprietà. Ad esempio:

class TicTacToeBase {
  @ApiMethod(httpMethod = "POST", clientIds = { "c1" })
  public Game setGame(Game game) { … }
}
@Api(name = "tictactoe", version = "v1")
class TicTacToe extends TicTacToeBase {
  // setGame behaves as if annotated with httpMethod = "GET" and clientIds = { "c1"}.
  @ApiMethod(httpMethod = "GET")
  @Override
  public Game setGame(Game game) { … }
}

Non esiste un'annotazione @ApiReference o equivalente per i metodi, quindi @ApiMethod viene sempre ereditato tramite l'ereditarietà Java, non tramite @ApiReference.

Regole di ereditarietà e precedenza

Per riassumere la discussione precedente, la tabella seguente mostra le regole di ereditarietà e l'ordine di precedenza.

Annotazione/ereditarietà	Regola
`@Api`	Deve essere identico per tutti i corsi.
`@ApiClass`	Specificato per un corso per ignorare le proprietà `@Api`.
Ereditarietà Java	La classe eredita `@Api` e `@ApiClass` della classe base.
`@ApiReference`	La classe eredita `@Api` e `@ApiClass` della classe a cui viene fatto riferimento.
Utilizzo di `@ApiReference` in una classe (Java) che eredita da una classe base	La classe eredita `@Api` e `@ApiClass` della classe a cui viene fatto riferimento, non dalla classe base.

Casi d'uso comuni per l'ereditarietà delle annotazioni

Di seguito sono riportati alcuni esempi di casi d'uso tipici per l'ereditarietà:

Per il controllo delle versioni dell'API:

@Api(name = "tictactoe", version = "v1")
class TicTacToeV1 { … }
@Api(version = "v2")
class TicTacToeV2 extends TicTacToeV1 { … }

Per le API multiclasse:

@Api(name = "tictactoe", version = "v1")
class TicTacToeBase {}
@ApiClass(resource = "boards")
class TicTacToeBoards extends TicTacToeBase { … }
@ApiClass(resource = "scores")
class TicTacToeScores extends TicTacToeBase { … }

Per testare versioni diverse della stessa API:

@Api(name = "tictactoe", version = "v1")
class TicTacToe {
  protected Foo someMethod() {
    // Do something real;
  }

  public Foo getFoo() { … }
}


@Api(version="v1test")
class TicTacToeTest extends TicTacToe {
  protected Foo someMethod() {
    // Stub out real action;
  }
}

dove someMethod potrebbe restituire risposte predeterminate, evitare chiamate con effetti collaterali, saltare una richiesta di rete o di datastore e così via.

Aggiunta dei corsi a `web.xml`

Dopo aver annotato le classi, devi aggiungerle al file web.xml. L'esempio seguente mostra una singola classe:

<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
         http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
         version="3.1">
    <!-- Wrap the backend with Endpoints Frameworks v2. -->
    <servlet>
        <servlet-name>EndpointsServlet</servlet-name>
        <servlet-class>com.google.api.server.spi.EndpointsServlet</servlet-class>
        <init-param>
            <param-name>services</param-name>
            <param-value>com.example.skeleton.MyApi</param-value>
        </init-param>
    </servlet>
    <!-- Route API method requests to the backend. -->
    <servlet-mapping>
        <servlet-name>EndpointsServlet</servlet-name>
        <url-pattern>/_ah/api/*</url-pattern>
    </servlet-mapping>
</web-app>

Per aggiungere più corsi:

Sostituisci <param-value>com.example.skeleton.MyApi</param-value> con il nome della tua classe API.

Aggiungi ogni classe all'interno dello stesso campo <param-value> separato da una virgola, ad esempio:

<param-value>com.example-company.example-api.Hello,com.example-company.example-api.Goodbye</param-value>

API multiclasse Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Utilizzo di @ApiClass per le proprietà che possono variare tra le classi