O SDK do App Engine inclui um terminal de comando para interagir com o App Engine. Você pode usar esse terminal para carregar novas versões do código, configurações e arquivos estáticos de sua aplicação para o App Engine. Você pode também gerenciar índices de banco de dados e baixar dados de log.
Carregando a aplicação
Se estiver usando o Eclipse e o Plugin do Google, pode carregar sua aplicação diretamente do Eclipse. Para carregar a aplicação, clique no botão deploy da barra de ferramenta do App Engine. Para obter mais informações, veja Google Eclipse Plugin.
Você pode também carregar a sua aplicação a partir da linha de comando. Para usar outras características desse recursos, como obtenção dos arquivos de log, você deve executar o comando a partir do terminal. O comando a ser executado está no diretório appengine-java-sdk/bin/ do SDK.
Se estiver usando o Windows, o comando é o seguinte:
appengine-java-sdk\bin\appcfg.cmd [options] <action> <war-location>
Se estiver usando MAc OS X ou Linux, o comando é o seguinte:
./appengine-java-sdk/bin/appcfg.sh [options] <action> <war-location>
O comando pega o nome de uma ação a ser executada e a localização do diretório WAR de sua aplicação como argumentos.
Para carregar uma aplicação, use a ação update, como a seguir:
./appengine-java-sdk/bin/appcfg.sh update myapp/war
Esses comandos são scripts de empacotadores específicos do Sistema operacional que executam a class Java com.google.appengine.tools.admin.AppCfg do diretório appengine-java-sdk/lib/appengine-tools-api.jar.
Atualizando índices
Quando você carrega uma aplicação usando a ação update, a atualização inclui o índice de configurações da aplicação (os arquivos datastore-indexes.xml e generated/datastore-indexes-auto.xml). Se o índice da configuração define um índice que não existe ainda no App Engine, o App Engine cria o novo índice. Dependendo da quantidade de dados contida na base de dados que precise ser mencionada no novo índice, processo de criação do índice pode levar algum tempo. Se a aplicação executar uma consulta que necessite de um índice que não tenha finalizado sua criação, a consulta retornará um erro.
Para prevenir isso, precisa garantir que a nova versão da aplicação que necessite de um novo índice não seja a versão ativa da aplicação até o termino da criação. Uma maneira de fazer isso é dar a aplicação um novo número no appengine-web.xml sempre que você adicionar ou alterar um índice da aplicação. A aplicação é carregada como uma nova versão, e não se tornará a versão padrão automaticamente. Quando os seus índices tiverem terminado de serem criados, pode alterar a versão padrão para a nova usando a seção “Versions” do Admin Console.
Outra maneira de garantir que novos índices sejam construídos antes que a nova aplicação se torne ativa é carregar o índice separadamente antes de carregar a aplicação. Para carregar apenas o índice, use a ação update_indexes:
./appengine-java-sdk/bin/appcfg.sh update_indexes myapp/war
Você pode checar o status dos índices da aplicação a partir da seção “Indexes” do Admin Console.
Apagando índices não utilizados
Quando você alterar ou remover um índice da configuração, o índice original não será apagado do App Engine automaticamente. Isso lhe dá a oportunidade de deixar uma versão antiga da aplicação rodando enquanto novos índices estão sendo construídos, ou reverter para a versão antiga imediatamente se um problema for descoberto com uma nova versão.
Quando você estiver certo que um índice antigo não é mais necessário, pode apaga-lo do App Engine usando a ação vacuum_indexes:
./appengine-java-sdk/bin/appcfg.sh vacuum_indexes myapp/war
Esse comando apaga todos os índices da aplicação que não são mencionados nas versões locais de datastore-indexes.xml e generated/datastore-indexes-auto.xml.
Gerenciando a fila de tarefas
Você define e configura a fila de tarefas em um arquivo chamado queue.xml. Você pode carregar esse arquivo de configuração separadamente do resto da aplicação através do uso do comando update_queues:
./appengine-java-sdk/bin/appcfg.sh update_queues myapp/war
appcfg update também carregará o arquivo de configuração da fila de tarefas se o arquivo existir.
Para mais detalhes sobre esse assunto, veja a documentação sobre a Fila de tarefas.
Gerenciando a proteção contra DoS
Você configura a proteção contra DoS para uma aplicação em um arquivo chamado dos.xml. Você pode carregar esse arquivo de configuração separadamente do resto da aplicação pelo uso do comando update_dos:
./appengine-java-sdk/bin/appcfg.sh update_dos myapp/war
appcfg update também carregará a proteção contra DoS se o arquivo existir.
Gerenciando o agendamento de tarefas
O App Engine suporta agendamento de tarefas (conhecido como cron jobs). Você especifica essas tarefas em um arquivo chamado cron.xml, e atualiza essas tarefas usando o comando update_cron:
./appengine-java-sdk/bin/appcfg.sh update_cron myapp/war
appcfg update também atualizará a especificação dos cron jobs se o arquivo existir.
Você pode verificar também a configuração de seu arquivo a partir da linha de comando usando a ação cron_info:
./appengine-java-sdk/bin/appcfg.sh cron_info myapp/war
Para mais detalhes sobre cron jobs, veja a documentação sobre Cron Jobs.
Baixando a aplicação
Você pode baixar a aplicação pela execução de appcfg.sh com a ação download_app com a ferramenta de linha de comando do SDK do Java:
./appengine-java-sdk/bin/appcfg.sh download_app -A <your_app_id> -V <your_app_version> <output-dir>
Esse comando baixa sua aplicação compilada no WAR com o arquivo WAR que foi carregado mais recentemente.
A saída desse comando deve apresentar os seguintes resultados se o comando for concluído com sucesso:
0% Fetching files... 0% [1/13] WEB-INF/lib/appengine-api-labs-1.2.6.jar 7% [2/13] WEB-INF/appengine-web.xml 14% [3/13] WEB-INF/lib/datanucleus-jpa-1.1.5.jar 21% [4/13] WEB-INF/lib/datanucleus-core-1.1.5.jar 28% [5/13] WEB-INF/lib/datanucleus-appengine-1.0.3.jar 35% [6/13] WEB-INF/lib/jdo2-api-2.3-eb.jar 42% [7/13] WEB-INF/classes/com/example/MyServlet.class 50% [8/13] WEB-INF/lib/geronimo-jpa_3.0_spec-1.1.1.jar 64% [9/13] WEB-INF/lib/geronimo-jta_1.1_spec-1.1.1.jar 71% [10/13] testlogin.html 78% [11/13] WEB-INF/web-bck.xml 85% [12/13] WEB-INF/web.xml 92% [13/13] __static__/testlogin.html download_app completed successfully.
Apenas o desenvolvedor que carregou a aplicação pode baixa-la. Se algum outro tentar baixar a aplicação, receberá um mensagem de erro.
Você pode desativar permanentemente o download a partir da tela Versions em seu servidor de desenvolvimento. Nessa página, clique em permanently prohibit code downloads:
Aviso! Essa ação é irreversível. Depois de proibir o download do código, não há maneira de re-ativar esse comportamento.
Baixando arquivos de Log
O App Engine mantém um log de mensagens que sua aplicação emite. O App Engine também grava cada requisição ao log. Cada log level tem um tamanho de buffer fixo que controla a quantidade de informação de log que você pode acessar. Normalmente, você usa o recurso de logging mas nos níveis mais baixos; assim, a janela de tempo é menor para eventos de log nesses níveis. Você pode navegar pelos logs de sua aplicação dos últimos 90 dias a partir da seção Log do Admin Console.
Se você desejar executar uma análise mais detalhada dos logs de sua aplicação, pode baixa-los em um arquivo em seu computador. Para baixar os logs para um arquivo chamado mylogs.txt, use a ação request_logs, como segue:
./appengine-java-sdk/bin/appcfg.sh request_logs myapp/war mylogs.txt
Por padrão, o comando baixa as mensagens de log do dia atual (a partir da meia noite na Hora do pacifico) com um nível de log de INFO ou superior (omitindo mensagens no nível DEBUG). Você pode ajustar o número de dias, o nível mínimo de log e se o conteúdo será sobrescrito ou anexado ao arquivo local usando as opções do comando.
Por padrão, o comando sobrescreve o arquivo local. Você pode dizer para anexar os dados baixados ao arquivo especificando o argumento --append. Isso simplesmente irá anexar os dados requisitados ao arquivo, não garantirá que o arquivo não conterá mensagens de log duplicadas.
Usando um Proxy HTTP
Se o seu ambiente de desenvolvimento reside sobre um proxy, o comando AppCfg precisa saber sobre o proxy para poder se conectar ao AppEngine. Para informar o AppCfg sobre o proxy, use a opção --proxy:
./appengine-java-sdk/bin/appcfg.sh --proxy=10.1.2.3 update myapp/war
Se você usar um proxy diferente para HTTPS, pode especifica-lo usando a opção --proxy_https.
Argumentos de linha de comando
O comando AppCfg usa um conjunto de opções, ações e argumentos para cada ação.
As seguintes ações estão disponíveis:
appcfg.sh [options] cron_info <app-directory>- Verifica e imprime a configuração de tarefas agendadas (cron).
appcfg.sh download_app -A <app_id> -V <version><output-dir>- Recupera a versão mais atual de sua aplicação usando as seguintes opções:
-A- O ID da aplicação (necessário).
-V- A versão atual da aplicação. Pode ser uma das seguintes opções:
-V major.minor– Especifica a versão exata.-V major– Especifica a versão principal (major).- Omitted entirely – Returna a versão padrãoatual, se existir.
<output-dir>- O diretório onde você deseja salvar os arquivo (necessário).
appcfg.sh [options] request_logs <war-location> <output-file>- Retrieves log data for the application running on App Engine.
output-fileis the name of the file to create or replace. Ifoutput-fileis a hyphen (-), the log data is printed to the console. The following options apply torequest_logs:--num_days=...- The number of days of log data to retrieve, ending on the current date at midnight UTC. A value of 0 retrieves all available logs. If
--appendis given, then the default is 0, otherwise the default is 1. --severity=...- The minimum log level for the log messages to retrieve. The value is a number corresponding to the log level: 4 for CRITICAL, 3 for ERROR, 2 for WARNING, 1 for INFO, 0 for DEBUG. All messages at the given log level and above will be retrieved. Default is 1 (INFO).
--append- Tells AppCfg to append logs to the log output file instead of overwriting the file. This simply appends the requested data, it does not guarantee the file won’t contain duplicate error messages. If this argument is not specified, AppCfg will overwrite the log output file.
appcfg.sh [options] help <action>- Prints a help message about the given action, then quits.
appcfg.sh [options] version- Prints detailed version information about the SDK, Java and the operating system, then quits. Use this when submitting bug reports.
appcfg.sh [options] rollback <war-location>- Undoes a partially completed update for the given application. You can use this if an update was interrupted, and the command is reporting that the application cannot be updated due to a lock.
appcfg.sh [options] update <war-location>- Uploads files for an application given the application’s root directory. The application ID and version are taken from the
appengine-web.xmlfile. appcfg.sh [options] update_cron <app-directory>- Updates the schedule task (cron) configuration for the app, based on the
cron.xmlfile. appcfg.sh [options] update_dos <app-directory>- Updates the DoS protection configuration for the app, based on the
dos.xmlfile. appcfg.sh [options] update_indexes <war-location>- Updates datastore indexes in App Engine to include newly added indexes. If a new version of your application requires an additional index definition that was added to the index configuration, you can update your index configuration in App Engine prior to uploading the new version of your application. Running this action a few hours prior to uploading your new application version will give the indexes time to build and be serving when the application is deployed.
appcfg.sh [options] update_queues <war-location>- Updates the task queue configuration (
queue.xml) in App Engine. If the new configuration does not include a named queue (other thandefault) that exists and has tasks, the existing queue is paused.
O comando AppCfg aceita as seguintes opções para todas as ações:
--email=...- The email address of the Google account of an administrator for the application, for actions that require signing in. If omitted and no cookie is stored from a previous use of the command, the command will prompt for this value.
--server=...- The App Engine server hostname. The default is
appengine.google.com. --host=...- The hostname of the local machine for use with remote procedure calls.
--sdk_root=...- A path to the App Engine Java SDK, if different from the location of the tool.
--passin- Do not store the administrator sign-in credentials as a cookie; prompt for a password every time.
--proxy=...- Use the given HTTP proxy to contact App Engine.
--proxy_https=...- Use the given HTTPS proxy to contact App Engine, when using HTTPS. If
--proxyis given but--proxy_httpsis not, both HTTP and HTTPS requests will use the given proxy.