Migrer vers Cloud Endpoints Frameworks version 2.0

Cloud Endpoints Frameworks s'appelait auparavant Cloud Endpoints. Pour distinguer les deux versions, cette page fait référence à la nouvelle version en tant que Cloud Endpoints Frameworks version 2.0, et à l'ancienne version en tant que Cloud Endpoints version 1.0. Cette page explique comment migrer une application Cloud Endpoints version 1.0 vers Cloud Endpoints Frameworks version 2.0. Cette migration consiste en un changement de bibliothèque et de configuration d'application, mais ne nécessite aucun changement de code.

Avantages

Cloud Endpoints version 2.0 présente de nombreux avantages, par exemple :

Latence réduite des requêtes
Meilleure intégration aux fonctionnalités d'App Engine (telles que les domaines personnalisés)
Nouvelles fonctionnalités de gestion d'API

Cloud Endpoints Framework version 2.0 n'a aucune incidence sur les interfaces avec l'API. Les clients existants continuent de fonctionner après la migration sans aucune modification du code côté client.

Présentation des fonctionnalités

Les fonctionnalités suivantes sont rétrocompatibles avec Cloud Endpoints version 1.0 :

Protocole JSON-REST, utilisé par toutes les bibliothèques clientes Google
Service Discovery
Toutes les fonctionnalités d'authentification existantes (OAuth2/OpenID Connect)
Compatibilité avec les bibliothèques clientes pour les clients générés
CORS (pour les appelants JavaScript n'utilisant pas la bibliothèque cliente Google JavaScript)
Explorateur d'API

La répartition du trafic n'est pas disponible.

Fonctionnalités actuellement exclues

Les fonctionnalités suivantes ne sont pas disponibles. Si vous en avez besoin, veuillez soumettre une demande de fonctionnalité.

Protocole JSON-RPC, requis pour les anciens clients iOS. Si vous souhaitez créer des clients iOS pour l'API Endpoints Frameworks version 2.0, nous vous recommandons d'employer la bibliothèque cliente Objective-C d'API Google pour les API REST.
ETags automatiques
Champs kind automatiques
Intégration avec l'IDE
Réponses partielles grâce au paramètre fields
Création automatique de méthodes API PATCH

Migrer à partir de Cloud Endpoints version 1.0

Pour migrer à partir de la version 1.0, procédez comme suit :

Créez un sous-dossier nommé /lib dans le répertoire principal de votre application.
Installez la bibliothèque à partir du répertoire principal de l'application :
```
 pip install -t lib google-endpoints --ignore-installed
```
Supprimez les entrées - name: endpoints et version 1.0 du fichier app.yaml de l'application dans la section libraries. Exemple :
```
libraries:
- name: endpoints   #Remove
  version: 1.0      #Remove
```
Dans la section libraries du fichier app.yaml, ajoutez les éléments suivants :
```
libraries:
- name: pycrypto
  version: 2.6
- name: ssl
  version: 2.7.11
```
Endpoints Frameworks nécessite ces versions des bibliothèques pycrypto et ssl.
Dans la section handlers du fichier app.yaml, modifiez l'instruction url en remplaçant - url: /_ah/spi/.* par - url: /_ah/api/.*.
Dans le répertoire racine de votre application, créez ou modifiez un fichier nommé appengine_config.py pour inclure les éléments suivants :
```
from google.appengine.ext import vendor

vendor.add('lib')
```
Vérifiez la chaîne de version de l'API. La chaîne de version, spécifiée dans le décorateur @endpoints.api(version='v1', ...), apparaît dans le chemin d'accès de l'API. Si la chaîne de version est compatible avec la norme SemVer, seul le numéro de version majeure figure dans le chemin d'accès de l'API au moment de son déploiement. Par exemple, une API nommée echo avec la version 2.1.0 doit avoir un chemin d'accès tel que /echo/v2. Si vous mettez à jour l'API echo vers la version 2.2.0 et que vous déployez une modification rétrocompatible, le chemin d'accès demeure /echo/v2. Vous pouvez ainsi mettre à jour le numéro de version de l'API lors d'une modification rétrocompatible, sans rompre les chemins d'accès existants pour les clients. En revanche, si vous mettez à jour l'API echo vers la version 3.0.0 (dans le cadre du déploiement d'une modification destructive), le chemin d'accès est remplacé par /echo/v3.
Redéployez l'application Endpoints Frameworks.
Remarque : Lors de la migration, vous devez procéder au déploiement vers une nouvelle version d'App Engine. Si vous ne spécifiez pas de version, cette opération s'effectue automatiquement. Consultez la page Problèmes connus.

Valider un nouveau déploiement

Pour vérifier que le nouveau framework diffuse le trafic, procédez comme suit :

Envoyez des requêtes au nouveau déploiement.
Accédez à la page Cloud Logging de votre projet.

Accéder à la page "Explorateur de journaux"
Si les requêtes sont affichées avec des chemins commençant par /_ah/api, cela signifie qu'Endpoints Frameworks version 2.0 diffuse maintenant votre API. Les journaux ne doivent afficher aucune requête dont le chemin commence par /_ah/spi. Ces requêtes indiquent que le proxy Endpoints version 1.0 les diffuse toujours.

Ajouter la gestion des API

Endpoints Frameworks version 2.0 ajoute des fonctionnalités de gestion des API, telles que :

Gestion des clés API
Partage de l'API
Authentification des utilisateurs
Métriques de l'API
Journaux de l'API

Pour commencer, accédez à la page Premiers pas avec Endpoints Frameworks pour Python.

Dépannage

Cette section décrit les sources d'instabilité courantes lors de la migration vers Endpoints Frameworks version 2.0, ainsi que les solutions suggérées.

L'API renvoie des erreurs `404`, mais l'explorateur d'API répertorie toujours correctement les API

Vous devez supprimer l'ancienne configuration d'Endpoints version 1.0 lors de la migration vers Endpoints Frameworks version 2. Si l'ancienne configuration est toujours présente dans la configuration de l'application, le service Endpoints continue à traiter l'application comme s'il s'agissait d'une application version 1.0. Il se peut que des requêtes figurant dans les journaux App Engine soient envoyées à /_ah/spi, ce qui entraîne l'envoi d'erreurs HTTP 404 au client.

Le cas échéant, supprimez les lignes suivantes du fichier app.yaml :
```
handlers:
- url: /_ah/spi/.*
  script: ...
```

Assurez-vous que la section handlers de votre fichier app.yaml indique le bon chemin :

handlers:
# The endpoints handler must be mapped to /_ah/api.
- url: /_ah/api/.*
  script: ...

Message d'erreur : `ImportError: cannot import name locked_file`

Cela se produit si vos dépendances contiennent une version de la bibliothèque oauth2client incompatible avec App Engine. Consultez la page Problèmes connus.