Referencia de appengine-web.xml

ID de región

REGION_ID es un código abreviado que Google asigna en función de la región que seleccionas cuando creas tu app. El código no corresponde a un país o provincia, aunque algunos ID de región puedan parecer similares a los códigos de país y provincia de uso común. Incluir REGION_ID.r en las URL de App Engine es opcional para las aplicaciones existentes, y pronto se requerirá para todas las aplicaciones nuevas.

A fin de garantizar una transición sin problemas, estamos actualizando App Engine con lentitud para usar los ID de región. Si aún no actualizamos tu proyecto de Google Cloud, no verás un ID de región para la app. Dado que el ID es opcional para las apps existentes, no necesitas actualizar las URL ni realizar otros cambios una vez que el ID de región esté disponible para las apps existentes.

Obtén más información acerca de los ID de región.

Además del descriptor de implementación web.xml, las aplicaciones de Java en App Engine usan un archivo de configuración appengine-web.xml, a fin de especificar información sobre tu app 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 app de Java de App Engine debe tener un archivo llamado appengine-web.xml en su WAR, en el directorio WEB-INF/. Este es un archivo XML cuyo elemento raíz es <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 app mediante las herramientas basadas en el SDK de Cloud, como el comando de gcloud app deploy, los complementos de IntelliJ o Eclipse, 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 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 Console. Cuando subes tu app, appcfg obtiene el ID del proyecto de 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
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 se ejecuta la aplicación.


<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 el servicio en una app de 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 la 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 usa 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 usa 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 usa 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 especificas una clase de instancia junto con el elemento manual_scaling.

Nota: Si se configura instance-class en F2 o en un nivel superior, puedes optimizar las instancias; para ello, configura 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 app no use la precompilación, agrega el siguiente código al archivo appengine-web.xmlappengine-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 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, comenzar o terminar con un guion y contener la string “-dot”. 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 El <public-root> es un directorio en tu aplicación que contiene los archivos estáticos para tu aplicación. Cuando se realiza una solicitud para un archivo estático, el directorio <public-root> de tu aplicación se antepone a la ruta de la solicitud. Esto proporciona la ruta del archivo de la aplicación que tiene el contenido que se solicita.

El valor predeterminado de <public-root> es /.

Por ejemplo, lo siguiente asignaría la ruta de URL /index.html a la ruta de 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 enumerados 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 la aplicación. Estos archivos solo están disponibles para tu código en modo de solo lectura y no para el tráfico. Incluye y excluye archivos.
<exclude>

Los archivos y directorios que coincidan con los patrones <exclude> no se subirán ni estarán disponibles para el código de la 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 Incluye y excluye 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 mediante Class.getResourceAsStream().

runtime

Para usar el entorno de ejecución de Java 8, debes especificar esta entrada con el valor java8.

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.

En la actualidad, definir un servicio como: <service>service_name</service > solo es compatible con los comandos de la app 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 de Datastore del tipo _ah_SESSION y entradas de Memcache mediante claves con un prefijo de _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 datos de sesión.

<ssl-enabled>

Opcional De forma predeterminada, cualquier usuario puede acceder a cualquier URL mediante HTTP o HTTPS. Puedes configurar una app 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, coloca 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 entreguen 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. El error-code indica que el código de error debe hacer que se entregue el archivo asociado. A continuación, se detallan los códigos de error admitidos:

over_quota
Indica que la app 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 exista una respuesta por parte de la app.

El error-code es opcional; si no se especifica, el archivo es la respuesta de error predeterminada para la app.

De manera opcional, puedes especificar un mime-type para usar cuando se entrega el error personalizado. Consulta la lista completa de tipos de MIME.

<static-files>

Opcional El elemento <static-files> especifica los patrones que coinciden con las rutas de archivos que se incluyen y excluyen de la lista de archivos estáticos, 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 son archivos JSP. El elemento <include> puede especificar encabezados HTTP para usar cuando se responde a la solicitud de los recursos especificados. Para obtener más información, consulta Incluye y excluye archivos.

Puedes especificar el vencimiento de la caché estática mediante el atributo expiration en el elemento de inclusión. El valor es una string de números y unidades, separados por espacios, en la que las unidades pueden ser d por días, h por horas, m por minutos y s por segundos. Por ejemplo, "4d 5h" establece el vencimiento de la caché en 4 días y 5 horas después de que se solicita el archivo 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 caché estática.

<exclude>
Los archivos y directorios que coincidan con los patrones <exclude> no se subirán cuando implementes tu app 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 Incluye y excluye 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 de entorno que se establecen cuando la aplicación se ejecuta.


<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 la aplicación debe usar la sincronización de subproceso adecuada antes de que habilites threadsafe.

<url-stream-handler>

Opcional Los valores posibles son native o urlfetch.

El valor predeterminado es native, lo que significa que las clases de red estándar de Java usan el transporte HTTP(S) estándar. Esta configuración requiere que la aplicación tenga la facturación habilitada. De lo contrario, obtendrás excepciones, que se documentan en Solicitudes de problemas.

Si configuras url-stream-handler en urlfetch, URL.openConnection y los métodos relacionados usarán la recuperación de URL para el transporte http y https.


<?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 app. 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.uc.r.appspot.com, que pueden interpretarse de dos maneras: si existe la versión “123”, el objeto 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 app con el identificador determinado si ya existe. Puedes probar versiones nuevas de la app con una URL mediante “-dot-” como separador de subdominio en  laURL, como https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com. Con Google Cloud Console, puedes seleccionar la versión predeterminada de tu app. 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 envía solicitudes “GET” a /_ah/warmup, lo que inicializa los 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 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 Conexión a recursos internos de 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.

Con el elemento automatic_scaling, se configuran niveles mínimos y máximos para la cantidad de instancias, latencia y conexiones simultáneas en un módulo.

Puede contener los elementos siguientes:

<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 implica que se iniciarán instancias nuevas cuando el uso de CPU alcance el 70%.

Importante: Si usas el comando appcfg del SDK de App Engine para Java a fin de implementarlo, no puedes usar este parámetro en tu appengine-web.xml. En su lugar, debes configurar el parámetro como se describe en la configuración de parámetros de ajuste de escala automático con el Explorador de API o mediante 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 a max-concurrent-requests veces target-throughput-utilization, el programador inicia una instancia nueva.

Importante: Si usas el comando appcfg del SDK de App Engine para Java a fin de implementarlo, no puedes usar este parámetro en tu appengine-web.xml. En su lugar, debes configurar el parámetro como se describe en la configuración de parámetros de ajuste de escala automático con el Explorador de API o mediante 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 usas appcfg desde el SDK de App Engine para Java a fin de implementar, no puedes usar este parámetro en tu appengine-web.xml. En su lugar, debes configurar el parámetro como se describe en la configuración de parámetros de ajuste de escala automático con el Explorador de API o mediante 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 el número de instancias especificadas, ya sea que reciban tráfico o no.

Importante: Si usas appcfg desde el SDK de App Engine para Java a fin de implementar, 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 mediante 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 está configurado en F2 o superior, puedes optimizar las instancias; para ello, configura 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 lo siguiente:

  • Un máximo alto reduce el número de instancias inactivas de manera más gradual cuando los niveles de cargo 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 de forma temporal 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 ejecución 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 valor 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 disponibles de inmediato para responder ante un pico de carga repentino.
  • Un mínimo alto te permite preparar la aplicación para picos rápidos en la carga de solicitud. 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> establece la cantidad de instancias de un módulo.

Puede contener los elementos siguientes:

<idle-timeout>
De forma 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 y establece la cantidad de instancias de un módulo.

Puede contener los elementos siguientes:

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

Especifica una lista de sufijos de archivos separados por comas. Si enable-jar-splitting está habilitado, todos los archivos que coincidan con los sufijos se excluirán de todos los archivos JAR.

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

Por ejemplo:


        <staging>
          <delete-jsps>false</delete-jsps>
        </staging>
        

Valor predeterminado para la opción de etapa de pruebas

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

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, por lo que si tu app depende de un determinado orden que usa el valor predeterminado false, 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 mediante 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 de incluir todos los archivos. Un elemento <exclude> aplica todos los patrones después de <include> (así como el valor predeterminado si no se proporciona un <include> explícito).

En el siguiente 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 de MIME personalizados con extensiones de nombre de archivo para archivos estáticos mediante 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 navegadores web retienen los archivos que cargan de un sitio web durante un período limitado.

Puedes configurar la duración de la caché para controladores de archivos estáticos específicos si proporcionas un atributo expiration para <static-files><include ... >. El valor es una string de números y unidades, separados por espacios, en la que las unidades pueden ser d por días, h por horas, m por minutos y s por segundos. Por ejemplo, "4d 5h" establece el vencimiento de la caché en 4 días y 5 horas después de que se solicita el archivo 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; por lo tanto, es probable que el navegador del usuario almacene los archivos en caché, y que también lo hagan los servidores proxy de almacenamiento en caché intermedia, como los proveedores de servicios de Internet. Después de que un archivo se transmite con un tiempo de vencimiento determinado, por lo general 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 app 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 cambiar este valor predeterminado si incluyes la siguiente configuración en tu 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>