Migrer vers Cloud NDB

Zones App Engine

App Engine est régional, ce qui signifie que l'infrastructure qui exécute vos applications est située dans une région spécifique, et que Google la gère de sorte qu'elle soit disponible de manière redondante dans toutes les zones de cette région.

Lors de la sélection d'une région dans laquelle exécuter vos applications, vous devez tout d'abord considérer vos exigences en matière de latence, de disponibilité et de durabilité. Vous pouvez généralement sélectionner la région la plus proche des utilisateurs de votre application, mais pensez aussi aux emplacements où App Engine est disponible ainsi qu'aux emplacements des autres produits et services Google Cloud que votre application utilise. L'utilisation de services situés dans des emplacements différents peut avoir des répercussions sur la latence de votre application, ainsi que sur les tarifs.

Une fois que vous avez défini la région d'une application, vous ne pouvez plus la modifier.

Si vous avez déjà créé une application App Engine, vous pouvez afficher sa région en effectuant l'une des opérations suivantes :

Cloud NDB est une bibliothèque cliente pour Python qui remplace App Engine NDB.

App Engine NDB permet aux applications Python 2 de stocker et d'interroger des données dans des bases de données Firestore en mode Datastore (Datastore). Cloud NDB permet aux applications Python 3 de stocker et d'interroger des données dans les mêmes bases de données. Elle utilise Datastore comme produit qui gère ces bases de données. Bien que la bibliothèque Cloud NDB puisse accéder à toutes les données créées avec App Engine NDB, certains types de données structurées stockées à l'aide de Cloud NDB sont inaccessibles avec App Engine NDB. Pour cette raison, la migration vers Cloud NDB doit être considérée comme irréversible.

Les versions plus récentes de Cloud NDB ne sont compatibles qu'avec Python 3. Les versions précédentes étaient compatibles avec Python 2 et Python 3. Pour migrer votre application Python 2 vers Python 3, nous vous recommandons de procéder comme suit:

  1. Migrer vers Cloud NDB, version 1.11.2 Il s'agit de la version finale compatible avec Python 2.
  2. Mettez à niveau votre application vers Python 3.
  3. Passez à la dernière version stable de Cloud NDB.

Cette approche incrémentielle de la migration vous permet de maintenir une application fonctionnelle et testable tout au long du processus.

Cloud NDB est destiné aux développeurs Python qui connaissent App Engine NDB et qui souhaitent moderniser leurs applications. La migration vers Cloud NDB vous aide à préparer votre application Python 2 pour Python 3 et vous permet d'abandonner App Engine ultérieurement si vous le souhaitez.

Pour en savoir plus sur Cloud NDB, consultez les pages suivantes:

Comparaison entre App Engine NDB et Cloud NDB

Similitudes :

  • Cloud NDB est compatible avec presque toutes les fonctionnalités acceptées par App Engine NDB, avec seulement des différences mineures dans la syntaxe des méthodes.

Différences :

  • Les API App Engine NDB qui reposent sur les services spécifiques à l'environnement d'exécution Python 2.7 d'App Engine ont été mises à jour ou supprimées de Cloud NDB.

  • Grâce aux nouvelles fonctionnalités de Python 3 et Django, vous n'avez plus besoin de google.appengine.ext.ndb.django_middleware. À la place, vous pouvez facilement écrire votre propre middleware en quelques lignes de code.

  • Les applications App Engine NDB et la base de données Datastore doivent se trouver dans le même projet Google Cloud. App Engine fournit automatiquement les identifiants. Cloud NDB peut accéder aux bases de données en mode Datastore dans n'importe quel projet, à condition que vous authentifiiez correctement votre client. Ceci assure une cohérence avec les autres API et bibliothèques clientes Google Cloud.

  • Cloud NDB n'utilise pas le service Memcache d'App Engine pour mettre en cache des données.

    À la place, Cloud NDB peut mettre en cache des données dans un datastore en mémoire Redis géré par Memorystore, Redis Labs ou d'autres systèmes. Bien que seuls les datastores Redis soient actuellement compatibles, Cloud NDB a généralisé et défini une mise en cache dans l'interface abstraite GlobalCache, qui peut prendre en charge d'autres mises en œuvres concrètes.

    Pour accéder à Memorystore pour Redis, votre application doit utiliser l'accès au VPC sans serveur.

    Memorystore pour Redis et l'accès au VPC sans serveur ne proposent pas de version gratuite. En outre, ces produits peuvent ne pas être disponibles dans la région de votre application. Pour en savoir plus, consultez la section Avant de commencer la migration.

La liste complète des différences est disponible dans les notes de migration du projet GitHub Cloud NDB.

Exemples de code :

Avant de commencer la migration

Avant de commencer la migration, suivez les étapes suivantes :

  1. Déterminez si vous devez mettre en cache des données.

  2. Si vous devez mettre en cache des données, assurez-vous que la région de votre application est compatible avec l'accès au VPC sans serveur et Memorystore pour Redis.

  3. Assurez-vous de bien comprendre les autorisations liées au mode Datastore.

Déterminer si vous devez mettre en cache des données

Vous devez vous assurer que votre application nécessite une mise en cache, car Memorystore pour Redis et l'accès au VPC sans serveur ne proposent pas de version gratuite et ne sont pas compatibles avec toutes les régions Google Cloud.

En général :

  • Si votre application lit fréquemment les mêmes données, la mise en cache peut réduire la latence.

  • Plus votre application traite de requêtes, plus l'impact de la mise en cache peut être important.

Pour connaître votre utilisation actuelle des données mises en cache, consultez le tableau de bord Memcache et observez le ratio entre les succès de cache et les défauts de cache. Si ce ratio est élevé, l'utilisation d'un cache de données est susceptible de réduire grandement la latence de votre application.

Consulter le tableau de bord Memcache

Pour en savoir plus sur la tarification, consultez les tarifs de Memorystore ainsi que les tarifs de l'accès au VPC sans serveur.

Vérifier la région de votre application

Si vous devez mettre en cache des données, assurez-vous que la région de votre application est compatible avec Memorystore pour Redis et l'accès au VPC sans serveur :

  1. Consultez la région de votre application, qui apparaît en haut du tableau de bord App Engine de la console Google Cloud.

    Ouvrir le tableau de bord

    La région apparaît en haut de la page, juste en dessous de l'URL de votre application.

  2. Vérifiez que votre application se situe bien dans l'une des régions compatibles avec l'accès au VPC sans serveur.

  3. Vérifiez également qu'elle se trouve dans l'une des régions compatibles avec Memorystore pour Redis en accédant à la page "Créer un connecteur" et en consultant les régions dans la liste Régions.

    Afficher la page "Créer un connecteur"

Si votre application ne se situe pas dans une région compatible avec Memorystore pour Redis et l'accès au VPC sans serveur, procédez comme suit :

  1. Créez un projet Google Cloud.

  2. Créez une application App Engine dans le projet et sélectionnez une région compatible.

  3. Créez les services Google Cloud utilisés par votre application dans le nouveau projet.

    Vous pouvez également mettre à jour votre application pour qu'elle exploite les services existants de votre ancien projet, mais la tarification et l'utilisation des ressources peuvent être différentes lorsque vous utilisez les services d'un projet et d'une région distincts. Pour en savoir plus, consultez la documentation de chaque service.

  4. Déployez votre application sur le nouveau projet.

Comprendre les autorisations liées au mode Datastore

Chaque interaction avec un service Google Cloud doit être autorisée. Par exemple, pour stocker ou interroger des données dans une base de données en mode Datastore, votre application doit fournir les identifiants d'un compte autorisé à accéder à la base de données.

Par défaut, votre application fournit les identifiants du compte de service App Engine par défaut, autorisé à accéder aux bases de données du même projet que votre application.

Vous devez utiliser une autre technique d'authentification qui fournit explicitement des identifiants si l'une des conditions suivantes est remplie :

  • Votre application et la base de données en mode Datastore se trouvent dans des projets Google Cloud différents.

  • Vous avez modifié les rôles attribués au compte de service App Engine par défaut.

Pour plus d'informations sur les autres techniques d'authentification, consultez la page Configurer l'authentification pour des applications de production serveur à serveur.

Présentation du processus de migration

Pour migrer vers Cloud NDB à partir d'App Engine NDB:

  1. Mettez à jour votre application Python :

    1. Installez la bibliothèque cliente Cloud NDB.

    2. Mettez à jour les instructions d'importation pour importer des modules depuis Cloud NDB.

    3. Ajoutez le code qui crée un client Cloud NDB. Le client peut lire les variables d'environnement de votre application et utiliser les données pour s'authentifier en mode Datastore.

    4. Ajoutez le code qui utilise le contexte d'exécution du client pour maintenir la mise en cache et les transactions séparées entre les threads.

    5. Supprimez ou mettez à jour le code qui utilise des méthodes et des propriétés obsolètes.

  2. Activez la mise en cache.

  3. Testez vos mises à jour.

  4. Déployez l'application sur App Engine.

    Comme pour toute modification apportée à votre application, envisagez d'utiliser la répartition du trafic afin d'augmenter le trafic progressivement. Surveillez attentivement les éventuels problèmes de base de données avant d'acheminer davantage de trafic vers l'application mise à jour.

Mettre à jour votre application Python

Installer la bibliothèque Cloud NDB pour les applications Python 2

  1. Créez un répertoire pour stocker les bibliothèques tierces, par exemple lib/.

  2. Créez un fichier requirements.txt dans le même dossier que votre fichier app.yaml et ajoutez le nom d'une bibliothèque cliente :

    google-cloud-ndb==1.11.2

  3. Utilisez pip (version 6 ou ultérieure) avec l'option -t <directory> pour installer les bibliothèques dans le dossier que vous avez créé à l'étape précédente. Exemple :

    pip install -t lib -r requirements.txt

  4. Spécifiez les bibliothèques RPC et setuptools dans la section libraries de votre fichier app.yaml :

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

  5. Créez un fichier appengine_config.py dans le même dossier que votre fichier app.yaml si vous n'en avez pas déjà un. Ajoutez le code ci-dessous à votre fichier 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)

    Veillez à exploiter le module pkg_resources, qui garantit que votre application utilise la bonne distribution des bibliothèques clientes.

    Le fichier appengine_config.py de l'exemple précédent suppose que le dossier lib se trouve dans le répertoire de travail actuel. Si vous ne pouvez pas garantir que lib sera toujours dans le répertoire de travail actuel, spécifiez le chemin d'accès complet au dossier lib. Exemple :

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

Lorsque vous déployez votre application, App Engine importe toutes les bibliothèques du répertoire que vous avez spécifié dans le fichier appengine_config.py.

Installer la bibliothèque Cloud NDB pour les applications Python 3

L'environnement d'exécution Python 3 d'App Engine utilise le fichier requirements.txt d'une application pour déterminer les packages et les versions à installer pour les applications. Pour installer la bibliothèque Cloud NDB dans l'environnement d'exécution Python 3, ajoutez la ligne suivante au fichier requirements.txt de votre application :

google-cloud-ndb

App Engine importe automatiquement toutes les bibliothèques dans le fichier requirements.txt de l'application lorsque vous déployez l'application.

Installer les dépendances en local

Si vous développez et testez votre application en local, nous vous recommandons vivement d'utiliser un environnement virtuel pour isoler les dépendances de votre application de vos packages système. Ainsi, votre application ne chargera que les dépendances que vous avez déclarées dans le fichier requirements.txt de votre application et synchronisera les versions de dépendance entre vos environnements local et de production.

Dans Python 2, vous pouvez utiliser virtualenv pour créer un environnement virtuel.

Dans Python 3, venv est la méthode recommandée pour créer un environnement virtuel.

Mettre à jour les instructions d'importation

Le module NDB a été déplacé vers l'emplacement google.cloud.ndb. Mettez à jour les instructions d'importation de votre application comme indiqué dans le tableau suivant :

Retirer Remplacer par
from google.appengine.ext import ndb from google.cloud import ndb

Créer un client Cloud NDB

Comme pour les autres bibliothèques clientes basées sur les API Google Cloud, la première étape de l'utilisation de Cloud NDB consiste à créer un objet Client. Le client contient des identifiants et d'autres données nécessaires pour se connecter en mode Datastore. Exemple :

from google.cloud import ndb

client = ndb.Client()

Dans le scénario d'autorisation par défaut décrit précédemment, le client Cloud NDB contient les identifiants du compte de service par défaut d'App Engine, autorisé à interagir avec le mode Datastore. Si vous n'appliquez pas ce scénario par défaut, consultez la section sur les identifiants par défaut de l'application pour savoir comment fournir des identifiants.

Utiliser le contexte d'exécution du client

En plus de fournir les identifiants nécessaires pour interagir avec le mode Datastore, le client Cloud NDB contient la méthode context() qui renvoie un contexte d'exécution. Le contexte d'exécution isole les requêtes de mise en cache et de transaction des autres interactions simultanées en mode Datastore.

Toutes les interactions en mode Datastore doivent se produire dans un contexte d'exécution NDB. Comme la création d'une définition de modèle n'interagit pas avec le mode Datastore, vous pouvez définir votre classe de modèle avant de créer un client Cloud NDB et de récupérer un contexte d'exécution, puis utiliser ce contexte d'exécution dans le gestionnaire de requêtes afin d'obtenir les données de la base de données.

Exemple :

datastore/cloud-ndb/quickstart.py
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())

Applications multithread

Le contexte d'exécution renvoyé par le client Cloud NDB ne s'applique qu'à un seul thread. Si votre application utilise plusieurs threads pour une même requête, vous devez récupérer un contexte d'exécution distinct pour chaque thread qui utilise la bibliothèque Cloud NDB.

Utiliser un contexte d'exécution avec les frameworks WSGI

Si votre application Web utilise un framework WSGI, vous pouvez créer automatiquement un contexte d'exécution pour chaque requête en créant un objet de middleware qui récupère le contexte d'exécution, puis en encapsulant l'application dans cet objet.

Dans l'exemple suivant d'utilisation de middleware avec Flask :

  • La méthode middleware crée un objet de middleware WSGI dans le contexte d'exécution du client NDB.

  • L'application Flask est encapsulée dans l'objet de middleware.

  • Flask transmet ensuite chaque requête via l'objet de middleware, qui récupère un nouveau contexte d'exécution NDB pour chaque requête.

datastore/cloud-ndb/flask_app.py
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])

Utiliser un contexte d'exécution avec Django

Le middleware Django fourni par la bibliothèque App Engine NDB n'est pas compatible avec la bibliothèque Cloud NDB. Si vous avez utilisé ce middleware (google.appengine.ext.ndb.django_middleware) dans votre application, procédez comme suit pour la mettre à jour :

  1. Utilisez le système de middleware de Django pour créer un contexte d'exécution pour chaque requête.

    Dans l'exemple suivant :

    • La méthode ndb_django_middleware crée un client Cloud NDB.

    • La méthode middleware crée un objet de middleware dans le contexte d'exécution du client NDB.

    datastore/cloud-ndb/django_middleware.py
    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. Dans le fichier Django "settings.py", mettez à jour le paramètre MIDDLEWARE afin qu'il répertorie le nouveau middleware que vous avez créé plutôt que google.appengine.ext.ndb.NdbDjangoMiddleware.

Django transmet désormais chaque requête via l'objet de middleware que vous avez indiqué dans le paramètre MIDDLEWARE, et cet objet récupère un nouveau contexte d'exécution NDB pour chaque requête.

Mettre à jour le code associé aux API NDB supprimées ou modifiées

Les API NDB reposant sur des API et services spécifiques à App Engine ont été mises à jour ou supprimées de la bibliothèque Cloud NDB.

Vous devrez mettre à jour votre code s'il utilise l'une des API NDB suivantes :

Modèles et propriétés des modèles

Les méthodes suivantes de google.appengine.ext.ndb.Model ne sont pas disponibles dans la bibliothèque Cloud NDB, car elles utilisent des API spécifiques à App Engine qui ne sont plus disponibles.

API supprimée Remplacement
Model.get_indexes et
Model.get_indexes_async		 Aucun
Model._deserialize et
Model._serialize		 Aucun
Model.make_connection Aucun

Le tableau suivant décrit les propriétés google.appengine.ext.ndb.Model spécifiques qui ont été modifiées dans la bibliothèque Cloud NDB :

Valeur Modifier
TextProperty google.cloud.ndb.TextProperty ne peut pas être indexé. Si vous tentez de définir google.cloud.ndb.TextProperty.indexed, une erreur NotImplementedError est générée.
StringProperty StringProperty est toujours indexé. Si vous tentez de définir google.cloud.ndb.StringProperty.indexed, une erreur NotImplementedError est générée.
Toutes les propriétés ayant des arguments name ou kind dans le constructeur. name ou kind doivent être des types de données str, car unicode a été remplacé par str dans Python 3.

Les classes et les méthodes du tableau suivant ne sont plus disponibles, car elles utilisent des ressources spécifiques à App Engine qui ne sont plus disponibles.

API supprimée Remplacement
google.appengine.ext.ndb.msgprop.MessageProperty et
google.appengine.ext.ndb.msgprop.EnumProperty		 Aucun

Si vous essayez de créer ces objets, une exception NotImplementedError est générée.
Dans google.appengine.ext.ndb.model.Property :
_db_get_value
_db_set_value
_db_set_compressed_meaning
_db_set_uncompressed_meaning
__creation_counter_global		 Aucun

Ces méthodes reposent sur les tampons de protocole du mode Datastore qui ont été modifiés.
Model.make_connection Aucun

Clés

Les méthodes suivantes de google.appengine.ext.ndb.Key ne sont pas disponibles dans la bibliothèque Cloud NDB. Ces méthodes servaient à transmettre des clés depuis et vers l'API DB Datastore, qui n'est plus compatible (DB était le prédécesseur d'App Engine NDB).

API supprimée Remplacement
Key.from_old_key et
Key.to_old_key		 Aucun

Notez également les modifications suivantes :

App Engine NDB Cloud NDB
Les genres et les ID de chaîne ne doivent pas dépasser 500 octets. Les genres et les ID de chaîne ne doivent pas dépasser 1 500 octets.
Key.app() renvoie l'ID de projet que vous avez spécifié lors de la création de la clé. La valeur renvoyée par google.cloud.ndb.Key.app() peut être différente de l'ID d'origine transmis au constructeur. En effet, les ID d'application comportant un préfixe tels que s~example sont d'anciens identifiants App Engine. Ces ID ont été remplacés par des ID de projet équivalents, tels que example.

Requêtes

Tout comme App Engine NDB, Cloud NDB fournit une classe QueryOptions (google.cloud.ndb.query.QueryOptions) qui vous permet de réutiliser un ensemble spécifique d'options de requête au lieu de les redéfinir pour chaque requête. Cependant, QueryOptions dans Cloud NDB n'hérite pas de google.appengine.datastore.datastore_rpc.Configuration et ne permet donc pas d'utiliser les méthodes ...datastore_rpc.Configuration.

En outre, google.appengine.datastore.datastore_query.Order a été remplacé par google.cloud.ndb.query.PropertyOrder. À l'instar de Order, la classe PropertyOrder vous permet de spécifier l'ordre de tri pour plusieurs requêtes. Le constructeur de PropertyOrder est identique au constructeur de Order. Seul le nom de la classe a changé.

API supprimée Remplacement
Dans google.appengine.datastore.datastore_rpc.Configuration :
deadline(value)
on_completion(value)
read_policy(value)
force_writes(value)
max_entity_groups_per_rpc(value)
max_allocate_ids_keys(value)
max_rpc_bytes(value)
max_get_keys(value)
max_put_entities(value)
max_delete_keys(value)

Consultez le code source pour obtenir une description de ces méthodes.

 Aucun
google.appengine.ext.ndb.Order
Par exemple :
order=Order(-Account.birthday, Account.name)		 google.cloud.ndb.PropertyOrder
Par exemple :
google.cloud.ndb.PropertyOrder(-Account.birthday, Account.name)

Utils

Le module ndb.utils (google.appengine.ext.ndb.utils) n'est plus disponible. La plupart des méthodes de ce module étaient internes à App Engine NDB. Certaines méthodes ont été supprimées en raison des différences de mise en œuvre dans la nouvelle bibliothèque ndb, tandis que d'autres ont été rendues obsolètes par les nouvelles fonctionnalités de Python 3. Un petit nombre de méthodes reste disponible pour faciliter la migration.

Par exemple, le décorateur positionnel de l'ancien module utils déclarait que seuls les n premiers arguments d'une fonction ou d'une méthode pouvaient être positionnels. Toutefois, Python 3 permet ceci à l'aide d'arguments de mot clé uniquement. Ce qui était écrit auparavant comme suit :

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

Peut être écrit comme ceci dans Python 3 :

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

Espaces de noms

Les espaces de noms permettent à une application mutualisée d'utiliser des données cloisonnées séparées pour chaque locataire tout en exploitant la même base de données en mode Datastore. Autrement dit, chaque locataire stocke des données sous son propre espace de noms.

Au lieu d'utiliser google.appengine.api.namespacemanager, spécifique à App Engine, vous spécifiez un espace de noms par défaut lorsque vous créez un client Cloud NDB, puis vous utilisez cet espace en appelant les méthodes Cloud NDB dans le contexte d'exécution du client. Ceci suit le même modèle que les autres API Google Cloud qui acceptent les espaces de noms.

API supprimée Remplacement
google.appengine.api.namespace_manager.namespace_manager.set_namespace(str) et
google.appengine.api.namespacemanager.getnamespace()		 

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

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

key-non-default-namespace=ndb.Key("SomeKind," "AnotherId",
namespace="non-default-nspace")
Toutes les autres méthodes google.appengine.api.namespacemanager Aucun

Tasklets

Les tasklets peuvent désormais utiliser une instruction return standard pour renvoyer un résultat au lieu de générer une exception Return. Exemple :

Bibliothèque App Engine NDB Bibliothèque Cloud NDB 

        @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

Notez que vous pouvez toujours renvoyer des résultats dans Cloud NDB en générant une exception Return, mais ce n'est pas recommandé.

En outre, les méthodes et sous-classes Tasklets suivantes ne sont plus disponibles, principalement en raison des modifications concernant la création et l'utilisation du contexte NDB dans la bibliothèque Cloud NDB.

API supprimée Remplacement
Dans google.appengine.api.ext.ndb.tasklets :
add_flow_exception
make_context
make_default_context
set_context		 Aucun
Dans google.appengine.api.ext.ndb.tasklets :
QueueFuture
ReducedFuture
SerialQueueFuture		 Aucun

Exceptions

Bien que le module google.cloud.ndb.exceptions de la bibliothèque Cloud NDB contienne la plupart des exceptions de la bibliothèque App Engine NDB, toutes les anciennes exceptions ne sont pas disponibles dans la nouvelle bibliothèque. Le tableau suivant répertorie les exceptions qui ne sont plus disponibles :

API supprimée Remplacement
Dans google.appengine.api.datastore_errors :
BadKeyError
BadPropertyError
CommittedButStillApplying
EntityNotFoundError
InternalError
NeedIndexError
QueryNotFoundError
ReferencePropertyResolveError
Timeout
TransactionFailedError
TransactionNotFoundError		 google.cloud.ndb.exceptions

Activer la mise en cache des données

Cloud NDB peut mettre en cache des données dans un datastore en mémoire Redis géré par Memorystore, Redis Labs ou d'autres systèmes. Ce guide explique comment mettre en cache des données à l'aide de Memorystore pour Redis :

  1. Configurez l'accès au VPC sans serveur.

  2. Configurez Memorystore pour Redis.

  3. Ajoutez l'URL de connexion Redis à votre application.

  4. Créez un objet RedisCache.

Configurer l'accès au VPC sans serveur

Votre application ne peut communiquer avec Memorystore que via un connecteur d'accès au VPC sans serveur. Pour configurer un connecteur d'accès au VPC sans serveur, procédez comme suit :

  1. Créez un connecteur d'accès au VPC sans serveur.

  2. Configurez votre application pour qu'elle utilise le connecteur.

Configurer Memorystore pour Redis

Pour configurer Memorystore pour Redis :

  1. Créez une instance Redis dans Memorystore. Lors de la création de l'instance :

  2. Prenez note de l'adresse IP et du numéro de port de l'instance Redis que vous créez. Vous exploiterez ces informations au moment d'activer la mise en cache des données pour Cloud NDB.

    Veillez à utiliser la commande gcloud beta pour déployer les mises à jour de votre application. Seule la commande beta permet de mettre à jour votre application pour qu'elle exploite un connecteur VPC.

Ajouter l'URL de connexion Redis

Vous pouvez vous connecter au cache Redis en ajoutant la variable d'environnement REDIS_CACHE_URL au fichier app.yaml de votre application. La valeur de REDIS_CACHE_URL prend la forme suivante :

redis://IP address for your instance:port

Par exemple, vous pouvez ajouter les lignes suivantes au fichier app.yaml de votre application :

     env_variables:
      REDIS_CACHE_URL: redis://10.0.0.3:6379

Créer et utiliser un objet de cache Redis

Si vous avez défini REDIS_CACHE_URL comme variable d'environnement, vous pouvez créer un objet RedisCache avec une seule ligne de code, puis utiliser le cache en le transmettant à Client.context() lorsque vous configurez le contexte d'exécution :

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 vous ne définissez pas REDIS_CACHE_URL en tant que variable d'environnement, vous devez construire un client Redis et le transmettre au constructeur ndb.RedisCache(). Exemple :

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

Notez que vous n'avez pas besoin de déclarer une dépendance à la bibliothèque cliente Redis, car la bibliothèque Cloud NDB dépend déjà de la bibliothèque cliente Redis.

Pour obtenir un exemple de construction d'un client Redis, reportez-vous à l'exemple d'application Memorystore.

Tester vos mises à jour

Pour configurer une base de données de test et exécuter votre application en local avant de la déployer dans App Engine, procédez comme suit :

  1. Exécutez l'émulateur local du mode Datastore pour stocker et récupérer des données.

    Assurez-vous de suivre les instructions de définition des variables d'environnement pour que votre application se connecte bien à l'émulateur, et non à l'environnement en mode Datastore de production.

    Vous pouvez également importer des données dans l'émulateur si vous souhaitez démarrer votre test avec des données préchargées dans la base de données.

  2. Utilisez le serveur de développement local pour exécuter votre application.

    Pour vous assurer que la variable d'environnement GOOGLE_CLOUD_PROJECT est correctement définie lors du développement local, initialisez dev_appserver à l'aide du paramètre suivant :

    --application=PROJECT_ID

    PROJECT_ID doit être l'ID de votre projet Google Cloud. Vous pouvez trouver cet ID en exécutant la commande gcloud config list project ou en consultant la page de votre projet dans Google Cloud Console.

Déployer l'application

Une fois que votre application est exécutée sur le serveur de développement local sans erreur :

  1. Testez l'application sur App Engine.

  2. Si l'application s'exécute sans erreur, répartissez le trafic pour augmenter lentement le trafic de votre application mise à jour. Surveillez attentivement les éventuels problèmes de base de données avant d'acheminer davantage de trafic vers l'application mise à jour.