Migrer vers la bibliothèque cliente Cloud pour Cloud Storage

Cloud Storage permet à votre application de diffuser des objets de données de grande taille, tels que des fichiers vidéo ou image, et de transférer des fichiers de données volumineux. App Engine fournit sa propre bibliothèque cliente dans l'environnement d'exécution Python 2 pour écrire et lire des objets dans Cloud Storage. Cette bibliothèque n'est pas disponible dans les environnements d'exécution App Engine plus récents, y compris l'environnement d'exécution Python 3.

Si votre application Python 2 utilise la bibliothèque GoogleAppEngineCloudStorageClient, vous devez migrer vers la bibliothèque cliente Cloud pour Cloud Storage avant de pouvoir exécuter l'application dans l'environnement d'exécution Python 3. Notez qu'il vous suffit de faire migrer votre application pour utiliser une nouvelle bibliothèque cliente. L'ensemble des objets de données et des autorisations de vos buckets Cloud Storage existants restent inchangés. Vous pouvez y accéder à l'aide de la nouvelle bibliothèque cliente.

Comparaison des bibliothèques clientes App Engine et Cloud

Similitudes :

La bibliothèque cliente Cloud est compatible avec toutes les fonctionnalités Cloud Storage activées par la bibliothèque cliente App Engine, telles que la lecture, l'écriture, la suppression et la création de listes d'objets. La migration ne nécessite que de légères modifications du code.

La bibliothèque cliente Cloud est également compatible avec d'autres fonctionnalités, telles que la création et l'ajout de libellés aux buckets, et la récupération d'anciennes versions d'objets.

Différences :

Dans la bibliothèque App Engine, la fonction qui récupère une liste d'objets fonctionne de manière asynchrone. La bibliothèque cliente Cloud ne fournit pas de fonction asynchrone pour répertorier les objets, mais vous pouvez parcourir et itérer un petit ensemble d'objets.
La bibliothèque cliente App Engine nécessite d'utiliser des listes de contrôle d'accès (LCA) pour contrôler l'accès aux buckets et aux objets. Toutefois, Cloud Storage et la bibliothèque cliente Cloud proposent deux systèmes permettant aux utilisateurs d'accéder à vos buckets et objets : les LCA et l'accès uniforme au niveau du bucket. L'accès uniforme au niveau du bucket offre une expérience de contrôle des accès plus simple et cohérente sur l'ensemble de vos ressources Cloud.

Toutes les LCA utilisées avec la bibliothèque cliente App Engine restent actives pour vos buckets existants après la migration vers la bibliothèque cliente Cloud. Vous pouvez donc continuer à les utiliser le cas échéant.

Si l'accès uniforme au niveau du bucket répond à vos besoins, nous vous recommandons d'utiliser ce système plus simple pour tous les buckets que vous créez. Bien que vous puissiez convertir des buckets existants pour utiliser un accès uniforme au niveau du bucket, cela peut nécessiter des changements importants dans la manière dont votre application sécurise l'accès à ses objets de stockage.

Exemples de code :

Opérations de stockage de base à l'aide des API App Engine
Opérations de stockage de base à l'aide de la bibliothèque cliente Cloud pour Cloud Storage

Avant de commencer la migration

Si ce n'est pas déjà fait, configurez votre environnement de développement Python pour utiliser une version de Python compatible avec Google Cloud et installez des outils de test pour créer des environnements Python isolés.

Comprendre les autorisations Cloud Storage

Le compte de service par défaut créé automatiquement de votre application dispose de droits de lecture et d'écriture sur les buckets de votre projet, et de droits complets sur les objets créés avant et après la migration.

Si vous avez choisi un autre compte de service ou compte utilisateur pour accéder de manière sécurisée à vos buckets et objets Cloud Storage, assurez-vous de continuer à utiliser ces comptes et ces techniques d'authentification avant et après la migration.

Présentation du processus de migration

Pour migrer votre application Python afin d'utiliser la bibliothèque cliente Cloud pour Cloud Storage au lieu de la bibliothèque cliente App Engine, procédez comme suit :

Installez la bibliothèque cliente Cloud pour Cloud Storage.
Modifiez le code pour qu'il utilise la bibliothèque cliente Cloud.
Testez vos mises à jour.
Déployez l'application sur App Engine.

Installer la bibliothèque cliente Cloud pour Cloud Storage

Pour que la bibliothèque cliente Cloud pour Cloud Storage soit disponible pour votre application lorsqu'elle s'exécute dans App Engine, procédez comme suit :

Mettez à jour le fichier app.yaml :
1. Si vous utilisez les bibliothèques clientes Cloud, ajoutez les dernières versions des bibliothèques grpcio et setuptools.
2. Ajoutez la bibliothèque ssl, car elle est requise par Cloud Storage.
Voici un exemple de fichier app.yaml :
```
runtime: python27
threadsafe: yes
api_version: 1

libraries:
- name: grpcio
  version: 1.0.0
- name: setuptools
  version: 36.6.0
- name: ssl
  version: latest
```
Certaines bibliothèques clientes n'ont pas besoin de la bibliothèque SSL. Si vous n'ajoutez pas la bibliothèque SSL à une bibliothèque cliente qui en a besoin, une erreur SSL s'affiche dans l'explorateur de journaux lorsque votre application reçoit une requête.
Mettez à jour le fichier requirements.txt en ajoutant les bibliothèques clientes cloud pour Cloud Storage à votre liste de dépendances :
```
google-cloud-storage==1.24.1
```
Nous vous recommandons d'utiliser la version 1.24.1 de la bibliothèque cliente Cloud Storage, car elle accepte les applications Python 2.7.

Exécutez ensuite pip install -t lib -r requirements.txt pour mettre à jour la liste des bibliothèques disponibles pour votre application.
Pour les applications Python 2, si votre application utilise des bibliothèques intégrées ou copiées, vous devez spécifier ces chemins d'accès dans le fichier 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)
```
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')
```

Modifier le code pour utiliser la bibliothèque cliente Cloud

Créer un client Cloud Storage

Vous devez créer un objet Client pour utiliser la bibliothèque cliente Cloud pour Cloud Storage. Le client contient des identifiants et d'autres données nécessaires pour se connecter à Cloud Storage. Exemple :

from google.cloud import storage

client = storage.Client()

Dans le scénario d'autorisation par défaut décrit précédemment, le client Cloud Storage contient les identifiants du compte de service par défaut d'App Engine, qui est autorisé à interagir avec les buckets et les objets de votre projet. Si vous n'appliquez pas ce scénario par défaut, consultez la section sur les identifiants par défaut de l'application (ADC, Application Default Credentials) pour savoir comment fournir des identifiants.

Utiliser les méthodes de la bibliothèque cliente Cloud

Le tableau suivant récapitule les méthodes de la bibliothèque cliente Cloud à utiliser lors de la mise en œuvre de fonctionnalités Cloud Storage spécifiques.

Fonctionnalité Cloud Storage	Méthodes du client Cloud
Répertorier les objets d'un bucket	`Client.list_blobs` Découvrez un exemple de code simple et un exemple d'émulation du mode d'un répertoire. Pour parcourir la liste d'objets, définissez la propriété `pages` de l'objet itérateur renvoyé par `Client.list_blobs`.
Écrire dans l'espace de stockage	`blob.upload_from_file` `blob.upload_from_filename` `blob.upload_from_string` Consultez un exemple de code.
Spécifier des LCA	Pour appliquer une LCA prédéfinie, définissez le paramètre `predefined_acl` lorsque vous créez un bucket ou un objet. Si vous souhaitez bénéficier d'un contrôle plus précis, utilisez `bucket.acl.reload()` ou `blob.acl.reload()` pour récupérer les LCA actuellement définies. Appliquez ensuite les méthodes `ACL` pour ajouter ou supprimer des LCA. Consultez un exemple de code.
Lire des données à partir de l'espace de stockage	`blob.download_to_file` `blob.download_to_filename` `blob.download_as_string` Consultez un exemple de code.
Supprimer un objet	`blob.delete` Consultez un exemple de code.
Copier un objet	`bucket.copy_blob` Consultez un exemple de code.
Lire les métadonnées d'un objet	`blob.propertyname` et `blob.metadata` Consultez un exemple de code.

Tester vos mises à jour

Vous pouvez tester les mises à jour de votre application dans un environnement local, mais toutes les requêtes Cloud Storage doivent être envoyées par Internet à un bucket Cloud Storage réel. Ni App Engine ni Cloud Storage ne proposent d'émulateur Cloud Storage.

Pour en savoir plus sur les tests des applications Python 2, consultez Utiliser le serveur de développement local.

Pour en savoir plus sur les tests des applications Python 3, consultez Tester et déployer une application.

Déployer l'application

Lorsque vous êtes prêt à déployer votre application, vous devez effectuer les opérations suivantes :

Testez l'application sur App Engine.
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 avant d'acheminer davantage de trafic vers cette application.