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 lo scheletro di endpoint versione 2.0 di endpoint per spiegare il software di base e i componenti necessari per iniziare.

Puoi 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 di 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 Introduzione a Endpoints Frameworks su App Engine.

Prima di iniziare

1. Accedi al tuo account Google Cloud. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

6. Prendi nota dell'ID progetto Google Cloud perché sarà necessario in seguito.

Installazione e configurazione del software richiesto

1. Se non hai installato Java 8, scarica il 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 configure Maven per il tuo ambiente di sviluppo locale.

   Gradle

   • Installa Gradle.
3. Scarica e inizializza Google Cloud CLI.
4. Esegui questi comandi:
   1. Assicurati che gcloud CLI sia autorizzato ad accedere a dati e servizi su Google Cloud:

      gcloud auth login

   2. Usa 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 alla versione più recente di Google Cloud SDK e di tutti i componenti:

      gcloud components update

5. Crea un'applicazione App Engine:
   1. Imposta il progetto predefinito sul tuo ID progetto Google Cloud:

      gcloud config set project YOUR_PROJECT_ID

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

   2. Seleziona la regione in cui vuoi creare l'applicazione App Engine. Consulta le località di App Engine per un elenco delle regioni.
   3. Creare un'applicazione App Engine. Sostituisci YOUR_PROJECT_ID con l'ID 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 che contiene l'esempio di scheletro di Endpoints Frameworks:

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

   L'esempio ha la seguente struttura di directory:

   

   • MyApi.java contiene una classe vuota che puoi usare per iniziare a scrivere la tua API. Consulta l'esempio di eco per codice campione utili per iniziare.

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

   • appengine-web.xml definisce le informazioni necessarie per eseguire il deployment dell'API nell'ambiente standard di 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 in App Engine.

Configurazione dei file di build

In questa sezione vengono descritti 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 per il file di build.

Maven

Dipendenze minime

Di seguito sono mostrate le dipendenze minime richieste in 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>

• La dipendenza endpoints-framework contiene le classi necessarie per creare la tua API.
• È necessario <atrack-type="tasks" l10n-attrs-original-order="href,track-type,track-name,track-metadata-position" l10n-crypt-href="8uk1g2YxVmQFExiHWQoDVLU3uURKQq2GHK/Q1ZkBJNo="href,track-type,track-name,track-metadata-position" l10n-crypt-href="8uk1g2YxVmQFExiHWQoDVLU3uURKQq2GHK/Q1ZkBJNo="l'API standard App Engine nell'ambiente standard di App Engineappengine-api-sdk
• Per creare un servlet è richiesto il pacchetto javax.servlet standard.
• Il pacchetto javax.inject standard è necessario per supportare l' inserimento delle dipendenze.

Applicare 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.
• L'elemento appengine-maven-plugin è necessario per eseguire l'API su App Engine.
• endpoints-framework-maven-plugin fornisce attività e configurazioni per creare progetti di Endpoints Frameworks.

Gradle

Dipendenze 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'
  }
}

• Il plug-in Gradle Endpoints Frameworks viene utilizzato per generare un documento OpenAPI e generare librerie client.
• Per eseguire il deployment del progetto in App Engine, è necessario il plug-in Gradle di App Engine.

Applicare plug-in

I seguenti plug-in vengono applicati per attivarli nello script di build 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 progetto passi 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 supporto lato server per il plug-in Gradle di Endpoints Frameworks.
• Il plug-in appengine è necessario per eseguire l'API su App Engine.

Dipendenze del 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'
}

• La dipendenza endpoints-framework contiene le classi necessarie per creare la tua API.
• L'SDK dell'API standard di App Engine (appengine-api-sdk) è necessario per eseguire il deployment del progetto nell'ambiente standard di App Engine.
• Per creare un servlet è necessario il pacchetto javax.servlet standard.
• Il pacchetto javax.inject standard è necessario per supportare l' inserimento delle dipendenze.

Definizione del nome host per il servizio

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

Per configurare il nome host del servizio, devi aggiungere il tuo ID progetto Google Cloud ai file di build. 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 che il nome di dominio che utilizzi per inviare richieste all'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 sul tuo ID progetto Google Cloud. Ad esempio: def projectId = 'example-project-12345'

Configurazione del servlet di Endpoints

Il servlet di Endpoints gestisce le richieste in entrata e le inoltra al servizio di backend in esecuzione su App Engine. Il servlet degli endpoint è necessario affinché l'API venga gestita da Endpoints.

Per maggiori informazioni su web.xml, consulta 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 App Engine

Il file appengine-web.xml viene utilizzato per definire la configurazione dell'ambiente standard di App Engine quando viene eseguito il deployment dell'API. Per ulteriori informazioni, consulta la documentazione di riferimento di 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

• Scrivi e annota il codice dell'API di backend.
• Scopri di più sulle annotazioni.
• Aggiungi la gestione delle API.
• Eseguire il deployment e testare l'API.
• Scopri di più sui parametri supportati e sui tipi restituiti.