Estás consultando la documentación de Apigee Edge.
Consulta la
documentación de Apigee X. Información
Cada organización tiene un ciclo de vida de desarrollo de software (SDLC) único. A menudo, es necesario sincronizar y alinear la implementación del proxy de API con los procesos que se usan para los servicios de backend.
Los métodos de la API de Edge que se muestran en este tema se pueden usar para integrar la administración de proxy de API en el SDLC de tu organización. Un uso común de esta API es escribir secuencias de comandos o código que implementan proxies de API o que migran proxies de API de un entorno a otro, como parte de un proceso automatizado más grande que también implementa o migra otras aplicaciones.
La API de Edge no hace suposiciones sobre tu SDLC (ni sobre el de otra persona, en realidad). En cambio, expone funciones atómicas que tu equipo de desarrollo puede coordinar para automatizar y optimizar el ciclo de vida de desarrollo de tu API.
Para obtener información completa, consulta APIs de Edge.
Para usar la API de Edge, debes autenticarte en tus llamadas. Puedes hacerlo con uno de los siguientes métodos:
- OAuth2 (solo nube pública)
- SAML (nube pública y privada)
- Autenticación básica (no recomendado; nube pública y privada)
En este tema, nos enfocaremos en el conjunto de APIs para administrar proxies de API.
Video: Mira este breve video para aprender a implementar una API.
Interactúa con la API
En los siguientes pasos, se explican interacciones simples con las APIs.
Enumerar las APIs de tu organización
Para comenzar, puedes obtener una lista de todos los proxies de API de tu organización. Recuerda sustituir las entradas por EMAIL:PASSWORD y ORG_NAME. Para obtener instrucciones, consulta Usa la API de Edge.
curl -u EMAIL:PASSWORD \ https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis
Respuesta de muestra:
[ "weatherapi" ]
Obtén una API
Puedes llamar al método GET en cualquier proxy de API de tu organización. Esta llamada muestra una lista de todas las revisiones disponibles del proxy de API.
curl -u EMAIL:PASSWORD -H "Accept: application/json" \ https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi
Respuesta de muestra:
{
"name" : "weatherapi",
"revision" : [ "1" ]
}
El único detalle que muestra este método es el nombre del proxy de API junto con la revisión asociada, que tiene un número asociado. Los proxies de API consisten en un conjunto de archivos de configuración. Las revisiones proporcionan un mecanismo básico para administrar las actualizaciones de la configuración a medida que iteras. Las revisiones están numeradas de forma secuencial, lo que te permite revertir un cambio mediante la implementación de una revisión anterior de tu proxy de API. Además, puedes implementar una revisión de un proxy de API en el entorno de producción y seguir creando revisiones nuevas de ese proxy de API en el entorno de pruebas. Cuando estés listo, puedes promover la revisión superior del proxy de API desde el entorno de pruebas sobre la revisión anterior del proxy de API en el entorno de producción.
En este ejemplo, solo hay una revisión porque se acaba de crear el proxy de API. A medida que un proxy de API se mueve por el ciclo de vida de la configuración y la implementación iterativa, el número de revisión se incrementa por números enteros. Mediante llamadas directas a la API para la implementación, tienes la opción de aumentar el número de revisión del proxy de API. A veces, cuando realizas cambios menores, es posible que no desees aumentar la revisión.
Obtener revisiones de API
La versión de la API (por ejemplo, api.company.com/v1) debería cambiar con muy poca frecuencia. Cuando aumentas la versión de la API, significa que se produjo un cambio significativo en la firma de la interfaz externa que expone la API.
La revisión del proxy de la API es un número incrementado asociado con una configuración de proxy de la API. Los servicios de API mantienen revisiones de tu configuración para que puedas revertir una
configuración cuando algo sale mal. De forma predeterminada, la revisión de un proxy de API aumenta automáticamente cada vez que importas un proxy de API mediante la API Importar un proxy de API. Si no deseas aumentar la revisión de un proxy de API, usa la API de Update API proxy review. Si usas Maven para la implementación, usa las opciones clean o update, como se describe en el archivo readme sobre el complemento de Maven.
Por ejemplo, puedes llamar al método GET en la revisión 1 del proxy de API para obtener una vista detallada.
curl -u EMAIL:PASSWORD -H "Accept:application/json" \ https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi/revisions/1
Respuesta de ejemplo
{
"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"
}
Estos elementos de configuración de proxy de API se documentan en detalle en la referencia de configuración de proxy de API.
Implementar una API en un entorno
Una vez que tu proxy de API esté configurado para recibir y reenviar solicitudes de forma correcta, puedes implementarlo
en uno o más entornos. Por lo general, iteras en los proxies de API en test y, cuando está todo listo, promocionas la revisión del proxy de API a prod. A menudo, descubrirás que tienes muchas más revisiones de un proxy de API en el entorno de pruebas, principalmente porque harás mucha menos iteración en el entorno de producción.
No se puede invocar un proxy de API hasta que se haya implementado en un entorno. Una vez que hayas
implementado la revisión del proxy de la API en producción, podrás publicar la URL prod para los desarrolladores
externos.
Cómo enumerar entornos
Cada organización de Apigee Edge tiene al menos dos entornos: test y prod. La distinción es arbitraria. El objetivo es brindarte un área para verificar que tu proxy de API funcione correctamente antes de abrirlo para los desarrolladores externos.
Cada entorno es solo una dirección de red, lo que te permite segregar el tráfico entre los proxies de API en los que trabajas y aquellos a los que acceden las apps en el tiempo de ejecución.
Los entornos también proporcionan segregación de datos y recursos. Por ejemplo, puedes configurar diferentes memorias caché en prueba y producción, a las que solo pueden acceder los proxies de API que se ejecutan en ese entorno.
Visualiza los entornos de una organización
curl -u EMAIL:PASSWORD \ https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments
Respuesta de ejemplo
[ "test", "prod" ]
Explora las implementaciones
Una implementación es una revisión de un proxy de API que se implementó en un entorno. Se puede acceder a un proxy de API en el estado implementado mediante la red en las direcciones definidas en el elemento <VirtualHost> para ese entorno.
Implementa proxies de API
No se pueden invocar los proxies de API hasta que se hayan implementado. Los servicios de la API exponen las APIs de RESTful que proporcionan control sobre el proceso de implementación.
Solo se puede implementar una revisión de un proxy de API en un entorno a la vez. Por lo tanto, se debe anular la implementación de la revisión implementada. Puedes controlar si el paquete nuevo se implementa como una revisión nueva o si reemplaza la revisión existente.
Estás viendo la documentación de Apigee Edge.
Consulta la documentación de Apigee X. Más información
Primero, anula la implementación de la revisión existente. Especifica el nombre del entorno y el número de revisión del proxy de API del que deseas anular la implementación:
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
Luego, implementa la revisión nueva. La nueva revisión del proxy de API ya debe existir:
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
Implementación sencilla (sin tiempo de inactividad)
Para minimizar el potencial de tiempo de inactividad durante la implementación, usa el parámetro override en el método de implementación y configúralo como true.
No puedes implementar una revisión de un proxy de API sobre otra. La primera siempre debe estar
anulada. Si configuras override como true, indicas que se debe implementar una revisión de un proxy de API sobre la revisión implementada actualmente. El resultado es que se revierte la secuencia de implementación: se implementa la revisión nueva y, una vez que se completa la implementación, se anula la implementación de la revisión ya implementada.
En el siguiente ejemplo, se configura el valor override pasándolo como un parámetro de formulario:
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
Puedes optimizar aún más la implementación si configuras el parámetro delay. El parámetro delay especifica un intervalo de tiempo, en segundos, antes del cual se debe anular la implementación de la revisión anterior. El efecto es que las transacciones en curso tienen un intervalo de tiempo en el que se debe completar antes de que el proxy de API que procesa la transacción se anule. A continuación, se muestra lo que sucede con override=true y el conjunto de parámetros delay:
- La revisión 1 controla las solicitudes.
- Se está implementando la revisión 2 en paralelo.
- Cuando la revisión 2 se implementa por completo, el tráfico nuevo se envía a la revisión 2. No se envía tráfico nuevo a la revisión 1.
- Sin embargo, es posible que la revisión 1 aún esté procesando transacciones existentes. Cuando configuras el parámetro
delay(por ejemplo, 15 segundos), le otorgas 15 segundos a la revisión 1 para que termine de procesar las transacciones existentes. - Después del intervalo de retraso, se anula la implementación de la Revisión 1.
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
| Parámetro de consulta | Descripción |
|---|---|
override |
El valor predeterminado es Configúralo en |
delay |
Para permitir que se complete el procesamiento de transacciones en la revisión existente antes de
anular la implementación y eliminar la posibilidad de El valor predeterminado es de 0 (cero) segundos. Cuando |
Cuando se usa override=true junto con un delay, se pueden eliminar las respuestas HTTP 5XX durante la implementación. Esto se debe a que ambas revisiones del proxy de la API se
implementarán de forma simultánea, y la revisión anterior se anulará su implementación después de la demora.
Ver todas las implementaciones de una revisión de API
A veces, es necesario recuperar una lista de todas las revisiones implementadas actualmente de un proxy de 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 respuesta anterior contiene muchas propiedades específicas de la infraestructura interna de Apigee Edge. A menos que uses Apigee Edge de forma local, no puedes cambiar esta configuración.
Las propiedades importantes que se incluyen en la respuesta son organization, environment, aPIProxy, name y state. Si
revisas estos valores de propiedad, puedes confirmar que una revisión específica de un proxy de API se
haya implementado en un entorno.
Ver todas las implementaciones en el entorno de pruebas
También puedes recuperar el estado de la implementación para un entorno específico (incluido el número de revisión del proxy de API implementado actualmente) mediante la siguiente llamada:
curl -u EMAIL:PASSWORD https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/test/deployments
Esta opción muestra el mismo resultado que el anterior para cada API implementada en el entorno de pruebas
Ver todas las implementaciones de tu organización
Para recuperar una lista de todas las revisiones implementadas actualmente de todos los proxies de API en todos los entornos, usa el siguiente método de API:
curl https://api.enterprise.apigee.com/v1/o/ORG_NAME/deployments \ -u EMAIL:PASSWORD
Se muestra el mismo resultado que el de arriba para todos los proxies de API implementados en todos los entornos.
Como la API es RESTful, puedes usar el método POST, junto con una carga útil de JSON o XML, en el mismo recurso para crear un proxy de API.
Se generará un perfil para tu proxy de API. La representación predeterminada de un proxy de API se encuentra en la notación de objetos de JavaScript (JSON). A continuación, se muestra la respuesta JSON predeterminada a la solicitud POST anterior, que creó un proxy de API llamado weatherapi. A continuación, se proporciona una descripción de cada elemento del perfil:
{
"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"
}
El perfil de proxy de API que se genera demuestra la estructura completa de un proxy de API:
APIProxy revision: La iteración numerada de forma secuencial de la configuración del proxy de API, como la mantienen los Servicios de APIAPIProxy name: Es el nombre único del proxy de API.ConfigurationVersion: Es la versión de los servicios de API a la que se ajusta la configuración de proxy de API.CreatedAt: Hora en la que se generó el proxy de API, con formato de tiempo UNIXCreatedBy: Dirección de correo electrónico del usuario de Apigee Edge que creó el proxy de APIDisplayName: Es un nombre fácil de usar para el proxy de API.LastModifiedAt: Hora en la que se generó el proxy de la API, con formato de tiempo UNIXLastModifiedBy: Dirección de correo electrónico del usuario de Apigee Edge que creó el proxy de APIPolicies: Es una lista de políticas que se agregaron a este proxy de API.ProxyEndpoints: Una lista de ProxyEndpoints con nombreResources: Es una lista de recursos (JavaScript, Python, Java, XSLT) disponibles para ejecutar en este proxy de APITargetServers: Una lista de TargetServers con nombre (que se pueden crear con la API de Management), que se usa en configuraciones avanzadas para fines de balanceo de cargasTargetEndpoints: Una lista de TargetEndpoints con nombre
Ten en cuenta que muchos de los elementos de la configuración del proxy de API que se creó con el método POST simple anterior están vacíos. En los siguientes temas, aprenderás a agregar y configurar los componentes clave de un proxy de API.
También puedes leer sobre estos elementos de configuración en la referencia de configuración del proxy de API.
Secuencia de comandos con la API
En la sección Usa los proxies de API de muestra, disponible en GitHub, se proporcionan secuencias de comandos de shell que unen la herramienta de implementación de Apigee. Si por algún motivo no puedes usar la herramienta de implementación de Python, puedes llamar directamente a la API. Ambos enfoques se demuestran en las secuencias de comandos de ejemplo que aparecen a continuación.
Une la herramienta de implementación
Primero, asegúrate de que la herramienta de implementación de Python esté disponible en tu entorno local.
Luego, crea un archivo para guardar tus credenciales. Las secuencias de comandos de implementación que escribas importarán
esta configuración, lo que te ayudará a administrar de forma centralizada las credenciales de tu cuenta. En la muestra de la plataforma de API, este archivo se llama 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
El archivo anterior pone a disposición toda tu configuración para las secuencias de comandos de shell que unen la herramienta de implementación.
A continuación, crea una secuencia de comandos de shell que importe esa configuración y la use para llamar a la herramienta de implementación. (Para ver un ejemplo, consulta las muestras de la plataforma de la API de 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
Para simplificarte mucho las cosas, también crea una secuencia de comandos para invocar y probar la API, como se indica a continuación:
#!/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}"
Cómo invocar directamente la API
Puede ser útil escribir secuencias de comandos de shell simples que automaticen el proceso de carga y de implementación de proxies de API.
La siguiente secuencia de comandos invoca directamente la API de Management. Anula la implementación de la revisión existente del proxy de API que estás actualizando, crea un archivo ZIP del directorio /apiproxy que contiene tus archivos de configuración del proxy y, luego, sube, importa y, luego, implementa la configuración.
#!/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