Migra a Cloud NDB

Cloud NDB es una biblioteca cliente para Python que reemplaza a App Engine NDB.

App Engine NDB permite que las apps de Python 2 almacenen y consulten datos en bases de datos de Firestore en modo Datastore (Datastore). Cloud NDB permite que las apps de Python 3 almacenen y consulten datos en las mismas bases de datos, y usan Datastore como el producto que administra esas bases de datos. Aunque la biblioteca de Cloud NDB puede acceder a cualquier dato creado con App Engine NDB, no se puede acceder con App Engine NDB a algunos tipos de datos estructurados almacenados mediante Cloud NDB. Por esta razón, la migración a Cloud NDB debe considerarse irreversible.

Las versiones más recientes de Cloud NDB solo admiten Python 3. Las versiones anteriores eran compatibles con Python 2 y Python 3. Para migrar la aplicación de Python 2 a Python 3, recomendamos lo siguiente:

1. Migra a Cloud NDB, versión 1.11.2. Esta es la última versión compatible con Python 2.
2. Actualiza tu aplicación a Python 3.
3. Actualiza a la versión estable más reciente de Cloud NDB.

Este enfoque incremental para la migración te permite mantener el funcionamiento y la posibilidad de probar la app durante todo el proceso de migración.

Cloud NDB está dirigido a desarrolladores de Python que están familiarizados con App Engine NDB y desean modernizar su aplicación. Migrar a Cloud NDB ayuda a preparar tu app de Python 2 para Python 3 y te brinda la opción de dejar App Engine más adelante si lo deseas.

Para obtener más información sobre Cloud NDB, consulta las siguientes páginas:

• Documentación de Cloud NDB

• Código fuente de Cloud NDB

Comparación entre App Engine NDB y Cloud NDB

Similitudes:

• Cloud NDB admite casi todas las funciones compatibles con App Engine NDB, solo con pequeñas diferencias en la sintaxis del método.

Diferencias:

• Las API de App Engine NDB que se basan en los servicios específicos del entorno de ejecución de Python 2.7 de App Engine se actualizaron o quitaron de Cloud NDB.

• Las nuevas funciones de Python 3 y Django borraron la necesidad de google.appengine.ext.ndb.django_middleware. En cambio, puedes escribir de manera sencilla tu propio middleware con solo unas líneas de código.

• App Engine NDB requería que las apps y la base de datos de Datastore estuvieran en el mismo proyecto de Google Cloud, y App Engine proporcionaba las credenciales de manera automática. Cloud NDB puede acceder a las bases de datos en modo Datastore en cualquier proyecto, siempre que autentiques tu cliente de manera correcta. Esto es coherente con otras bibliotecas cliente y API de Google Cloud.

• Cloud NDB no usa el servicio Memcache de App Engine para almacenar datos en caché.

  En su lugar, Cloud NDB puede almacenar datos en caché en un almacén de datos en memoria de Redis administrado por Memorystore, Redis Labs y otros sistemas. Si bien por el momento solo se admiten almacenes de datos de Redis, Cloud NDB generalizó y definió el almacenamiento en caché en la interfaz abstracta GlobalCache, que puede admitir implementaciones concretas adicionales.

  Para acceder a Memorystore para Redis, la app debe usar el Acceso a VPC sin servidores.

  Ni Memorystore para Redis ni el Acceso a VPC sin servidores proporcionan un nivel gratuito y es posible que estos productos no estén disponibles en la región de la app. Consulta Antes de comenzar a migrar para obtener más información.

La lista completa de diferencias está disponible en las notas de migración del proyecto de Cloud NDB de GitHub.

Muestras de código:

• Operaciones básicas de bases de datos mediante Cloud NDB

• Operaciones básicas de bases de datos mediante App Engine NDB

Antes de comenzar la migración

Antes de comenzar la migración, haz lo siguiente:

1. Determina si necesitas almacenar datos en caché.

2. Si necesitas almacenar en caché los datos, asegúrate de que la región de la app sea compatible con el Acceso a VPC sin servidores y Memorystore para Redis.

3. Comprende los permisos del modo Datastore.

Determina si necesitas almacenar datos en caché

Debes asegurarte de que la app necesite almacenamiento en caché, ya que Memorystore para Redis y el Acceso a VPC sin servidores no tienen un nivel gratuito ni son compatibles con todas las regiones de Google Cloud.

En general, debes hacer lo siguiente:

• Si la app lee los mismos datos con frecuencia, el almacenamiento en caché podría disminuir la latencia.

• Cuantas más solicitudes entregue tu app, mayor será el impacto del almacenamiento en caché.

Si deseas ver cuánto dependes de los datos almacenados en caché, consulta el panel de Memcache para ver la proporción de aciertos de caché frente a errores. Si la proporción es alta, es probable que el uso de una caché de datos tenga un gran efecto en la reducción de la latencia de la app.

Visualizar el panel de Memcache

Para obtener información sobre los precios, consulta Precios de Memorystore y Precios de Acceso a VPC sin servidores.

Confirma la región de la app

Si necesitas almacenar datos en caché, asegúrate de que la región de la app sea compatible con Memorystore para Redis y el Acceso a VPC sin servidores:

1. Visualiza la región de la app, que aparece cerca de la parte superior del panel de App Engine en la consola de Google Cloud.

   Abrir el panel

   La región aparece cerca de la parte superior de la página, justo debajo de la URL de la app.

2. Confirma que la app está en una de las regiones compatibles con el Acceso a VPC sin servidores.

3. Confirma que la app se encuentra en una de las regiones compatibles con Memorystore para Redis. Para ello, visita la página Crear conector y visualiza las regiones en la lista Regiones.

   Ver la página Crear conector

Si la app no se encuentra en una región compatible con Memorystore para Redis y el Acceso a VPC sin servidores, haz lo siguiente:

1. Crea un proyecto de Google Cloud.

2. Crea una app de App Engine nueva en el proyecto y selecciona una región compatible.

3. Crea los servicios de Google Cloud que la app usa en el proyecto nuevo.

   Como alternativa, puedes actualizar la app para usar los servicios existentes en tu proyecto anterior, pero el precio y el uso de recursos pueden ser distintos cuando usas servicios en un proyecto y una región diferentes. Consulta la documentación de cada servicio a fin de obtener más información.

4. Implementa la app en el proyecto nuevo.

Comprende los permisos del modo Datastore

Cada interacción con un servicio de Google Cloud debe estar autorizada. Por ejemplo, a fin de almacenar o consultar datos en una base de datos en modo Datastore, la app debe proporcionar las credenciales de una cuenta autorizada para acceder a la base de datos.

De forma predeterminada, la app proporciona las credenciales de la cuenta de servicio predeterminada de App Engine, que está autorizada para acceder a las bases de datos en el mismo proyecto que la app.

Deberás usar una técnica de autenticación alternativa que proporcione credenciales de forma explícita si se cumple alguna de las siguientes condiciones:

• La app y la base de datos en modo Datastore están en diferentes proyectos de Google Cloud.

• Cambiaste las funciones asignadas a la cuenta de servicio predeterminada de App Engine.

Si deseas obtener información sobre técnicas de autenticación alternativas, consulta Configura la autenticación para aplicaciones de producción de servidor a servidor.

Descripción general del proceso de migración

Para migrar a Cloud NDB desde App Engine NDB, sigue estos pasos:

1. Actualiza la app de Python:

   1. Instala la biblioteca cliente de Cloud NDB.

   2. Actualiza las declaraciones de importación para importar módulos desde Cloud NDB.

   3. Agrega el código que crea un cliente de Cloud NDB. El cliente puede leer las variables de entorno de la app y usar los datos para autenticarse con el modo Datastore.

   4. Agrega un código que use el contexto de entorno de ejecución del cliente para mantener el almacenamiento en caché y las transacciones separados entre subprocesos.

   5. Quita o actualiza el código que usa métodos y propiedades que ya no son compatibles.

2. Habilita el almacenamiento en caché.

3. Prueba las actualizaciones.

4. Implementa la app en App Engine.

   Al igual que con cualquier cambio que realices en la app, considera usar la división del tráfico para aumentar el tráfico con lentitud. Supervisa la app de cerca para detectar cualquier problema de la base de datos antes de enrutar más tráfico a la app actualizada.

Actualiza la app de Python

Instala la biblioteca de Cloud NDB para apps de Python 2

1. Crea un directorio para almacenar tus bibliotecas de terceros, como lib/.

2. Crea un archivo requirements.txt en la misma carpeta que tu archivo app.yaml y agrega el nombre de una biblioteca cliente:

   google-cloud-ndb==1.11.2
   

3. Usa pip (versión 6 o posterior) con la marca -t <directory> para instalar las bibliotecas en la carpeta que creaste en el paso anterior. Por ejemplo:

   pip install -t lib -r requirements.txt

4. Especifica las bibliotecas RPC y setuptools en la sección libraries de tu archivo app.yaml:

   libraries:
   - name: grpcio
     version: 1.0.0
   - name: setuptools
     version: 36.6.0
   

5. Crea un archivo appengine_config.py en la misma carpeta en la que está el archivo app.yaml si aún no tienes uno. Agrega lo siguiente al archivo appengine_config.py:

   # 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)

   Asegúrate de usar el módulo pkg_resources, que garantiza que la app use la distribución correcta de las bibliotecas cliente.

   En el archivo appengine_config.py del ejemplo anterior, se supone que la carpeta lib se encuentra en el directorio de trabajo actual. Si no puedes garantizar que lib esté siempre en el directorio de trabajo actual, especifica la ruta completa a la carpeta lib. Por ejemplo:

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

Cuando implementas la app, App Engine sube todas las bibliotecas del directorio que especificaste en el archivo appengine_config.py.

Instala la biblioteca de Cloud NDB para apps de Python 3

El entorno de ejecución de Python 3 de App Engine usa el archivo requirements.txt de una app a fin de determinar qué paquetes y versiones instalar para las apps. Para instalar la biblioteca de Cloud NDB en el entorno de ejecución de Python 3, agrega la siguiente línea al archivo requirements.txt de la app:

google-cloud-ndb

App Engine sube de manera automática todas las bibliotecas del archivo requirements.txt de la app cuando la implementas.

Instala las dependencias de manera local

Cuando desarrolles y pruebes la app de forma local, te recomendamos que uses un entorno virtual para aislar las dependencias de la app de los paquetes del sistema. Esto garantiza que la app solo cargue las dependencias que declaraste en el archivo requirements.txt de la app y que sincronice las versiones de dependencia entre tus entornos locales y de producción.

En Python 2, puedes usar virtualenv para crear un entorno virtual.

En Python 3, venv es la forma recomendada de crear un entorno virtual.

Actualiza las declaraciones de importación

La ubicación del módulo NDB se cambió a google.cloud.ndb. Actualiza las declaraciones de importación de la app como se muestra en la siguiente tabla:

Crea un cliente de Cloud NDB

Al igual que con otras bibliotecas cliente que se basan en las API de Google Cloud, el primer paso para usar Cloud NDB es crear un objeto Client. El cliente contiene credenciales y otros datos necesarios para conectarse al modo Datastore. Por ejemplo:

from google.cloud import ndb

client = ndb.Client()

En la situación de autorización predeterminada que se describió antes, en el cliente de Cloud NDB hay credenciales de la cuenta de servicio predeterminada de App Engine, que está autorizada para interactuar con el modo Datastore. Si no trabajas en esta situación predeterminada, consulta credenciales predeterminadas de la aplicación (ADC) para obtener información sobre cómo proporcionarlas.

Usa el contexto de entorno de ejecución del cliente

Además de proporcionar las credenciales necesarias para interactuar con el modo Datastore, en el cliente de Cloud NDB está el método context(), que muestra un contexto de entorno de ejecución. El contexto de entorno de ejecución aísla las solicitudes de transacción y almacenamiento en caché de otras interacciones simultáneas del modo Datastore.

Todas las interacciones con el modo Datastore deben ocurrir dentro de un contexto de entorno de ejecución de NDB. Dado que la creación de una definición de modelo no interactúa con el modo Datastore, puedes definir tu clase de modelo antes de crear un cliente de Cloud NDB, recuperar un contexto de entorno de ejecución y, luego, usarlo en el controlador de solicitudes para obtener datos de la base de datos.

Por ejemplo:

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())

Apps con varios subprocesos

El contexto del entorno de ejecución que muestra el cliente de Cloud NDB solo se aplica a un subproceso. Si la app usa varios subprocesos para una sola solicitud, debes recuperar un contexto de entorno de ejecución independiente para cada subproceso que usará la biblioteca de Cloud NDB.

Usa un contexto de entorno de ejecución con frameworks WSGI

Si tu app web usa un framework WSGI, puedes crear de forma automática un nuevo contexto de entorno de ejecución para cada solicitud mediante la creación de un objeto middleware que recupera el contexto de entorno de ejecución y, luego, une la app al objeto middleware.

El siguiente es un ejemplo del uso de middleware con Flask:

• El método middleware crea un objeto middleware WSGI intermedio dentro del contexto de entorno de ejecución del cliente de NDB.

• La app de Flask está unida al objeto middleware.

• Flask pasará cada solicitud a través del objeto middleware, que recupera un nuevo contexto de entorno de ejecución de NDB para cada solicitud.

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])

Usa un contexto de entorno de ejecución con Django

El middleware de Django que proporciona la biblioteca de App Engine NDB no es compatible con la biblioteca de Cloud NDB. Si usaste este middleware (google.appengine.ext.ndb.django_middleware) en la app, sigue estos pasos para actualizarla:

1. Usa el sistema de middleware de Django con el fin de crear un nuevo contexto de entorno de ejecución para cada solicitud.

   En el ejemplo que se incluye a continuación, se ilustra lo siguiente:

   • El método ndb_django_middleware crea un cliente de Cloud NDB.

   • El método middleware crea un objeto middleware dentro del contexto del entorno de ejecución del cliente de NDB.

   datastore/cloud-ndb/django_middleware.py

   Ver en GitHub
   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. En el archivo settings.py de Django, actualiza la configuración de MIDDLEWARE para que enumere el nuevo middleware que creaste en lugar de google.appengine.ext.ndb.NdbDjangoMiddleware.

Django ahora pasará cada solicitud a través del objeto de middleware que enumeraste en la configuración de MIDDLEWARE, y este objeto recuperará un nuevo contexto de entorno de ejecución NDB para cada solicitud.

Actualiza el código de las API de NDB que se quitaron o modificaron

Las API de NDB que dependen de los servicios y las API específicas de App Engine se actualizaron o quitaron de la biblioteca de Cloud NDB.

Deberás actualizar tu código si se usa cualquiera de las siguientes API de NDB:

• google.appengine.ext.ndb.Model y propiedades de modelos
• google.appengine.ext.ndb.Key
• google.appengine.ext.ndb.query.QueryOptions y PropertyOrder
• google.appengine.ext.ndb.utils
• google.appengine.api.namespacemanager
• google.appengine.api.ext.ndb.tasklets
• google.appengine.api.datastore_errors

Modelos y propiedades de modelos

Los siguientes métodos de google.appengine.ext.ndb.Model no están disponibles en la biblioteca de Cloud NDB porque usan las API específicas de App Engine que ya no están disponibles.

En la siguiente tabla, se describen las propiedades específicas de google.appengine.ext.ndb.Model que cambiaron en la biblioteca de Cloud NDB:

Las clases y los métodos de la siguiente tabla ya no están disponibles porque usan recursos específicos de App Engine que ya no están disponibles.

Claves

Los siguientes métodos de google.appengine.ext.ndb.Key no están disponibles en la biblioteca de Cloud NDB. Estos métodos se usaban para pasar claves desde y hacia la API de DB de Datastore, que ya no es compatible (DB era el predecesor de App Engine NDB).

Además, ten en cuenta los siguientes cambios:

Consultas

Al igual que App Engine NDB, Cloud NDB proporciona una clase QueryOptions (google.cloud.ndb.query.QueryOptions) que te permite volver a usar un conjunto específico de opciones de consulta en lugar de volver a definirlas. Sin embargo, QueryOptions en Cloud NDB no hereda de google.appengine.datastore.datastore_rpc.Configuration y, por lo tanto, no es compatible con métodos ...datastore_rpc.Configuration.

Además, google.appengine.datastore.datastore_query.Order se reemplazó por google.cloud.ndb.query.PropertyOrder. Al igual que Order, la clase PropertyOrder te permite especificar el orden de clasificación en varias consultas. El constructor de PropertyOrder es el mismo que el constructor de Order. Solo cambió el nombre de la clase.

Utils

El módulo ndb.utils (google.appengine.ext.ndb.utils) ya no está disponible. La mayoría de los métodos en ese módulo eran internos de App Engine NDB. Algunos métodos se descartaron debido a diferencias de implementación en la nueva ndb, mientras que otros métodos quedaron obsoletos por las nuevas funciones de Python 3. Una pequeña cantidad de los métodos permanecen disponibles para facilitar la migración.

Por ejemplo, el decorador posicional en el módulo utils anterior declaraba que solo los primeros argumentos n de una función o un método pueden ser posicionales. Sin embargo, Python 3 puede hacerlo mediante el uso de argumentos solo de palabras clave. Lo que solía escribirse de la siguiente manera:

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

Se puede escribir así en Python 3:

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

Espacios de nombres

Los espacios de nombres habilitan una aplicación multiusuario a fin de usar sistemas aislados de datos independientes para cada usuario mientras se usa la misma base de datos en modo Datastore. Es decir, cada usuario almacena los datos en su propio espacio de nombres.

En lugar de usar el google.appengine.api.namespacemanager específico de App Engine, debes especificar un espacio de nombres predeterminado cuando creas un cliente de Cloud NDB. Luego, usa el espacio de nombres predeterminado mediante una llamada a los métodos de Cloud NDB en el contexto del entorno de ejecución del cliente. Esto sigue el mismo patrón que otras API de Google Cloud que admiten espacios de nombres.

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

Ahora Tasklets puede usar una declaración return estándar para mostrar un resultado en lugar de generar una excepción Return. Por ejemplo:

        @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
        

Ten en cuenta que aún puedes mostrar resultados en Cloud NDB si generas una excepción Return, pero no es recomendable.

Además, los siguientes métodos y subclases de Tasklets ya no están disponibles debido, en gran medida, a los cambios en la creación y el uso de un contexto de NDB en la biblioteca de Cloud NDB.

Excepciones

Si bien en el módulo google.cloud.ndb.exceptions de la biblioteca de Cloud NDB hay muchas de las excepciones de la biblioteca de App Engine NDB, no todas las excepciones anteriores están disponibles en la biblioteca nueva. En la siguiente tabla, se enumeran las excepciones que ya no están disponibles:

Habilita el almacenamiento en caché de datos

Cloud NDB puede almacenar datos en caché en un almacén de datos en memoria de Redis administrado por Memorystore, Redis Labs y otros sistemas. En esta guía, se describe cómo usar Memorystore para Redis a fin de almacenar datos en caché.

1. Configura el Acceso a VPC sin servidores.

2. Configura Memorystore para Redis.

3. Agrega la URL de conexión de Redis a tu app.

4. Crea un objeto RedisCache.

Configura el Acceso a VPC sin servidores

La app solo puede comunicarse con Memorystore a través de un conector de Acceso a VPC sin servidores. Para configurar un conector de Acceso a VPC sin servidores, haz lo siguiente:

1. Crea un conector de Acceso a VPC sin servidores.

2. Configura la app para usar el conector.

Configura Memorystore para Redis

Si deseas configurar Memorystore para Redis, debes hacer lo siguiente:

1. Crea una instancia de Redis en Memorystore. Cuando crees la instancia, ten en cuenta lo siguiente:

   • En Región, selecciona la misma región en la que se encuentra la app de App Engine.

   • En Red autorizada, selecciona la misma red que usa tu conector de Acceso a VPC sin servidores.

2. Anota la dirección IP y el número de puerto de la instancia de Redis que crees. Usarás esta información cuando habilites el almacenamiento en caché de datos para Cloud NDB.

   Asegúrate de usar el comando de gcloud beta para implementar las actualizaciones de la app. Solo el comando beta puede actualizar la app para que use un conector de VPC.

Agrega la URL de conexión de Redis

Puedes conectarte a la caché de Redis si agregas la variable de entorno REDIS_CACHE_URL al archivo app.yaml de la app. El valor de REDIS_CACHE_URL tiene el siguiente formato:

redis://IP address for your instance:port

Por ejemplo, puedes agregar las siguientes líneas al archivo app.yaml de la app:

     env_variables:
      REDIS_CACHE_URL: redis://10.0.0.3:6379

Crea y usa un objeto almacenado en caché de Redis

Si configuraste REDIS_CACHE_URL como una variable de entorno, puedes crear un objeto RedisCache con una sola línea de código y pasar la caché a Client.context() cuando configures el contexto del entorno de ejecución:

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())

Si no configuras REDIS_CACHE_URL como una variable de entorno, deberás construir un cliente de Redis y pasar el cliente al constructor ndb.RedisCache(). Por ejemplo:

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

Ten en cuenta que no es necesario declarar una dependencia en la biblioteca cliente de Redis, ya que la biblioteca de Cloud NDB ya depende de la biblioteca cliente de Redis.

Consulta la aplicación de muestra de Memorystore para ver un ejemplo de cómo construir un cliente de Redis.

Prueba las actualizaciones

Para configurar una base de datos de prueba y ejecutar la app de manera local antes de implementarla en App Engine, sigue estos pasos:

1. Ejecuta el emulador local del modo Datastore para almacenar y recuperar datos.

   Asegúrate de seguir las instrucciones para configurar las variables de entorno a fin de que la app se conecte al emulador en lugar de al entorno de producción del modo Datastore.

   También puedes importar datos al emulador si deseas comenzar tu prueba con datos precargados en la base de datos.

2. Usa el servidor de desarrollo local para ejecutar la app.

   Para asegurarte de que la variable de entorno GOOGLE_CLOUD_PROJECT se configure de forma correcta durante el desarrollo local, inicializa dev_appserver mediante el siguiente parámetro:

   --application=PROJECT_ID

   PROJECT_ID debe ser el ID del proyecto de Google Cloud. Para encontrar el ID del proyecto, ejecuta el comando gcloud config list project o consulta la página del proyecto en Google Cloud Console.

Implementa tu app

Una vez que la app se ejecute en el servidor de desarrollo local sin errores, haz lo siguiente:

1. Prueba la app en App Engine.

2. Si la app se ejecuta sin errores, usa la división de tráfico para aumentar el tráfico de la app actualizada. Supervísala de cerca a fin de detectar cualquier problema en la base de datos antes de enrutar más tráfico a la app actualizada.