Configurazione di un ambiente di sviluppo

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

Ti consigliamo di utilizzare endpoints-skeleton-archetype o hello-endpoints-archetype descritto in Utilizzare Apache Maven e il 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 i framework Endpoints, consulta il tutorial Introduzione ai framework Endpoints 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.

   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. Make sure 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.

   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. Make sure that billing is enabled for your Google Cloud project.

6. Prendi nota dell'ID progetto Google Cloud perché ti servirà in seguito.

Installazione e configurazione del software necessario

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. Scaricare Apache Maven versione 3.3.9 o successive
   2. Installa e configura Maven per il tuo ambiente di sviluppo locale.

   Gradle

   • Installa 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 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 sull'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 gestirli con gcloud, consulta Gestire la gcloud CLI Cloud 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 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

Ottenere l'esempio di scheletro di Endpoints Frameworks

L'esempio di scheletro di Endpoints Frameworks versione 2.0 contiene gli script di compilazione necessari per Maven e Gradle. Contiene inoltre 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 di esempio per i framework Endpoints:

    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 utilizzare per iniziare a scrivere la tua API. Consulta l'esempio di echo per trovare un codice campione che ti aiuti a 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 App Engine Standard utilizzando Java 8.

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

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

Configurazione dei file di compilazione

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

Informazioni sulla configurazione minima

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

Maven

Dipendenze minime

Di seguito sono riportate 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 l'API.
• Per eseguire il deployment del progetto nell'ambiente standard di App Engine, devi disporre dell'SDK API App Engine Standard (appengine-api-sdk).
• Il pacchetto javax.servlet standard è necessario per creare un servlet.
• Il pacchetto standard javax.inject è necessario per supportare l' iniezione di dipendenze.

Applicare i plug-in

Per attivarli 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 la creazione di 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'
  }
}

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

Applicare i plug-in

I seguenti plug-in vengono applicati per attivarli nello script di compilazione 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 i passaggi di compilazione e di compilazione 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 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 l'API.
• L'SDK API App Engine Standard (appengine-api-sdk) è necessario per eseguire il deployment del progetto nell'ambiente standard di App Engine.
• Il pacchetto standard javax.servlet è necessario per creare un servlet.
• Il pacchetto standard javax.inject è necessario per supportare l' iniezione di dipendenze.

Definire il nome host per il servizio

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

Per configurare il nome host del servizio, devi aggiungere l'ID progetto Google Cloud ai file di compilazione. 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 utilizzato 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 sull'ID progetto Google Cloud. Ad esempio: def projectId = 'example-project-12345'

Configurazione del servlet Endpoints

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

Per ulteriori 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 di App Engine

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

• Scrivi e annota il codice dell'API di backend.
• Scopri di più sulle annotazioni.
• Aggiungi Gestione delle API.
• Esegui il deployment e il test dell'API.
• Scopri di più sui tipi di parametri e di valori restituiti supportati.