Referencia de appengine-web.xml

Además del descriptor de implementación web.xml, las aplicaciones de App Engine para Java usan un archivo de configuración denominado appengine-web.xml a fin de especificar información de la aplicación y de identificar cuáles son los archivos estáticos (como imágenes ) en el WAR y cuáles son los archivos de recursos que usa la aplicación.

Ejemplo

En el siguiente ejemplo, se muestra un archivo mínimo que especifica el ID de la aplicación, un identificador de versión, y ningún archivo estático o archivo de recursos:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>_your_app_id_</application><!-- unused for Cloud SDK based tooling -->
  <version>alpha-001</version><!-- unused for Cloud SDK based tooling -->
  <threadsafe>true</threadsafe>
  <runtime>java8</runtime>
</appengine-web-app>

Sintaxis

Una aplicación de Java en App Engine debe tener un archivo llamado appengine-web.xml en su WAR, en el directorio WEB-INF/. Este es un archivo XML con el elemento raíz <appengine-web-app>.

Puedes encontrar las especificaciones de la definición del tipo de documento y del esquema para appengine-web.xml en el directorio docs/ del SDK.

Elemento Descripción
<application>

No es necesario si implementas tu aplicación con herramientas basadas en el SDK de Cloud, como el comando de gcloud app deploy, los complementos de IntelliJ o Eclipse, o los complementos de Maven o Gradle. Las herramientas basadas en el SDK de Cloud ignoran este elemento y obtienen el ID del proyecto desde la propiedad del proyecto en la configuración de gcloud. Ten en cuenta que, aunque puedas anular el ID del proyecto con la herramienta de línea de comandos de gcloud, este elemento establece un ID de proyecto en toda la máquina, lo que puede generar confusión si estás desarrollando varios proyectos. El elemento <application> contiene el ID del proyecto de la aplicación. Este es el ID del proyecto que registras cuando creas tu proyecto en Google Cloud Platform Console. Cuando subes tu aplicación, appcfg obtiene el ID del proyecto desde este archivo.

<async-session-persistence>

Opcional. Es posible reducir la latencia de la solicitud mediante la configuración de tu aplicación para escribir de forma asíncrona los datos de sesión HTTP en el almacén de datos.


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <async-session-persistence enabled="true" />
  <!-- ... -->
</appengine-web-app>

Con el elemento async session persistence activado, App Engine enviará una tarea de lista de tareas en cola para escribir los datos de la sesión en el almacén de datos antes de escribirlos en Memcache. De forma predeterminada, la tarea se enviará a la lista “predeterminada”. Si deseas usar una lista diferente, agrega el atributo “queue-name”:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <async-session-persistence enabled="true" queue-name="myqueue"/>
  <!-- ... -->
</appengine-web-app>

Los datos de la sesión siempre se escriben de manera síncrona en Memcache. Si una solicitud intenta leer los datos de una sesión cuando Memcache no está disponible (o se limpiaron los datos de la sesión), se conmutará por error a Datastore, que todavía no tendrá la versión más reciente de los datos de sesión. Esto significa que la persistencia de la sesión asíncrona puede generar que tu aplicación vea datos de sesión inactivos. Sin embargo, para la mayoría de las aplicaciones, las ventajas de la latencia superan el riesgo.

<auto-id-policy> Opcional. Si configuras identificadores de entidad de manera automática, puedes cambiar el método empleado; para ello, configura la política de ID automático. Las siguientes son opciones válidas:
default
Valor predeterminado. Utiliza ID automáticos dispersos que sean números enteros grandes y bien distribuidos, pero lo suficientemente pequeños para que los representen números de coma flotante de 64 bits.
legacy
La opción heredada quedará obsoleta en una actualización futura y, al final, se quitará. Para obtener más información, consulta la entrada de blog que anuncia este cambio.
<automatic-scaling>

Opcional. Para obtener una explicación completa, consulta la sección ajuste de escala automático.

<basic-scaling>

Opcional. Para obtener una explicación completa, consulta la sección ajuste de escala básico.

<env-variables>

Opcional. El archivo appengine-web.xml puede definir variables de entorno que se establecen cuando la aplicación se está ejecutando.


<env-variables>
  <env-var name="DEFAULT_ENCODING" value="UTF-8" />
</env-variables>

Para evitar conflictos con tu entorno local, el servidor de desarrollo no establece variables de entorno basadas en este archivo y requiere que el entorno local ya tenga estas variables configuradas con valores coincidentes.


export DEFAULT_ENCODING="UTF-8"
dev_appserver war

Cuando se implementa en App Engine, el entorno se crea con estas variables ya configuradas.

<inbound-services>

Opcional. Antes de que una aplicación pueda recibir correos electrónicos, esta debe estar configurada para habilitar el servicio. A fin de habilitarlo en una aplicación para Java 8, debes incluir la sección <inbound-services> en el archivo appengine-web.xml.

El siguiente servicio de entrada está disponible:

mail
Permite que tu aplicación reciba correos electrónicos.
<instance-class>

Opcional. El tamaño de la clase de instancia para este módulo.

Las siguientes clases de instancia están disponibles cuando se especifican diferentes opciones de escalamiento:

automatic_scaling
Cuando se utiliza el ajuste de escala automático, se encuentran disponibles las clases de instancias F1, F2, F4 y F4_1G.
Predeterminado: Se asigna F1 si no especificaste una clase de instancia junto con el elemento automatic_scaling.
basic_scaling
Cuando se utiliza el ajuste de escala básico, se encuentran disponibles las clases de instancias B1, B2, B4, B4_1G y B8.
Predeterminado: Se asigna B2 si no especificaste una clase de instancia junto con el elemento basic_scaling.
manual_scaling
Cuando se utiliza el ajuste de escala manual, se encuentran disponibles las clases de instancias B1, B2, B4, B4_1G y B8.
Predeterminado: Se asigna B2 si no especificaste una clase de instancia junto con el elemento manual_scaling.

Nota: Si instance-class se configura en F2 o un nivel superior, puedes optimizar las instancias; para ello, establece max-concurrent-requests en un valor superior a 10, que es el valor predeterminado. Para encontrar el valor óptimo, auméntalo gradualmente y supervisa el rendimiento de tu aplicación.

<manual-scaling>

Opcional. Para obtener una explicación completa, consulta la sección ajuste de escala manual.

<precompilation-enabled>

Opcional. App Engine utiliza un proceso de “precompilación” con el código de bytes (bytecode) de Java de una aplicación para mejorar el rendimiento de la aplicación en Java Runtime Environment. El código precompilado funciona de la misma manera que el código de bytes original.

Si por algún motivo prefieres que tu aplicación no utilice la precompilación, agrega el siguiente código al archivo appengine-web.xml para desactivarla:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <precompilation-enabled>false</precompilation-enabled>
  <!-- ... -->
</appengine-web-app>
module

Nota: Los módulos ahora se denominan Servicios y los servicios aún se declaran en los archivos appengine-web.xml como módulos, por ejemplo: <module>service_name</module>.

Es obligatorio si se crea un servicio. Es opcional para el servicio predeterminado. Cada servicio y versión deben tener un nombre. Un nombre puede contener números, letras y guiones. No puede tener más de 63 caracteres ni comenzar o terminar con un guion. Elige un nombre único para cada servicio y cada versión. No utilices los mismos nombres en otros servicios y versiones.

También consulta servicio.

<public-root>

Opcional. <public-root> es un directorio de tu aplicación que contiene los archivos estáticos correspondientes. Cuando se realiza una solicitud de un archivo estático, el directorio <public-root> de tu aplicación se agrega a la ruta de la solicitud. Esto proporciona la ruta del archivo de la aplicación que tiene el contenido que se solicita.

El directorio <public-root> predeterminado es /.

Por ejemplo, lo siguiente asignaría la ruta de URL /index.html a la ruta del archivo de la aplicación /static/index.html:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <public-root>/static</public-root>
  <!-- ... -->
</appengine-web-app>
<resource-files>

Opcional. El código de la aplicación puede acceder a los archivos en el elemento <resource-files> mediante el sistema de archivos. Estos archivos se almacenan en los servidores de la aplicación, a diferencia de los archivos estáticos que se almacenan y entregan de manera distinta.

El elemento <resource-files> puede contener los siguientes elementos:

<include>
Un elemento <include> designa los archivos como archivos de recursos que están disponibles para el código de tu aplicación. Estos archivos solo están disponibles para tu código en modo de solo lectura y no para el tráfico. Cómo incluir y excluir archivos.
<exclude>

Los archivos y directorios que coincidan con patrones <exclude> no se subirán ni estarán disponibles para el código de tu aplicación. Sin embargo, tu aplicación aún tendrá acceso a estos archivos y directorios cuande se ejecute en el servidor de desarrollo local. Para obtener más información, consulta Cómo incluir y excluir archivos.

Ejemplo:

<resource-files>
  <include path="/**.xml" />
  <exclude path="/feeds/**.xml" />
</resource-files>

En este ejemplo se demuestra cómo designar todos los archivos .xml como archivos de recursos, excepto aquellos en el directorio feeds/ y en todos sus subdirectorios.

Los archivos de recursos de App Engine se leen con java.io.File o javax.servlet.ServletContext.getResource/getResourceAsStream. No se puede acceder a estos archivos mediante Class.getResourceAsStream().

runtime

Para usar el entorno de ejecución de Java 8, debes especificar esta entrada con el valor java8. Para usar el entorno de ejecución de Java 7, omite esta entrada o especifica el valor java7. (Ten en cuenta que los entornos de ejecución de Java en App Engine se basan en OpenJDK).

Ejemplo:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <runtime>java8</runtime>
  <!-- ... -->
</appengine-web-app>
service

Los servicios se conocían anteriormente como módulos.

Actualmente, definir un servicio como <service>service_name</service > solo es compatible con los comandos de la aplicación de gcloud.

<sessions-enabled>

Opcional. App Engine incluye una implementación de sesiones, mediante el uso de la interfaz de sesiones de servlet. La implementación almacena datos de sesión en Datastore para obtener persistencia y utiliza Memcache para obtener velocidad. Como con la mayoría de los contenedores servlet, los atributos de la sesión que se establecen con “session.setAttribute()” durante la solicitud se mantienen al final de ella.

Esta función se encuentra desactivada de forma predeterminada. Para activarla, agrega lo siguiente a appengine-web.xml:

Ejemplo:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <sessions-enabled>true</sessions-enabled>
  <!-- ... -->
</appengine-web-app>

La implementación crea entidades en Datastore del tipo _ah_SESSION y entradas de Memcache mediante el uso de claves con un prefijo _ahs. Puedes borrar estas entidades con la plantilla de Dataflow.

Nota: Debido a que App Engine almacena datos de sesión en Datastore y Memcache, todos los valores almacenados en la sesión deben implementar la interfaz java.io.Serializable.

Consulta el elemento async-session-persistence para reducir la latencia del almacenamiento de los datos de sesión.

<ssl-enabled>

Opcional. De manera predeterminada, cualquier usuario puede acceder a cualquier URL mediante los protocolos HTTP o HTTPS. Puedes configurar una aplicación que requiera HTTPS para determinadas URL en el descriptor de implementación. Consulta Descriptor de implementación: URL seguras.

Si deseas inhabilitar el uso de HTTPS para la aplicación, incluye lo siguiente en el archivo appengine-web.xml:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <ssl-enabled>false</ssl-enabled>
  <!-- ... -->
</appengine-web-app>

No existe una forma de inhabilitar HTTPS únicamente para algunas rutas de URL en el entorno de ejecución de Java.

<static-error-handlers>

Opcional. Cuando se producen determinados errores, App Engine entrega una página de error genérica. Puedes configurar tu aplicación para que muestre un archivo estático personalizado, en lugar de estas páginas de error genéricas, siempre y cuando los datos de error personalizados sean menores que 10 kilobytes. Puedes especificar diferentes archivos estáticos en el archivo appengine-web.xml de tu aplicación, de modo que se muestren para cada código de error admitido. Para entregar páginas de error personalizadas, agrega una sección <static-error-handlers> a appengine-web.xml, como se muestra en este ejemplo:


<static-error-handlers>
  <handler file="default_error.html" />
  <handler file="over_quota.html" error-code="over_quota" />
</static-error-handlers>

Advertencia: Asegúrate de que la ruta al archivo de respuesta de error no se superponga con las rutas del controlador de archivos estáticos.

Cada entrada file indica un archivo estático que debe entregarse en lugar de la respuesta de error genérica. error-code indica qué código de error debe mostrar el archivo asociado. A continuación, se detallan los códigos de error admitidos:

over_quota
Indica que la aplicación superó una cuota de recursos.
dos_api_denial
Esta opción entrega esta página de error para cualquier cliente bloqueado por la configuración de protección contra DoS de tu aplicación.
timeout
Se entrega si se alcanza un plazo antes de que tu aplicación responda.

error-code es opcional; si no se especifica, el archivo determinado será la respuesta de error predeterminada para tu aplicación.

Opcionalmente, puedes especificar un mime-type para la página de error personalizada. Consulta la lista completa de tipos MIME.

<static-files>

Opcional. El elemento <static-files> especifica patrones que coinciden con las rutas de archivo que se incluyen en la lista de archivos estáticos o que se excluyen de ella, lo que anula o modifica el comportamiento predeterminado. Los archivos estáticos se entregan desde servidores dedicados y memorias caché que están separados de los servidores de la aplicación y son útiles para entregar contenido estático como imágenes, hojas de estilo CSS o archivos de JavaScript.

El elemento <static-files> puede contener los siguientes elementos:

<include>

Un elemento <include> anula el comportamiento predeterminado, que incluye todos los archivos que no sean JSP. El elemento <include> puede especificar qué encabezados HTTP usar para responder a una solicitud de recursos específicos. Para obtener más información, consulta Cómo incluir y excluir archivos.

Puedes especificar el vencimiento de la memoria caché estática mediante el atributo expiration en el elemento <include>. El valor es una string de números y unidades, separados por espacios. En las unidades, d representa días, h representa horas, m representa minutos y s representa segundos. Por ejemplo, "4d 5h" configura el vencimiento de la memoria caché en 4 días y 5 horas después de que el archivo se solicite por primera vez. Si se omite el tiempo de vencimiento, el servidor de producción se configura en 10 minutos de forma predeterminada. Para obtener más información, consulta Vencimiento de la memoria caché estática.

<exclude>
Los archivos y directorios que coincidan con patrones <exclude> no se subirán cuando implementes tu aplicación en App Engine. Sin embargo, tu aplicación aún tendrá acceso podrá seguir a estos archivos y directorios cuando se ejecute en el servidor de desarrollo local. Para obtener más información, consulta Cómo incluir y excluir archivos.
Ejemplo

<static-files>
  <include path="/my_static-files" >
    <http-header name="Access-Control-Allow-Origin"
                 value="http://example.org" />
  </include>
</static-files>
<system-properties>

Opcional. El archivo appengine-web.xml puede definir propiedades del sistema y variables del entorno que se establecen cuando la aplicación se está ejecutando.


<system-properties>
  <property name="myapp.maximum-message-length" value="140" />
  <property name="myapp.notify-every-n-signups" value="1000" />
  <property name="myapp.notify-url"
            value="http://www.example.com/signupnotify" />
</system-properties>

<env-variables>
  <env-var name="DEFAULT_ENCODING" value="UTF-8" />
</env-variables>
<threadsafe>

Obligatorio. Cuando el elemento threadsafe en appengine-web.xml es false, App Engine envía solicitudes en serie a un servidor web determinado. Cuando el valor es true, App Engine puede enviar varias solicitudes en paralelo:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <threadsafe>true</threadsafe>
  <!-- ... -->
</appengine-web-app>

Si deseas usar solicitudes simultáneas, el código de tu aplicación debe usar la sincronización de suproceso adecuada antes de que habilites threadsafe.

<url-stream-handler>

Opcional. Los valores posibles son native o urlfetch. El valor predeterminado y la función de la configuración varían según el entorno de ejecución que se utilice (Java 8 o Java 7).

Para el entorno de ejecución de Java 8, el valor predeterminado es native, lo que implica que las clases de red estándar de Java usan el transporte HTTP(S) estándar de Java, como se describe en la sección sobre el comportamiento del entorno de ejecución de Java 8 frente a Java 7. Esta configuración requiere que la aplicación tenga la facturación habilitada. De lo contrario, se generarán los siguientes errores de ejecución cuando se realicen solicitudes:

En el entorno de ejecución de Java 8, configurar el elemento url-stream-handler en urlfetch hace que App Engine instale un URLStreamHandlerFactory que ocasiona que URL.openConnection y los métodos relacionados usen el transporte de recuperación de URL en las URL http y https.

Para el entorno de ejecución de Java 7, el valor predeterminado es urlfetch, lo que implica que las clases de red estándar de Java usan el servicio de recuperación de URL, como se describe en la sección sobre el comportamiento del entorno de ejecución de Java 8 frente a Java 7.

En el entorno de ejecución de Java 7, configurar el valor en native implica que App Engine usa la API de Sockets para java.net.HttpURLConnection en vez de la recuperación de URL. Al igual que en Java 8, esta configuración requiere que la aplicación tenga la facturación habilitada. De lo contrario, se generarán los siguientes errores de tiempo de ejecución cuando se realicen solicitudes:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <url-stream-handler>urlfetch</url-stream-handler>
  <!-- ... -->
</appengine-web-app>
<version>

El elemento <version> contiene el identificador de la última versión del código de la aplicación. El identificador de versión puede contener letras en minúscula, dígitos y guiones. No puede comenzar con el prefijo “ah-”, y los nombres “default” y “latest” están reservados, por lo que no pueden utilizarse.

Los nombres de las versiones deben comenzar con una letra para distinguirlos de las instancias numéricas que siempre se especifican con un número. Esto evita la ambigüedad con las URL como 123.my-module.appspot.com, que pueden interpretarse de dos maneras: si existe la versión “123”, el objetivo será la versión “123” del módulo determinado. Si esa versión no existe, el objetivo será el número de instancia 123 de la versión predeterminada del módulo.

El comando de appcfg usa este identificador de versión cuando sube la aplicación, lo que le indica a App Engine que cree una versión nueva de la aplicación con el identificador determinado o que reemplace la versión de la aplicación con un identificador determinado existente. Puedes probar versiones nuevas de tu aplicación con una URL que contenga “-dot-” como separador de subdominio en la URL, por ejemplo, https://_version_id_-dot-_your_app_id_.appspot.com. Con Google Cloud Platform Console, puedes seleccionar la versión predeterminada de tu aplicación. La versión predeterminada se carga cuando se especifica una versión no válida o no se especifica ninguna.

<warmup-requests-enabled>

Opcional. Valor predeterminado: true (verdadero). Las solicitudes de preparación están habilitadas de forma predeterminada para las aplicaciones de Java 8.

Cuando las solicitudes de preparación están habilitadas, la infraestructura de App Engine emite solicitudes “GET” a /_ah/warmup, lo que inicializa servlets <load-on-startup>, ServletContextListeners y servlets de preparación personalizados, que te permiten inicializar el código de tu aplicación como se requiere. Es posible que debas implementar tu propio controlador para /_ah/warmup según el método que elijas.

Con el fin de inhabilitar las solicitudes de preparación, especifica false para este elemento:


<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- ... -->
  <warmup-requests-enabled>false</warmup-requests-enabled>
  <!-- ... -->
</appengine-web-app>
<vpc-access-connector>

Opcional. Configura tu aplicación para que use un conector de acceso a VPC sin servidores, lo que permite que la aplicación envíe solicitudes a recursos internos de tu red de VPC. Para ello, especifica el nombre completo de un conector en el elemento <name> de la siguiente manera:


<vpc_access_connector>
  <name>projects/[PROJECT_ID]/locations/[REGION]/connectors/[CONNECTOR_NAME]</name>
</vpc_access_connector>

Para obtener más información, consulta Cómo conectarte a recursos internos en una red de VPC.

Elementos de escalamiento

En la siguiente tabla, se enumeran las opciones para definir cómo debe escalar tu aplicación.

Para obtener información sobre las funciones de rendimiento de los tipos de ajuste de escala, consulta Cómo escalar instancias dinámicas.

Elemento Descripción
<automatic-scaling>

Opcional: La clase de instancia predeterminada del ajuste de escala automático se trata como F1, a menos que se especifique lo contrario.

El elemento automatic_scaling establece los niveles mínimos y máximos para la cantidad de instancias, latencia y conexiones simultáneas en un módulo.

Puede contener los siguientes elementos:

<target-cpu-utilization>
Opcional. Especifica un valor de 0.5 a 0.95.

Este parámetro especifica el límite de uso de la CPU en el que se iniciarán instancias nuevas para manejar el tráfico, lo que te permite balancear el rendimiento y el costo. Los valores más bajos aumentan el rendimiento y el costo, y los valores más altos disminuyen el rendimiento, pero también el costo. Por ejemplo, un valor de 0.7 significa que se iniciarán instancias nuevas después de que el uso de CPU alcance el 70%.

Importante: Si, con el fin de implementación, usas el comando de appcfg desde el SDK de App Engine para Java, no puedes usar este parámetro en tu appengine-web.xml. En cambio, configura el parámetro según se describe en Configura parámetros de ajuste de escala automático con el Explorador de API, o puedes utilizar la API de Administrador de App Engine.

<target-throughput-utilization>
Opcional. Especifica un valor de 0.5 a 0.95.

Se usa con max-concurrent-requests para especificar cuándo se inicia una instancia nueva debido a solicitudes simultáneas. Cuando la cantidad de solicitudes simultáneas alcanza un valor igual que max-concurrent-requests multiplicado por target-throughput-utilization, el programador inicia una instancia nueva.

Importante: Si, con el fin de implementación, usas el comando de appcfg desde el SDK de App Engine para Java, no puedes usar este parámetro en tu appengine-web.xml. En cambio, configura el parámetro según se describe en Configura parámetros de ajuste de escala automático con el Explorador de API, o puedes utilizar la API de Administrador de App Engine.

<max-instances>
Opcional. La cantidad máxima de instancias que App Engine debe crear para esta versión de la aplicación. Esto es útil para limitar los costos de un módulo. Especifica un valor entre 0 y 2147483647.

Importante: Si, con el fin de implementación, usas el comando de appcfg desde el SDK de App Engine para Java, no puedes usar este parámetro en tu appengine-web.xml. En cambio, configura el parámetro según se describe en Configura parámetros de ajuste de escala automático con el Explorador de API, o puedes utilizar la API de Administrador de App Engine.

<min-instances>
Opcional. La cantidad mínima de instancias que App Engine debe crear para esta versión del módulo. Estas instancias entregan tráfico cuando llegan solicitudes y continúan haciéndolo incluso cuando se inician instancias adicionales según sea necesario para manejar el tráfico.

Especifica un valor de 0 a 1,000. Puedes configurar el parámetro en el valor 0 para permitir que el escalamiento a 0 instancias reduzca los costos cuando no se entregan solicitudes. Ten en cuenta que se te cobrará por la cantidad de instancias especificadas, ya sea que reciban tráfico o no.

Importante: Si, con el fin de implementación, usas el comando de appcfg desde el SDK de App Engine para Java, no puedes usar este parámetro en tu appengine-web.xml. En cambio, configura el parámetro según se describe en Configura parámetros de ajuste de escala automático con el Explorador de API, o puedes utilizar la API de Administrador de App Engine.

<max-concurrent-requests>

Opcional. La cantidad de solicitudes simultáneas que una instancia con ajuste de escala automático puede aceptar antes de que el programador genere una instancia nueva (valor predeterminado: 10; máximo: 80).

Es posible que experimentes una mayor latencia de la API si esta configuración es demasiado alta. Ten en cuenta que el programador puede generar una instancia nueva antes de que se alcance el número máximo real de solicitudes.

Nota: Si instance-class se configura en F2 o un nivel superior, puedes optimizar tus instancias si configuras max-concurrent-requests en un valor superior a 10, que es el valor predeterminado. Para encontrar el valor óptimo, auméntalo gradualmente y supervisa el rendimiento de tu aplicación.

<max-idle-instances>

La cantidad máxima de instancias inactivas que App Engine debería mantener para esta versión. El valor predeterminado es “automático”. Ten en cuenta los siguientes datos:

  • Un máximo alto reduce la cantidad de instancias inactivas de manera más gradual cuando los niveles de carga vuelven a la normalidad después de un pico. Esto ayuda a que la aplicación mantenga un rendimiento constante a través de las fluctuaciones en la carga de solicitud, pero también aumenta el número de instancias inactivas (y los consiguientes costos de ejecución) durante los períodos de carga pesada.
  • Un máximo bajo mantiene los costos de ejecución más bajos, pero puede degradar el rendimiento ante niveles de carga volátiles.

Nota: Cuando se vuelve a los valores normales después de un pico de carga, el número de instancias inactivas puede superar temporalmente el máximo especificado. Sin embargo, no se te cobrarán más instancias que el número máximo que hayas especificado.

<max-pending-latency>

La cantidad máxima de tiempo que App Engine debe permitir que una solicitud espere en la lista de pendientes antes de iniciar instancias adicionales para manejar las solicitudes a fin de reducir la latencia pendiente. El valor predeterminado es “30 ms”.

  • Si el máximo es bajo, App Engine iniciará instancias nuevas antes para las solicitudes pendientes, lo que mejora el rendimiento, pero aumenta los costos de ejecución.
  • Si el máximo es alto, es posible que los usuarios deban esperar más tiempo hasta que se entreguen sus solicitudes (si existen solicitudes pendientes y no hay instancias inactivas para entregarlas), pero ejecutar tu aplicación tendrá un costo menor.
<min-idle-instances>

La cantidad de instancias que se mantendrán en funcionamiento y listas para entregar el tráfico.Esta configuración solo se aplica a la versión que recibe la mayor parte del tráfico. Ten en cuenta estas pautas:

  • Si el mínimo es bajo, los costos de ejecución serán más bajos durante los períodos de poca actividad, pero habrá menos instancias inmediatamente disponibles para responder ante un pico de carga repentino.
  • Si el mínimo es alto, podrás preparar la aplicación para picos rápidos en la carga de solicitudes. App Engine mantiene la cantidad mínima de instancias en ejecución para responder a las solicitudes entrantes. Se te cobrará por las instancias, ya sea que manejen solicitudes o no. Para que esta característica funcione de manera adecuada, debes asegurarte de que las solicitudes de preparación estén habilitadas y de que tu aplicación maneje las solicitudes de preparación.

    Si configuras un mínimo de instancias inactivas, la latencia pendiente tendrá menos efecto en el rendimiento de tu aplicación. Debido a que App Engine mantiene las instancias inactivas en reserva, es poco probable que las solicitudes ingresen en la lista de pendientes, excepto en picos de carga excepcionalmente altos. Tendrás que probar la aplicación y el volumen de tráfico esperado para determinar la cantidad ideal de instancias a mantener en reserva.

<min-pending-latency>

La cantidad mínima de tiempo en segundos que App Engine debe permitir para que una solicitud espere en la lista de pendientes antes de iniciar una instancia nueva para manejarla. Especifica un valor de 0.01 a 15.

  • Si el mínimo es bajo, las solicitudes deberán pasar menos tiempo en la lista de pendientes cuando todas las instancias existentes estén activas. Esto mejora el rendimiento, pero aumenta el costo de ejecución de la aplicación.
  • Un mínimo alto significa que las solicitudes permanecerán pendientes por más tiempo si todas las instancias existentes están activas. Esto reduce los costos de ejecución, pero aumenta el tiempo que los usuarios deben esperar para que se entreguen sus solicitudes.
Ejemplo

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <instance-class>F2</instance-class>
  <automatic-scaling>
    <target-cpu-utilization>0.65</target-cpu-utilization>
    <min-instances>5</min-instances>
    <max-instances>100</max-instances>
    <max-concurrent-requests>50</max-concurrent-requests>
  </automatic-scaling>
</appengine-web-app>
<basic-scaling>

Opcional. El elemento <basic-scaling> configura la cantidad de instancias para un módulo.

Puede contener los siguientes elementos:

<idle-timeout>
Opcional. La instancia se detendrá cuando transcurra este período después de recibir la última solicitud. El valor predeterminado es 5 minutos.
<max-instances>
Obligatorio. La cantidad máxima de instancias que App Engine debe crear para esta versión del módulo. Esto es útil para limitar los costos de un módulo.
Ejemplo

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <instance-class>B8</instance-class>
  <basic-scaling>
    <max-instances>11</max-instances>
    <idle-timeout>10m</idle-timeout>
  </basic-scaling>
</appengine-web-app>
<manual-scaling>

Opcional. El elemento <manual-scaling> habilita el ajuste de escala manual para un módulo y configura la cantidad de instancias que se le asignan.

Puede contener los siguientes elementos:

<instances>
El número de instancias que debe asignarse al módulo en el inicio.
Ejemplo

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>simple-app</application>
  <module>default</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <instance-class>B8</instance-class>
  <manual-scaling>
    <instances>5</instances>
  </manual-scaling>
</appengine-web-app>

Elementos en la etapa de pruebas

La mayoría del trabajo realizado durante la implementación ocurre de manera local en la etapa de preparación llamada etapa de pruebas, en la que se ensamblan los archivos JAR, se compilan los JSP y así sucesivamente. Puedes configurar de manera opcional algunas partes del comportamiento de la etapa de pruebas mediante el uso de elementos de prueba en el archivo de configuración de la aplicación. La mayoría de las aplicaciones se implementarán correctamente sin configurar manualmente el comportamiento de la etapa de pruebas. Si la aplicación no se implementa, es posible que debas configurar la etapa de pruebas con las opciones que se detallan a continuación.

Elemento Descripción
<staging>

Opcional. La mayoría de las aplicaciones no deben cambiar el comportamiento predeterminado.

El elemento de etapa de pruebas te permite especificar una configuración de prueba específica en caso necesario para la implementación.

Puede contener los siguientes elementos:

<enable-jar-splitting>

Opcional. Divide los archivos jar grandes (> 10 megabytes) en fragmentos más pequeños. (Valor predeterminado: true).

<jar-splitting-excludes>

Lista de sufijos para excluir cuando utilizas jar-splitting.

<disable_jar_jsps>

No convierte en archivo JAR aquellas clases generadas de JSP. (Valor predeterminado: false).

<enable-jar-classes>

Convierte el contenido de WEB-INF/classes. (Valor predeterminado: true).

<delete-jsps>

Borra los archivos JSP de origen después de la compilación. (Valor predeterminado: true).

<compile-encoding>

Ingresa la codificación de los archivos de origen para la compilación. (Valor predeterminado: utf-8).

Valores predeterminados para la opción de etapa de pruebas

Los valores predeterminados para las opciones de etapa de pruebas son diferentes según si usas herramientas basadas en el SDK de App Engine, como appcfg, herramientas basadas en el SDK de Cloud, como la línea de comandos de gcloud, o bien complementos de Maven, Gradle, Eclipse o IntelliJ basados en el SDK de Cloud.

Elemento de etapa de pruebas Valor predeterminado basado en el SDK de App Engine Valor predeterminado basado en el SDK de Cloud
enable-jar-splitting false true
jar-splitting-excludes NA NA
disable-jar-jsps false false
enable-jar-classes false true. Esto puede afectar el orden de carga de la clase. Si tu aplicación depende de un determinado orden que utiliza el valor predeterminado false anterior, puedes configurarlo en false.
delete-jsps false true
compile-encoding utf-8 utf-8

Cómo incluir y excluir la sintaxis

Los patrones de ruta se especifican con cero o más elementos <include> y <exclude>. En un patrón, '*' representa cero o más caracteres en un archivo o nombre de directorio y ** representa cero o más directorios en una ruta. Los archivos y directorios que coinciden con los patrones <exclude> no se subirán cuando implementes tu aplicación en App Engine. Sin embargo, tu aplicación aún tendrá acceso a estos archivos y directorios cuando se ejecuta en el servidor de desarrollo local.

Un elemento <include> anula el comportamiento predeterminado para incluir todos los archivos. Un elemento <exclude> aplica todos los patrones después de <include> (así como el valor predeterminado si no se proporciona <include> explícitamente).

En este ejemplo se muestra cómo designar todos los archivos .png como archivos estáticos (excepto aquellos en el directorio data/ y en todos sus subdirectorios):

<static-files>
  <include path="/**.png" />
  <exclude path="/data/**.png" />
</static-files>

También puedes establecer encabezados HTTP para responder solicitudes a estos recursos estáticos.

<static-files>
  <include path="/my_static-files" >
    <http-header name="Access-Control-Allow-Origin"
                 value="http://example.org" />
  </include>
</static-files>

Tipos MIME para archivos estáticos

De forma predeterminada, los archivos estáticos se entregan con un tipo MIME seleccionado basado en la extensión del nombre de archivo. Puedes asociar tipos MIME personalizados con extensiones de nombre de archivo para archivos estáticos mediante el uso de elementos <mime-mapping> en web.xml. Para obtener más información, consulta la wiki de referencia sobre web.xml de Metawerx.

Vencimiento de la caché estática

A menos que se indique lo contrario, los proxies y los navegadores web retienen los archivos que cargan desde un sitio web durante un período limitado.

Puedes configurar la duración de la caché para controladores de archivos estáticos específicos proporcionando un atributo expiration para <static-files><include ... >. El valor es una string de números y unidades, separados por espacios. En las unidades, d representa días, h representa horas, m representa minutos y s representa segundos. Por ejemplo, "4d 5h" configura el vencimiento de la memoria caché en 4 días y 5 horas después de que el archivo se solicite por primera vez. Si se omite el tiempo de vencimiento, el servidor de producción se configurará en 10 minutos de forma predeterminada.

Por ejemplo:

<static-files>
  <include path="/**.png" expiration="4d 5h" />
</static-files>

El tiempo de vencimiento se enviará en los encabezados de respuesta HTTP Cache-Control y Expires, y, por lo tanto, es probable que el navegador del usuario almacene en caché los archivos. Después de que un archivo se transmite con un tiempo de vencimiento determinado, generalmente no hay forma de borrarlo de las memorias caché intermedias, incluso si el usuario borra su propia caché del navegador. Volver a implementar una versión nueva de la aplicación no restablecerá ninguna caché. Por lo tanto, si alguna vez planeas modificar un archivo estático, este debe tener un tiempo de vencimiento corto (menos de una hora). En la mayoría de los casos, el tiempo de vencimiento predeterminado de 10 minutos es adecuado.

Tiempo de espera de URLFetch

Puedes establecer un plazo para cada solicitud URLFetch. De forma predeterminada, este plazo es de 5 segundos. Puedes cambiarlo si incluyes el siguiente ajuste en el archivo de configuración appengine-web.xml. Especifica el tiempo de espera en segundos:

<system-properties>
    <property name="appengine.api.urlfetch.defaultDeadline" value="10"/>
</system-properties>
¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Entorno estándar de App Engine para Java 8