Migrar para a versão 2.0 dos Cloud Endpoints Frameworks para o App Engine

Esta página descreve a migração de uma aplicação Cloud Endpoints versão 1.0 existente para os Endpoints Frameworks para App Engine em Java.

Nota: esta página refere-se aos Endpoints 1.0 como Endpoints Frameworks versão 1.0 e aos novos Endpoints Frameworks para o App Engine como Endpoints Frameworks versão 2.0.

Vantagens

A nova estrutura oferece várias vantagens, incluindo:

• Latência do pedido reduzida.
• Melhor integração com as funcionalidades do App Engine, como domínios personalizados.
• Apoio técnico oficial para configurações do Guice.
• Opcionalmente, novas funcionalidades de gestão de APIs.

A versão 2.0 do Endpoints Frameworks não afeta as interfaces da sua API. Os clientes existentes continuam a funcionar após a migração sem alterações ao código do lado do cliente.

Funcionalidades e ferramentas atualmente excluídas

As seguintes funcionalidades não estão disponíveis atualmente. Se precisar de alguma destas opções, envie um pedido de funcionalidade.

• Protocolo JSON-RPC, que é necessário para clientes iOS antigos. Para criar clientes iOS para a sua API do Endpoints Frameworks versão 2.0, recomendamos que use a biblioteca de cliente Objective-C das APIs Google para APIs REST.
• ETags automáticos
• Campos de tipo automáticos
• Integração de IDE
• fields respostas parciais
• Criação automática do método da API PATCH

Além disso, o suporte do Android Studio para a versão 1.0 dos Endpoints não é atualmente suportado para a versão 2.0.

Migrar para a versão 2.0 dos frameworks de Endpoints

A versão 2.0 dos Endpoints Frameworks foi movida para artefactos Maven no grupo com.google.endpoints. O JAR obrigatório de base encontra-se no artefacto endpoints-framework. Se quiser usar a configuração do Guice, adicione o artefacto endpoints-framework-guice.

As instruções seguintes fornecem um exemplo de como migrar da versão 1.0 dos Frameworks de Endpoints para a versão 2.0 dos Frameworks de Endpoints através de um documento de descoberta:

Nota: se estiver a usar a versão 1.0 dos Endpoints Frameworks com o Eclipse, converta primeiro o seu projeto num projeto Maven e, em seguida, siga as instruções do Maven abaixo.

1. Transfira e inicialize a CLI Google Cloud.
2. Execute os seguintes comandos:
   1. Certifique-se de que a CLI gcloud está autorizada a aceder aos seus dados e serviços em Google Cloud:

      gcloud auth login

   2. Usar credenciais padrão da aplicação:

      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 do Google Cloud e de todos os componentes:

      gcloud components update

Migre através do Maven ou do Gradle

Maven

1. Remova a dependência antiga, que é o artefacto appengine-endpoints:
   <dependency>
         <groupId>com.google.appengine</groupId>
         <artifactId>appengine-endpoints</artifactId>
         <version>1.9.53</version>
   </dependency>

2. Adicione a nova dependência do Endpoints Frameworks:
   <dependency>
       <groupId>com.google.endpoints</groupId>
       <artifactId>endpoints-framework</artifactId>
       <version>2.2.1</version>
   </dependency>

3. Adicione o novo plug-in Endpoints Frameworks e defina o nome de anfitrião para um documento de descoberta gerado:
   <plugin>
       <groupId>com.google.cloud.tools</groupId>
       <artifactId>endpoints-framework-maven-plugin</artifactId>
       <version>1.0.2</version>
       <configuration>
           <!-- plugin configuration -->
           <hostname>YOUR-PROJECT-ID.appspot.com</hostname>
       </configuration>
   </plugin>

4. Adicione o novo plugin do App Engine Maven:
   <plugin>
       <groupId>com.google.cloud.tools</groupId>
       <artifactId>appengine-maven-plugin</artifactId>
       <version>1.3.2</version>
       <configuration>
           <!-- deploy configuration -->
       </configuration>
   </plugin>

   Nota: o antigo plug-in do Maven do App Engine, com o grupo com.google.appengine, é incompatível com o plug-in dos Frameworks de Endpoints. Tem de usar a nova versão.
5. Atualize o ponto de entrada da API no ficheiro web.xml do seu projeto:
   • Mudar o nome de todas as ocorrências de SystemServiceServlet para EndpointsServlet
   • Substitua todas as ocorrências do caminho /_ah/spi/ pelo novo caminho obrigatório /_ah/api/
     

   A imagem seguinte mostra o conteúdo do web.xml antes e depois da migração:

   Antes da migração

   Endpoints Frameworks versão 1.0 web.xml:

   <servlet>
       <servlet-name>SystemServiceServlet</servlet-name>
       <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-class>
       <init-param>
           <param-name>services</param-name>
           <param-value>com.example.helloendpoints.Greetings</param-value>
       </init-param>
       <init-param>
           <param-name>restricted</param-name>
           <param-value>false</param-value>
       </init-param>
   </servlet>
   <servlet-mapping>
       <servlet-name>SystemServiceServlet</servlet-name>
       <url-pattern>/_ah/spi/*</url-pattern>
   </servlet-mapping>

   Após a migração

   Frameworks de Endpoints versão 2.0 web.xml:

   <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.helloendpoints.Greetings</param-value>
       </init-param>
       <init-param>
           <param-name>restricted</param-name>
           <param-value>false</param-value>
       </init-param>
   </servlet>
   <servlet-mapping>
       <servlet-name>EndpointsServlet</servlet-name>
       <url-pattern>/_ah/api/*</url-pattern>
   </servlet-mapping>

6. Depois de modificar as dependências, limpe o projeto:

   mvn clean

7. Pode gerar um documento de deteção:

   mvn endpoints-framework:discoveryDocs

   Saiba mais sobre os frameworks de pontos finais do Maven objetivos do plug-in.
8. Pode implementar um projeto:

   mvn appengine:deploy

   Saiba mais acerca dos objetivos do plug-in do Maven App Engine.

   Nota: quando migrar, tem de implementar numa nova versão do App Engine. Isto é feito automaticamente se não especificar uma versão. Consulte os problemas conhecidos.

Gradle

1. Remova a dependência antiga, que é o artefacto appengine-endpoints:

   compile group: 'com.google.appengine', name: 'appengine-endpoints', version: '+'

2. Adicione a nova dependência do Endpoints Frameworks:
   compile group: 'com.google.endpoints', name: 'endpoints-framework', version: '2.0.8'

3. Adicione os novos plug-ins do App Engine e dos Frameworks de pontos finais:
   buildscript {    // Configuration for building
     repositories {
       mavenCentral()
       jcenter()    // Bintray's repository - a fast Maven Central mirror & more
     }
     dependencies {
       // App Engine Gradle plugin
       classpath 'com.google.cloud.tools:appengine-gradle-plugin:1.3.3'
   
       // Endpoints Frameworks Gradle plugin
       classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:1.0.2'
     }
   }

4. Aplique os novos plug-ins do App Engine e dos Frameworks de pontos finais:
   apply plugin: 'com.google.cloud.tools.appengine'
   apply plugin: 'com.google.cloud.tools.endpoints-framework-server'

5. Defina o ponto final do nome de anfitrião para documentos de descoberta gerados:
   endpointsServer {
     // Endpoints Framework Plugin server-side configuration
     hostname = "YOUR-PROJECT-ID.appspot.com"
   }

6. Atualize o ponto de entrada da API no ficheiro web.xml do seu projeto:
   • Mudar o nome de todas as ocorrências de SystemServiceServlet para EndpointsServlet
   • Substitua todas as ocorrências do caminho /_ah/spi/ pelo novo caminho obrigatório /_ah/api/
     

   A imagem seguinte mostra o conteúdo do web.xml antes e depois da migração:

   Antes da migração

   Endpoints Frameworks versão 1.0 web.xml:

   <servlet>
       <servlet-name>SystemServiceServlet</servlet-name>
       <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-class>
       <init-param>
           <param-name>services</param-name>
           <param-value>com.example.helloendpoints.Greetings</param-value>
       </init-param>
       <init-param>
           <param-name>restricted</param-name>
           <param-value>false</param-value>
       </init-param>
   </servlet>
   <servlet-mapping>
       <servlet-name>SystemServiceServlet</servlet-name>
       <url-pattern>/_ah/spi/*</url-pattern>
   </servlet-mapping>

   Após a migração

   Frameworks de Endpoints versão 2.0 web.xml:

   <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.helloendpoints.Greetings</param-value>
       </init-param>
       <init-param>
           <param-name>restricted</param-name>
           <param-value>false</param-value>
       </init-param>
   </servlet>
   <servlet-mapping>
       <servlet-name>EndpointsServlet</servlet-name>
       <url-pattern>/_ah/api/*</url-pattern>
   </servlet-mapping>

7. Depois de modificar as dependências, limpe o projeto com o seguinte comando:

   gradle clean

8. Pode gerar um documento de descoberta através de:

   gradle endpointsDiscoveryDocs

   Saiba mais sobre as tarefas do plugin Gradle Endpoints Frameworks
9. Pode implementar um projeto através de:

   gradle appengineDeploy

   Saiba mais sobre as tarefas do plugin do Gradle App Engine.

   Nota: quando migrar, tem de implementar numa nova versão do App Engine. Isto é feito automaticamente se não especificar uma versão. Consulte os problemas conhecidos.

Usar o Guice para configurar o Endpoints Frameworks para Java

Se quiser usar o Guice:

1. Adicione a nova dependência do Guice do Endpoints Frameworks:

   Maven

   <dependency>
       <groupId>com.google.endpoints</groupId>
       <artifactId>endpoints-framework-guice</artifactId>
       <version>2.2.1</version>
   </dependency>

   Gradle

   compile 'com.google.endpoints:endpoints-framework-guice:2.0.9'

2. Declare um novo módulo que se estenda a EndpointsModule e configure-o da seguinte forma:
   public class EchoEndpointModule extends EndpointsModule {
     @Override
     public void configureServlets() {
       super.configureServlets();
   
       bind(ServiceManagementConfigFilter.class).in(Singleton.class);
       filter("/_ah/api/*").through(ServiceManagementConfigFilter.class);
   
       Map<String, String> apiController = new HashMap<String, String>();
       apiController.put("endpoints.projectId", "YOUR-PROJECT-ID");
       apiController.put("endpoints.serviceName", "YOUR-PROJECT-ID.appspot.com");
   
       bind(GoogleAppEngineControlFilter.class).in(Singleton.class);
       filter("/_ah/api/*").through(GoogleAppEngineControlFilter.class, apiController);
   
       bind(Echo.class).toInstance(new Echo());
       configureEndpoints("/_ah/api/*", ImmutableList.of(Echo.class));
     }
   }

Validar uma nova implementação

Pode verificar se a nova estrutura está a publicar tráfego:

1. Envie alguns pedidos para a nova implementação.

2. Na Google Cloud consola, aceda à página Registo > Explorador de registos.

   Aceda à página do Explorador de registos

3. Se os pedidos forem apresentados com caminhos que começam por /_ah/api, significa que a versão 2.0 dos Frameworks de Endpoints está a publicar a sua API. Os registos não devem apresentar pedidos com caminhos que comecem por /_ah/spi. Estes pedidos indicam que o proxy da versão 1.0 do Endpoints Frameworks ainda está a publicar pedidos.

Adicionar gestão da API Endpoints

A versão 2.0 do Endpoints Frameworks também lhe permite ativar funcionalidades de gestão de APIs, incluindo:

• Gestão de chaves da API
• Partilha de APIs
• Autenticação do utilizador
• Métricas da API
• Registos da API

Para começar a usar estas funcionalidades, consulte o artigo Adicionar gestão de APIs.

Resolução de problemas

Esta secção descreve comportamentos irregulares comuns ao migrar para a versão 2.0 dos Frameworks de Endpoints e as soluções sugeridas.

A API devolve erros 404, mas o Explorador de APIs continua a listar as APIs corretamente

Tem de remover a configuração da versão 1.0 do Endpoints Frameworks quando migrar para a versão 2.0 do Endpoints Frameworks. Se a configuração antiga ainda estiver presente na configuração da aplicação, o serviço Endpoints continua a tratar a app como uma app da versão 1.0. Pode ver pedidos nos registos do App Engine enviados para /_ah/spi, o que resulta em erros HTTP 404 enviados para o cliente.

1. Remova as seguintes linhas do ficheiro web.xml, se estiverem presentes:

   <servlet>
       <servlet-name>SystemServiceServlet</servlet-name>
       <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-class>
       <init-param>
           <param-name>services</param-name>
           <param-value>...</param-value>
       </init-param>
   </servlet>
   <servlet-mapping>
       <servlet-name>SystemServiceServlet</servlet-name>
       <url-pattern>/_ah/spi/*</url-pattern>
   </servlet-mapping>
   

2. Certifique-se de que o ficheiro web.xml contém o seguinte:

   <servlet-mapping>
       <servlet-name>EndpointsServlet</servlet-name>
       <url-pattern>/_ah/api/*</url-pattern>
   </servlet-mapping>
   

A API está a gerar erros de reflexão

Tem de incluir apenas o artefacto endpoints-framework na sua aplicação e não o JAR appengine-endpoints antigo. Se implementar uma aplicação com ambos os JARs, pode deparar-se com erros de reflexão ou erros de tipo de tempo de execução, como NoClassDefFoundError, NoSuchMethodError e ClassCastException. Remova as seguintes linhas do ficheiro de compilação, se estiverem presentes:

Maven

<dependency>
      <groupId>com.google.appengine</groupId>
      <artifactId>appengine-endpoints</artifactId>
      <version>1.9.53</version>
</dependency>

Gradle

compile group: 'com.google.appengine', name: 'appengine-endpoints', version: '+'

Além disso, se alguma das suas outras dependências depender de versões mais antigas do Guava, isto também pode manifestar-se como um método TypeToken em falta. Tem de garantir que usa o Guava v19 ou o artefacto endpoints-framework-all, que oculta dependências.

As origens da biblioteca de cliente não são compiladas

Se vir um erro como method does not override or implement a method from a supertype ou cannot find symbol method setBatchPath(String), é provável que a sua aplicação cliente dependa de uma versão antiga da biblioteca cliente Java da Google. Tem de garantir que o seu artefacto google-api-client é 1.23.0 ou superior.

Maven

<dependency>
    <groupId>com.google.api-client</groupId>
    <artifactId>google-api-client</artifactId>
    <version>1.23.0</version>
</dependency>

Gradle

compile group: 'com.google.api-client', name: 'google-api-client', version: '1.23.0'

Problemas com a melhoria do Datanucleus JPA/JDO

Maven

O novo plug-in do App Engine Maven baseado na CLI do Google Cloud não suporta o melhoramento do Datanucleus de nenhum tipo. Se o seu projeto usar o suporte de melhoramento do Datanucleus JDO ou JPA do plug-in antigo, tem de configurar o plug-in Maven do Datanucleus de terceiros separadamente quando fizer a migração. Consulte o seguinte para mais informações:

• Instruções do JDO
• Instruções da JPA

Gradle

Se o seu projeto usar o melhoramento do gradle-appengine-pluginJPA/JDO Datanucleus, tem de configurar manualmente o melhoramento do Datanucleus depois de mudar para o novo plug-in do Gradle baseado na CLI gcloud. Veja um exemplo do Stackoverflow.