Nesta página, descrevemos como migrar um Cloud Endpoints versão 1.0 aplicativo para Endpoints Frameworks para App Engine em Java.
Vantagens
Existem vários benefícios no novo framework, incluindo:
- latência reduzida de solicitação;
- melhor integração com os recursos do App Engine (como domínios personalizados);
- suporte oficial para configurações do Guice;
- opcionalmente, novos recursos de gerenciamento de API.
O Endpoints Frameworks versão 2.0 não afeta as interfaces com a API. Os clientes atuais continuam a funcionar depois da migração sem alterações de código no lado do cliente.
Recursos e ferramentas excluídos no momento
Os recursos a seguir ainda não estão disponíveis. Se precisar de algum deles, envie uma solicitação de recurso.
- Protocolo JSON-RPC, obrigatório para clientes iOS legados. Para criar clientes iOS para a API do Endpoints Frameworks 2.0, recomenda-se usar a biblioteca de cliente Objective-C de APIs do Google para APIs REST (em inglês)
- ETags automáticos
- Campos de tipo automáticos
- Integração de ambiente de desenvolvimento integrado (IDE, na sigla em inglês)
- Respostas parciais de
fields
- Criação automática de método da API PATCH
Além disso, o suporte do Android Studio para Endpoints versão 1.0 ainda não é compatível com a versão 2.0.
Como migrar para o Endpoints Frameworks versão 2.0
O Endpoints Frameworks versão 2.0 foi migrado para os artefatos Maven no grupo com.google.endpoints
.
O JAR obrigatório de base está no artefato endpoints-framework
. Se quiser usar a configuração do Guice, adicione o artefato endpoints-framework-guice
.
Com as seguintes instruções, você aprenderá a migrar do Endpoints Frameworks versão 1.0 para o Endpoints Frameworks versão 2.0 usando um documento de descoberta:
- Faça o download e inicialize a CLI do Google Cloud.
- Execute os seguintes comandos:
- Verifique se a CLI gcloud tem autorização para acessar seus dados e serviços no Google Cloud:
gcloud auth login
- Use o Application Default Credentials:
gcloud auth application-default login
- Instale o componente
app-engine-java
do SDK do Google Cloud:gcloud components install app-engine-java
- Atualize para a versão mais recente do SDK Google Cloud e de todos os componentes:
gcloud components update
- Verifique se a CLI gcloud tem autorização para acessar seus dados e serviços no Google Cloud:
Migrar usando Maven ou Gradle:
Maven
- Remova a dependência legada, que é o
artefato
appengine-endpoints
: - Adicione a nova dependência do Endpoints Frameworks:
- Adicione o novo plug-in do Endpoints Frameworks e defina o nome do host para um documento de descoberta gerado:
- Adicione o novo plug-in do Maven para App Engine:
- Atualize o ponto de entrada da API no seu projeto
web.xml
arquivo:- Renomeie todas as ocorrências de
SystemServiceServlet
aEndpointsServlet
. - Substitua todas as ocorrências do caminho
/_ah/spi/
pelo novo caminho obrigatório/_ah/api/
.
Veja a seguir o conteúdo de
web.xml
antes e depois da migração:Antes da migração
web.xml
do Endpoints Frameworks versão 1.0:Depois da migração
web.xml
do Endpoints Frameworks versão 2.0: - Renomeie todas as ocorrências de
- Depois de modificar as dependências, limpe o projeto usando:
mvn clean
- É possível gerar um documento de descoberta:
Saiba mais sobre o Maven Endpoints Frameworks metas do plug-in.mvn endpoints-framework:discoveryDocs
- É possível implantar um projeto:
mvn appengine:deploy
Saiba mais sobre as metas do plug-in do Maven App Engine.
Gradle
- Remova a dependência legada, que é o artefato
appengine-endpoints
:compile group: 'com.google.appengine', name: 'appengine-endpoints', version: '+'
- Adicione a nova dependência do Endpoints Frameworks:
- Adicione os novos plug-ins do App Engine e do Endpoints Frameworks:
- Aplique os novos plug-ins do App Engine e do Endpoints Frameworks:
- Defina o endpoint de nome do host para documentos de descoberta gerados:
- Atualize o ponto de entrada da API no arquivo
web.xml
do projeto:- Renomeie todas as ocorrências de
SystemServiceServlet
aEndpointsServlet
. - Substitua todas as ocorrências do caminho
/_ah/spi/
pelo novo caminho obrigatório/_ah/api/
.
Veja a seguir o conteúdo de
web.xml
antes e depois da migração:Antes da migração
web.xml
do Endpoints Frameworks versão 1.0:Depois da migração
web.xml
do Endpoints Frameworks versão 2.0: - Renomeie todas as ocorrências de
- Depois de modificar as dependências, limpe o projeto usando:
gradle clean
- Gere um documento de descoberta usando:
Saiba mais sobre o Gradle Endpoints Frameworks tarefas de plug-ingradle endpointsDiscoveryDocs
- Para implantar um projeto, use:
gradle appengineDeploy
Saiba mais sobre as tarefas do Gradle App Engine Plugin.
Como usar o Guice para configurar o Endpoints Frameworks para Java
Se quiser usar Guice:
- Adicione a nova dependência do Endpoints Frameworks:
Maven
Gradle
- Declare um novo módulo que estenda o
EndpointsModule
e configure-o da seguinte maneira:
Como verificar uma nova implantação
Verifique se o novo framework está veiculando tráfego:
- Envie alguns pedidos para a nova implantação.
No console do Google Cloud, acesse a página Logging > Análise de registros.
Se as solicitações forem exibidas com caminhos que começam com
/_ah/api
, o Endpoints Frameworks versão 2.0 exibirá a API. Os registros não podem mostrar solicitações com caminhos que começam com/_ah/spi
. Elas indicam que o proxy do Endpoints Frameworks versão 1.0 ainda está exibindo solicitações.
Como adicionar gerenciamento da API do Endpoints
O Endpoints Frameworks versão 2.0 também permite ativar recursos de gerenciamento de API, incluindo:
- Gerenciamento de chaves de API
- Compartilhamento da API
- Autenticação de usuários
- Métricas da API
- Registros da API
Para começar a usar esses recursos, consulte Como adicionar o gerenciamento da API.
Resolver problemas
Nesta seção, você verá os comportamentos erráticos comuns durante a migração para o Endpoints Frameworks versão 2.0 e as soluções sugeridas.
A API retorna erros 404
, mas a API Explorer continua a listar as APIs corretamente
É obrigatória a remoção da antiga configuração do Endpoints Frameworks versão 1.0 na migração para o Endpoints Frameworks versão 2.0. Se a configuração antiga ainda estiver presente na configuração do aplicativo, o serviço do Endpoints continuará a tratá-lo como versão 1.0. É possível ver solicitações, nos registros do App Engine, enviadas para /_ah/spi
, que resultam em erros HTTP 404
enviados ao cliente.
Remova as seguintes linhas do arquivo
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>
Verifique se o arquivo
web.xml
contém o seguinte:<servlet-mapping> <servlet-name>EndpointsServlet</servlet-name> <url-pattern>/_ah/api/*</url-pattern> </servlet-mapping>
API com erros de reflexão
Apenas o artefato endpoints-framework
precisar estar no pacote do aplicativo. O JAR appengine-endpoints
antigo não é necessário. Implantar um aplicativo com os dois JARs pode causar erros de reflexão ou de tipo de ambiente de execução, como NoClassDefFoundError
, NoSuchMethodError
e ClassCastException
. Remova as seguintes linhas do arquivo de compilação, se estiverem presentes:
Maven
Gradle
compile group: 'com.google.appengine', name: 'appengine-endpoints', version: '+'
Além disso, se alguma das outras dependências precisar de versões mais antigas do Guava, esse erro também se manifestará como um método TypeToken
ausente. Use o Guava v19 ou o artefato endpoints-framework-all
, que controla as dependências.
Fontes da biblioteca de cliente não compilam
Se aparecerem erros, como method does not override or implement a method
from a supertype
ou cannot find symbol method setBatchPath(String)
, o aplicativo cliente provavelmente depende de uma versão antiga da biblioteca de cliente do Google para Java. É preciso garantir que o artefato google-api-client
seja 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 o aprimoramento do DataNucleus JPA/JDO
Maven
O novo plug-in do Maven para App Engine baseado na Google Cloud CLI não oferecer suporte a qualquer tipo de aprimoramento do Datanucleus. Se o projeto usa o suporte ao aprimoramento JDO ou JPA do Datanucleus do plug-in antigo, configure o plug-in do Maven para Datanucleus de terceiros separadamente ao migrar. Para saber mais, consulte os seguintes artigos:
Gradle
Se o projeto usa o aprimoramento de gradle-appengine-plugin
JPA/JDO
Datanucleus, é preciso configurar manualmente o aprimoramento do
Datanucleus depois de mudar para o novo plug-in Gradle
baseado na CLI gcloud.
Veja um exemplo do Stackoverflow (em inglês).