Migrar para o Cloud NDB

O Google Cloud NDB é uma biblioteca de cliente para Python que substitui o App Engine NDB. O App Engine NDB permite que os aplicativos Python 2 armazenem e consultem dados em bancos de dados do Datastore. O Cloud NDB permite que aplicativos Python 2 e Python 3 armazenem e consultem dados nos mesmos bancos de dados. No entanto, o produto que gerencia esses bancos de dados mudou do Datastore para o Firestore no modo Datastore. A biblioteca do Cloud NDB pode acessar qualquer dado criado com o App Engine NDB, mas alguns tipos de dados estruturados armazenados que usam o Cloud NDB não podem ser acessados com o App Engine NDB. Por esse motivo, a migração para o Cloud NDB deve ser considerada irreversível.

Recomendamos que você migre para o Cloud NDB antes de fazer upgrade do aplicativo para o Python 3. Essa abordagem incremental da migração permite manter um app funcional e testável durante todo o processo de migração.

O Cloud NDB destina-se a substituir os recursos no NDB do App Engine. Portanto, ele não será compatível com novos recursos do Firestore no modo Datastore. É recomendável que os novos aplicativos Python 3 usem a biblioteca de cliente do modo Datastore em vez do Cloud NDB.

Para mais informações sobre o Cloud NDB, consulte as seguintes páginas no GitHub:

• Documentação do Cloud NDB

• Código-fonte do Cloud NDB

Comparação entre o NDB do App Engine e o NDB do Cloud

Semelhanças:

• O NDB do Cloud é compatível com quase todos os recursos compatíveis com o NDB do App Engine, apenas com pequenas diferenças na sintaxe do método.

Diferenças:

• As APIs NDB do App Engine que dependem de serviços específicos do ambiente de execução Python 2.7 do App Engine foram atualizadas ou removidas do Cloud NDB.

• Os novos recursos do Python 3 e do Django eliminaram a necessidade de google.appengine.ext.ndb.django_middleware. Em vez disso, é possível escrever seu próprio middleware com apenas algumas linhas de código.

• Os App Engine NDB requer aplicativos e o banco de dados do Datastore para estar no mesmo projeto do Google Cloud, enquanto o Google App Engine fornece as credenciais automaticamente. O Cloud NDB pode acessar bancos de dados do modo Datastore em qualquer projeto, desde que você autentique o cliente corretamente. Isso é consistente com outras APIs do Google Cloud e bibliotecas de cliente.

• O Cloud NDB não usa o serviço Memcache do App Engine para armazenar dados em cache.

  Em vez disso, ele pode armazenar dados em cache em um repositório de dados na memória do Redis gerenciado pelo Memorystore, Redis Labs ou outros sistemas. Embora, atualmente, apenas armazenamentos de dados do Redis sejam compatíveis, o Cloud NDB generalizou e definiu o armazenamento em cache na interface GlobalCache abstrata, que pode aceitar implementações concretas adicionais.

  Para acessar o Memorystore para Redis, seu aplicativo precisa usar o acesso VPC sem servidor.

  Nem o Memorystore para Redis nem o acesso VPC sem servidor oferecem um nível gratuito, e esses produtos podem não estar disponíveis na região do seu aplicativo. Consulte Antes de começar a migração para mais informações.

A lista completa de diferenças está disponível nas notas de migração para o projeto GitHub do Cloud NDB.

Exemplos de código:

• Operações básicas de banco de dados usando o App Engine NDB

• Operações básicas de banco de dados usando o Cloud NDB

Antes de começar a migração

Antes de começar a migração

1. Se você ainda não tiver feito isso, configure o ambiente de desenvolvimento do Python para usar uma versão do Python compatível com o Google Cloud e instale ferramentas de teste para criar Python isolado.

2. Determine se você precisa armazenar dados em cache.

3. Se precisar armazenar dados em cache, verifique se a região do seu aplicativo é compatível pelo acesso VPC sem servidor e pelo Memorystore para Redis.

4. Entenda as permissões do modo Datastore.

Como determinar se você precisa armazenar dados em cache

Se o aplicativo precisar armazenar dados em cache, é importante entender que o Memorystore para Redis e o acesso VPC sem servidor não têm um nível gratuito e não são compatíveis com todas as regiões do Google Cloud.

Em geral:

• Se o aplicativo lê os mesmos dados com frequência, o armazenamento em cache pode diminuir a latência.

• Quanto mais solicitações seu aplicativo atender, maior impacto poderá ter o armazenamento em cache.

Para ver o volume de dados armazenados em cache, consulte o painel do Memcache e veja a proporção de ocorrências em cache para falhas. Se essa proporção for alta, usar um cache de dados terá provavelmente um grande impacto na redução da latência do aplicativo.

Acessar o Memcache do App Engine

Para informações sobre preços, consulte Preços do Memorystore e Preços de acesso VPC sem servidor.

Como confirmar a região do seu app

Se precisar armazenar dados em cache, verifique se a região do seu aplicativo é compatível com o Memorystore para Redis e o acesso VPC sem servidor:

1. Veja a região do aplicativo. Ela aparece perto da parte superior do painel do App Engine no Console do Google Cloud.

   Acessar o App Engine

   A região aparece perto da parte superior da página, logo abaixo do URL do seu aplicativo.

2. Confirme se o aplicativo está em uma das regiões compatíveis com o acesso VPC sem servidor.

3. Confirme se o aplicativo está em uma das regiões compatíveis com o Memorystore para Redis visitando a página "Criar conector" e visualizando as regiões na lista Regiões.

   Página do console sobre o acesso VPC sem servidor

Se o aplicativo não estiver em uma região compatível com o Memorystore para Redis e o acesso VPC sem servidor:

1. Criar um projeto do Google Cloud.

2. Crie um aplicativo do App Engine no projeto e selecione uma região compatível.

3. Crie os serviços do Google Cloud que o aplicativo usa no novo projeto.

   Como alternativa, é possível atualizar seu app para usar os serviços existentes no projeto antigo, mas os preços e o uso de recursos podem ser diferentes quando você usa serviços em um projeto e região diferentes. Consulte a documentação de cada serviço para mais informações.

4. Implante o app no novo projeto.

Como entender as permissões do modo Datastore

Toda interação com um serviço do Google Cloud precisa ser autorizada. Por exemplo, para armazenar ou consultar dados em um banco de dados no modo Datastore, o aplicativo precisa fornecer as credenciais de uma conta que está autorizada a acessar esse banco de dados.

Por padrão, o aplicativo fornece as credenciais da conta de serviço padrão do App Engine, que está autorizada a acessar bancos de dados no mesmo projeto que o aplicativo.

Você precisará usar uma técnica de autenticação alternativa que forneça credenciais explicitamente, caso alguma das seguintes condições for verdadeira:

• Seu aplicativo e o banco de dados do modo Datastore estão em projetos diferentes do Google Cloud.

• Você alterou os papéis atribuídos à conta de serviço padrão do App Engine.

Para saber mais sobre técnicas de autenticação alternativas, consulte Como configurar a autenticação para aplicativos de produção de servidor para servidor.

Visão geral do processo de migração

Para migrar para o Cloud NDB:

1. Atualize seu aplicativo Python:

   1. Instale a biblioteca de cliente do Cloud NDB.

   2. Atualize as instruções de importação para importar módulos do Cloud NDB.

   3. Adicione um código que crie um cliente do Cloud NDB. O cliente pode ler as variáveis de ambiente do aplicativo e usar os dados para autenticar com o modo Datastore.

   4. Adicione o código que usa o contexto do ambiente de execução do cliente para manter o cache e as transações separados entre as linhas de execução.

   5. Remova ou atualize o código que usa métodos e propriedades que não são mais suportados.

2. Ative o armazenamento em cache.

3. Teste as atualizações.

4. Implante o aplicativo no App Engine.

   Como acontece com qualquer alteração feita no seu app, considere usar a divisão de tráfego para aumentar o tráfego lentamente. Monitore de perto o aplicativo em busca de problemas no banco de dados antes de direcionar mais tráfego para o aplicativo atualizado.

Como atualizar seu aplicativo Python

Como instalar a biblioteca do Cloud NDB para aplicativos Python

Para instalar a biblioteca de cliente do Cloud NDB no aplicativo Python do App Engine:

1. Atualize o arquivo app.yaml. Siga as instruções para sua versão do Python:

   Python 2

   Para aplicativos Python 2, adicione as versões mais recentes das bibliotecas grpcio e setuptools.

   A seguir, um exemplo de arquivo app.yaml:

   runtime: python27
   threadsafe: yes
   api_version: 1
   
   libraries:
   - name: grpcio
     version: latest
   - name: setuptools
     version: latest
   

   Python 3

   Para aplicativos Python 3, especifique o elemento runtime com uma versão compatível do Python 3 e exclua as linhas desnecessárias. Por exemplo, o arquivo app.yaml pode ser semelhante ao seguinte:

   runtime: python310 # or another support version
   

   O ambiente de execução do Python 3 instala bibliotecas automaticamente. Portanto, não é necessário especificar bibliotecas integradas do ambiente de execução anterior do Python 2. Se o app Python 3 estiver usando outros serviços em pacote legados ao migrar, deixe o arquivo app.yaml como está.

2. Atualize o arquivo requirements.txt. Siga as instruções para sua versão do Python:

   Python 2

   Adicione as bibliotecas de cliente do Cloud para Cloud NDB à lista de dependências no arquivo requirements.txt.

   google-cloud-ndb
   

   Em seguida, execute pip install -t lib -r requirements.txt para atualizar a lista de bibliotecas disponíveis para seu app.

   Python 3

   Adicione as bibliotecas de cliente do Cloud para Cloud NDB à lista de dependências no arquivo requirements.txt.

   google-cloud-ndb
   

   O App Engine instala automaticamente essas dependências durante a implantação do app no ambiente de execução do Python 3. Portanto, exclua a pasta lib, se houver uma.

3. Para aplicativos em Python 2, se o aplicativo usar bibliotecas integradas ou copiadas especificadas no diretório lib, será necessário especificar esses caminhos no arquivo appengine_config.py:

   import pkg_resources
   from google.appengine.ext import vendor
   
   # Set PATH to your libraries folder.
   PATH = 'lib'
   # Add libraries installed in the PATH folder.
   vendor.add(PATH)
   # Add libraries to pkg_resources working set to find the distribution.
   pkg_resources.working_set.add_entry(PATH)
   

   Use o módulo pkg_resources, que garante que o aplicativo use a distribuição correta das bibliotecas de cliente.

   O arquivo appengine_config.py no exemplo anterior supõe que a pasta lib está localizada no diretório de trabalho atual. Se não for possível garantir que lib estará sempre no diretório de trabalho atual, especifique o caminho completo para a pasta lib. Exemplo:

   import os
   path = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'lib')
   

   Quando você implanta o aplicativo, o App Engine faz o upload de todas as bibliotecas no diretório especificado no arquivo appengine_config.py.

Como atualizar declarações de importação

O local do módulo NDB foi movido para google.cloud.ndb. Atualize as instruções de importação do aplicativo, conforme mostrado na tabela a seguir:

Como criar um cliente do Cloud NDB

Assim como acontece com outras bibliotecas de cliente baseadas nas APIs do Google Cloud, a primeira etapa para usar o Cloud NDB é criar um objeto Client. O cliente contém credenciais e outros dados necessários para se conectar ao modo Datastore. Exemplo:

from google.cloud import ndb

client = ndb.Client()

No cenário de autorização padrão descrito anteriormente, o cliente Cloud NDB contém credenciais da conta de serviço padrão do App Engine, que está autorizada a interagir com o modo Datastore. Se você não estiver trabalhando nesse cenário padrão, consulte Application Default Credentials (ADC) para informações sobre como fornecer credenciais.

Como usar o contexto de ambiente de execução do cliente

Além de fornecer as credenciais necessárias para interagir com o modo Datastore, o cliente do Cloud NDB contém o método context(), que retorna um contexto de ambiente de execução. O contexto do ambiente de execução isola as solicitações de cache e transação de outras interações simultâneas do modo Datastore.

Todas as interações com o modo Datastore precisam ocorrer em um contexto de ambiente de execução do NDB. Como a criação de uma definição de modelo não interage com o Datastore, defina sua classe de modelo antes de criar um cliente do Cloud NDB e recuperar um contexto de ambiente de execução. Depois, use o contexto de ambiente de execução no gerenciador de solicitações para obter dados do banco de dados.

Exemplo:

from google.cloud import ndb


class Book(ndb.Model):
    title = ndb.StringProperty()


client = ndb.Client()


def list_books():
    with client.context():
        books = Book.query()
        for book in books:
            print(book.to_dict())

Aplicativos multithreaded

O contexto do ambiente de execução que o cliente do Cloud NDB retorna se aplica apenas a uma única linha de execução. Se o aplicativo usar várias linhas de execução para uma única solicitação, você precisará recuperar um contexto de ambiente de execução separado para cada linha de execução que usará a biblioteca do Cloud NDB.

Como usar um contexto de ambiente de execução com frameworks WSGI

Se o aplicativo da Web usa um framework WSGI, é possível criar automaticamente um novo contexto de ambiente de execução para cada solicitação criando um objeto de middleware (que recupera o contexto de ambiente de execução) e, depois, unindo o aplicativo no objeto de middleware.

No exemplo a seguir, o uso de middleware com Flask:

• O método middleware cria um objeto de middleware WSGI no contexto do ambiente de execução do cliente NDB.

• O aplicativo Flask é encapsulado no objeto de middleware.

• O Flask transmitirá cada solicitação pelo objeto de middleware, que recupera um novo contexto de ambiente de execução do NDB para cada solicitação.

from flask import Flask

from google.cloud import ndb


client = ndb.Client()


def ndb_wsgi_middleware(wsgi_app):
    def middleware(environ, start_response):
        with client.context():
            return wsgi_app(environ, start_response)

    return middleware


app = Flask(__name__)
app.wsgi_app = ndb_wsgi_middleware(app.wsgi_app)  # Wrap the app in middleware.


class Book(ndb.Model):
    title = ndb.StringProperty()


@app.route("/")
def list_books():
    books = Book.query()
    return str([book.to_dict() for book in books])

Como usar um contexto de ambiente de execução com o Django

O middleware do Django fornecido pela biblioteca NDB do App Engine não é compatível com a biblioteca do Cloud NDB. Se você usou esse middleware (google.appengine.ext.ndb.django_middleware) no aplicativo, siga estas etapas para atualizá-lo:

1. Use o sistema de middleware do Django para criar um novo contexto de ambiente de execução para cada solicitação.

   Estes são os elementos do exemplo a seguir:

   • O método ndb_django_middleware cria um cliente do Cloud NDB.

   • O método middleware cria um objeto de middleware dentro do contexto do ambiente de execução do cliente NDB.

   from google.cloud import ndb
   
   
   # Once this middleware is activated in Django settings, NDB calls inside Django
   # views will be executed in context, with a separate context for each request.
   def ndb_django_middleware(get_response):
       client = ndb.Client()
   
       def middleware(request):
           with client.context():
               return get_response(request)
   
       return middleware
   

2. No arquivo settings.py do Django, atualize a configuração MIDDLEWARE para que ela liste o novo middleware criado em vez de google.appengine.ext.ndb.NdbDjangoMiddleware.

O Django transmitirá cada solicitação pelo objeto de middleware que você listou na configuração MIDDLEWARE, e esse objeto recuperará um novo contexto de ambiente de execução do NDB para cada solicitação.

Como atualizar o código para APIs NDB removidas ou alteradas

As APIs NDB que dependem de APIs e serviços específicos do App Engine foram atualizadas ou removidas da biblioteca do Cloud NDB.

Você precisará atualizar seu código se ele usar qualquer uma das seguintes APIs NDB:

• google.appengine.ext.ndb.Model e as propriedades do modelo
• google.appengine.ext.ndb.Key
• google.appengine.ext.ndb.query.QueryOptions e PropertyOrder
• google.appengine.ext.ndb.utils
• google.appengine.api.namespacemanager
• google.appengine.api.ext.ndb.tasklets
• google.appengine.api.datastore_errors

Modelos e propriedades do modelo

Os seguintes métodos de google.appengine.ext.ndb.Model não estão disponíveis na biblioteca do Cloud NDB porque usam APIs específicas do App Engine que não estão mais disponíveis.

A tabela a seguir descreve as propriedades google.appengine.ext.ndb.Model específicas que foram alteradas na biblioteca do Cloud NDB:

As classes e métodos na tabela a seguir não estão mais disponíveis porque usam recursos específicos do App Engine que não estão mais disponíveis.

Chaves

Os seguintes métodos do google.appengine.ext.ndb.Key não estão disponíveis na biblioteca do Cloud NDB. Esses métodos foram usados para transmitir chaves para e da API Datastore DB, que não é mais compatível (DB foi o predecessor do App Engine NDB).

Além disso, observe as seguintes alterações:

Consultas

Como o App Engine NDB, o Cloud NDB fornece uma classe QueryOptions (google.cloud.ndb.query.QueryOptions) que permite reutilizar um conjunto específico de opções de consulta, em vez de redefini-las para cada consulta. No Cloud NDB, porém, QueryOptions não herda de google.appengine.datastore.datastore_rpc.Configuration e, portanto, não é compatível com métodos ...datastore_rpc.Configuration.

Além disso, google.appengine.datastore.datastore_query.Order foi substituído por google.cloud.ndb.query.PropertyOrder. Assim como Order, a classe PropertyOrder permite especificar a ordem de classificação em várias consultas. O construtor PropertyOrder é o mesmo que o construtor de Order. Somente o nome da classe foi alterado.

Utils

O módulo ndb.utils (google.appengine.ext.ndb.utils) não está mais disponível. A maioria dos métodos nesse módulo era interna ao App Engine NDB. Alguns foram descartados devido a diferenças de implementação no novo ndb, enquanto outros se tornaram obsoletos pelos novos recursos do Python 3.

Por exemplo, o decorador posicional no antigo módulo utils declarava que apenas os primeiros n argumentos de uma função ou método poderiam ser posicionais. No entanto, o Python 3 pode fazer isso usando argumentos somente de palavra-chave. O que costumava ser escrito como:

@utils.positional(2)
def function1(arg1, arg2, arg3=None, arg4=None)
  pass

Pode ser escrito assim no Python 3:

def function1(arg1, arg2, *, arg3=None, arg4=None)
  pass

Namespaces

Os namespaces permitem que um aplicativo multilocatário use silos de dados separados para cada locatário enquanto segue usando o mesmo banco de dados do modo Datastore. Ou seja, cada locatário armazena dados no próprio namespace.

Em vez de usar o google.appengine.api.namespacemanager específico do App Engine, especifique um namespace padrão ao criar um cliente do Cloud NDB e use o namespace padrão chamando os métodos do Cloud NDB no contexto do ambiente de execução do cliente. Isso segue o mesmo padrão de outras APIs do Google Cloud compatíveis com namespaces.

client=google.cloud.ndb.Client(namespace="my namespace")

with client.context() as context:
    key = ndb.Key("SomeKind", "SomeId")
       

key-non-default-namespace=ndb.Key("SomeKind," "AnotherId",
namespace="non-default-nspace")

Tasklets

Tasklets agora podem usar uma instrução return padrão para retornar um resultado em vez de aumentar uma exceção Return. Exemplo:

        @ndb.tasklet
        def get_cart():
          cart = yield
        CartItem.query().fetch_async()
          raise Return(cart)
       

        @ndb.tasklet
        def get_cart():
          cart = yield
        CartItem.query().fetch_async()
          return cart
        

Observe que ainda é possível retornar resultados no Cloud NDB gerando uma exceção Return, mas isso não é recomendado.

Além disso, os seguintes métodos e subclasses Tasklets não estão mais disponíveis, principalmente devido a alterações na forma como um contexto do NDB é criado e usado na biblioteca do Cloud NDB.

Exceções

Embora o módulo google.cloud.ndb.exceptions na biblioteca do Cloud NDB contenha muitas das mesmas exceções da biblioteca do App Engine NDB, nem todas as exceções antigas estão disponíveis na nova biblioteca. A tabela a seguir lista as exceções que não estão mais disponíveis:

Como ativar o armazenamento em cache de dados

O Cloud NDB pode armazenar dados em cache em um repositório de dados na memória Redis gerenciado por Memorystore, Redis Labs ou outros sistemas. Neste guia, descrevemos como usar o Memorystore para Redis quando se quer armazenar dados em cache:

1. Configure o acesso VPC sem servidor.

2. Configure o Memorystore para Redis.

3. Adicione o URL de conexão do Redis ao seu aplicativo.

4. Crie um objeto RedisCache.

Como configurar o acesso VPC sem servidor

Seu app só pode se comunicar com o Memorystore por meio de um conector de acesso VPC sem servidor. Para configurar um conector de acesso VPC sem servidor:

1. Crie um conector de acesso VPC sem servidor.

2. Configure seu app para usar o conector.

Como configurar o Memorystore para Redis

Para configurar o Memorystore para Redis:

1. Crie uma instância do Redis no Memorystore. Ao criar a instância:

   • Em Região, selecione a mesma região onde seu aplicativo do App Engine está localizado.

   • Em Rede autorizada, selecione a mesma rede usada pelo conector de acesso VPC sem servidor.

2. Anote o endereço IP e o número da porta da instância do Redis criada. Você usará essas informações quando ativar o armazenamento em cache de dados para o Cloud NDB.

   Use o comando gcloud beta para implantar as atualizações do app. Somente o comando Beta pode atualizar seu app para usar um conector VPC.

Como adicionar o URL de conexão do Redis

Conecte-se ao cache do Redis adicionando a variável de ambiente REDIS_CACHE_URL ao arquivo app.yaml do seu aplicativo. O valor de REDIS_CACHE_URL tem o seguinte formato:

redis://IP address for your instance:port

Por exemplo, é possível adicionar as seguintes linhas ao arquivo app.yaml do aplicativo:

     env_variables:
      REDIS_CACHE_URL: redis://10.0.0.3:6379

Como criar e usar um objeto de cache do Redis

Se você definiu REDIS_CACHE_URL como uma variável de ambiente, é possível criar um objeto RedisCache com uma única linha de código e, em seguida, usar o cache transmitindo-o para Client.context() ao configurar o contexto do ambiente de execução:

client = ndb.Client()
global_cache = ndb.RedisCache.from_environment()

with client.context(global_cache=global_cache):
  books = Book.query()
  for book in books:
      print(book.to_dict())

Se você não definir REDIS_CACHE_URL como uma variável de ambiente, você precisará construir um cliente Redis e transmiti-lo para o construtor ndb.RedisCache(). Exemplo:

global_cache = ndb.RedisCache(redis.StrictRedis(host=IP-address, port=redis_port))

Observe que você não precisa declarar uma dependência na biblioteca de cliente do Redis, porque a biblioteca do Cloud NDB já depende da biblioteca de cliente do Redis.

Consulte o aplicativo de amostra do Memorystore para ver um exemplo de como construir um cliente Redis.

Como testar suas atualizações

Para configurar um banco de dados de teste e executar seu aplicativo localmente antes de implantá-lo no App Engine:

1. Execute o emulador local no modo Datastore para armazenar e recuperar dados.

   Siga as instruções para definir variáveis de ambiente. Assim, o aplicativo se conecta ao emulador em vez do ambiente de produção do modo Datastore.

   Você também pode importar dados para o emulador se quiser iniciar o teste com dados pré-carregados no banco de dados.

2. Use o servidor de desenvolvimento local para executar o aplicativo.

   Para garantir que a variável de ambiente GOOGLE_CLOUD_PROJECT esteja definida corretamente durante o desenvolvimento local, inicialize dev_appserver usando o seguinte parâmetro:

   --application=PROJECT_ID

   Substitua PROJECT_ID pelo ID do projeto do Google Cloud. Para encontrar o ID do projeto, execute o comando gcloud config list project ou consulte a página do projeto no console do Google Cloud.

Como implantar o app

Quando seu aplicativo estiver em execução no servidor de desenvolvimento local sem erros:

1. Teste o aplicativo no App Engine.

2. Se o aplicativo for executado sem erros, use a divisão de tráfego para aumentar gradualmente o tráfego para o aplicativo atualizado. Monitore de perto o aplicativo em busca de problemas no banco de dados antes de direcionar mais tráfego para o aplicativo atualizado.

A seguir

• Para ver um tutorial prático, consulte o codelab Migrar do NDB do App Engine para o Cloud NDB.
• Consulte a documentação do Cloud NDB para mais detalhes.