Configurazione di un ambiente di sviluppo

Questa pagina descrive come configurare l'ambiente di sviluppo per creare ed eseguire il deployment dell'API di backend utilizzando Cloud Endpoints Frameworks per l'ambiente standard di App Engine. Questa pagina utilizza l'esempio di codice Endpoints Frameworks versione 2.0 skeleton per spiegare il software e i componenti di base necessari per iniziare.

Potresti voler utilizzare endpoints-skeleton-archetype o hello-endpoints-archetype descritti in Utilizzo di Apache Maven e del plug-in App Engine (basato su Google Cloud CLI) per creare un nuovo progetto Endpoints Frameworks versione 2.0.

Per comprendere meglio i passaggi necessari per eseguire il deployment di un'API di esempio utilizzando Endpoints Frameworks, consulta il tutorial Guida introduttiva a Endpoints Frameworks su App Engine.

Prima di iniziare

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Prendi nota dell' Google Cloud ID progetto perché ti servirà in seguito.
  7. Installazione e configurazione del software richiesto

    1. Se non hai installato Java 8, scarica Java Development Kit (JDK) dal sito di Oracle e installalo.
    2. Installa Maven o Gradle:

      Maven

      1. Scarica Apache Maven versione 3.3.9 o successive
      2. Installa e configura Maven per il tuo ambiente di sviluppo locale.

      Gradle

    3. Scarica e inizializza Google Cloud CLI.
    4. Esegui i seguenti comandi:
      1. Assicurati che gcloud CLI sia autorizzata ad accedere ai tuoi dati e servizi su Google Cloud:
        gcloud auth login
      2. Utilizza le credenziali predefinite dell'applicazione:
        gcloud auth application-default login
      3. Installa il componente app-engine-java di Google Cloud SDK:
        gcloud components install app-engine-java
      4. Esegui l'aggiornamento all'ultima versione di Google Cloud SDK e di tutti i componenti:
        gcloud components update
    5. Crea un'applicazione App Engine:
      1. Imposta il progetto predefinito sull'ID progetto Google Cloud :
        gcloud config set project YOUR_PROJECT_ID

        Sostituisci YOUR_PROJECT_ID con l'ID progetto Google Cloud. Se hai altri progetti Google Cloud e vuoi utilizzare gcloud per gestirli, consulta Gestione delle configurazioni di gcloud CLI.

      2. Seleziona la regione in cui vuoi creare l'applicazione App Engine. Consulta Località di App Engine per un elenco delle regioni.
      3. Crea un'applicazione App Engine. Sostituisci YOUR_PROJECT_ID con l'ID del tuo progetto Google Cloud e YOUR_REGION con la regione in cui vuoi creare l'applicazione App Engine.
          gcloud app create \
          --project=YOUR_PROJECT_ID \
          --region=YOUR_REGION

    Recupero dell'esempio di scheletro di Endpoints Frameworks

    L'esempio di scheletro di Endpoints Frameworks versione 2.0 contiene gli script di build necessari per Maven e Gradle. Contiene anche i file necessari per iniziare a creare la tua prima API.

    1. Clona il repository di esempio sulla tua macchina locale:

       git clone https://github.com/GoogleCloudPlatform/java-docs-samples
      
    2. Passa alla directory contenente lo scheletro dell'esempio di Endpoints Frameworks:

       cd java-docs-samples/appengine-java8/endpoints-v2-skeleton/
      

      L'esempio ha la seguente struttura di directory:

      Layout di esempio dello scheletro di Endpoints Frameworks

      • MyApi.java contiene una classe vuota che puoi utilizzare per iniziare a scrivere la tua API. Consulta l' esempio di echo per un codice campione che ti aiuti a iniziare.

      • web.xml è un file standard utilizzato per configurare una servlet.

      • appengine-web.xml definisce le informazioni necessarie per eseguire il deployment dell'API nell'ambiente standard App Engine utilizzando Java 8.

      • pom.xml contiene informazioni sul progetto e sulla configurazione utilizzate da Maven per creare il progetto ed eseguire il deployment dell'API in App Engine.

      • build.gradle contiene informazioni sul progetto e sulla configurazione utilizzate da Gradle per creare il progetto ed eseguire il deployment dell'API su App Engine.

    Configurazione dei file di build

    Questa sezione descrive i file Maven pom.xml e Gradle build.gradle inclusi nel codice campione. A parte l'inserimento dell'ID progetto Google Cloud in modo che possa essere utilizzato nel nome host, i file di build sono pronti per iniziare a creare l'API.

    Informazioni sulla configurazione minima

    Questa sezione descrive la configurazione minima necessaria nel file di build.

    Maven

    Dipendenze minime

    Di seguito sono riportate le dipendenze minime richieste nel tuo pom.xml per iniziare:

    <dependencies>
      <!-- Compile/runtime dependencies -->
      <dependency>
        <groupId>com.google.endpoints</groupId>
        <artifactId>endpoints-framework</artifactId>
        <version>2.2.2</version>
      </dependency>
      <dependency>
        <groupId>com.google.appengine</groupId>
        <artifactId>appengine-api-1.0-sdk</artifactId>
        <version>2.0.23</version>
      </dependency>
      <dependency>
        <groupId>javax.servlet</groupId>
        <artifactId>javax.servlet-api</artifactId>
        <version>3.1.0</version>
        <type>jar</type>
        <scope>provided</scope>
      </dependency>
      <dependency>
        <groupId>javax.inject</groupId>
        <artifactId>javax.inject</artifactId>
        <version>1</version>
      </dependency>
    </dependencies>

    Applicare i plug-in

    Per abilitarli, vengono applicati i seguenti plug-in:

    <build>
      <!-- for hot reload of the web application-->
      <outputDirectory>${project.build.directory}/${project.build.finalName}/WEB-INF/classes</outputDirectory>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-war-plugin</artifactId>
          <version>3.4.0</version>
          <configuration>
            <webResources>
              <resources>
                <directory>${basedir}/src/main/webapp/WEB-INF</directory>
                <filtering>true</filtering>
                <targetPath>WEB-INF</targetPath>
              </resources>
            </webResources>
          </configuration>
        </plugin>
        <plugin>
          <groupId>com.google.cloud.tools</groupId>
          <artifactId>appengine-maven-plugin</artifactId>
          <version>2.5.0</version>
          <configuration>
            <!-- deploy configuration -->
            <projectId>GCLOUD_CONFIG</projectId>
            <version>GCLOUD_CONFIG</version>
          </configuration>
        </plugin>
        <plugin>
          <groupId>com.google.cloud.tools</groupId>
          <artifactId>endpoints-framework-maven-plugin</artifactId>
          <version>2.1.0</version>
          <configuration>
            <!-- plugin configuration -->
            <!--
            You must replace YOUR_PROJECT_ID with your
            Google Cloud Project Id
          -->
            <hostname>YOUR_PROJECT_ID.appspot.com</hostname>
          </configuration>
        </plugin>
      </plugins>
    </build>
    • maven-war-plugin estende il plug-in java per aggiungere il supporto per l'assemblaggio di un'applicazione web.
    • appengine-maven-plugin è necessario per eseguire l'API su App Engine.
    • endpoints-framework-maven-plugin fornisce attività e configurazioni per creare progetti Endpoints Frameworks.

    Gradle

    Dipendenze dei plug-in

    Di seguito sono riportati i plug-in necessari per creare l'API:

    buildscript {
      repositories {
        mavenCentral()
      }
    
      dependencies {
        classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:2.1.0'
        classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.5.0'
      }
    }

    Applicare i plug-in

    I seguenti plug-in vengono applicati per abilitarli nello script di build di Gradle:

    apply plugin: 'java'
    apply plugin: 'war'
    apply plugin: 'com.google.cloud.tools.endpoints-framework-server'
    apply plugin: 'com.google.cloud.tools.appengine'

    • Il plug-in java aggiunge al tuo progetto passaggi di compilazione e build specifici per Java.
    • Il plug-in war estende il plug-in java per aggiungere il supporto per l'assemblaggio di un'applicazione web.
    • Il plug-in endpoints-framework-server fornisce il supporto lato server al plug-in Gradle di Endpoints Frameworks.
    • Il plug-in appengine è necessario per eseguire l'API su App Engine.

    Dipendenze progetto

    Il progetto utilizza le seguenti dipendenze:

    dependencies {
        compile 'com.google.endpoints:endpoints-framework:2.2.2'
        compile 'com.google.appengine:appengine-api-1.0-sdk:2.0.23'
    
        compile 'javax.inject:javax.inject:1'
        compileOnly 'javax.servlet:javax.servlet-api:3.1.0'
    }

    Definizione del nome host per il servizio

    Endpoints Frameworks utilizza nomi compatibili con il DNS per identificare in modo univoco i servizi. Poiché Google Cloud gli ID progetto sono univoci a livello globale, devi utilizzare il tuo Google Cloud ID progetto come parte del nome del servizio dell'API.

    Devi aggiungere l'ID progetto Google Cloud ai file di build per configurare il nome host per il tuo servizio. Il nome host deve avere il seguente formato:

    YOUR_PROJECT_ID.appspot.com

    Quando esegui il deployment dell'API in App Engine, viene creata automaticamente una voce DNS con un nome nel formato YOUR_PROJECT_ID.appspot.com. Il nome host è sia il nome del servizio Cloud Endpoints sia il nome di dominio che utilizzi per inviare richieste alla tua API.

    Maven

    <plugin>
      <groupId>com.google.cloud.tools</groupId>
      <artifactId>endpoints-framework-maven-plugin</artifactId>
      <version>2.1.0</version>
      <configuration>
        <!-- plugin configuration -->
        <!--
        You must replace YOUR_PROJECT_ID with your
        Google Cloud Project Id
      -->
        <hostname>YOUR_PROJECT_ID.appspot.com</hostname>
      </configuration>
    </plugin>

    Nel campo hostname, sostituisci YOUR_PROJECT_ID con l'ID del tuo progetto Google Cloud .

    Gradle

    // You must replace YOUR_PROJECT_ID with your Google Cloud Project Id
    def projectId = 'YOUR_PROJECT_ID'
    
    endpointsServer {
      // Endpoints Framework Plugin server-side configuration
      hostname = "${projectId}.appspot.com"
    }

    Imposta la variabile projectID sull'ID progetto Google Cloud. Ad esempio: def projectId = 'example-project-12345'

    Configurazione della servlet Endpoints

    La servlet Endpoints gestisce le richieste in entrata e le inoltra al servizio di backend in esecuzione su App Engine. La servlet Endpoints è necessaria per la gestione della tua API da parte di Endpoints.

    Per maggiori informazioni su web.xml, vedi Il descrittore di deployment: web.xml.

    <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">
        <!-- Wrap the backend with Endpoints Frameworks v2. -->
        <servlet>
            <servlet-name>EndpointsServlet</servlet-name>
            <servlet-class>com.google.api.server.spi.EndpointsServlet</servlet-class>
            <init-param>
                <param-name>services</param-name>
                <param-value>com.example.skeleton.MyApi</param-value>
            </init-param>
        </servlet>
        <!-- Route API method requests to the backend. -->
        <servlet-mapping>
            <servlet-name>EndpointsServlet</servlet-name>
            <url-pattern>/_ah/api/*</url-pattern>
        </servlet-mapping>
    </web-app>

    Configurazione del deployment di App Engine

    Il file appengine-web.xml viene utilizzato per definire la configurazione dell'ambiente standard App Engine quando viene eseguito il deployment dell'API. Per saperne di più, consulta il riferimento appengine-web.xml.

    <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
        <runtime>java8</runtime>
        <threadsafe>true</threadsafe>
    
        <system-properties>
            <property name="java.util.logging.config.file" value="WEB-INF/logging.properties"/>
        </system-properties>
    </appengine-web-app>

    Passaggi successivi