Configura un entorno de desarrollo

En esta página, se describe cómo configurar tu entorno de desarrollo para compilar y, luego, implementar tu API de backend con Cloud Endpoints Frameworks para el entorno estándar de App Engine. En esta página, se usa el muestra de código Esqueleto de Endpoints Frameworks versión 2.0 para explicar el software básico y los componentes necesarios para comenzar.

Puede que desees usar el endpoints-skeleton-archetype o el hello-endpoints-archetype que se describe en Usar Apache Maven y el complemento de App Engine (basado en Google Cloud CLI) para crear un nuevo proyecto de Endpoints Frameworks versión 2.0.

Si deseas comprender mejor los pasos necesarios para implementar una API de muestra con Endpoints Frameworks, consulta el isntructivoComienza a usar marcos de trabajo de Endpoints para Java .

Antes de comenzar

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. Toma nota del ID del proyecto de Google Cloud, ya que lo necesitarás más adelante.

Instala y configura el software obligatorio

1. Si no tienes Java 8 instalado, descarga el Java Development Kit (JDK) desde la página de Oracle y, luego, instálalo.
2. Instala Maven o Gradle:

   Maven

   1. Descarga la versión 3.3.9 o superior de Apache Maven
   2. Instala y configura Maven para tu entorno de desarrollo local.

   Gradle

   • Instala Gradle.
3. Descarga e inicializa Google Cloud CLI.
4. Ejecuta los siguientes comandos:
   1. Asegúrate de que gcloud CLI esté autorizada para acceder a tus datos y servicios en Google Cloud:

      gcloud auth login

   2. Usa las credenciales predeterminadas de la aplicación:

      gcloud auth application-default login

   3. Instala el componente app-engine-java del SDK de Google Cloud:

      gcloud components install app-engine-java

   4. Actualiza a la versión más reciente del SDK de Google Cloud y de todos los componentes:

      gcloud components update

5. Crea una aplicación de App Engine:
   1. Establece tu ID de proyecto de Google Cloud como predeterminado:

      gcloud config set project YOUR_PROJECT_ID

      Reemplaza YOUR_PROJECT_ID con tu ID del proyecto de Google Cloud. Si tienes otros proyectos de Google Cloud y quieres usar gcloud para administrarlos, consulta Cómo gcloud CLI de gcloud.

   2. Selecciona la región en la que deseas crear tu app de App Engine. Consulta Ubicaciones de App Engine para obtener una lista de regiones.
   3. Crea una aplicación de App Engine. Reemplaza YOUR_PROJECT_ID por tu ID del proyecto de Google Cloud y YOUR_REGION por la región en la que deseas crear la aplicación de App Engine.

        gcloud app create \
        --project=YOUR_PROJECT_ID \
        --region=YOUR_REGION

Obtén el esqueleto de muestra de Endpoints Frameworks

El esqueleto de muestra de Endpoints Frameworks versión 2.0 contiene las secuencias de comandos de compilación necesarias para Maven y Gradle. Además, contiene los archivos necesarios para comenzar a crear tu primera API.

1. Clona el repositorio de muestra en tu máquina local:

    git clone https://github.com/GoogleCloudPlatform/java-docs-samples
   

2. Cambia al directorio que contiene el esqueleto de muestra de Endpoints Frameworks:

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

   La muestra tiene la siguiente estructura de directorios:

   

   • MyApi.java contiene una clase vacía que puedes usar para comenzar a escribir tu API. Consulta el ejemplo de eco para obtener un código de muestra que te ayude a comenzar.

   • web.xml es un archivo estándar que se usa para configurar un servlet.

   • appengine-web.xml define la información que se requiere para implementar la API en el entorno estándar de App Engine con Java 8.

   • pom.xml contiene la información de proyecto y configuración que usa Maven para compilar el proyecto y, luego, implementar la API en App Engine.

   • build.gradle contiene información de proyecto y configuración que usa Gradle para compilar el proyecto y, luego, implementar la API en App Engine.

Configura los archivos de compilación

En esta sección, se describen los archivos Maven pom.xml y Gradle build.gradle incluidos en el código de muestra. Los archivos de compilación están listos para que puedas comenzar a crear tu API; solo tienes que ingresar tu ID del proyecto de Google Cloud para que pueda usarse en el nombre de host.

Acerca de la configuración mínima

En esta sección, se describe la configuración mínima necesaria en tu archivo de compilación.

Maven

Dependencias mínimas

A continuación, se muestran las dependencias mínimas requeridas en tu pom.xml para comenzar:

<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 dependencia endpoints-framework contiene las clases necesarias para crear tu API.
• Necesitas el SDK de API de App Engine Standard (appengine-api-sdk) para implementar tu proyecto en el entorno estándar de App Engine.
• Se necesita el paquete estándar javax.servlet para compilar un servlet.
• Se necesita el paquete estándar javax.inject para admitir la inyección de dependencias.

Aplica complementos

Se aplican los siguientes complementos para habilitarlos:

<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 extiende el complemento java para agregar compatibilidad a fin de ensamblar una aplicación web.
• El appengine-maven-plugin es necesario para ejecutar la API en App Engine.
• endpoints-framework-maven-plugin proporciona tareas y configuraciones para compilar proyectos de Endpoints Frameworks.

Gradle

Dependencias de complementos

A continuación, se muestran los complementos necesarios para compilar tu 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'
  }
}

• El Complemento de Maven para Endpoints Framework se usa a fin de generar un documento de OpenAPI y bibliotecas cliente.
• Necesitas el complemento de Gradle para App Engine a fin de implementar tu proyecto en App Engine.

Aplica complementos

Los siguientes complementos se aplican para habilitarlos en tu secuencia de comandos de compilación de Gradle:

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

• El complemento java agrega pasos de compilación específicos de Java a tu proyecto.
• El complemento war extiende el complemento java para agregar compatibilidad a fin de ensamblar una aplicación web.
• El complemento endpoints-framework-server proporciona compatibilidad del lado del servidor con el complemento de Gradle para Endpoints Frameworks.
• El complemento appengine es necesario para ejecutar la API en App Engine.

Dependencias del proyecto

El proyecto usa las siguientes dependencias:

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 dependencia endpoints-framework contiene las clases necesarias para crear tu API.
• El SDK de API de App Engine Standard (appengine-api-sdk) es necesario para implementar tu proyecto en el entorno estándar de App Engine.
• Se necesita el paquete estándar javax.servlet para compilar un servlet.
• Se necesita el paquete estándar javax.inject para admitir la inyección de dependencias.

Define el nombre de host para tu servicio

Endpoints Frameworks usa nombres compatibles con DNS para identificar los servicios de forma exclusiva. Dado que se garantiza que los ID del proyecto de Google Cloud son únicos a nivel global, debes usar tu ID del proyecto de Google Cloud como parte del nombre de servicio de la API.

Debes agregar tu ID del proyecto de Google Cloud a los archivos de compilación a fin de configurar el nombre de host para tu servicio. El nombre de host debe tener el siguiente formato:

YOUR_PROJECT_ID.appspot.com

Cuando implementas la API en App Engine, se crea una entrada DNS con un nombre con el formato YOUR_PROJECT_ID.appspot.com de forma automática. El nombre de host es el nombre del servicio de Cloud Endpoints y el nombre de dominio que usas para enviar solicitudes a tu 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>

En el campo hostname, reemplaza YOUR_PROJECT_ID por el ID de tu proyecto de 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"
}

Establece la variable projectID en tu ID del proyecto de Google Cloud. Por ejemplo: def projectId = 'example-project-12345'

Configura el servlet de Endpoints

El servlet de Endpoints controla las solicitudes entrantes y las reenvía al servicio de backend que se ejecuta en App Engine. El servlet de Endpoints es necesario para que Endpoints pueda administrar tu API.

Para obtener más información acerca de web.xml, consulta El descriptor de implementación: 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>

Configura tu implementación de App Engine

El archivo appengine-web.xml se usa para definir la configuración del entorno estándar de App Engine cuando se implementa la API. Consulta la referencia de appengine-web.xml para obtener más información.

<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>

¿Qué sigue?

• Escribir y anotar el código de tu API de backend.
• Obtén más información sobre las anotaciones.
• Agrega la administración de la API.
• Implementar y probar una API.
• Obtén más información sobre los tipos de parámetros y resultados compatibles.