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:
- OAuth2 (cloud public uniquement)
- SAML (cloud public et privé)
- Authentification de base (non recommandée : cloud public et cloud privé)
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 Définissez la valeur sur |
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 La valeur par défaut est 0 (zéro) seconde. Lorsque |
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'APIAPIProxy name
: nom unique du proxy d'APIConfigurationVersion
: version des services d'API à laquelle la configuration du proxy d'API est conformeCreatedAt
: heure à laquelle le proxy d'API a été généré, formaté en heure UNIXCreatedBy
: adresse e-mail de l'utilisateur Apigee Edge qui a créé le proxy d'APIDisplayName
: nom convivial du proxy d'APILastModifiedAt
: heure à laquelle le proxy d'API a été généré, formaté en heure UNIXLastModifiedBy
: adresse e-mail de l'utilisateur Apigee Edge qui a créé le proxy d'APIPolicies
: liste des règles qui ont été ajoutées à ce proxy d'APIProxyEndpoints
: liste des ProxyEndpoints nommésResources
: liste des ressources (JavaScript, Python, Java, YAML) pouvant être exécutées dans ce proxy d'APITargetServers
: 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 chargeTargetEndpoints
: 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