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

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X.
en savoir plus

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

Les méthodes d'API Edge présentées dans cet article peuvent être utilisées pour intégrer la gestion des proxys d'API au SDLC de votre organisation. Cette API est couramment utilisée pour écrire des scripts ou du code qui déploient des proxys d'API ou qui migrent des proxys d'API d'un environnement à un autre, dans le cadre d'un processus automatisé plus vaste qui déploie ou migre également d'autres applications.

L'API Edge n'émet aucune hypothèse concernant votre SDLC (ou celle de qui que ce soit d'autre). Il expose plutôt des fonctions atomiques qui peuvent être coordonnées par votre équipe de développement pour automatiser et optimiser le cycle de vie du 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. Pour ce faire, utilisez l'une des méthodes suivantes:

Cette rubrique se concentre sur l'ensemble des API destinées à la gestion des proxys d'API.

Vidéo:regardez cette courte vidéo pour savoir 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 lister 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 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 une 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 a un numéro associé. Les proxys d'API sont constitués d'un ensemble de fichiers de configuration. Les révisions constituent un mécanisme léger pour gérer les mises à jour de la configuration au fur et à mesure que vous effectuez des itérations. Les révisions sont numérotées dans l'ordre, ce qui vous permet d'annuler une modification en déployant une révision précédente de votre proxy d'API. En outre, vous pouvez déployer une révision de proxy d'API dans l'environnement de production, tout en continuant à créer des 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éé. Lorsqu'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 s'incrémente de nombres 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. Lorsque vous apportez des modifications mineures, il se peut que vous ne souhaitiez pas incrémenter la révision.

Obtenir la révision de l'API

La version de l'API (par exemple, api.company.com/v1) doit changer très rarement. Lorsque vous incrémentez la version de l'API, cela signifie 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 numéro incrémenté associé à une configuration de proxy d'API. Les services d'API gèrent les révisions de vos configurations pour vous permettre de les annuler 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 (Importer un proxy d'API). Si vous ne souhaitez pas incrémenter la révision d'un proxy d'API, utilisez l'API Update API proxy revision (Mettre à jour le proxy d'API). Si vous utilisez Maven pour le déploiement, utilisez les options clean ou update, comme décrit dans le fichier README 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 des proxys d'API sont documentés 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 votre proxy d'API configuré pour recevoir et transférer correctement des requêtes, vous pouvez le déployer dans un ou plusieurs environnements. En général, vous itérez sur les proxys d'API dans test puis, lorsque vous êtes prêt, vous promouvez la révision du proxy d'API vers prod. Souvent, vous constaterez 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 pour les développeurs externes.

Comment répertorier les environnements

Dans Apigee Edge, chaque organisation possède au moins deux environnements: test et prod. Cette distinction est arbitraire. L'objectif est de vous fournir un espace permettant de vérifier que votre proxy d'API fonctionne correctement avant de l'ouvrir à des développeurs externes.

Chaque environnement n'est en fait 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. Vous pouvez par exemple configurer différents caches en test et en production, auxquels seuls les proxys d'API s'exécutant dans cet environnement peuvent accéder.

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é 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. Les services d'API exposent 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 à la fois. Par conséquent, la révision déployée doit être annulée. Vous pouvez déterminer si le nouveau groupe est déployé en tant que nouvelle révision ou s'il remplace la révision existante.

Vous consultez la documentation Apigee Edge.
Consulter la documentation d'Apigee X
en savoir plus

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 du 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 (aucun temps d'arrêt)

Pour réduire les risques de temps d'arrêt pendant le déploiement, définissez le paramètre override sur true dans la méthode de déploiement.

Vous ne pouvez pas déployer une révision d'un proxy d'API sur une autre. Le premier doit toujours être annulé. 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. La séquence de déploiement est donc inversée : la nouvelle révision est déployée et, une fois le déploiement 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 paramètre delay spécifie un intervalle de temps, en secondes, avant l'annulation du déploiement de la révision précédente. Il en résulte que les transactions en cours de transfert ont un intervalle de temps devant s'achever avant que le proxy d'API ne traite leur transaction et que leur déploiement soit annulé. Voici ce qui se passe avec override=true et le paramètre delay défini:

  • La révision 1 traite les requêtes.
  • La révision 2 est déployée en parallèle.
  • Une fois la révision 2 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, il est possible que les transactions existantes soient encore en cours de traitement dans la révision 1. En définissant le paramètre delay (par exemple, 15 secondes), vous accordez à 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 normal de déploiement: la révision existante est annulée, puis une nouvelle révision est déployée).

Définissez la valeur sur true pour ignorer le comportement de déploiement normal et permettre 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. Lorsque la nouvelle révision est déployée, le déploiement de l'ancienne révision est annulé. Utilisez ce paramètre conjointement avec le paramètre delay pour contrôler le moment où l'annulation du déploiement a lieu.

delay

Pour permettre au traitement des transactions sur la révision existante avant son annulation du déploiement, et pour éliminer l'éventualité de voir 502 Bad Gateway ou 504 Gateway Timeout errors, définissez ce paramètre sur le délai d'annulation du déploiement (en secondes). Vous pouvez définir autant de secondes que vous le souhaitez, et le fait de définir un grand nombre de secondes n'a aucune incidence sur les performances. Pendant ce temps, aucun nouveau trafic n'est envoyé à l'ancienne révision.

La valeur par défaut est 0 (zéro) seconde. Lorsque override est défini sur "true" et que delay est défini 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 égales à 0 (zéro) seconde.

Lorsque override=true est utilisé avec un delay, les réponses HTTP 5XX lors du déploiement peuvent être supprimées. En effet, les deux révisions du 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. Vous ne pouvez pas modifier ces paramètres, sauf si vous utilisez Apigee Edge sur site.

Les principales propriétés contenues dans la réponse sont organization, environment, aPIProxy, name et state. En examinant ces valeurs de propriété, 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 de l'environnement de test

Vous pouvez également récupérer l'état du déploiement pour 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

Cette commande 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 API suivante:

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

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

L'API étant RESTful, vous pouvez simplement utiliser la méthode POST, avec une charge utile JSON ou XML, sur la même ressource pour créer un proxy d'API.

Un profil est généré pour votre proxy d'API. 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. Voici la description de chaque élément du profil:

{
  "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 dans l'ordre de la configuration du proxy d'API, telle qu'elle est gérée par les services d'API
  • APIProxy name: nom unique du proxy d'API
  • ConfigurationVersion: version des services d'API à laquelle la configuration du proxy d'API est conforme
  • CreatedAt: heure à laquelle le proxy d'API a été généré, formaté en heure 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é, formaté en heure UNIX
  • 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, YAML) pouvant être exécutées dans ce proxy d'API
  • TargetServers: liste de TargetServers nommés (qui peuvent être créés à l'aide de l'API de gestion), utilisés dans des 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éée à l'aide de la méthode simple POST ci-dessus sont vides. Dans les rubriques 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.

Rédiger un script basé sur 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 conserver 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 API, ce fichier s'appelle 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 rend tous vos paramètres disponibles pour les 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 les exemples de plates-formes 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 simplifier la vie, 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 de proxys d'API.

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