Aceder ao App Engine com a API Remote

ID da região

O REGION_ID é um código abreviado que a Google atribui com base na região que seleciona quando cria a sua app. O código não corresponde a um país ou uma província, embora alguns IDs de regiões possam parecer semelhantes aos códigos de países e províncias usados frequentemente. Para apps criadas após fevereiro de 2020, REGION_ID.r está incluído nos URLs do App Engine. Para apps existentes criadas antes desta data, o ID da região é opcional no URL.

Saiba mais acerca dos IDs de regiões.

OK

A biblioteca da API Remote permite que qualquer cliente Python aceda aos serviços disponíveis para aplicações do App Engine.

Por exemplo, se a sua aplicação App Engine usar o Datastore ou o Google Cloud Storage, um cliente Python pode aceder a esses recursos de armazenamento através da API Remote.

Pode usar a API Remote para aceder ao arquivo de dados da sua aplicação a partir de uma app executada no seu computador local ou a partir de uma shell da API Remote interativa local. A API Remote interage com serviços reais, pelo que este acesso usa quota e recursos faturáveis.

Aviso: esta solução já não é recomendada: as apps que usam esta API só podem ser executadas no tempo de execução do Python 2 e têm de ser atualizadas para uma solução recomendada antes da migração para o tempo de execução do Python 3.

Ativar o acesso à API remota na sua app

A forma mais fácil de ativar a API Remote para a sua aplicação é usar a diretiva builtins no ficheiro app.yaml da sua app, que especifica o URL predefinido /_ah/remote_api/. No entanto, pode usar a diretiva url nesse mesmo ficheiro para especificar outro URL.

builtin

A diretiva builtins no ficheiro app.yaml torna a API Remote disponível no URL predefinido /_ah/remote_api:

runtime: python27
api_version: 1
threadsafe: true

builtins:
- remote_api: on

URL

A utilização da diretiva url em app.yaml permite-lhe especificar um URL diferente para utilização com a API Remote:

- url: /some-URL/*
  script: google.appengine.ext.remote_api.handler.application

Certifique-se de que implementa a sua aplicação no App Engine depois de fazer esta alteração.

Usar a shell da API Remote

O SDK Python inclui uma shell da API Remote, que lhe permite invocar comandos Python nos serviços do App Engine usados pela sua aplicação. Não tem de fornecer nenhuma autenticação adicional, porque esta usa automaticamente as mesmas credenciais que usou para carregar a app para o App Engine.

Para iniciar a shell da API remota:

1. Invoque o seguinte comando a partir de uma janela de terminal na sua máquina local:

   SDK-INSTALL-DIRECTORY/remote_api_shell.py -s YOUR-PROJECT-ID. REGION_ID.r.appspot.com

   Substitua [SDK-INSTALL-DIRECTORY] pelo caminho para o SDK do App Engine para Python e [YOUR-PROJECT-ID] pelo ID do projeto.

2. No shell interativo apresentado, invoque os comandos Python que quer executar. Por exemplo, se a sua aplicação usar o Datastore, pode invocar a seguinte consulta ndb para obter 10 registos:

    >>> from google.appengine.ext import ndb
    >>>
    >>> # Fetch 10 keys from the datastore
    >>> ndb.Query().fetch(10, keys_only=True)
   

Nota: na shell, pode aceder a ficheiros e recursos na sua máquina local, além dos serviços em execução na Google Cloud Platform. Também pode importar módulos da sua aplicação se executar a shell a partir do diretório da aplicação.

Usar a API Remote num cliente local

Também pode usar a API Remote em aplicações locais para aceder a serviços usados pela sua app em execução no App Engine.

Para usar a API Remote numa aplicação local:

1. Ative a API remota.

2. Exporte a variável de ambiente PYTHONPATH para o seu diretório Python, por exemplo:

    export PYTHONPATH=/usr/somedir/v3/bin/python2.7
   

   Substitua esse caminho pelos valores reais da sua localização do Python.

3. Adicione a localização do SDK do App Engine para Python a PYTHONPATH:

    export GAE_SDK_ROOT="/usr/local/home/mydir/google_appengine"
    export PYTHONPATH=${GAE_SDK_ROOT}:${PYTHONPATH}
   

   Substitua o caminho do SDK apresentado acima pelo caminho real do SDK do App Engine.

4. No código do cliente, importe dev_appserver e chame dev_appserver.fix_sys_path() para garantir que todos os módulos do SDK do App Engine são importados corretamente:

   try:
       import dev_appserver
       dev_appserver.fix_sys_path()

5. Adicione o seguinte código remote_api_stub à sua aplicação, certificando-se de que transmite o ID do projeto no código:

   remote_api_stub.ConfigureRemoteApiForOAuth(
       '{}.appspot.com'.format(project_id),
       '/_ah/remote_api')

   Se não usar o URL predefinido /_ah/remote_api para a API Remote, tem de alterar o código acima para refletir o URL que está a usar. Para a definição e a documentação de remote_api_stub.ConfigureRemoteApiForOAuth, consulte o ficheiro do SDK [SDK-INSTALL-DIRECTORY]/google/appengine/ext/remote_api/remote_api_stub.py.

6. Adicione as importações do App Engine e o código Python necessários para aceder aos serviços do App Engine pretendidos. O seguinte código de exemplo acede ao arquivo de dados do projeto:

   
   import argparse
   
   try:
       import dev_appserver
       dev_appserver.fix_sys_path()
   except ImportError:
       print('Please make sure the App Engine SDK is in your PYTHONPATH.')
       raise
   
   from google.appengine.ext import ndb
   from google.appengine.ext.remote_api import remote_api_stub
   
   
   def main(project_id):
       remote_api_stub.ConfigureRemoteApiForOAuth(
           '{}.appspot.com'.format(project_id),
           '/_ah/remote_api')
   
       # List the first 10 keys in the datastore.
       keys = ndb.Query().fetch(10, keys_only=True)
   
       for key in keys:
           print(key)
   
   
   if __name__ == '__main__':
       parser = argparse.ArgumentParser(
           description=__doc__,
           formatter_class=argparse.RawDescriptionHelpFormatter)
       parser.add_argument('project_id', help='Your Project ID.')
   
       args = parser.parse_args()
   
       main(args.project_id)

7. Com a aplicação implementada no App Engine, inicie o cliente da API Remote:

    python your-client.py YOUR-PROJECT-ID
   

   Substituindo your-client.py pelo seu módulo de cliente e YOUR-PROJECT-ID pelo ID do projeto. Isto pressupõe que o seu cliente aceita o ID do projeto como a entrada da linha de comandos, seguindo o exemplo de código client.py.

Limitações e práticas recomendadas

O módulo remote_api esforça-se por garantir que, na medida do possível, se comporta exatamente como o datastore do App Engine nativo. Em alguns casos, isto significa fazer coisas que são menos eficientes do que poderiam ser de outra forma. Quando usar a API remote_api, tenha em atenção o seguinte:

Cada pedido de armazenamento de dados requer um processo de ida e volta

Uma vez que está a aceder ao arquivo de dados através de HTTP, existe um pouco mais de sobrecarga e latência do que quando acede localmente. Para acelerar o processo e diminuir a carga, tente limitar o número de viagens de ida e volta que faz agrupando as obtenções e as colocações, e obtendo lotes de entidades a partir de consultas. Este é um bom conselho não só para a remote_api, mas também para a utilização da base de dados em geral, porque uma operação em lote é considerada uma única operação da base de dados. Por exemplo, em vez disto:

for key in keys:
  rec = key.get()
  rec.foo = bar
  rec.put()

Pode fazê-lo da seguinte forma:

records = ndb.get_multi(keys)
for rec in records:
  rec.foo = bar
  ndb.put_multi(records)

Ambos os exemplos têm o mesmo efeito, mas o último requer apenas duas viagens de ida e volta no total, enquanto o primeiro requer duas viagens de ida e volta para cada entidade.

Pedidos de utilização da quota da remote_api

Uma vez que a remote_api opera através de HTTP, cada chamada de datastore que fizer incorre na utilização da quota para pedidos HTTP, bytes de entrada e saída, bem como na quota de datastore habitual. Tenha isto em atenção se estiver a usar a API remote_api para fazer atualizações em massa.

Aplicam-se limites da API de 1 MB

Tal como quando são executados nativamente, o limite de 1 MB nas solicitações e respostas da API continua a aplicar-se. Se as suas entidades forem particularmente grandes, pode ter de limitar o número de entidades que obtém ou coloca de cada vez para se manter abaixo deste limite. Infelizmente, isto entra em conflito com a minimização das viagens de ida e volta. Por isso, a melhor recomendação é usar os maiores lotes possíveis sem exceder as limitações de tamanho de pedidos ou respostas. No entanto, é improvável que isto seja um problema para a maioria das entidades.

Evite iterar consultas

Um padrão comum com o acesso ao repositório de dados é o seguinte:

q = MyModel.query()
for entity in q:
  # Do something with entity

Quando o faz, o SDK obtém entidades do repositório de dados em lotes de 20, obtendo um novo lote sempre que usa os existentes. Uma vez que cada lote tem de ser obtido num pedido separado pela API remote_api, não é possível fazê-lo de forma tão eficiente. Em alternativa, a API remote_api executa uma consulta totalmente nova para cada lote, usando a funcionalidade de deslocamento para obter mais resultados.

Se souber de quantas entidades precisa, pode fazer toda a obtenção num único pedido pedindo o número de que precisa:

entities = MyModel.query().fetch(100)
for entity in entities:
  # Do something with entity

Se não souber quantas entidades quer, pode usar cursores para iterar de forma eficiente em grandes conjuntos de resultados. Isto também permite evitar o limite de 1000 entidades imposto nas consultas normais da base de dados.

As transações são menos eficientes

Para implementar transações através da remote_api, acumula informações sobre entidades obtidas na transação, juntamente com cópias de entidades que foram colocadas ou eliminadas na transação. Quando a transação é confirmada, envia todas estas informações para o servidor do App Engine, onde tem de obter novamente todas as entidades que foram usadas na transação, verificar se não foram modificadas, colocar e eliminar todas as alterações feitas pela transação e confirmá-la. Se existir um conflito, o servidor reverte a transação e notifica o cliente, que tem de repetir todo o processo.

Esta abordagem funciona e duplica exatamente a funcionalidade fornecida pelas transações no arquivo de dados local, mas é bastante ineficiente. Use transações sempre que necessário, mas tente limitar o número e a complexidade das transações que executa para aumentar a eficiência.