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

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. 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 Google Cloud CLI.
4. 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 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á-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.

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 o exemplo de eco para conferir um código de exemplo que vai 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ê precisará do SDK da API App Engine padrão (appengine-api-sdk) para implantar o projeto no ambiente padrão do App Engine.
• 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. 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.