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

Endpoints Frameworks version 2.0 n'a pas d'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 :

  1. Créez un sous-dossier nommé /lib dans le répertoire principal de votre application.

  2. Installez la bibliothèque à partir du répertoire principal de l'application :

     pip install -t lib google-endpoints --ignore-installed
        
  3. Supprimez les entrées - name: endpoints et version 1.0 du fichier app.yaml de votre application dans la section libraries. Exemple :

    libraries:
        - name: endpoints   #Remove
          version: 1.0      #Remove
        
  4. 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.

  5. Dans la section handlers du fichier app.yaml, modifiez le paramètre url de - url: /_ah/spi/.* à - url: /_ah/api/.*.

  6. 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')
        
  7. Vérifiez la chaîne de version de l'API. Votre chaîne de version, spécifiée dans le décorateur @endpoints.api(version='v1', ...), apparaît dans le chemin d'accès de votre API. Si la chaîne de version est compatible avec le SemVer standard, 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 appelée echo avec la version 2.1.0 doit avoir un chemin 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 vos 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.

  8. Redéployez l'application Endpoints Frameworks.

Valider un nouveau déploiement

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

  1. Envoyez des requêtes au nouveau déploiement.
  2. Consultez la page Cloud Logging pour votre projet.

    Accéder à la page Visionneuse de journaux

  3. 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.

  1. Le cas échéant, supprimez les lignes suivantes du fichier app.yaml :

    handlers:
        - url: /_ah/spi/.*
          script: ...
        
  2. 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.