API Remote per servizi in bundle legacy

L'SDK Java include una libreria chiamata API remota che ti consente di accedere in modo trasparente ai servizi App Engine da qualsiasi applicazione Java. Ad esempio, puoi utilizzare l'API Remote 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 Engine da un'altra app di App Engine.

Importante: l'utilizzo di RemoteApi su un proxy di rete non è supportato.

Attenzione: questa soluzione non è più consigliata: le app che utilizzano questa API possono essere eseguite solo nel runtime Java 8 e dovranno eseguire l'upgrade a una soluzione consigliata prima di eseguire la migrazione al runtime Java 11/17.

Configurazione dell'API remota sul server

Il componente server dell'API Remote è un servlet Java che fa parte dell'applicazione Runtime Engine per Java. Questo servlet riceve richieste dal client API Remote, li invia al servizio di backend appropriato e quindi restituisce il risultato della chiamata di servizio al client. Per installare il servlet dell'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>

Nota: per ulteriori informazioni sull'utilizzo di web.xml, consulta la pagina Descrittore di deployment.

Il servlet restituisce un errore se non è presente un utente autenticato o se l'utente autenticato non è un amministratore dell'applicazione, pertanto non è necessario configurare alcuna sicurezza aggiuntiva. Dopo aver eseguito il deployment dell'app con questi , qualsiasi app con il client API Remote installato può utilizzare i propri servizi. Sono inclusi i client Python che utilizzano l'API Python Remote.

Configurazione dell'API remota su un client autonomo

Per configurare il componente client dell'API Remote per l'utilizzo all'interno di una finestra Java aggiungere ${SDK_ROOT}/lib/impl/appengine-api.jar e ${SDK_ROOT}/lib/appengine-remote-api.jar al percorso della classe. Poi, il codice, configurare e installare 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 remoto si baserà sulle Credenziali predefinite dell'applicazione che utilizzano OAuth 2.0.

Per ottenere una credenziale, esegui:

gcloud auth application-default login

Nota: la chiamata API Remote a useApplicationDefaultCredential() può utilizzare esclusivamente le credenziali fornite dal comando gcloud.

Puoi connetterti facilmente a un'app App Engine in esecuzione localmente Server di sviluppo:

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

Ecco un'applicazione Java completa che, quando viene 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();
    }
  }
}

Configurare l'API remota su un client App Engine

Puoi anche utilizzare l'API Remote 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 tua directory WEB-INF/lib e poi, nell'app client App Engine, configurare e installare l'API Remote come hai fatto nel client Java autonomo.

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

Utilizzo dell'API remota con Maven

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

<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 fare in modo che, per quanto possibile, si comporta esattamente come il datastore nativo di App Engine. In alcuni casi, ciò significa fare cose meno efficienti di quanto non in caso contrario. Quando utilizzi remote_api, tieni presente quanto segue:

Ogni richiesta di datastore richiede un round trip

Poiché si accede al datastore tramite HTTP, l'overhead è leggermente superiore anziché in locale. Per velocizzare le operazioni e diminuire il carico, prova a limitare il numero di viaggi di andata e ritorno che esegui raggruppando get e put e recuperando batch di entità dalle query. Questo è un buon consiglio non solo per remote_api, ma anche per l'utilizzo del datastore in generale, perché un'operazione batch è considerata solo una singola operazione di Datastore.

Quota di utilizzo delle richieste a remote_api

Poiché remote_api opera tramite HTTP, ogni chiamata al datastore comporta un utilizzo della quota per le richieste HTTP, i byte in entrata e in uscita, nonché la consueta quota del datastore. Tieni presente questo aspetto se utilizzi remote_api per eseguire aggiornamenti collettivi.

Si applicano i limiti dell'API di 1 MB

Come quando viene eseguita in modo nativo, il limite di 1 MB per le richieste e le risposte API rimane . Se le entità sono particolarmente grandi, potrebbe essere necessario limitare il numero di elementi recuperati o inseriti contemporaneamente per rimanere al di sotto di questo limite. Questo conflitto riducendo al minimo i viaggi di andata e ritorno, purtroppo il miglior consiglio è quello di utilizzare batch più grandi possibili senza superare le dimensioni della richiesta o della risposta limitazioni. Tuttavia, per la maggior parte delle entità, è improbabile che si tratti di un problema.

Evita di eseguire l'iterazione sulle query

Quando esegui l'iterazione sulle 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 visualizzare altri risultati.

Se sai di quante entità hai bisogno, puoi eseguire l'intero recupero in una richiesta chiedendo il numero che ti serve.

Se non sai quante entità ti serviranno, puoi utilizzare i cursori per eseguire in modo efficiente l'iterazione su insiemi di risultati di grandi dimensioni. Anche questo permette di evitare il limite di 1000 entità imposto al datastore normale query.

Le transazioni sono meno efficienti

Per implementare le transazioni tramite remote_api, informazioni sulle entità recuperate all'interno della transazione, insieme alle copie inserite o eliminate all'interno della transazione. Quando la transazione viene eseguita, invia tutte queste informazioni al server App Engine, dove deve recuperare di nuovo tutte le entità utilizzate nella transazione, verificare che non siano state modificate, quindi inserire ed eliminare tutte le modifiche apportate dalla transazione ed eseguirne il commit. Se si verifica un conflitto, il server esegue il rollback della transazione e invia una notifica al client, che deve ripetere la procedura da capo.

Questo approccio funziona e duplica esattamente la funzionalità fornita dalle transazioni nel datastore locale, ma è piuttosto inefficiente. A tutti i costi utilizzano le transazioni dove necessario, ma cerca di limitare il numero e la complessità delle transazioni eseguite nell'interesse dell'efficienza.