Questa pagina è stata tradotta dall'API Cloud Translation.

Ambiente di runtime Java

Il runtime Java è lo stack software responsabile dell'installazione del codice e delle dipendenze del servizio web e dell'esecuzione del servizio.

Dichiara il runtime Java per l'ambiente standard di App Engine nel file app.yaml. Ad esempio:

runtime: javaVERSION

Dove VERSION è il numero di versione di MAJOR Java. Ad esempio, per utilizzare l'ultima versione di Java, Java 21, specifica 21.

Per altre versioni di Java supportate e la versione Ubuntu corrispondente per la tua versione Java, fai riferimento alla pianificazione del supporto di runtime.

Prima di iniziare

Scarica la versione più recente di Google Cloud CLI o aggiorna gcloud CLI alla versione attuale:
```
gcloud components update
```
Per eseguire il deployment tramite Maven, devi aggiungere il plug-in Maven di App Engine al tuo file pom.xml:
```
<plugin>
   <groupId>com.google.cloud.tools</groupId>
   <artifactId>appengine-maven-plugin</artifactId>
   <version>2.7.0</version>
</plugin>
```
Altre opzioni per il deployment includono l'utilizzo del comando gcloud app deploy o del plug-in Gradle di App Engine.
Segui le istruzioni relative al framework della tua applicazione per configurare la build di un file JAR eseguibile.

Compatibilità del framework

Con il runtime Java di App Engine, puoi eseguire il deployment di file JAR eseguibili. I runtime non includono alcun framework per la pubblicazione sul web, il che significa che non devi limitarti all'utilizzo di framework o librerie basati su servlet. Utilizza le tue dipendenze native o stack di networking come la libreria Netty.

Nel repository GitHub di Google Cloud sono disponibili hello world esempi che utilizzano framework web Java popolari:

Non hai limiti a questi framework e ti consigliamo di provare quello che preferisci, come Grails, Blade, Play!, Vaadin o jHipster.

esegui il deployment di progetti di origine Maven nel runtime Java

Puoi eseguire il deployment del tuo progetto Maven come codice sorgente e fare in modo che venga creato e sottoposto a deployment mediante i buildpack di Google Cloud.

Per eseguire il deployment di un progetto Maven come codice sorgente, vai alla directory di primo livello del tuo progetto e digita:

gcloud app deploy pom.xml

I log di build ed deployment verranno trasmessi in flusso e puoi visualizzare i log dettagliati nella sezione Cronologia di Cloud Build nella console Cloud.

Utilizzo degli eseguibili GraalVM

Il runtime Java dell'ambiente standard di App Engine supporta gli eseguibili di immagini native GraalVM. Dopo aver compilato l'app Java in un'immagine nativa GraalVM, puoi utilizzare l'impostazione entrypoint nel file app.yaml per puntare all'eseguibile.

Ad esempio, un eseguibile con il nome file myexecutable potrebbe avere il seguente file di configurazioneapp.yaml:

runtime: java17 # or another supported runtime
entrypoint: ./myexecutable

Le librerie client di Google Cloud possono essere usate per compilare le applicazioni come immagine nativa GraalVM. Per ulteriori informazioni, consulta la documentazione su come compilare immagini native.

Versione Java

Il runtime Java utilizza l'ultima release stabile della versione specificata nel file app.yaml. App Engine si aggiorna automaticamente alle nuove versioni delle patch, ma non aggiorna automaticamente la versione secondaria.

Ad esempio, il deployment dell'applicazione potrebbe essere eseguito con Java 11.0.4 e aggiornata automaticamente alla versione Java 11.0.5 in un deployment successivo della piattaforma gestita, ma non verrà aggiornata automaticamente a Java 12.

Per informazioni su come eseguire l'upgrade della tua versione di Java, consulta Eseguire l'upgrade di un'applicazione esistente.

L'ambiente aperto JDK del runtime

App Engine esegue app Java in un container protetto da gVisor su una distribuzione Linux aggiornata e il relativo runtime openjdk-11-jdk per Java 11 o openjdk-17-jdk per Java 17 supportato.

Per le versioni Ubuntu supportate per la tua versione Java, consulta la pianificazione del supporto del runtime.

App Engine mantiene l'immagine di base e aggiorna il pacchetto OpenJDK 11 e OpenJDK 17 senza che tu debba rieseguire il deployment dell'app.

L'app di cui hai eseguito il deployment si trova nella directory /workspace del runtime. È accessibile anche tramite un link simbolico all'indirizzo /srv.

Versioni Java di App Engine

Tutti gli artefatti rilasciati che iniziano con la versione 2.x.x utilizzano il meccanismo di rilascio open source. Gli artefatti rilasciati che iniziano con la versione 1.9.9xx o precedenti utilizzano il sistema di compilazione interno. Per ulteriori dettagli, consulta il repository GitHub.

Dipendenze

Per ulteriori informazioni sulla dichiarazione e la gestione delle dipendenze, consulta Specifica delle dipendenze.

Avvio dell'applicazione

I framework come Spring Boot, Micronaut e Ktor creano un'uber eseguibile JAR per impostazione predefinita. Se il file di build Maven o Gradle produce un JAR Uber eseguibile, il runtime avvia l'applicazione eseguendo un'applicazione Uber JAR.

In alternativa, App Engine utilizzerà i contenuti del campo facoltativo entrypoint nel file app.yaml. Ad esempio:

runtime: java21 # or another supported runtime
entrypoint: java -Xmx64m -jar YOUR-ARTIFACT.jar

Dove il jar dell'applicazione YOUR-ARTIFACT.jar di esempio deve:

Trova il file app.yaml nella directory root.
Contenere una voce Main-Class nel relativo file di metadati META-INF/MANIFEST.MF.
Facoltativamente, contiene una voce Class-Path con un elenco di percorsi relativi ad altri jar dipendenti. Questi verranno caricati automaticamente con l'applicazione.

Affinché la tua app riceva richieste HTTP, il tuo punto di ingresso deve avviare un server web che rimane in ascolto sulla porta specificata dalla variabile di ambiente PORT. Il valore della variabile di ambiente PORT viene impostato in modo dinamico dall'ambiente di gestione di App Engine. Questo valore non può essere impostato nella sezione env_variables del file app.yaml.

Con un punto di ingresso personalizzato, puoi creare e pacchettizzare la tua applicazione come un sottile file JAR che contiene solo il codice dell'applicazione e le dipendenze dirette. Durante il deployment dell'applicazione, il plug-in App Engine carica solo i file modificati, anziché l'intero pacchetto JAR.

Accertati di utilizzare la variabile di ambiente PORT

Se vedi gli avvisi relativi alla porta 8080 e NGINX nei file di log dell'app, significa che il server web dell'app è in ascolto sulla porta predefinita 8080. Questo impedisce ad App Engine di usare il suo livello NGINX per comprimere le risposte HTTP. Ti consigliamo di configurare il server web in modo che risponda alle richieste HTTP sulla porta specificata dalla variabile di ambiente PORT, in genere 8081. Ad esempio:

/*
 * Copyright 2019 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.example.appengine;

import com.sun.net.httpserver.HttpServer;
import java.io.IOException;
import java.io.OutputStream;
import java.net.InetSocketAddress;

public class Main {

  public static void main(String[] args) throws IOException {
    // Create an instance of HttpServer bound to port defined by the 
    // PORT environment variable when present, otherwise on 8080.
    int port = Integer.parseInt(System.getenv().getOrDefault("PORT", "8080"));
    HttpServer server = HttpServer.create(new InetSocketAddress(port), 0);

    // Set root URI path.
    server.createContext("/", (var t) -> {
      byte[] response = "Hello World!".getBytes();
      t.sendResponseHeaders(200, response.length);
      try (OutputStream os = t.getResponseBody()) {
        os.write(response);
      }
    });

    // Create a second URI path.
    server.createContext("/foo", (var t) -> {
      byte[] response = "Foo!".getBytes();
      t.sendResponseHeaders(200, response.length);
      try (OutputStream os = t.getResponseBody()) {
        os.write(response);
      }
    });

    server.start();
  }
}

Compatibilità con le versioni precedenti di Java

Per le differenze tra Java 8 e l'ultima versione di Java supportata, consulta Differenze principali tra i runtime di Java 8 e Java 11 e versioni successive.

Variabili di ambiente

Le seguenti variabili di ambiente sono impostate dal runtime:

Variabile di ambiente	Descrizione
`GAE_APPLICATION`	L'ID della tua applicazione App Engine. Questo ID è preceduto dal prefisso "`region code`~", ad esempio "e~" per le applicazioni di cui è stato eseguito il deployment in Europa.
`GAE_DEPLOYMENT_ID`	L'ID del deployment attuale.
`GAE_ENV`	L'ambiente App Engine. Impostata su `standard`.
`GAE_INSTANCE`	L'ID dell'istanza su cui è attualmente in esecuzione il servizio.
`GAE_MEMORY_MB`	La quantità di memoria disponibile per il processo di richiesta, in MB.
`GAE_RUNTIME`	Il tempo di esecuzione specificato nel file `app.yaml`.
`GAE_SERVICE`	Il nome del servizio specificato nel file `app.yaml`. Se non viene specificato alcun nome di servizio, viene impostato su `default`.
`GAE_VERSION`	L'etichetta della versione corrente del servizio.
`GOOGLE_CLOUD_PROJECT`	L'ID progetto Google Cloud associato alla tua applicazione.
`PORT`	La porta che riceve le richieste HTTP.
`NODE_ENV` (disponibile solo nel runtime Node.js)	Imposta su `production` quando viene eseguito il deployment del servizio.

Puoi definire variabili di ambiente aggiuntive nel file app.yaml, ma i valori precedenti non possono essere sostituiti, ad eccezione di NODE_ENV.

Proxy HTTPS e di forwarding

App Engine termina le connessioni HTTPS a livello di bilanciatore del carico e inoltra le richieste all'applicazione. Alcune applicazioni devono determinare l'IP e il protocollo della richiesta originale. L'indirizzo IP dell'utente è disponibile nell'intestazione X-Forwarded-For standard. Le applicazioni che richiedono queste informazioni devono configurare il proprio framework web per considerare attendibile il proxy.

Accesso al file system

Il runtime include una directory /tmp accessibile in scrittura, con tutte le altre directory che dispongono dell'accesso di sola lettura. La scrittura su /tmp occupa memoria di sistema.

Server metadati

Ogni istanza dell'applicazione può utilizzare il server di metadati di App Engine per eseguire query sulle informazioni sull'istanza e sul progetto.

Puoi accedere al server di metadati tramite i seguenti endpoint:

http://metadata
http://metadata.google.internal

Le richieste inviate al server dei metadati devono includere l'intestazione della richiesta Metadata-Flavor: Google. Questa intestazione indica che la richiesta è stata inviata con l'intento di recuperare i valori dei metadati.

La tabella seguente elenca gli endpoint in cui è possibile effettuare richieste HTTP per metadati specifici:

Endpoint metadati	Descrizione
`/computeMetadata/v1/project/numeric-project-id`	Il numero del progetto assegnato al tuo progetto.
`/computeMetadata/v1/project/project-id`	L'ID progetto assegnato al progetto.
`/computeMetadata/v1/instance/region`	La regione in cui è in esecuzione l'istanza.
`/computeMetadata/v1/instance/service-accounts/default/aliases`
`/computeMetadata/v1/instance/service-accounts/default/email`	L'indirizzo email dell'account di servizio predefinito assegnato al progetto.
`/computeMetadata/v1/instance/service-accounts/default/`	Elenca tutti gli account di servizio predefiniti per il tuo progetto.
`/computeMetadata/v1/instance/service-accounts/default/scopes`	Elenca tutti gli ambiti supportati per gli account di servizio predefiniti.
`/computeMetadata/v1/instance/service-accounts/default/token`	Restituisce il token di autenticazione che può essere utilizzato per autenticare l'applicazione in altre API Google Cloud.

Ad esempio, per recuperare l'ID progetto, invia una richiesta a http://metadata.google.internal/computeMetadata/v1/project/project-id.