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.

É possível usar o endpoints-skeleton-archetype ou o hello-endpoints-archetype descritos 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

Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

Acessar o seletor de projetos

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

No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

Acessar o seletor de projetos

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

Anote o ID do projeto do Google Cloud porque ele será necessário posteriormente.

Como instalar e configurar o software necessário

Se o Java 8 não estiver instalado, faça o download do Java Development Kit (JDK) no site da Oracle e instale-o.
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.
Faça o download e inicialize a Google Cloud CLI.
Execute os seguintes comandos:
1. Verifique se a CLI gcloud está autorizada a 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
```
Crie um aplicativo do App Engine:
1. Defina o projeto padrão como o 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á-los, consulte Como gerenciar configurações da CLI gcloud.
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.

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

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

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. No exemplo echo (link em inglês), consulte o código de amostra que 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 projeto e implantar a API no App Engine.
- build.gradle contém informações do projeto e da configuração usados pelo Gradle para criar o projeto 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.

Maven

Dependências mínimas

A seguir, mostramos as dependências mínimas necessárias no pom.xml para começar:

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

A dependência endpoints-framework contém as classes necessárias para criar sua API.
Você precisa do <atrack-type="tasks" l10n-attrs-original-order="href,track-type,track-name,track-metadata-position" l10n-encrypted-href="8uk1g2YxVmQFExiHWQoDVLU3uURKQq2GHK/Q1ZkBJNo=" track-metadata-position="body" track-name="internalLink"> SDK padrão da API App Engine (appengine-api-sdk) para implantar seu projeto no ambiente padrão do App Engine..</atrack-type="tasks">
O pacote javax.servlet padrão é necessário para criar um servlet.
O pacote javax.inject padrão é necessário para compatibilidade com a injeção de dependência.

Aplicar plug-ins

Os plug-ins a seguir são aplicados para ativá-los:

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

O maven-war-plugin estende o plug-in java para acrescentar a compatibilidade para a montagem de um aplicativo da Web.
O plug-in appengine-maven-plugin é necessário para executar a API no App Engine.
O endpoints-framework-maven-plugin fornece tarefas e configurações para criar projetos do Endpoints Frameworks.

Gradle

Dependências de plug-ins

A seguir, veja os plug-ins necessários para criar sua 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'
  }
}

O plug-in Gradle do Endpoints Frameworks é usado para gerar um documento OpenAPI e gerar bibliotecas de cliente.
Você precisa do plug-in Gradle do App Engine para implantar seu projeto no App Engine.

Aplicar plug-ins

Os plug-ins a seguir são aplicados para serem ativados no script de criação do Gradle:

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

O plug-in java adiciona etapas de compilação e criação específicas do Java ao projeto.
O plug-in war estende o plug-in java para acrescentar a compatibilidade para a montagem de um aplicativo da Web.
O plug-in endpoints-framework-server fornece compatibilidade do servidor para o plug-in Gradle do Endpoints Frameworks.
O plug-in appengine é necessário para executar a API no App Engine.

Dependências do projeto

As dependências a seguir são usadas pelo projeto:

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

A dependência endpoints-framework contém as classes necessárias para criar sua API.
O SDK da API App Engine padrão (appengine-api-sdk) é necessário para implantar seu projeto no ambiente padrão do App Engine.
O pacote javax.servlet é necessário para criar um servlet.
O pacote javax.inject padrão é necessário para compatibilidade com a injeção de dependência.

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.

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>

No campo hostname substitua YOUR_PROJECT_ID pelo ID do projeto do 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"
}

Defina a variável projectID para seu ID do projeto do Google Cloud. Por exemplo: def projectId = 'example-project-12345'

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. Para mais informações, consulte a referência de 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>