Como configurar um ambiente de desenvolvimento

Nesta página, descrevemos como configurar seu ambiente de desenvolvimento para criar e implantar sua API de back-end usando o Cloud Endpoints Framework para o ambiente padrão do App Engine. Nesta página, usamos o exemplo de código da estrutura do Endpoints Frameworks versão 2.0 para explicar o software e os componentes básicos necessários para começar.

Você pode usar o endpoints-skeleton-archetype ou a hello-endpoints-archetype descrita em Como usar o Apache Maven e o plug-in do App Engine (baseado na Google Cloud CLI) para criar um novo projeto do Endpoints Frameworks versão 2.0.

Para entender melhor as etapas necessárias para implantar uma API de exemplo usando o Endpoints Frameworks, consulte o tutorial Primeiros passos com o Endpoints Frameworks no App Engine.

Antes de começar

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. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

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

   Go to project selector

5. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

6. Anote o ID do projeto do Google Cloud porque vai precisar dele depois.

Como instalar e configurar o software necessário

1. Se o Java 8 não estiver instalado, faça o download do Java Development Kit (JDK) no site da Oracle e instale-o.
2. Instale o Maven ou o Gradle:

   Maven

   1. Faça o download do Apache Maven versão 3.3.9 ou mais recente.
   2. Instale e configure o Maven para seu ambiente de desenvolvimento local.

   Gradle

   • Instale o Gradle (link em inglês).
3. Faça o download e inicialize a CLI do Google Cloud.
4. Execute os seguintes comandos:
   1. Verifique se a CLI gcloud tem autorização para acessar seus dados e serviços no Google Cloud:

      gcloud auth login

   2. Use o Application Default Credentials:

      gcloud auth application-default login

   3. Instale o componente app-engine-java do SDK Google Cloud:

      gcloud components install app-engine-java

   4. Atualize para a versão mais recente do SDK Google Cloud e de todos os componentes:

      gcloud components update

5. Crie um aplicativo do App Engine:
   1. Defina o projeto padrão para seu ID do projeto do Google Cloud:

      gcloud config set project YOUR_PROJECT_ID

      Substitua YOUR_PROJECT_ID pelo ID do projeto do Google Cloud. Se você tiver outros projetos do Google Cloud e quiser usar gcloud para gerenciá-las, consulte Gerenciamento CLI gcloud CLI.

   2. Selecione a região em que você quer criar o aplicativo do App Engine. Consulte uma lista das regiões em Localizações do App Engine.
   3. Crie um aplicativo do App Engine. Substitua YOUR_PROJECT_ID pelo ID do projeto do Google Cloud e YOUR_REGION pela região em que você quer que o aplicativo do App Engine seja criado.

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

Como conseguir o exemplo de estrutura do Endpoints Frameworks

O exemplo de estrutura do Endpoints Frameworks versão 2.0 contém os scripts de criação necessários para o Maven e o Gradle. Ele também contém os arquivos necessários para começar a criar sua primeira API.

1. Clone o repositório de amostra na sua máquina local:

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

2. Mude para o diretório que contém o exemplo de estrutura do Endpoints Frameworks:

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

   O exemplo tem a seguinte estrutura de diretórios:

   

   • MyApi.java contém uma classe vazia que pode ser usada para começar a escrever sua API. Consulte a exemplo de echo um exemplo de código para ajudar você a começar.

   • web.xml é um arquivo padrão usado para configurar um servlet.

   • appengine-web.xml define as informações necessárias para implantar a API no ambiente padrão do App Engine usando o Java 8.

   • pom.xml contém informações do projeto e da configuração usados pelo Maven para criar o e implantar a API no App Engine.

   • build.gradle contém informações do projeto e da configuração usados pelo Gradle para criar a e implantar a API no App Engine.

Como configurar os arquivos de criação

Nesta seção, você verá a descrição dos arquivos pom.xml do Maven e build.gradle do Gradle incluídos no código de exemplo. Os arquivos de criação estão prontos para dar início à criação da API, mas não para inserir o ID do projeto do Google Cloud para que possa ser usado no nome do host.

Sobre a configuração mínima

Nesta seção, descrevemos a configuração mínima necessária em seu arquivo de criação.

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

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

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

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

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

Como definir o nome do host do serviço

O Endpoints Frameworks usa nomes compatíveis com DNS para identificar os serviços de maneira exclusiva. Como os IDs de projetos do Google Cloud têm a garantia de serem globalmente exclusivos, use o ID do projeto do Google Cloud como parte do nome de serviço da sua API.

É necessário adicionar o ID do projeto do Google Cloud aos arquivos de criação para configurar o nome de host do serviço. A lista deve estar no seguinte formato:

YOUR_PROJECT_ID.appspot.com

Quando você implanta a API no App Engine, uma entrada DNS com um nome no formato YOUR_PROJECT_ID.appspot.com é criada automaticamente. O nome do host é o nome do serviço do Cloud Endpoints e o nome de domínio usado para enviar solicitações à API.

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

// 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"
}

Como configurar o servlet do Endpoints

O servlet do Endpoints processa as solicitações recebidas e as encaminha ao serviço de back-end em execução no App Engine. O servlet do Endpoints é necessário para que a API seja gerenciada pelo Endpoints.

Para mais informações sobre web.xml, consulte o Descritor de implantação: 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>

Como configurar sua implantação do App Engine

O arquivo appengine-web.xml é usado para definir a configuração do ambiente padrão do App Engine quando a API é implantada. Consulte a referência de appengine-web.xml para mais informações.

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

A seguir

• Escreva e anote o código da API de back-end.
• Saiba mais sobre anotações.
• Adicione gerenciamento de API.
• Implemente e teste sua API.
• Saiba mais sobre tipos de retorno e parâmetro aceitos.