Aviso: nos próximos meses, vamos reorganizar o site de documentação do App Engine para facilitar a localização de conteúdo e o alinhamento com o restante dos produtos do Google Cloud. O mesmo conteúdo estará disponível, mas a navegação agora corresponderá ao restante dos produtos do Cloud.

Como migrar para o plug-in Maven baseado na CLI gcloud

Se você já usou o plug-in baseado no SDK do App Engine para Java (com.google.appengine.appengine-maven) e quiser passar para a nova Google Cloud CLI, migre para o plug-in (com.google.cloud.tools.appengine-maven) baseado em CLI gcloud.

Benefícios do plug-in baseado na CLI gcloud

O upgrade para o novo plug-in oferece os seguintes benefícios:

Usa as mesmas credenciais de autenticação que todos os outros comandos baseados na CLI gcloud, que são provenientes do fluxo padrão gcloud auth login. .
É compatível com o ambiente flexível do App Engine.
Atualiza o servidor de desenvolvimento local automaticamente como parte do fluxo padrão de atualização da CLI gcloud.
É compatível com a implantação das configurações de serviço do App Engine (cron, filas, DoS, expedição), independentemente do serviço.

Diferenças significativas

Antes de migrar, esteja ciente destas diferenças significativas:

Dependência da CLI gcloud: O plug-in antigo pode ser executado sem dependências de ambiente local específicas, além do Java, mas o novo plug-in exige a instalação da CLI gcloud.
Sem geração de documentos de descoberta do Endpoints: O novo plug-in não gera documentos de descoberta do Endpoints. Esse recurso está disponível em um plug-in diferente. A execução do back-end do Endpoints não exige mais a geração desse arquivo em etapas de criação, já que agora ele é gerado pelo servidor no ambiente de execução. Use o novo plug-in somente se você precisar gerar bibliotecas de cliente para iOS ou Android, por exemplo. Saiba mais sobre os novos plug-ins no guia Como migrar para o Endpoints Frameworks para App Engine.
O formato de arquivo EAR não é mais aceito: O novo plug-in não é mais compatível com o formato de arquivo EAR para executar e implantar vários serviços ao mesmo tempo.
Novo comando de implantação: O plug-in antigo chama o comando appcfg para implantar aplicativos, enquanto o novo plug-in faz a implantação usando a nova CLI do gcloud.

Tarefas de aprimoramento de JPA/JDO do Datanucleus não estão mais incluídas: O novo plug-in não é compatível com qualquer tipo de aprimoramento do Datanucleus. Se o projeto precisar do suporte ao aprimoramento de JDO ou JPA Datanucleus do plug-in antigo, será necessário configurar separadamente o plug-in Maven do Datanucleus terceirizado (instruções para JDO ou instruções para JPA) ao fazer a migração.

O uso de arquivos de configuração YAML é aceito, mas não XML.

Como migrar para o novo plug-in

Para migrar para o novo plug-in, faça o seguinte:

Adicione o plug-in baseado na CLI gcloud baseado no arquivo pom.xml.

<build>
    <plugins>
       [...]
          <plugin>
            <groupId>com.google.cloud.tools</groupId>
            <artifactId>appengine-maven-plugin</artifactId>
            <version>2.7.0</version>
            <configuration>
                <projectId>your-project-ID-goes-here</projectId>
                <version>1</version>
            </configuration>
        </plugin>
       [...]
    </plugins>
</build>

Especifique ID do projeto do Google Cloud de destino e o serviço e a versão na configuração do plug-in. As novas ferramentas ignoram os elementos do aplicativo e da versão no arquivo appengine-web.xml.
Teste a nova configuração executando e implantando o aplicativo da seguinte maneira:
1. Execute o aplicativo usando o nome totalmente qualificado do plug-in:
```
  mvn com.google.cloud.tools:appengine-maven-plugin:run
```
2. Implante o aplicativo usando o nome totalmente qualificado do plug-in:
```
  mvn com.google.cloud.tools:appengine-maven-plugin:deploy
```
  Atribua um namespace à invocação de meta do plug-in se você ainda tiver o antigo plug-in appengine no pom.xml.

Se você tiver uma configuração mais personalizada, encontre sinalizações equivalentes de preparo, execução local e implantação no novo plug-in.

Depois de confirmar que está tudo funcionando como esperado, remova o com.google.appengine appengine-maven-plugin do pom.xml e os elementos do aplicativo e da versão do arquivo appengine-web.xml.

Agora é possível invocar as metas do novo plug-in usando a notação abreviada:

mvn package appengine:deploy

Como migrar configurações de multisserviço baseadas em EAR

Com o novo plug-in, você não agrega os serviços a um pacote EAR. Em vez disso, quando você quiser testar os serviços localmente, será possível executar cada serviço individualmente ou seguir etapas extras para executar vários serviços com apenas um comando. Quando estiver pronto para implantar seus serviços, implante-os individualmente ou, dependendo de como você organizou o projeto, implante todos os serviços com um único comando.

Para executar vários serviços localmente, atualize o appengine-maven-plugin com a lista de serviços que você quer executar. Se os serviços compartilharem um POM pai, será possível adicionar essa lista ao appengine-maven-plugin no POM pai. Caso contrário, adicione a lista ao appengine-maven-plugin no POM do serviço padrão.

Para adicionar a lista de serviços ao appengine-maven-plugin:

Para cada context-root no application.xml do pacote EAR, adicione um elemento service ao appengine-maven-plugin.

Em cada elemento service, especifique o subdiretório target que contém o WAR expandido do serviço.

Exemplo:

<plugin>
    <groupId>com.google.cloud.tools</groupId>
    <artifactId>appengine-maven-plugin</artifactId>
    <version>2.7.0</version>
    <configuration>
        <deploy.projectId>your-project-name</deploy.projectId>
        <deploy.version>your-project-version</deploy.version>
        <services>
            <!-- for each service in your EARs application.xml -->
            <service>
                ${project.parent.basedir}/service-name/target/service-name-${project.version}
            </service>
            <service>
                ${project.parent.basedir}/another-service/target/another-service-${project.version}
            </service>
        </services>
    </configuration>
</plugin>

Se a estrutura do diretório for assim:

 ~/my-ear/default-service/
 ~/my-ear/another-service/

Então, os nomes de caminho nos elementos service precisam ser renderizados da seguinte forma:

 <service>~/my-ear/default-service/target/default-service-1.0-SNAPSHOT</service>
 <service>~/my-ear/another-service/target/another-service-1.0-SNAPSHOT</service>

Confirme que a nova configuração funciona executando o seguinte comando no diretório de serviços padrão:
```
mvn package appengine:run
```
Depois de verificar que o serviço padrão está executando todos os serviços localmente, remova o pacote EAR por completo.

Se o diretório raiz do projeto contiver apenas os serviços, implante todos esses serviços com um comando mvn appengine:deploy. Primeiro, você precisa adicionar o appengine-maven-plugin ao arquivo pom.xml pai. Quando você executa mvn appengine:deploy, o comando itera em cada um dos serviços do projeto para localizar os arquivos de configuração e implantar cada serviço.

Comandos Maven baseados em SDK do App Engine vs. Comandos Maven baseados na CLI gcloud

A tabela a seguir mostra as diferentes maneiras de invocar o plug-in Maven, dependendo se você usa o plug-in Maven com base no SDK do App Engine ou com base no CLI gcloud.

Ação	Baseado do SDK do App Engine	Baseado na CLI do gcloud
Executar o aplicativo localmente	`appengine:devserver`	`appengine:run`
Implantar um novo aplicativo, versão ou serviço.	`appengine:update`	`appengine:deploy` ou `appengine:deployAll`
Definir a versão padrão do aplicativo.	`appengine:set_default_version`	gcloud app services set-traffic ou gcloud app versions migrate
Atualizar os cron jobs do aplicativo.	`appengine:update_cron`	`appengine:deployCron`
Atualizar a configuração de expedição do aplicativo.	`appengine:update_dispatch`	`appengine:deployDispatch`
Atualizar a configuração da proteção contra DoS do aplicativo.	`appengine:update_dos`	`appengine:deployDos`
Atualizar as definições da fila de tarefas do aplicativo.	`appengine:update_queues`	`appengine:deployQueue`
Atualizar os índices do armazenamento de dados.	`appengine:update_indexes`	`appengine:deployIndex`
Excluir os índices não utilizados do aplicativo.	`appengine:vacuum_indexes`	limpeza de índices do armazenamento de dados da gcloud
Iniciar a versão especificada.	`appengine:start_module_version`	gcloud app versions start
Parar a versão especificada.	`appengine:stop_module_version`	gcloud app versions stop
Reverter uma atualização em andamento.	`appengine:rollback` Também é possível migrar o tráfego de volta para uma versão anterior	gcloud app versions start, gcloud app versions stop ou use gcloud app services set-traffic para migrar de volta para uma versão anterior.