API remota per servizi in bundle legacy

L'SDK Java include una libreria chiamata Remote API che ti consente di accedere in modo trasparente ai servizi App Engine da qualsiasi applicazione Java. Ad esempio, puoi utilizzare l'API remota per accedere a un datastore di produzione da un'app in esecuzione sulla tua macchina locale. Puoi anche utilizzare l'API Remote per accedere al datastore di un'app App Engine da un'altra app App Engine.

Configurazione dell'API remota sul server

Il componente server dell'API remota è una servlet Java che fa parte del runtime App Engine per Java. Questa servlet riceve le richieste dal client API remota, le invia al servizio di backend appropriato e poi restituisce il risultato della chiamata al servizio al client. Per installare il servlet API remota, aggiungi quanto segue a web.xml:

<servlet>
  <display-name>Remote API Servlet</display-name>
  <servlet-name>RemoteApiServlet</servlet-name>
  <servlet-class>com.google.apphosting.utils.remoteapi.RemoteApiServlet</servlet-class>
  <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
  <servlet-name>RemoteApiServlet</servlet-name>
  <url-pattern>/remote_api</url-pattern>
</servlet-mapping>

La servlet restituisce un errore se non è presente alcun utente autenticato o se l'utente autenticato non è un amministratore della tua applicazione, quindi non è necessario configurare alcuna sicurezza aggiuntiva. Una volta eseguito il deployment dell'app con queste impostazioni, qualsiasi app con il client API remoto installato può utilizzare i suoi servizi. Sono inclusi i client Python che utilizzano l'API Python Remote.

Configurazione dell'API Remote su un client autonomo

Per configurare il componente client dell'API Remote per l'utilizzo all'interno di un'applicazione Java, aggiungi ${SDK_ROOT}/lib/impl/appengine-api.jar e ${SDK_ROOT}/lib/appengine-remote-api.jar al classpath. Quindi, nel codice, configura e installa l'API Remote:

import com.google.appengine.tools.remoteapi.RemoteApiInstaller;
import com.google.appengine.tools.remoteapi.RemoteApiOptions;

// ...
RemoteApiOptions options = new RemoteApiOptions()
    .server("[APP_ID].[REGION_ID].r.appspot.com", 443)
    .useApplicationDefaultCredential();

RemoteApiInstaller installer = new RemoteApiInstaller();
installer.install(options);
// ... all API calls executed remotely
installer.uninstall();

Il client API remota si basa sulle Credenziali predefinite dell'applicazione che utilizzano OAuth 2.0.

Per ottenere una corsa delle credenziali:

gcloud auth application-default login

Puoi connetterti altrettanto facilmente a un'app App Engine in esecuzione in locale nel server di sviluppo:

RemoteApiOptions options = new RemoteApiOptions()
    .server("localhost", 8888) // server name must equal "localhost"
    .useDevelopmentServerCredential();

Ecco un'applicazione Java completa che, una volta eseguita, inserisce un'entità nel datastore:

public class RemoteApiExample {

  public static void main(String[] args) throws IOException {
    String serverString = args[0];
    RemoteApiOptions options;
    if (serverString.equals("localhost")) {
      options = new RemoteApiOptions().server(serverString,
        8080).useDevelopmentServerCredential();
    } else {
      options = new RemoteApiOptions().server(serverString,
        443).useApplicationDefaultCredential();
    }
    RemoteApiInstaller installer = new RemoteApiInstaller();
    installer.install(options);
    try {
      DatastoreService ds = DatastoreServiceFactory.getDatastoreService();
      System.out.println("Key of new entity is " + ds.put(new Entity("Hello Remote API!")));
    } finally {
      installer.uninstall();
    }
  }
}

Configurazione dell'API remota su un client App Engine

Puoi anche utilizzare l'API remota per accedere ai servizi di un'applicazione App Engine da un'altra applicazione App Engine. Devi aggiungere ${SDK_ROOT}/lib/appengine-remote-api.jar alla directory WEB-INF/lib e poi, nell'app client App Engine, configura e installa l'API Remote proprio come hai fatto nel client Java autonomo.

Tieni presente che RemoteApiInstaller installa l'API Remote solo sul thread che esegue l'installazione, quindi fai attenzione a non condividere istanze di questa classe tra i thread.

Utilizzo dell'API Remote con Maven

Per utilizzare la funzionalità API Remote nel tuo progetto Maven, aggiungi le seguenti dipendenze al file pom.xml del progetto:

<dependency>
  <groupId>com.google.appengine</groupId>
  <artifactId>appengine-remote-api</artifactId>
  <version>1.9.64</version>
</dependency>
<dependency>
  <groupId>com.google.appengine</groupId>
  <artifactId>appengine-api-1.0-sdk</artifactId>
  <version>1.9.64</version>
</dependency>

Limitazioni e best practice

Il modulo remote_api fa di tutto per assicurarsi che, per quanto possibile, si comporti esattamente come il datastore App Engine nativo. In alcuni casi, ciò significa fare cose meno efficienti di quanto potrebbero essere altrimenti. Quando utilizzi remote_api, tieni presente quanto segue:

Ogni richiesta del datastore richiede un round trip

Poiché accedi al datastore tramite HTTP, il sovraccarico e la latenza sono leggermente superiori rispetto all'accesso locale. Per velocizzare le operazioni e ridurre il carico, prova a limitare il numero di round trip eseguito raggruppando le operazioni get e put e recuperando batch di entità dalle query. Questo è un buon consiglio non solo per remote_api, ma per l'utilizzo del datastore in generale, perché un'operazione batch è considerata una singola operazione Datastore.

Richieste di utilizzo della quota di remote_api

Poiché l'API remote_api opera su HTTP, ogni chiamata al datastore che effettui comporta l'utilizzo della quota per le richieste HTTP, i byte in entrata e in uscita, nonché la normale quota del datastore che ti aspetteresti. Tieni presente questo aspetto se utilizzi remote_api per eseguire aggiornamenti collettivi.

Si applicano i limiti API di 1 MB

Come quando viene eseguita in modo nativo, il limite di 1 MB per le richieste e le risposte API è ancora valido. Se le tue entità sono particolarmente grandi, potresti dover limitare il numero di entità recuperate o inserite contemporaneamente per rimanere al di sotto di questo limite. Purtroppo, questo è in conflitto con la riduzione al minimo dei round trip, quindi il consiglio migliore è di utilizzare i batch più grandi possibili senza superare i limiti di dimensioni delle richieste o delle risposte. Per la maggior parte delle entità, tuttavia, è improbabile che si verifichi un problema.

Evita di iterare le query

Quando esegui l'iterazione delle query, l'SDK recupera le entità dal datastore in batch di 20, recuperando un nuovo batch ogni volta che esaurisce quelli esistenti. Poiché ogni batch deve essere recuperato in una richiesta separata da remote_api, non è possibile farlo in modo efficiente. Al contrario, remote_api esegue una query completamente nuova per ogni batch, utilizzando la funzionalità di offset per approfondire i risultati.

Se sai di quante entità hai bisogno, puoi eseguire l'intero recupero in un'unica richiesta chiedendo il numero di cui hai bisogno.

Se non sai quante entità ti serviranno, puoi utilizzare i cursori per scorrere in modo efficiente grandi set di risultati. In questo modo puoi anche evitare il limite di 1000 entità imposto alle normali query datastore.

Le transazioni sono meno efficienti

Per implementare le transazioni tramite remote_api, vengono accumulate informazioni sulle entità recuperate all'interno della transazione, insieme a copie delle entità inserite o eliminate all'interno della transazione. Quando la transazione viene eseguita, tutte queste informazioni vengono inviate al server App Engine, dove devono essere recuperate tutte le entità utilizzate nella transazione, verificare che non siano state modificate, quindi inserire ed eliminare tutte le modifiche apportate dalla transazione ed eseguirla. Se si verifica un conflitto, il server esegue il rollback della transazione e invia una notifica al client, che deve ripetere l'intera procedura.

Questo approccio funziona e duplica esattamente la funzionalità fornita dalle transazioni nell'archivio dati locale, ma è piuttosto inefficiente. Utilizza le transazioni dove sono necessarie, ma cerca di limitarne il numero e la complessità per motivi di efficienza.