ID regione
REGION_ID
è un codice abbreviato assegnato da Google
in base alla regione selezionata al momento della creazione dell'app. Il codice non
corrispondono a un paese o a una provincia, anche se potrebbero essere visualizzati alcuni ID regione
in modo simile ai codici paese e provincia di uso comune. Per le app create dopo il giorno
Febbraio 2020, REGION_ID.r
è incluso in
URL di App Engine. Per le app esistenti create prima di questa data,
l'ID regione è facoltativo nell'URL.
Scopri di più sugli ID regione.
Le applicazioni web Java utilizzano un file descrittore di deployment per determinare la modalità di mappatura degli URL
ai servlet, gli URL che richiedono l'autenticazione e altre informazioni. Questo file
è denominato web.xml
e fa parte della specifica servlet per le applicazioni web.
Per ulteriori informazioni sul descrittore di deployment web.xml
, consulta
specifiche di servlet.
Se stai eseguendo la migrazione da Java 8 e devi utilizzare il
ai servizi in bundle legacy con l'ultima versione di Java supportata, devi aggiungere il
<app-engine-apis>
e impostalo su true
nel file web.xml
:
<app-engine-apis>true</app-engine-apis>
Descrittori del deployment
Il descrittore di deployment di un'applicazione web descrive le classi, le risorse dell'applicazione e il modo in cui vengono utilizzati dal server web per la pubblicazione richieste. Quando il server web riceve una richiesta per l'applicazione, utilizza il descrittore di deployment per mappare l'URL della richiesta al codice che deve per gestire la richiesta.
Il descrittore di deployment è un file denominato web.xml
. Si trova nella cartella WAR dell'app
nella directory WEB-INF/
. Il file è un file XML il cui elemento principale è
<web-app>
.
Il seguente esempio di web.xml
mappa tutti i percorsi dell'URL (/*
) al servlet
classe mysite.server.ComingSoonServlet
per la versione 21 e successive su EE10 (impostazione predefinita), versione
21 su EE8 e versione 17 e precedenti. Per utilizzare l'ultima versione supportata su
devi aggiornare i servlet delle applicazioni
per includere lo spazio dei nomi Jakarta
. Per saperne di più sulle opzioni di configurazione,
consulta l'articolo Eseguire l'upgrade di un'applicazione esistente.
v21 e successive (EE10)
<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd"
version="6.0">
<runtime>java21</runtime> <!-- or another supported version -->
<servlet>
<servlet-name>comingsoon</servlet-name>
<servlet-class>mysite.server.ComingSoonServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>comingsoon</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>
Versione 21 (EE8)
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
version="3.1">
<runtime>java21</runtime>
<system-properties> <!-- run your apps on EE8 -->
<property name="appengine.use.EE8" value="true"/>
</system-properties>
<servlet>
<servlet-name>comingsoon</servlet-name>
<servlet-class>mysite.server.ComingSoonServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>comingsoon</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>
v17 e precedenti
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
version="3.1">
<runtime>java17</runtime>
<servlet>
<servlet-name>comingsoon</servlet-name>
<servlet-class>mysite.server.ComingSoonServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>comingsoon</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>
Se scomponi la tua applicazione nei servizi, ogni servizio ha il proprio parametri di configurazione.
Servlet e percorsi degli URL
web.xml
definisce le mappature tra i percorsi dell'URL e i servlet che gestiscono
richieste con quei percorsi. Il server web utilizza questa configurazione per identificare
il servlet per gestire una determinata richiesta e chiamare il metodo della classe che corrisponde
al metodo di richiesta. Ad esempio: il metodo doGet()
per HTTP GET
richieste.
Per mappare un URL a un servlet, devi dichiarare il servlet con l'elemento <servlet>
,
quindi definisci una mappatura da un percorso URL a una dichiarazione servlet con
Elemento <servlet-mapping>
.
L'elemento <servlet>
dichiara il servlet, incluso un nome utilizzato per fare riferimento a
il servlet da altri elementi nel file, la classe da utilizzare per il servlet e
parametri di inizializzazione. Puoi dichiarare più servlet utilizzando lo stesso
con diversi parametri di inizializzazione. Il nome di ogni servlet deve
essere univoci nel descrittore di deployment.
<servlet> <servlet-name>redteam</servlet-name> <servlet-class>mysite.server.TeamServlet</servlet-class> <init-param> <param-name>teamColor</param-name> <param-value>red</param-value> </init-param> <init-param> <param-name>bgColor</param-name> <param-value>#CC0000</param-value> </init-param> </servlet> <servlet> <servlet-name>blueteam</servlet-name> <servlet-class>mysite.server.TeamServlet</servlet-class> <init-param> <param-name>teamColor</param-name> <param-value>blue</param-value> </init-param> <init-param> <param-name>bgColor</param-name> <param-value>#0000CC</param-value> </init-param> </servlet>
L'elemento <servlet-mapping>
specifica un pattern URL e il nome di un
servlet dichiarato da utilizzare per le richieste il cui URL corrisponde al pattern. URL
utilizzare un asterisco (*
) all'inizio o alla fine del pattern per
indicare zero o più caratteri. Il pattern URL non supporta i caratteri jolly
al centro di una stringa e non consente più caratteri jolly
pattern. Il pattern corrisponde al percorso completo dell'URL, iniziando con e
inclusa la barra (/
) che segue il nome di dominio. Il percorso dell'URL non può
iniziano con un punto (.
).
<servlet-mapping> <servlet-name>redteam</servlet-name> <url-pattern>/red/*</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>blueteam</servlet-name> <url-pattern>/blue/*</url-pattern> </servlet-mapping>
Con questo esempio, una richiesta dell'URL
http://www.example.com/blue/teamProfile
è gestito dalla classe TeamServlet
,
con il parametro teamColor
uguale a blue
e il parametro bgColor
uguale
a #0000CC
. Il servlet può ottenere la porzione del percorso dell'URL che corrisponde alla
carattere jolly che utilizza il metodo getPathInfo()
dell'oggetto ServletRequest.
Il servlet può accedere ai parametri di inizializzazione ottenendo il suo servlet
utilizzando il proprio metodo getServletConfig()
, quindi chiamando il metodo
getInitParameter()
nell'oggetto di configurazione utilizzando il nome del
come argomento.
String teamColor = getServletConfig().getInitParameter("teamColor");
JSPs
Un'app può utilizzare JSP (JavaServer Pages) per implementare le pagine web. I JSP sono servlet definiti mediante contenuti statici, come HTML, combinati con codice Java.
App Engine supporta la compilazione automatica e la mappatura degli URL per JSP. Un file JSP
nella WAR dell'applicazione (all'esterno di WEB-INF/
) il cui nome file termina con .jsp
viene compilata automaticamente in una classe servlet e mappata al percorso dell'URL
equivalente al percorso del file JSP dalla radice WAR. Ad esempio, se un'app
ha un file JSP denominato start.jsp
in una sottodirectory denominata register/
nella relativa WAR,
App Engine lo compila e lo mappa al percorso dell'URL /register/start.jsp
.
Se desideri maggiore controllo su come il JSP viene mappato a un URL, puoi specificare
il mapping in modo esplicito dichiarandolo con un elemento <servlet>
nel
descrittore di deployment. Anziché un elemento <servlet-class>
, puoi specificare un valore
Elemento <jsp-file>
con il percorso del file JSP dalla radice WAR. La
L'elemento <servlet>
per JSP può contenere parametri di inizializzazione.
<servlet> <servlet-name>register</servlet-name> <jsp-file>/register/start.jsp</jsp-file> </servlet> <servlet-mapping> <servlet-name>register</servlet-name> <url-pattern>/register/*</url-pattern> </servlet-mapping>
Puoi installare le librerie di tag JSP con l'elemento <taglib>
. Una libreria di tag ha
un percorso al file JSP Tag Library Descriptor (TLD) (<taglib-location>
) e un
URI utilizzato dalle JSP per selezionare la libreria da caricare (<taglib-uri>
). Tieni presente che
App Engine fornisce il tag standard JavaServer Pages
Library (JSTL) e non è necessario
installarlo.
<taglib> <taglib-uri>/escape</taglib-uri> <taglib-location>/WEB-INF/escape-tags.tld</taglib-location> </taglib>
Sicurezza e autenticazione
Un'applicazione App Engine può utilizzare gli account Google per l'autenticazione degli utenti. La può utilizzare l'API Google Account per rilevare se l'utente ha eseguito l'accesso, ricevere l'email dell'utente che ha eseguito l'accesso e generare URL di accesso e uscita. Un'app può anche specificare l'accesso delle restrizioni per i percorsi degli URL basati sugli Account Google, utilizzando descrittore.
L'elemento <security-constraint>
definisce un vincolo di sicurezza per gli URL che
corrispondono a uno schema. Se un utente accede a un URL il cui percorso ha un vincolo di sicurezza
e se l'utente non ha eseguito l'accesso, App Engine lo reindirizza alla piattaforma Google
Pagina di accesso degli account. Gli Account Google reindirizzano l'utente al
URL dell'applicazione dopo aver eseguito l'accesso o aver registrato un nuovo account. La
l'app non deve fare altro per garantire che solo gli utenti che hanno eseguito l'accesso possano
accedere all'URL.
Un vincolo di sicurezza include un vincolo di autorizzazione che specifica
Gli utenti di Account Google possono accedere al percorso. Se il vincolo di autorizzazione
specifica un ruolo utente di *
, tutti gli utenti che hanno eseguito l'accesso con un Account Google potranno
accedere all'URL. Se il vincolo specifica un ruolo utente admin
, allora solo
gli sviluppatori registrati dell'applicazione possono accedere all'URL. Il ruolo admin
semplifica la creazione di sezioni del sito riservate agli amministratori.
<security-constraint> <web-resource-collection> <web-resource-name>profile</web-resource-name> <url-pattern>/profile/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>*</role-name> </auth-constraint> </security-constraint> <security-constraint> <web-resource-collection> <web-resource-name>admin</web-resource-name> <url-pattern>/admin/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>admin</role-name> </auth-constraint> </security-constraint>
App Engine non supporta i ruoli di sicurezza personalizzati (<security-role>
) o
meccanismi di autenticazione alternativi (<login-config>
) nel deployment
descrittore.
I vincoli di sicurezza si applicano ai file statici e ai servlet.
URL protetti
App Engine supporta connessioni sicure con HTTPS per gli URL che utilizzano
Dominio REGION_ID.r.appspot.com
. Quando una richiesta accede a un URL tramite HTTPS e l'URL in questione
è configurato per utilizzare HTTPS nel file web.xml
, sia i dati della richiesta che
i dati di risposta vengono criptati dal mittente prima di essere trasmessi
decriptato dal destinatario dopo la ricezione. Le connessioni sicure
utile per proteggere i dati dei clienti, come dati di contatto, password e
messaggi privati.
Per dichiarare che per un URL deve essere utilizzato HTTPS, devi configurare un vincolo di sicurezza
nel descrittore di deployment (come descritto
Sicurezza e autenticazione) con un
<user-data-constraint>
il cui <transport-guarantee>
è CONFIDENTIAL
.
Ad esempio:
<security-constraint> <web-resource-collection> <web-resource-name>profile</web-resource-name> <url-pattern>/profile/*</url-pattern> </web-resource-collection> <user-data-constraint> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint> </security-constraint>
Richieste che utilizzano HTTP (non sicuro) per gli URL la cui garanzia di trasporto è
CONFIDENTIAL
vengono reindirizzati automaticamente allo stesso URL tramite HTTPS.
La garanzia di trasporto del CONFIDENTIAL
può essere utilizzata da qualsiasi URL, inclusi JSP e
file statici.
Il server web di sviluppo non supporta le connessioni HTTPS. Ignora di trasporto pubblico, quindi i percorsi destinati a essere utilizzati con HTTPS possono essere testati normali connessioni HTTP al server web di sviluppo.
Quando testi i gestori HTTPS della tua app utilizzando l'URL appspot.com con il controllo delle versioni,
ad esempio https://1.latest.your_app_id.REGION_ID.r.appspot.com/
,
il browser ti avvisa che il certificato HTTPS non è stato firmato
uno specifico percorso del dominio. Se accetti il certificato per quel dominio, le pagine verranno
caricamento completato. Gli utenti non vedranno l'avviso relativo al certificato quando accedono
https://your_app_id.REGION_ID.r.appspot.com/
.
Puoi anche utilizzare una forma alternativa dell'URL appspot.com con controllo delle versioni progettato per
evita questo problema sostituendo i punti che separano i componenti del sottodominio
con la stringa "-dot-
". Ad esempio, all'esempio precedente,
senza avviso relativo al certificato in
https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com
.
L'accesso e la disconnessione dall'Account Google vengono sempre eseguiti utilizzando un sistema e non è correlata alla configurazione degli URL dell'applicazione.
Come già detto, i vincoli di sicurezza si applicano ai file statici e servlet. È inclusa la garanzia di trasporto.
Nota: Google consiglia
con il protocollo HTTPS per inviare richieste alla tua app. Google non rilascia SSL
certificati per domini con doppio carattere jolly ospitati all'indirizzo appspot.com
. Di conseguenza, con HTTPS
devi utilizzare la stringa "-dot-" anziché "." per separare i sottodomini, come mostrato negli esempi
di seguito. Puoi utilizzare un semplice "." con il tuo dominio personalizzato o con indirizzi HTTP.
L'elenco dei file di benvenuto
Se gli URL del tuo sito rappresentano percorsi di file statici o JSP nella WAR,
spesso è una buona idea che anche i percorsi verso le directory facciano qualcosa di utile.
Un utente visita il percorso dell'URL /help/accounts/password.jsp
per informazioni su
le password degli account potrebbero tentare di visitare /help/accounts/
per trovare una pagina
illustrando la documentazione del sistema di account. Il descrittore di deployment può
specificare un elenco di nomi file che il server deve provare quando l’utente accede a un
percorso che rappresenta una sottodirectory WAR non ancora mappata esplicitamente
a un servlet. La specifica del servlet lo chiama welcome file list
.
Ad esempio, se l'utente accede al percorso dell'URL /help/accounts/
, il seguente codice
L'elemento <welcome-file-list>
nel descrittore di deployment comunica al server di
controlla help/accounts/index.jsp
e help/accounts/index.html
prima
segnalando che l'URL non esiste:
<welcome-file-list>
<welcome-file>index.jsp</welcome-file>
<welcome-file>index.html</welcome-file>
</welcome-file-list>
Filtri
Un filtro è una classe che agisce su una richiesta come un servlet, ma può Consentire alla gestione della richiesta di continuare con altri filtri o servlet. R un filtro può eseguire un'attività ausiliaria, come il logging, l'esecuzione dei controlli di autenticazione o annotare gli oggetti di richiesta o risposta prima per chiamare il servlet. I filtri consentono di comporre attività di elaborazione delle richieste il descrittore di deployment.
Il seguente esempio di implementazione del filtro registra una
un messaggio e passa controlli lungo la catena, che può includere altri filtri o
servlet, come descritto dal descrittore di deployment per la versione 21 e successive
EE10 (impostazione predefinita), versione 21 su EE8 e versione 17 e precedenti. Per utilizzare l'ultima versione supportata su
devi aggiornare i servlet delle applicazioni
per includere lo spazio dei nomi Jakarta
. Per saperne di più sulle opzioni di configurazione,
consulta l'articolo Eseguire l'upgrade di un'applicazione esistente.
v21 e successive (EE10)
Questa classe di filtro implementa l'interfaccia jakarta.servlet.Filter
con
Metodo doFilter()
.
package mysite.server;
import java.io.IOException;
import java.util.logging.Logger;
import jakarta.servlet.Filter;
import jakarta.servlet.FilterChain;
import jakarta.servlet.FilterConfig;
import jakarta.servlet.ServletException;
import jakarta.servlet.ServletRequest;
import jakarta.servlet.ServletResponse;
public class LogFilterImpl implements Filter {
private FilterConfig filterConfig;
private static final Logger log = Logger.getLogger(LogFilterImpl.class.getName());
public void doFilter(ServletRequest request, ServletResponse response, FilterChain filterChain)
throws IOException, ServletException {
log.warning("Log filter processed a " + getFilterConfig().getInitParameter("logType")
+ " request");
filterChain.doFilter(request, response);
}
public FilterConfig getFilterConfig() {
return filterConfig;
}
public void init(FilterConfig filterConfig) {
this.filterConfig = filterConfig;
}
public void destroy() {}
}
Versione 21 (EE8)
Questa classe di filtro implementa l'interfaccia javax.servlet.Filter
con
Metodo doFilter()
.
package mysite.server;
import java.io.IOException;
import java.util.logging.Logger;
import javax.servlet.Filter;
import javax.servlet.FilterChain;
import javax.servlet.FilterConfig;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
public class LogFilterImpl implements Filter {
private FilterConfig filterConfig;
private static final Logger log = Logger.getLogger(LogFilterImpl.class.getName());
public void doFilter(ServletRequest request, ServletResponse response, FilterChain filterChain)
throws IOException, ServletException {
log.warning("Log filter processed a " + getFilterConfig().getInitParameter("logType")
+ " request");
filterChain.doFilter(request, response);
}
public FilterConfig getFilterConfig() {
return filterConfig;
}
public void init(FilterConfig filterConfig) {
this.filterConfig = filterConfig;
}
public void destroy() {}
}
v17 e precedenti
Questa classe di filtro implementa l'interfaccia javax.servlet.Filter
con
Metodo doFilter()
.
package mysite.server;
import java.io.IOException;
import java.util.logging.Logger;
import javax.servlet.Filter;
import javax.servlet.FilterChain;
import javax.servlet.FilterConfig;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
public class LogFilterImpl implements Filter {
private FilterConfig filterConfig;
private static final Logger log = Logger.getLogger(LogFilterImpl.class.getName());
public void doFilter(ServletRequest request, ServletResponse response, FilterChain filterChain)
throws IOException, ServletException {
log.warning("Log filter processed a " + getFilterConfig().getInitParameter("logType")
+ " request");
filterChain.doFilter(request, response);
}
public FilterConfig getFilterConfig() {
return filterConfig;
}
public void init(FilterConfig filterConfig) {
this.filterConfig = filterConfig;
}
public void destroy() {}
}
Analogamente ai servlet, configuri un filtro nel descrittore di deployment
dichiarando il filtro con l'elemento <filter>
e associandolo a un URL
con l'elemento <filter-mapping>
. Puoi anche mappare i filtri direttamente
ad altri servlet.
L'elemento <filter>
contiene <filter-name>
, <filter-class>
e
elementi <init-param>
facoltativi.
<filter> <filter-name>logSpecial</filter-name> <filter-class>mysite.server.LogFilterImpl</filter-class> <init-param> <param-name>logType</param-name> <param-value>special</param-value> </init-param> </filter>
L'elemento <filter-mapping>
contiene un <filter-name>
che corrisponde al nome
di un filtro dichiarato e un elemento <url-pattern>
per l'applicazione
filtrare in base agli URL o a un elemento <servlet-name>
che corrisponde al nome di un
servlet dichiarato per l'applicazione del filtro ogni volta che viene chiamato il servlet.
<!-- Log for all URLs ending in ".special" --> <filter-mapping> <filter-name>logSpecial</filter-name> <url-pattern>*.special</url-pattern> </filter-mapping> <!-- Log for all URLs that use the "comingsoon" servlet --> <filter-mapping> <filter-name>logSpecial</filter-name> <servlet-name>comingsoon</servlet-name> </filter-mapping>
Gestione degli errori
Puoi personalizzare ciò che il server invia all'utente quando si verifica un errore, utilizzando il descrittore di deployment. Il server può visualizzare una posizione di pagina alternativa quando sta per inviare un particolare codice di stato HTTP o quando un servlet genera una particolare eccezione Java.
L'elemento <error-page>
contiene un elemento <error-code>
con un
valore del codice di errore HTTP (ad es. 500
) o un elemento <exception-type>
con
nome della classe dell'eccezione prevista (ad esempio java.io.IOException
). Inoltre,
contiene un elemento <location>
contenente il percorso dell'URL della risorsa da mostrare
quando si verifica l'errore.
<error-page> <error-code>500</error-code> <location>/errors/servererror.jsp</location> </error-page>
Non puoi configurare gestori degli errori personalizzati per il seguente errore condizioni:
- Pagina di risposta di
404
quando non è stata definita alcuna mappatura servlet per un URL. - Pagina di errore della quota
403
- Pagina di errore del server
500
visualizzata dopo un errore interno di App Engine.
Funzionalità web.xml non supportate
Le seguenti funzionalità web.xml non sono supportate da App Engine:
- App Engine supporta l'elemento
<load-on-startup>
per le dichiarazioni servlet. Tuttavia, il caricamento si verifica effettivamente durante la prima richiesta gestita dal web un'istanza del server, non la precedente. - Alcuni elementi descrittore di deployment possono assumere un nome visualizzato leggibile, descrizione e icona da usare negli IDE. App Engine non li utilizza, e li ignora.
- App Engine non supporta le variabili di ambiente JNDI (
<env-entry>
). - App Engine non supporta le risorse EJB (
<resource-ref>
). - La notifica relativa all'eliminazione di servlet, contesto servlet o filtri è non supportati.
- L'elemento
<distributable>
viene ignorato. - La pianificazione del servlet con
<run-at>
non è supportata.