Migrer vers Cloud Endpoints Frameworks version 2.0
Restez organisé à l'aide des collections
Enregistrez et classez les contenus selon vos préférences.
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é.
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.
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.
Consultez la page Cloud Logging pour votre projet.
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 :
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.
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/09/04 (UTC).
[[["Facile à comprendre","easyToUnderstand","thumb-up"],["J'ai pu résoudre mon problème","solvedMyProblem","thumb-up"],["Autre","otherUp","thumb-up"]],[["Difficile à comprendre","hardToUnderstand","thumb-down"],["Informations ou exemple de code incorrects","incorrectInformationOrSampleCode","thumb-down"],["Il n'y a pas l'information/les exemples dont j'ai besoin","missingTheInformationSamplesINeed","thumb-down"],["Problème de traduction","translationIssue","thumb-down"],["Autre","otherDown","thumb-down"]],["Dernière mise à jour le 2025/09/04 (UTC)."],[[["\u003cp\u003eEndpoints Frameworks version 2.0 is a migration from the older Endpoints version 1.0, requiring a library change and application configuration update, without needing code alterations.\u003c/p\u003e\n"],["\u003cp\u003eMigrating to Endpoints Frameworks version 2.0 offers benefits such as reduced request latency, improved App Engine integration, and new API management capabilities, while maintaining backward compatibility with existing client interfaces.\u003c/p\u003e\n"],["\u003cp\u003eThe migration process involves creating a \u003ccode\u003e/lib\u003c/code\u003e subfolder, installing the \u003ccode\u003egoogle-endpoints\u003c/code\u003e library, modifying the \u003ccode\u003eapp.yaml\u003c/code\u003e file to remove old Endpoints entries and include new library dependencies, and updating the \u003ccode\u003eurl\u003c/code\u003e directive to \u003ccode\u003e/_ah/api/.*\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eEndpoints Frameworks version 2.0 supports various features like JSON-REST protocol, Discovery service, and OAuth2/OpenID Connect authentication, but excludes features like JSON-RPC protocol and automatic ETags.\u003c/p\u003e\n"],["\u003cp\u003eVerifying a successful migration to Endpoints Frameworks version 2.0 involves checking the Cloud Logging for requests with paths beginning with \u003ccode\u003e/_ah/api\u003c/code\u003e, confirming that no requests start with \u003ccode\u003e/_ah/spi\u003c/code\u003e.\u003c/p\u003e\n"]]],[],null,["# Migrating to Cloud Endpoints Frameworks version 2.0\n\nCloud Endpoints Frameworks was formerly called Endpoints. To\ndistinguish between the two versions, this page refers to the new version as\nEndpoints Frameworks version 2.0, and the older version as\nEndpoints version 1.0. This page describes how to migrate an\nCloud Endpoints version 1.0 application to\n[Endpoints Frameworks version 2.0](/endpoints/docs/frameworks/python).\nThe migration consists of a library change and an application configuration\nchange, but you don't have to make any changes to your code.\n\nBenefits\n--------\n\nEndpoints version 2.0 brings a number of benefits, including:\n\n- Reduced request latency.\n- Better integration with App Engine features, such as custom domains.\n- New API management features.\n\nEndpoints Frameworks version 2.0 doesn't affect the interfaces to your\nAPI. Existing clients continue to work after migration without any client-side\ncode changes.\n\nFeature overview\n----------------\n\nThe following features are backward compatible with Endpoints\nversion 1.0:\n\n- JSON-REST protocol, which is used by all Google client libraries\n- Discovery service\n- All existing authentication features (OAuth2/OpenID Connect)\n- Client library support for generated clients\n- CORS (for JavaScript callers not using Google JavaScript client library)\n- API Explorer\n\nTraffic splitting is unavailable.\n\nCurrently excluded features\n---------------------------\n\nThe following features are unavailable. If you require any of these,\nplease submit a\n[feature request](https://github.com/cloudendpoints/endpoints-python/issues).\n\n- JSON-RPC protocol, which is required for legacy iOS clients. To create iOS clients for your Endpoints Frameworks version 2.0 API, we recommend that you use [Google APIs Objective-C client library for REST APIs](https://github.com/google/google-api-objectivec-client-for-rest/wiki).\n- Automatic ETags\n- Automatic `kind` fields\n- IDE integration\n- `fields` partial responses\n- Automatic PATCH API method creation\n\nMigrating from Endpoints version 1.0\n------------------------------------\n\n| **Important:** You must download the linked packages and import them into your application. You must remove the old dependencies.\n\nTo migrate from version 1.0:\n\n1. Create a subfolder named `/lib` in your application's main directory.\n\n2. Install the library from your application's main directory:\n\n pip install -t lib google-endpoints --ignore-installed\n\n3. Remove the `- name: endpoints` and `version 1.0` entries from your\n application's `app.yaml` file under the `libraries` section. For example:\n\n libraries:\n - name: endpoints #Remove\n version: 1.0 #Remove\n\n4. In the `libraries` section in the `app.yaml` file, add the following:\n\n libraries:\n - name: pycrypto\n version: 2.6\n - name: ssl\n version: 2.7.11\n\n Endpoints Frameworks requires these versions of the `pycrypto` and\n `ssl` libraries.\n5. In the `handlers` section in the `app.yaml` file, change the `url` directive\n from `- url: /_ah/spi/.*` to `- url: /_ah/api/.*`.\n\n6. In the root directory of your application, create or modify a file named\n `appengine_config.py` to include the following:\n\n from google.appengine.ext import vendor\n\n vendor.add('lib')\n\n7. Check your API version string. Your version string, specified in the\n `@endpoints.api(version='v1', ...)` decorator, appears in your API's path.\n If you specify a version string compatible with the\n [SemVer standard](https://semver.org/spec/v2.0.0.html),\n only the major version number appears in your API's path when you deploy\n your API. For example, an API called `echo` with version `2.1.0` would\n have a path such as `/echo/v2`. If you update the `echo` API to version\n `2.2.0` and deploy a backwards-compatible change, the path remains `/echo/v2`.\n This allows you to update the API version number when you make a\n backwards-compatible change without breaking existing paths for your clients.\n But if you update the `echo` API to version `3.0.0` (because you are\n deploying a breaking change), the path is changed to `/echo/v3`.\n\n8. Redeploy your Endpoints Frameworks application.\n\n | **Note** : When migrating, you must deploy to a new App Engine version. This is done automatically if you don't specify a version. See [Known Issues](/endpoints/docs/frameworks/known-issues#endpoints_frameworks_migration).\n\n \u003cbr /\u003e\n\n### Verifying a new deployment\n\nTo verify that the new framework is serving traffic:\n\n1. Send some requests to the new deployment.\n2. Visit the Cloud Logging page for your project. \n\n [Go to the Logs Explorer page](https://console.cloud.google.com/logs/query)\n3. If requests are shown with having paths beginning with `/_ah/api`, then Endpoints Frameworks version 2.0 is now serving your API. The logs shouldn't show any requests with paths beginning with `/_ah/spi`. These requests indicate that the Endpoints version 1.0 proxy is still serving requests.\n\nAdding API management\n---------------------\n\nEndpoints Frameworks version 2.0 adds API management features,\nincluding:\n\n- API key management\n- API sharing\n- User authentication\n- API metrics\n- API logs\n\nTo get started, go to the\n[Getting started with Endpoints Frameworks for Python](/endpoints/docs/frameworks/python)\npage.\n\nTroubleshooting\n---------------\n\nThis section describes common erratic behaviors when migrating to\nEndpoints Frameworks version 2.0 and suggested solutions.\n\n### API returns `404` errors, but API Explorer still lists APIs correctly\n\nYou are required to remove the old version 1.0 Endpoints\nconfiguration when migrating to Endpoints Frameworks version 2.0. If\nthe old configuration is still present in the application's configuration, the\nEndpoints service continues to treat the app as a version 1.0\napp. You might see requests in your App Engine logs sent to `/_ah/spi`,\nwhich result in `HTTP 404` errors sent to the client.\n\n1. Remove the following lines, from the `app.yaml` file if they are present:\n\n handlers:\n - url: /_ah/spi/.*\n script: ...\n\n2. Make sure the `handlers` section in your `app.yaml` file has the correct\n path:\n\n handlers:\n # The endpoints handler must be mapped to /_ah/api.\n - url: /_ah/api/.*\n script: ...\n\n### Error message: `ImportError: cannot import name locked_file`\n\nThis happens if your dependencies contain a version of the `oauth2client`\nlibrary that is incompatible with App Engine. See the\n[known issue](/endpoints/docs/frameworks/known-issues#error_message_importerror_cannot_import_name_locked_file)."]]
