API remota para servicios agrupados antiguos

El SDK de Java incluye una biblioteca llamada API remota que te permite acceder de forma transparente a los servicios de App Engine desde cualquier aplicación Java. Por ejemplo, puedes usar la API remota para acceder a un almacén de datos de producción desde una aplicación que se ejecute en tu máquina local. También puedes usar la API remota para acceder al almacén de datos de una aplicación de App Engine desde otra aplicación de App Engine.

Importante: No se admite el uso de RemoteApi a través de un proxy de red.

Precaución: Esta solución ya no se recomienda: las aplicaciones que usan esta API solo pueden ejecutarse en el tiempo de ejecución de Java 8 y deberán actualizarse a una solución recomendada antes de migrar al tiempo de ejecución de Java 11 o 17.

Cómo configurar el API remota en el servidor

El componente de servidor de la API remota es un servlet de Java que forma parte del entorno de ejecución de App Engine para Java. Este servlet recibe solicitudes del cliente de la API remota, las envía al servicio de backend adecuado y, a continuación, devuelve el resultado de la llamada al servicio al cliente. Para instalar el servlet de la API Remote, añade lo siguiente a tu 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: Para obtener más información sobre el uso de web.xml, consulta la página Descriptor de implementación.

El servlet devuelve un error si no hay ningún usuario autenticado o si el usuario autenticado no es administrador de tu aplicación, por lo que no es necesario configurar ninguna seguridad adicional. Una vez que hayas implementado tu aplicación con estos ajustes, cualquier aplicación que tenga instalado el cliente de la API remota podrá usar sus servicios. Esto incluye a los clientes Python que estén usando el API remota para Python.

Configurar la API remota en un cliente independiente

Para configurar el componente de cliente de la API remota para usarlo en una aplicación Java, añade ${SDK_ROOT}/lib/impl/appengine-api.jar y ${SDK_ROOT}/lib/appengine-remote-api.jar a tu classpath. A continuación, en tu código, configura e instala la API remota:

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();

El cliente de la API remota usará las credenciales predeterminadas de la aplicación, que utilizan OAuth 2.0.

Para obtener una ejecución de credenciales, sigue estos pasos:

gcloud auth application-default login

Nota: La llamada a la API remota a useApplicationDefaultCredential() solo puede usar las credenciales proporcionadas por el comando gcloud.

Puedes conectarte fácilmente a una aplicación de App Engine que se ejecute localmente en el servidor de desarrollo:

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

A continuación, se muestra una aplicación Java completa que, cuando se ejecuta, inserta una entidad en el almacén de datos:

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();
    }
  }
}

Configurar la API remota en un cliente de App Engine

También puedes usar la API remota para acceder a los servicios de una aplicación de App Engine desde otra aplicación de App Engine. Debes añadir ${SDK_ROOT}/lib/appengine-remote-api.jar a tu directorio WEB-INF/lib y, a continuación, en tu aplicación cliente de App Engine, configura e instala la API remota del mismo modo que lo hiciste en tu cliente Java independiente.

Ten en cuenta que RemoteApiInstaller solo instala la API remota en el subproceso que realiza la instalación, por lo que debes tener cuidado de no compartir instancias de esta clase entre subprocesos.

Usar la API remota con Maven

Para usar la función de API remota en tu proyecto de Maven, añade las siguientes dependencias al archivo pom.xml de tu proyecto:

<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>

Limitaciones y prácticas recomendadas

El módulo remote_api hace todo lo posible para que se comporte exactamente igual que el almacén de datos nativo de App Engine. En algunos casos, esto implica hacer cosas que son menos eficientes de lo que podrían ser. Cuando uses remote_api, ten en cuenta lo siguiente:

Todas las solicitudes del almacén de datos requieren un recorrido de ida y vuelta

Como accedes al almacén de datos a través de HTTP, hay un poco más de sobrecarga y latencia que cuando accedes a él de forma local. Para agilizar las cosas y reducir la carga, intenta limitar el número de viajes de ida y vuelta que haces agrupando las operaciones de obtención e inserción, y obteniendo lotes de entidades de las consultas. Este consejo no solo es útil para remote_api, sino también para usar el almacén de datos en general, ya que una operación por lotes solo se considera una operación de almacén de datos.

Solicitudes de la cuota de uso del módulo remote_api

Como remote_api funciona a través de HTTP, cada llamada a Datastore que hagas incurrirá en el uso de cuota para las solicitudes HTTP, los bytes entrantes y salientes, así como la cuota de Datastore habitual. Tenlo en cuenta si usas remote_api para hacer actualizaciones en bloque.

Aplicación de un límite de 1 MB para el API

Al igual que cuando se ejecuta de forma nativa, se sigue aplicando el límite de 1 MB en las solicitudes y respuestas de la API. Si tus entidades son especialmente grandes, puede que tengas que limitar el número que obtienes o insertas a la vez para no superar este límite. Por desgracia, esto entra en conflicto con la minimización de los viajes de ida y vuelta, por lo que lo más recomendable es usar los lotes más grandes posibles sin superar los límites de tamaño de las solicitudes o las respuestas. Sin embargo, esto no supondría ningún problema para la mayoría de las entidades.

Evitación de la iteración de las consultas

Cuando iteras sobre las consultas, el SDK obtiene entidades del almacén de datos en lotes de 20 y obtiene un nuevo lote cada vez que se agotan los existentes. Como cada lote se tiene que obtener en una solicitud independiente mediante remote_api, no se puede hacer de forma tan eficiente. En su lugar, remote_api ejecuta una consulta completamente nueva para cada lote, usando la función de desplazamiento para obtener más resultados.

Si sabes cuántas entidades necesitas, puedes hacer toda la obtención en una solicitud pidiendo el número que necesites.

Si no sabes cuántas entidades vas a querer, puedes usar cursores para iterar de forma eficiente en conjuntos de resultados grandes. También te permite evitar el límite de 1000 entidades impuesto en las consultas normales de Datastore.

Las transacciones son menos eficientes

Para implementar transacciones a través de remote_api, se acumula información sobre las entidades obtenidas en la transacción, junto con copias de las entidades que se insertaron o eliminaron en la transacción. Cuando se confirma la transacción, se envía toda esta información al servidor de App Engine, donde se deben obtener de nuevo todas las entidades que se han usado en la transacción, verificar que no se han modificado, insertar y eliminar todos los cambios que ha realizado la transacción y confirmarla. Si hay un conflicto, el servidor revierte la transacción y notifica al extremo del cliente, que tiene que repetir el proceso desde el principio.

Este enfoque funciona y duplica exactamente la funcionalidad que ofrecen las transacciones en el almacén de datos local, pero es bastante ineficiente. Usa transacciones siempre que sea necesario, pero intenta limitar el número y la complejidad de las transacciones que ejecutes para mejorar la eficiencia.