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

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X. En savoir plus

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

Les méthodes d'API Edge présentées dans cette rubrique peuvent être utilisées pour intégrer un proxy d'API dans le 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 un processus automatisé plus vaste qui déploie ou migre d'autres applications.

L'API Edge n'émet aucune hypothèse sur votre SDLC (ou sur celui de quelqu'un d'autre, d'ailleurs). 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. Vous pouvez le faire avec l'une des méthodes suivantes:

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

Vidéo:regardez cette courte vidéo pour apprendre à déployer une API.

Interagir avec l'API

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

Lister les API de votre organisation

Vous pouvez commencer par lister tous les proxys d'API de votre organisation. (N'oubliez pas de remplacer pour EMAIL:PASSWORD et ORG_NAME. Pour savoir comment procéder, consultez Utilisez 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 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 les attributs revision, à laquelle un numéro est associé. Les proxys d'API sont constitués d'un ensemble de configurations . Les révisions fournissent un mécanisme léger pour gérer les mises à jour de la configuration à mesure que vous itérez. 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. Vous pouvez également déployer une révision d'un proxy d'API environnement de production, tout en continuant à créer de nouvelles révisions de ce proxy d'API dans le test environnement. Lorsque vous êtes prêt, vous pouvez promouvoir la révision supérieure de votre proxy d'API à partir du 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éé. En tant qu'API passe par le cycle de vie d'une configuration et d'un déploiement itératifs, le numéro de révision par incréments de nombres entiers. À l'aide d'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, pour incrémenter la révision.

Obtenir la révision de l'API

La version de l'API (par exemple, api.company.com/v1) devrait changer de façon très importante rarement. Lorsque vous incrémentez la version de l'API, cela signifie aux développeurs qu'il existe un changement significatif dans la signature de l'interface externe exposée par l'API.

La révision du proxy d'API est un nombre incrémenté associé à un proxy d'API. configuration. Les services d'API conservent les révisions de vos configurations afin que vous puissiez configuration en cas de problème. Par défaut, la révision d'un proxy d'API est automatiquement 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 la fonction Mettre à jour Révision du proxy d'API. Si vous utilisez Maven pour le déploiement, utilisez la méthode clean ou update, comme décrit dans le plug-in Maven Lisez-moi.

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 du proxy API sont documentés en détail dans la documentation de référence sur la configuration du proxy d'API.

Le déploiement d'une API environnement

Une fois votre proxy d'API configuré pour recevoir et transférer correctement les requêtes, vous pouvez le déployer. à un ou plusieurs environnements. En règle générale, 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 en prod. Vous constaterez souvent que vous avez beaucoup plus d'un proxy d'API dans l'environnement de test, principalement parce que vous ferez beaucoup moins de des 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 ensuite publier l'URL prod sur des serveurs externes développeurs.

Comment répertorier les environnements

Chaque organisation dans Apigee Edge possède au moins deux environnements: test et prod. La la distinction est arbitraire. L'objectif est de vous fournir un espace pour 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. Par exemple, vous pouvez configurer caches de test et de production différents, auxquels seuls les proxys d'API s'exécutant environnement.

Affichez les environnements dans un 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. Une API proxy déployé à 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 les 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 contrôler si le nouveau bundle est déployé en tant que nouvelle révision ou écraser la révision existante.

Vous consultez la documentation d'Apigee Edge.
Accédez à la documentation sur 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 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 le risque de temps d'arrêt pendant le déploiement, utilisez le paramètre override sur la méthode de déploiement, puis définissez-la sur true.

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

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. La Le paramètre delay spécifie un intervalle de temps, en secondes, avant lequel la précédente le déploiement de la révision doit être annulé. Cela se traduit par un intervalle de temps entre à effectuer avant que le proxy d'API traite la transaction soit annulé. Le suivi est 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é vers cette révision. Aucun nouveau trafic n'est envoyé à la Révision 1.
  • Toutefois, il est possible que la révision 1 traite encore des transactions existantes. En définissant delay (par exemple, 15 secondes), vous accordez 15 secondes à la révision 1 pour terminer le traitement des transactions existantes.
  • Après l'intervalle de délai, le déploiement de la révision 1 est annulé.
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 n'est pas déployé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 offrir une fluidité le déploiement. La révision existante reste déployée pendant que la nouvelle révision est en cours déployés. Une fois la nouvelle révision déployée, le déploiement de l'ancienne est annulé. Utiliser dans conjointement avec le paramètre delay pour contrôler l'annulation du déploiement. se produit.
delay

Pour permettre le traitement des transactions sur la révision existante avant qu'elle ne soit non déployées, et éliminent les risques de 502 Bad Gateway ou 504 Gateway Timeout errors : définissez ce paramètre sur le nombre de secondes souhaité pour l'annulation du déploiement. en retard. Vous pouvez définir autant de secondes que vous le souhaitez, sur les performances lors de la définition d'un grand nombre de secondes. Pendant le délai, aucune nouvelle le trafic 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 est défini sur 0. Le déploiement de la révision existante est annulé dès que le nouveau la révision de l'ancienne version est déployée. Les valeurs négatives sont traitées comme des 0 (zéro) seconde.

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

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

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

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. Périphérie. Vous ne pouvez pas modifier ces paramètres, sauf si vous utilisez Apigee Edge sur site.

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

Affichez tous les déploiements dans environnement de test

Vous pouvez également récupérer l'état de déploiement d'un environnement spécifique (y compris la version le numéro 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.

Affichez tous les déploiements dans votre organisation

Pour récupérer une 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

Cela 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 un fichier JSON ou XML par rapport à 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 dans 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 ce qui 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'une API proxy:

  • APIProxy revision: itération numérotée séquentiellement du proxy d'API telles que gérées par les services d'API
  • APIProxy name: nom unique du proxy d'API.
  • ConfigurationVersion: version des services d'API vers laquelle le 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 d'Apigee Edge qui a créé l'API proxy
  • DisplayName: nom convivial du proxy d'API.
  • LastModifiedAt: heure à laquelle le proxy d'API a été généré, au format UNIX durée
  • LastModifiedBy: adresse e-mail de l'utilisateur d'Apigee Edge qui a créé l'API proxy
  • Policies: une liste des règles qui ont été ajoutées à ce proxy d'API
  • ProxyEndpoints: liste des points de terminaison de proxy nommés
  • Resources: liste des ressources (JavaScript, Python, Java, LTI) disponibles pour être exécutée dans ce proxy d'API
  • TargetServers: liste de TargetServers nommés (que vous pouvez créer à l'aide de la méthode de gestion), utilisée dans les configurations avancées à des fins d'équilibrage de charge.
  • TargetEndpoints: liste de TargetEndpoints nommés

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

Pour en savoir plus sur ces éléments de configuration, consultez la documentation de référence sur la configuration du proxy d'API.

Créer un script à l'aide de l'API

Le module Utiliser les exemples de proxy d'API disponibles sur GitHub fournissent 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é 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 disponibles 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 permet de gérer de manière centralisée les identifiants de votre compte. Dans l'API Dans l'exemple de plate-forme, 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 le déploiement .

Créez maintenant un script shell qui importe ces paramètres et les utilise pour appeler l'outil de déploiement. (Pour voir un exemple, consultez <ph type="x-smartling-placeholder"></ph> 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 vie, créez également un script pour appeler et tester l'API, ce qui 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 déployer des proxys d'API.

Le script ci-dessous appelle directement l'API de gestion. Elle annule le déploiement de la révision existante le 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 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