Ajouter la gestion des API

Cloud Endpoints Frameworks fournit des fonctionnalités de gestion d'API comparables à celles les caractéristiques Extensible Service Proxy (ESP) fournies pour Cloud Endpoints. Endpoints Frameworks comprend un intégré API Gateway qui intercepte toutes les requêtes et effectue les vérifications nécessaires : l'authentification, avant de transmettre la requête au backend de l'API. Lorsque le backend répond, Endpoints Frameworks rassemble et consigne les données de télémétrie. Vous pouvez afficher les métriques de votre API sur la page Endpoints > Services de Google Cloud Console.

Les fonctionnalités de gestion des API disponibles dans Endpoints Frameworks comprennent :

Pour que votre API soit gérée par Endpoints, vous devez déployer un document OpenAPI décrivant votre API à l'aide de la version 2.0 de la spécification OpenAPI. Cette page explique comment générer et déployer un document OpenAPI permettant à Endpoints de gérer votre API.

Si vous n'ajoutez pas la gestion des API, votre API diffuse tout de même les requêtes, mais votre L'API n'apparaît pas sous Endpoints > la page Services de la console Google Cloud et les fonctionnalités fournies par Cloud Endpoints, comme la journalisation, la surveillance et la définition de quotas, disponibles.

Installer et configurer le logiciel requis

Si vous ne l'avez pas déjà fait, installez et configurez la Google Cloud CLI pour Python. Ensuite, ajoutez la bibliothèque Endpoints Frameworks pour Python à votre répertoire de projet API afin qu'elle soit importée avec le code de l'API lors du déploiement.

Installer et configurer la CLI gcloud pour Python

  1. Installez et initialisez gcloud CLI :

    Télécharger et installer la gcloud CLI

  2. Installez le composant gcloud qui inclut l'extension App Engine pour Python :

    gcloud components install app-engine-python
    
  3. Mettre à jour la CLI gcloud

    gcloud components update
    
  4. Assurez-vous que la gcloud CLI est autorisée à accéder à vos données et sur Google Cloud:

    gcloud auth login
    

    Un nouvel onglet de navigateur vous invite à choisir un compte.

  5. Définissez le projet par défaut sur votre ID de projet. Remplacez YOUR_PROJECT_ID par l'ID de votre projet Google Cloud.

    gcloud config set project YOUR_PROJECT_ID
    
  6. Pour Linux, définissez la variable d'environnement ENDPOINTS_GAE_SDK sur le chemin d'accès au dossier de votre SDK App Engine :

    PATH_TO_CLOUD_SDK/platform/google_appengine
    

    Remplacez PATH_TO_CLOUD_SDK par le résultat de la commande suivante :

    gcloud info --format="value(installation.sdk_root)"
    

Ajouter la bibliothèque Endpoints Frameworks pour Python

  1. Assurez-vous de pouvoir compiler des extensions C pour Python.

    • Windows : le compilateur Microsoft Visual C++ 9.0 (ou version ultérieure) est requis. Vous pouvez télécharger le compilateur Microsoft Visual C++ pour Python 2.7 depuis le centre de téléchargement Microsoft.

    • Autres systèmes d'exploitation : en fonction de votre système d'exploitation, vous devrez peut-être installer des outils de compilation (parfois dans un package appelé build-essential) et/ou les en-têtes de développement Python (parfois dans un package appelé python-dev).

  2. Modifiez le répertoire pour sélectionner le répertoire principal de votre API.

  3. Créez un sous-répertoire /lib dans le répertoire principal de l'API :

    mkdir lib
    
  4. Installez la bibliothèque :

    pip install -t lib google-endpoints --ignore-installed
    

Générer le document OpenAPI

Dans le répertoire principal de l'API, générez un document OpenAPI à l'aide des outils de framework. Exemple :

Une seule classe

Dans la commande suivante, remplacez YOUR_PROJECT_ID par votre ID de projet Google Cloud.

python lib/endpoints/endpointscfg.py get_openapi_spec main.EchoApi \
    --hostname YOUR_PROJECT_ID.appspot.com

Ignorez les avertissements qui s'affichent.

Plusieurs classes

Vous pouvez répertorier plusieurs classes sur la ligne de commande. Endpoints génère un document OpenAPI pour chaque combinaison de nom et version de l'API.

Si vous souhaitez déployer plusieurs classes d'API avec des noms d'API différents dans le cadre d'un même service, vous devez également ajouter l'option --x-google-api-name. L'activation de cet indicateur ajoute des restrictions supplémentaires concernant les noms de vos API. Plus précisément, les noms doivent correspondre à l'expression régulière [a-z][a-z0-9]{0,39}. En d'autres termes, le nom doit être composé de 1 à 40 caractères, qui peuvent tous être soit des lettres minuscules, soit des chiffres (à l'exception du premier caractère, qui ne doit pas être un chiffre). Exemple :

Dans la commande suivante, remplacez YOUR_PROJECT_ID par votre ID de projet Google Cloud.

python lib/endpoints/endpointscfg.py get_openapi_spec main.FooApi main.BarApi \
   --hostname YOUR_PROJECT_ID.appspot.com \
   --x-google-api-name

Ignorez les avertissements qui s'affichent.

Endpoints utilise le texte spécifié dans l'argument hostname en tant que nom de service. Lorsque vous déployez l'API sur App Engine, une entrée DNS portant un nom au format YOUR_PROJECT_ID.appspot.com est créée automatiquement.

Déployer le document OpenAPI

Une seule classe

gcloud endpoints services deploy echov1openapi.json

Plusieurs classes

Si vous possédez plusieurs documents OpenAPI, répertoriez-les tous sur la ligne de commande. Exemple :

 gcloud endpoints services deploy foov1openapi.json barv1openapi.json

Après le premier déploiement de vos documents OpenAPI, un service Endpoints est créé sous le nom YOUR_PROJECT_ID.appspot.com.

Si l'opération réussit, une ligne semblable à la suivante affiche l'ID de configuration du service et le nom du service :

Service Configuration 2017-02-13r0 uploaded for service example-project-12345.appspot.com

Dans l'exemple ci-dessus, 2017-02-13r0 correspond à l'ID de configuration du service. L'ID de configuration du service se compose d'un horodatage, suivi d'un numéro de révision. Si vous déployez à nouveau votre document OpenAPI, le numéro de révision est ajouté à l'ID de configuration du service.

Si vous devez afficher à nouveau l'ID de configuration du service, exécutez la commande suivante, mais remplacez YOUR_PROJECT_ID par l'ID de votre projet Google Cloud :

gcloud endpoints configs list --service=YOUR_PROJECT_ID.appspot.com

Vous pouvez créer votre propre document OpenAPI et le déployer plutôt que d'utiliser un document généré. Il vous suffit pour cela de remplacer l'élément echov1openapi.json ci-dessus par le chemin d'accès à votre document OpenAPI. Pour en savoir plus sur la rédaction d'un document OpenAPI, consultez la page Présentation d'OpenAPI.

Redéployer et tester votre API

  1. Modifiez la section app.yaml du fichier de votre projet et ajoutez une section env_variables comme suit :

    env_variables:
      ENDPOINTS_SERVICE_NAME: YOUR_PROJECT_ID.appspot.com
      ENDPOINTS_SERVICE_VERSION: YOUR_SERVICE_VERSION
    

    Remplacez YOUR_PROJECT_ID par votre ID de projet Google Cloud et YOUR_SERVICE_VERSION par votre ID de configuration de service comme défini dans la section précédente. Si vous ajoutez ces éléments au fichier app.yaml, Endpoints gère votre API après le redéploiement de votre application.

  2. Redéployez votre application.

    gcloud app deploy
    
  3. Attendez que le déploiement soit terminé, en ignorant les messages d'avertissement. Une fois le déploiement terminé, un message semblable au suivant s'affiche :

    File upload done.
    Updating service [default]...done.
    
  4. Effectuez un test pour constater si le redéploiement s'est effectué avec succès, par exemple en utilisant curl :

    curl --request POST \
        --header "Content-Type: application/json" \
        --data '{"content":"echo"}' \
        https://YOUR_PROJECT_ID.appspot.com/_ah/api/echo/v1/echo?n=2
    

    Remplacez echo par le nom de votre API.

    Les résultats devraient se présenter sous la forme suivante :

    {
     "content": "echo echo"
    }
    
  5. Adressez des requêtes supplémentaires à votre API.

  6. À afficher les métriques de l'API, ouvrez le panneau Points de terminaison > Page Services de la console Google Cloud pour votre projet:

    Accédez à la page Services Endpoints