Estás viendo la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
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 del 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 implementen proxies de API, o que migren 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 (o la de otra persona, para el caso). En su lugar, expone funciones atómicas que tu equipo de desarrollo puede coordinar para automatizar y optimizar el ciclo de vida del desarrollo de la API.
Para obtener información completa, consulta API de Edge.
Para usar la API de Edge, debes autenticarte en tus llamadas. Puedes hacerlo con uno de los siguientes métodos:
- OAuth2 (solo en la nube pública)
- SAML (nube pública y privada)
- Autenticación básica (no se recomienda; nube pública y privada)
Este tema se centra en el conjunto de APIs que se usan para administrar proxies de API.
Video: Mire este video breve para obtener información sobre cómo implementar una API.
Interactúa con la API
En los siguientes pasos, se te guiará por interacciones simples con las API.
Enumerar las API de tu organización
Puedes comenzar con la 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 Cómo usar 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 en 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 liviano 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 del proxy de API. Además, puedes implementar una revisión de un proxy de API en el entorno de producción y, al mismo tiempo, crear revisiones nuevas de ese proxy de API en el entorno de prueba. Cuando estés listo, puedes promover la revisión superior del proxy de API en el entorno de pruebas con 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 recorre el ciclo de vida de la implementación y configuración iterativas, el número de revisión aumenta por números enteros. Con las llamadas directas a la API para implementar, 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 quieras aumentar la revisión.
Obtener revisión de la API
La versión de la API (por ejemplo, api.company.com/v1) debería cambiar con poca frecuencia. Cuando aumentas la versión de la API, les indicas a los desarrolladores que hubo un cambio significativo en la firma de la interfaz externa expuesta por la API.
La revisión del proxy de API es un número incrementado asociado con una configuración de proxy de API. Los servicios de API mantienen las revisiones de tus configuraciones para que puedas revertir una configuración cuando algo salga 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 de importación de un proxy de API. Si no quieres que se aumente la revisión de un proxy de API, usa la API de actualización de revisiones del proxy de la API. Si usas Maven para realizar la implementación, usa las opciones clean o update, como se describe en el archivo readme del complemento de Maven.
Por ejemplo, puedes llamar al método GET en la revisión 1 del proxy de la 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 muestra
{
"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 del proxy de la API se documentan en detalle en la referencia de configuración del proxy de API.
Implementar una API en un entorno
Una vez que el proxy de API esté configurado para recibir y reenviar solicitudes de forma adecuada, puedes implementarlo en uno o más entornos. Por lo general, debes iterar en los proxies de API en test y, cuando esté listo, promover 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 habrás mucho menos iteraciones 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
implementes la revisión del proxy de la API en producción, puedes publicar la URL prod para los desarrolladores
externos.
Cómo crear una lista de entornos
Cada organización en Apigee Edge tiene al menos dos entornos: test y prod. La distinción es arbitraria. El objetivo es brindarte un área para verificar que el proxy de API funcione correctamente antes de abrirlos para desarrolladores externos.
Cada entorno es en realidad solo una dirección de red, lo que te permite segregar el tráfico entre los proxies de API en los que estás trabajando y 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 cachés en prueba y producción, a las que solo pueden acceder los proxies de API que se ejecutan en ese entorno.
Ver 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 que está en el estado implementado a través de la red, en las direcciones definidas en el elemento <VirtualHost> para ese entorno.
Implementa proxies de API
Los proxies de API no se pueden invocar hasta que se hayan implementado. Los servicios de API exponen las API 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 nuevo paquete 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.
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 que quieres anular.
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 continua (cero 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 establécelo en true.
No se puede implementar una revisión de un proxy de API por encima de otra. Siempre se debe anular la implementación
de la primera. Si configuras override como true, indicas que una revisión de un proxy de API debe implementarse sobre la revisión implementada actualmente. El resultado es que la secuencia de implementación se revierte, la revisión nueva se implementa y, una vez que se completa la implementación, se anula 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 debería anular la implementación de la revisión anterior. El efecto es que las transacciones en tránsito tienen un intervalo en el cual se debe completar antes de que se anule la implementación del proxy de API que procesa la transacción. A continuación, se muestra lo que sucede con override=true y el parámetro delay configurado:
- La revisión 1 controla solicitudes.
- Se está implementando la revisión 2 en paralelo.
- Cuando la Revisión 2 está completamente implementada, 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. Si configuras el parámetro
delay(por ejemplo, 15 segundos), le darás a la Revisión 1 15 segundos para terminar 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 que se anule la implementación, y para eliminar la posibilidad de El valor predeterminado es 0 (cero) segundos. Cuando |
Cuando se usa override=true junto con un delay, se pueden eliminar las respuestas 5XX de HTTP durante la implementación. Esto se debe a que ambas revisiones del proxy de API se implementarán de forma simultánea, y la revisión anterior se anulará después del retraso.
Ver todas las implementaciones de una revisión de la 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 use Apigee Edge de forma local, no puede 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 se implemente una revisión específica de un proxy de API en un entorno.
Ver todas las implementaciones en el entorno de pruebas
También puedes recuperar el estado de implementación de 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
Esto muestra el mismo resultado que el anterior para cada API implementada en el entorno de prueba.
Ver todas las implementaciones en 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
Esto muestra el mismo resultado anterior para todos los proxies de API implementados en todos los entornos.
Dado que la API es RESTful, puedes usar el método POST, junto con una carga útil JSON o XML, en el mismo recurso para crear un proxy de API.
Se generará un perfil para su proxy de API. La representación predeterminada de un proxy de API está en la notación de objetos 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 incluye 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 secuencialmente de la configuración del proxy de API, como la mantienen los servicios de APIAPIProxy name: El nombre único del proxy de APIConfigurationVersion: Es la versión de los servicios de API a la que cumple la configuración del proxy de API.CreatedAt: La hora en la que se generó el proxy de API, en formato UNIXCreatedBy: Es la dirección de correo electrónico del usuario de Apigee Edge que creó el proxy de API.DisplayName: Un nombre fácil de usar para el proxy de APILastModifiedAt: La hora en la que se generó el proxy de API, en formato UNIXLastModifiedBy: Es la dirección de correo electrónico del usuario de Apigee Edge que creó el proxy de API.Policies: Una lista de las políticas que se agregaron a este proxy de APIProxyEndpoints: Una lista de ProxyEndpoints con nombreResources: Una lista de recursos (JavaScript, Python, Java, XSLT) disponibles para su ejecución en este proxy de APITargetServers: Una lista de TargetServers con nombre (que se pueden crear mediante la API de administración), 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 creados mediante 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.
Secuencias de comandos con la API
Usa los proxies de API de muestra, disponibles en GitHub, para proporcionar 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 muestran 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 que contenga 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 hace que toda tu configuración esté disponible para las secuencias de comandos de shell que unen la herramienta de implementación.
Ahora cree 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 muestras de la plataforma de 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
A fin de facilitarte la vida, crea una secuencia de comandos para invocar y probar la API de la siguiente manera:
#!/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}"
Invoca la API directamente
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 administración. 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 de proxy y, luego, sube, importa e 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