Déployer des proxys d'API à l'aide de l'API

Vous consultez la documentation Apigee Edge.
Accédez à la documentation**Apigee X**. info

Chaque entreprise suit un cycle de développement logiciel unique. Il est souvent nécessaire de synchroniser et d'aligner le déploiement des proxys d'API avec les processus utilisés pour les services de backend.

Les méthodes de l'API Edge présentées dans cet article peuvent être utilisées pour intégrer la gestion des proxys d'API au cycle de développement logiciel unique de votre entreprise. Une utilisation courante de cette API consiste à écrire des scripts ou du code qui déploient des proxys d'API ou qui migrent les proxys d'API d'un environnement vers un autre, dans le cadre d'un processus automatisé plus important qui déploie ou migre d'autres applications.

L'API Edge ne formule aucune hypothèse concernant votre SDLC (ou celui de toute autre personne). Elle expose plutôt des fonctions atomiques pouvant être coordonnées par votre équipe de développement afin d'automatiser et d'optimiser le cycle de vie de développement de vos API.

Pour obtenir des informations complètes, consultez la section API Edge.

Pour utiliser l'API Edge, vous devez vous authentifier dans vos appels. Vous pouvez le faire à l'aide de l'une des méthodes suivantes :

Cet article se concentre sur l'ensemble des API permettant de gérer les proxys d'API.

Vidéo : Regardez cette courte vidéo pour découvrir comment déployer une API.

Interagir avec l'API

Les étapes suivantes vous guident à travers des interactions simples avec les API.

Répertorier les API de votre organisation

Vous pouvez commencer par répertorier tous les proxys d'API de votre organisation. (N'oubliez pas de remplacer les entrées par EMAIL:PASSWORD et ORG_NAME. Pour obtenir des instructions, consultez la section Utiliser l'API Edge.

curl -u EMAIL:PASSWORD \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis

Exemple de réponse :

[ "weatherapi" ]

Obtenir une API

Vous pouvez appeler la méthode GET sur n'importe quel proxy d'API de votre organisation. Cet appel renvoie la liste de toutes les révisions disponibles du proxy d'API.

curl -u EMAIL:PASSWORD -H "Accept: application/json" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi

Exemple de réponse :

{
  "name" : "weatherapi",
  "revision" : [ "1" ]
}

Le seul détail renvoyé par cette méthode est le nom du proxy d'API, ainsi que la révision associée, qui possède un numéro associé. Les proxys d'API sont constitués d'un ensemble de fichiers de configuration. Les révisions fournissent un mécanisme léger pour gérer vos mises à jour de la configuration lorsque vous effectuez des itérations. Les révisions sont numérotées de manière séquentielle, ce qui vous permet d'annuler une modification en déployant une révision précédente de votre proxy d'API. Vous pouvez également déployer une révision d'un proxy d'API dans l'environnement de production , tout en continuant à créer de nouvelles révisions de ce proxy d'API dans l'environnement de test. Lorsque vous êtes prêt, vous pouvez promouvoir la révision supérieure de votre proxy d'API de l' environnement de test par rapport à la révision précédente du proxy d'API dans l'environnement de production.

Dans cet exemple, il n'y a qu'une seule révision, car le proxy d'API vient d'être créé. À mesure qu'un proxy d'API progresse dans le cycle de vie de la configuration et du déploiement itératifs, le numéro de révision augmente par entiers. En utilisant des appels d'API directs pour le déploiement, vous pouvez éventuellement incrémenter le numéro de révision du proxy d'API. Parfois, lorsque vous apportez des modifications mineures, vous ne souhaitez peut-être pas incrémenter la révision.

Obtenir la révision de l'API

La version de l'API (par exemple, api.company.com/v1) ne doit changer que très rarement. Lorsque vous incrémentez la version de l'API, cela indique aux développeurs qu'une modification importante a été apportée à la signature de l'interface externe exposée par l'API.

La révision du proxy d'API est un nombre incrémenté associé à une configuration de proxy d'API. API Service conserve les révisions de vos configurations afin que vous puissiez revenir à une configuration précédente en cas de problème. Par défaut, la révision d'un proxy d'API est automatiquement incrémentée chaque fois que vous importez un proxy d'API à l'aide de l'API Import an API proxy. Si vous ne souhaitez pas incrémenter la révision d'un proxy d'API, utilisez l'API Update API proxy revision. Si vous utilisez Maven pour le déploiement, utilisez les clean ou update options, comme décrit dans le fichier Lisez-moi du plug-in Maven.

Par exemple, vous pouvez appeler la méthode GET sur la révision 1 du proxy d'API pour obtenir une vue détaillée.

curl -u EMAIL:PASSWORD -H "Accept:application/json" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi/revisions/1

Exemple de réponse

{
  "configurationVersion" : {
    "majorVersion" : 4,
    "minorVersion" : 0
  },
  "contextInfo" : "Revision 1 of application weatherapi, in organization {org_name}",
  "createdAt" : 1343178905169,
  "createdBy" : "andrew@apigee.com",
  "lastModifiedAt" : 1343178905169,
  "lastModifiedBy" : "andrew@apigee.com",
  "name" : "weatherapi",
  "policies" : [ ],
  "proxyEndpoints" : [ ],
  "resources" : [ ],
  "revision" : "1",
  "targetEndpoints" : [ ],
  "targetServers" : [ ],
  "type" : "Application"
}

Ces éléments de configuration de proxy d'API sont décrits en détail dans la documentation de référence sur la configuration des proxys d'API.

Déployer une API dans un environnement

Une fois que votre proxy d'API est configuré pour recevoir et transférer correctement les requêtes, vous pouvez le déployer dans un ou plusieurs environnements. En règle générale, vous effectuez des itérations sur les proxys d'API dans test, puis, lorsque vous êtes prêt, vous promouvez la révision du proxy d'API vers prod. Vous constaterez souvent que vous avez beaucoup plus de révisions d'un proxy d'API dans l'environnement de test, principalement parce que vous effectuerez beaucoup moins d'itérations dans l'environnement de production.

Un proxy d'API ne peut pas être appelé tant qu'il n'a pas été déployé dans un environnement. Une fois que vous avez déployé la révision du proxy d'API en production, vous pouvez publier l'URL prod auprès des développeurs externes.

Répertorier les environnements

Chaque organisation dans Apigee Edge possède au moins deux environnements : test et prod. La distinction est arbitraire. L'objectif est de vous fournir une zone pour vérifier que votre proxy d'API fonctionne correctement avant de l'ouvrir aux développeurs externes.

Chaque environnement n'est qu'une adresse réseau, ce qui vous permet de séparer le trafic entre les proxys d'API sur lesquels vous travaillez et ceux auxquels les applications accèdent au moment de l'exécution.

Les environnements fournissent également une séparation des données et des ressources. Par exemple, vous pouvez configurer différents caches en test et en production, qui ne sont accessibles que par les proxys d'API exécutés dans cet environnement.

Afficher les environnements d'une organisation

curl -u EMAIL:PASSWORD \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments

Exemple de réponse

[ "test", "prod" ]

Explorer les déploiements

Un déploiement est une révision d'un proxy d'API qui a été déployée dans un environnement. Un proxy d'API à l'état déployé est accessible sur le réseau, aux adresses définies dans l'élément <VirtualHost> pour cet environnement.

Déployer des proxys d'API

Les proxys d'API ne peuvent pas être appelés tant qu'ils n'ont pas été déployés. API Service expose des API RESTful qui permettent de contrôler le processus de déploiement.

Une seule révision d'un proxy d'API peut être déployée dans un environnement à un moment donné. Par conséquent la révision déployée doit être annulée. Vous pouvez contrôler si le nouveau groupe est déployé en tant que nouvelle révision ou s'il écrase la révision existante.

Vous consultez la documentation Apigee Edge.
Accédez à la documentation Apigee X. info

Commencez par annuler le déploiement de la révision existante. Spécifiez le nom de l'environnement et le numéro de révision de le proxy d'API dont vous souhaitez annuler le déploiement :

curl -X DELETE \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments \
  -u EMAIL:PASSWORD

Déployez ensuite la nouvelle révision. La nouvelle révision du proxy d'API doit déjà exister : 

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments \
  -u EMAIL:PASSWORD

Déploiement fluide (sans interruption)

Pour minimiser le risque d'interruption lors du déploiement, utilisez le paramètre override sur la méthode de déploiement et définissez-le sur true.

Vous ne pouvez pas déployer une révision d'un proxy d'API sur une autre. La première doit toujours être annulée. En définissant override sur true, vous indiquez qu'une révision d'un proxy d'API doit être déployée sur la révision actuellement déployée. Le résultat est que la séquence de déploiement est inversée : la nouvelle révision est déployée, et une fois le déploiement est terminé, la révision déjà déployée est annulée.

L'exemple suivant définit la valeur override en la transmettant en tant que paramètre de formulaire : 

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/e/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments" \
  -d "override=true" \
  -u EMAIL:PASSWORD

Vous pouvez optimiser davantage le déploiement en définissant le paramètre delay. Le delay paramètre spécifie un intervalle de temps, en secondes, avant lequel la révision précédente doit être annulée. L'effet est que les transactions en cours disposent d'un intervalle de temps en lequel se terminer avant que le proxy d'API qui traite leur transaction ne soit annulé. Voici ce qui se passe avec override=true et le paramètre delay défini :

  • La révision 1 gère les requêtes.
  • La révision 2 est en cours de déploiement en parallèle.
  • Lorsque la révision 2 est entièrement déployée, le nouveau trafic est envoyé à la révision 2. Aucun nouveau trafic n'est envoyé à la révision 1.
  • Toutefois, la révision 1 peut toujours traiter les transactions existantes. En définissant le delay paramètre (par exemple, 15 secondes), vous donnez à la révision 1 15 secondes pour terminer le traitement des transactions existantes.
  • Après l'intervalle de délai, la révision 1 est annulée.
curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/e/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments?delay=15" \
  -d "override=true" \
  -u EMAIL:PASSWORD
Paramètre de requête Description
override

La valeur par défaut est false (comportement de déploiement normal : la révision existante est annulée, puis la nouvelle révision est déployée).

Définissez la valeur sur true pour remplacer le comportement de déploiement normal et fournir un déploiement fluide. La révision existante reste déployée pendant que la nouvelle révision est également en cours de déploiement. Une fois la nouvelle révision déployée, l'ancienne révision est annulée. Utilisez-la conjointement avec le paramètre delay pour contrôler le moment où l'annulation du déploiement se produit.
delay

Pour permettre le traitement des transactions sur la révision existante avant son annulation et éliminer la possibilité de 502 Bad Gateway ou 504 Gateway Timeout errors—définissez ce paramètre sur le nombre de secondes pendant lesquelles vous souhaitez que l'annulation du déploiement soit retardée. Vous pouvez définir le nombre de secondes de votre choix, et la définition d'un nombre élevé de secondes n'a aucune incidence sur les performances. Pendant le délai, aucun nouveau trafic n'est envoyé à l'ancienne révision.

La valeur par défaut est de 0 (zéro) seconde. Lorsque override est défini sur "true" et delay sur 0, la révision existante est annulée immédiatement après le déploiement de la nouvelle révision. Les valeurs négatives sont traitées comme 0 (zéro) seconde.

Lorsque override=true est utilisé avec un delay, les réponses HTTP 5XX lors du déploiement peuvent être éliminées. En effet, les deux révisions de proxy d'API seront déployées simultanément, l'ancienne révision étant annulée après le délai.

Afficher tous les déploiements d'une révision d'API

Il est parfois nécessaire de récupérer la liste de toutes les révisions actuellement déployées d'un proxy d'API.

curl https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi/revisions/1/deployments \
  -u EMAIL:PASSWORD
 
{
  "aPIProxy" : "weatherapi",
  "environment" : [ {
    "configuration" : {
      "basePath" : "",
      "steps" : [ ]
    },
    "name" : "test",
    "server" : [ {
      "status" : "deployed",
      "type" : [ "message-processor" ],
      "uUID" : "90096dd1-1019-406b-9f42-fbb80cd01200"
    }, {
      "status" : "deployed",
      "type" : [ "message-processor" ],
      "uUID" : "7d6e2eb1-581a-4db0-8045-20d9c3306549"
    }, {
      "status" : "deployed",
      "type" : [ "router" ],
      "uUID" : "1619e2d7-c822-45e0-9f97-63882fb6a805"
    }, {
      "status" : "deployed",
      "type" : [ "router" ],
      "uUID" : "8a5f3d5f-46f8-4e99-b4cc-955875c8a8c8"
    } ],
    "state" : "deployed"
  } ],
  "name" : "1",
  "organization" : "org_name"
}

La réponse ci-dessus contient de nombreuses propriétés spécifiques à l'infrastructure interne d'Apigee Edge. Sauf si vous utilisez Apigee Edge sur site, vous ne pouvez pas modifier ces paramètres.

Les propriétés importantes contenues dans la réponse sont organization, environment, aPIProxy, name, et state. En examinant les valeurs de ces propriétés, vous pouvez confirmer qu'une révision spécifique d'un proxy d'API est déployée dans un environnement.

Afficher tous les déploiements dans l' environnement de test

Vous pouvez également récupérer l'état de déploiement d'un environnement spécifique (y compris le numéro de révision du proxy d'API actuellement déployé) à l'aide de l'appel suivant :

curl -u EMAIL:PASSWORD
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/test/deployments

Cela renvoie le même résultat que ci-dessus pour chaque API déployée dans l'environnement de test.

Afficher tous les déploiements de votre organisation

Pour récupérer la liste de toutes les révisions actuellement déployées de tous les proxys d'API dans tous les environnements, utilisez la méthode d'API suivante :

curl https://api.enterprise.apigee.com/v1/o/ORG_NAME/deployments \
  -u EMAIL:PASSWORD

Cela renvoie le même résultat que ci-dessus pour tous les proxys d'API déployés dans tous les environnements.

Étant donné que l'API est RESTful, vous pouvez simplement utiliser la méthode POST, ainsi qu'une charge utile JSON ou XML, sur la même ressource pour créer un proxy d'API.

Un profil pour votre proxy d'API est généré. La représentation par défaut d'un proxy d'API est au format JSON (JavaScript Object Notation). Vous trouverez ci-dessous la réponse JSON par défaut à la requête POST ci-dessus, qui a créé un proxy d'API appelé weatherapi. Une description de chaque élément du profil suit :

{
  "configurationVersion" : {
    "majorVersion" : 4,
    "minorVersion" : 0
  },
  "contextInfo" : "Revision 1 of application weatherapi, in organization {org_name}",
  "createdAt" : 1357172145444,
  "createdBy" : "you@yourcompany.com",
  "displayName" : "weatherapi",
  "lastModifiedAt" : 1357172145444,
  "lastModifiedBy" : "you@yourcompany.com",
  "name" : "weatherapi",
  "policies" : [ ],
  "proxyEndpoints" : [ ],
  "resources" : [ ],
  "revision" : "1",
  "targetEndpoints" : [ ],
  "targetServers" : [ ],
  "type" : "Application"
}

Le profil de proxy d'API généré illustre la structure complète d'un proxy d'API :

  • APIProxy revision : itération numérotée de manière séquentielle de la configuration du proxy d'API, telle qu'elle est gérée par API Service
  • APIProxy name : nom unique du proxy d'API
  • ConfigurationVersion : version d'API Service à laquelle la configuration du proxy d'API est conforme
  • CreatedAt : heure à laquelle le proxy d'API a été généré, au format UNIX
  • CreatedBy : adresse e-mail de l'utilisateur Apigee Edge qui a créé le proxy d'API
  • DisplayName : nom convivial du proxy d'API
  • LastModifiedAt : heure à laquelle le proxy d'API a été généré, au format UNIX heure
  • LastModifiedBy : adresse e-mail de l'utilisateur Apigee Edge qui a créé le proxy d'API
  • Policies : liste des règles qui ont été ajoutées à ce proxy d'API
  • ProxyEndpoints : liste des ProxyEndpoints nommés
  • Resources : liste des ressources (JavaScript, Python, Java, XSLT) pouvant être exécutées dans ce proxy d'API
  • TargetServers : liste des TargetServers nommés (qui peuvent être créés à l'aide de l'API de gestion), utilisés dans les configurations avancées à des fins d'équilibrage de charge
  • TargetEndpoints : liste des TargetEndpoints nommés

Notez que de nombreux éléments de la configuration de proxy d'API créés à l'aide de la méthode POST simple ci-dessus sont vides. Dans les sections suivantes, vous apprendrez à ajouter et à configurer les composants clés d'un proxy d'API.

Vous pouvez également en savoir plus sur ces éléments de configuration dans la documentation de référence sur la configuration des proxys d'API .

Écrire des scripts pour l'API

La section Utiliser les exemples de proxys d'API, disponible sur GitHub, fournit des scripts shell qui encapsulent l'outil de déploiement Apigee. Si, pour une raison quelconque vous ne pouvez pas utiliser l'outil de déploiement Python, vous pouvez appeler l'API directement. Les deux approches sont illustrées dans les exemples de scripts ci-dessous.

Encapsuler l'outil de déploiement

Tout d'abord, assurez-vous que l'outil de déploiement Python est disponible dans votre environnement local.

Créez ensuite un fichier pour stocker vos identifiants. Les scripts de déploiement que vous écrivez importeront ces paramètres, ce qui vous aidera à gérer de manière centralisée les identifiants de votre compte. Dans l'exemple de plate-forme d'API, ce fichier est appelé setenv.sh.

#!/bin/bash

org="Your ORG on enterprise.apigee.com"
username="Your USERNAME on enterprise.apigee.com"

# While testing, it's not necessary to change the setting below
env="test"
# Change the value below only if you have an on-premise deployment
url="https://api.enterprise.apigee.com"
# Change the value below only if you have a custom domain
api_domain="apigee.net"

export org=$org
export username=$username
export env=$env
export url=$url
export api_domain=$api_domain

Le fichier ci-dessus met tous vos paramètres à la disposition des scripts shell qui encapsulent l'outil de déploiement.

Créez maintenant un script shell qui importe ces paramètres et les utilise pour appeler l'outil de déploiement. (Pour obtenir un exemple, consultez Exemples de plate-forme d'API Apigee.)

#!/bin/bash

source path/to/setenv.sh

echo "Enter your password for the Apigee Enterprise organization $org, followed by [ENTER]:"

read -s password

echo Deploying $proxy to $env on $url using $username and $org

path/to/deploy.py -n {api_name} -u $username:$password -o $org -h $url -e $env -p / -d path/to/apiproxy

Pour vous faciliter la tâche, créez également un script pour appeler et tester l'API, comme suit :

#!/bin/bash

echo Using org and environment configured in /setup/setenv.sh

source /path/to/setenv.sh

set -x

curl "http://$org-$env.apigee.net/{api_basepath}"

Appeler directement l'API

Il peut être utile d'écrire des scripts shell simples qui automatisent le processus d'importation et de déploiement des proxys d'API.

Le script ci-dessous appelle directement l'API de gestion. Il annule le déploiement de la révision existante de le proxy d'API que vous mettez à jour, crée un fichier ZIP à partir du /apiproxy répertoire contenant vos fichiers de configuration de proxy, puis importe et déploie la configuration.

#!/bin/bash

#This sets the name of the API proxy and the basepath where the API will be available
api=api

source /path/to/setenv.sh

echo Delete the DS_store file on OSX

echo find . -name .DS_Store -print0 | xargs -0 rm -rf
find . -name .DS_Store -print0 | xargs -0 rm -rf

echo "Enter your password for the Apigee Enterprise organization $org, followed by [ENTER]:"

read -s password

echo Undeploy and delete the previous revision

# Note that you need to explicitly update the revision to be undeployed.
# One benefit of the Python deploy tool is that it manages this for you.

curl -k -u $username:$password "$url/v1/o/$org/e/$env/apis/$api/revisions/1/deployments" -X DELETE

curl -k -u $username:$password -X DELETE "$url/v1/o/$org/apis/$api/revisions/1"

rm -rf $api.zip

echo Create the API proxy bundle and deploy

zip -r $api.zip apiproxy

echo Import the new revision to $env environment 

curl -k -v -u $username:$password "$url/v1/o/$org/apis?action=import&name=$api" -T $api.zip -H "Content-Type: application/octet-stream" -X POST

echo Deploy the new revision to $env environment 

curl -k -u $username:$password "$url/v1/o/$org/e/$env/apis/$api/revisions/1/deployments" -X POST