Implementa proxies de API con la API

Estás viendo la documentación de Apigee Edge.
Ve a 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 para sincronizar y alinear la implementación del proxy de API con los procesos usados para los servicios de backend.

Los métodos de la API de Edge que se muestran en este tema se pueden usar para integrar el proxy de API la administración 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 es 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 el de otra persona, por el momento). En cambio, expone funciones atómicas que pueden ser coordinadas por tu equipo de desarrollo para automatizar y optimizar el ciclo de vida de desarrollo de tus APIs.

Para obtener información completa, consulta API de Edge.

Para usar la API de Edge, debes autenticarte en tus llamadas. Puedes hacer esto con uno de los siguientes métodos:

En este tema, nos enfocaremos en el conjunto de APIs que se usan 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 las interacciones simples con las APIs.

Obtén una lista de las APIs de tu organización

Para comenzar, puedes enumerar todos los proxies de API de tu organización. (Recuerda reemplazar entradas para 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 devuelve 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 los atributos revision, que tiene un número asociado. Los proxies de API consisten en un paquete de archivos. Las revisiones proporcionan un mecanismo básico para administrar las actualizaciones de la configuración a medida que iteras. Las revisiones se enumeran de manera secuencial para que puedas revertir un cambio implementando una revisión anterior de tu proxy de API. Además, puedes implementar una revisión de un proxy de API en la entorno de producción, mientras se siguen creando revisiones nuevas de ese proxy de API en la prueba en un entorno de nube. Cuando esté todo listo, puedes promover la revisión superior de tu proxy de API desde la entorno de prueba de 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. Como API y el proxy se mueven a través del ciclo de vida de la configuración y la implementación iterativas, incrementa por números enteros. Si usas 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 haces cambios menores, es posible que no quieras incrementar la revisión.

Obtener revisión de API

La versión de la API (por ejemplo, api.company.com/v1) debería cambiar muy con poca frecuencia. Cuando incrementas la versión de la API, significa que los desarrolladores hubo un cambio significativo en la firma de la interfaz externa que expuso la API.

La revisión del proxy de API es un número incrementado asociado con un proxy de API configuración. Los servicios de API mantienen revisiones de tus configuraciones para que puedas revertir un la configuración cuando algo sale mal. De forma predeterminada, la revisión de un proxy de API se aumenta cada vez que importas un proxy de API mediante la API de Importar un proxy de API. Si aumentar la revisión de un proxy de API, usa el comando Update API de revisión del proxy de API. Si usas Maven para la implementación, usa clean o Opciones de update, como se describe en el complemento de Maven readme.

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 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 la API.

Implementar una API en un medio ambiente

Una vez que tu proxy de API esté configurado para recibir y reenviar solicitudes de forma correcta, puedes implementarlo a uno o más entornos. Por lo general, debes iterar en los proxies de API en test y, luego, cuando esté todo listo, Asciende la revisión del proxy de API a prod. A menudo, descubrirás que hay muchos más de un proxy de API en el entorno de pruebas, principalmente porque hará mucho menos la 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 tengas implementaste la revisión del proxy de API en producción, puedes publicar la URL prod en archivos desarrolladores.

Cómo enumerar entornos

Cada organización de Apigee Edge tiene al menos dos entornos: test y prod. El la distinción es arbitraria. El objetivo es proporcionarte un área para verificar que tu proxy de API funcione correctamente antes de ofrecerlo a desarrolladores externos.

En realidad, cada entorno es solo una dirección de red, lo que 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 cachés en prueba y producción, a las que solo pueden acceder los proxies de API que se ejecutan en ese en un entorno de nube.

Ver entornos en un organización

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

Respuesta de muestra:

[ "test", "prod" ]

Explora las implementaciones

Una implementación es una revisión de un proxy de API que se implementó en un entorno. Una API que se encuentra en el estado implementado es accesible 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 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 se implementa el paquete nuevo como una revisión nueva o si reemplaza la 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 de el 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. Ya debe existir la nueva revisión del proxy de API: 

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 sin interrupciones (cero tiempo de inactividad)

Para minimizar las posibilidades 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 puedes implementar una revisión de un proxy de API por encima de otra. El primero siempre debe ser sin implementar. Si estableces override en true, indicas que una revisión de un proxy de API se debe implementar sobre la revisión actualmente implementada. Como resultado, se revierte la secuencia de implementación: se implementa la revisión nueva y, una vez la revisión ya implementada se anulará.

En el siguiente ejemplo, se configura el valor override pasándolo como un parámetro del 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 El parámetro delay especifica un intervalo de tiempo, en segundos, antes del cual se crea se debe anular la implementación de la revisión. Como resultado, las transacciones en tránsito tienen un intervalo de tiempo en que completar antes de que se anule la implementación del proxy de API que procesa su transacción. Siguiendo es Lo que sucede con override=true y el conjunto de parámetros delay:

  • La revisión 1 controla las solicitudes.
  • La revisión 2 se implementa en paralelo.
  • Cuando la revisión 2 está completamente implementada, el tráfico nuevo se envía a la revisión 2. No hay tráfico nuevo se envía a la revisión 1.
  • Sin embargo, es posible que la revisión 1 aún esté procesando transacciones existentes. Si estableces parámetro delay (por ejemplo, 15 segundos), le das a la revisión 1 15 segundos para 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 false (comportamiento normal de implementación: la revisión existente no se implementa, luego, se implementa una nueva revisión).

Se establece en true para anular el comportamiento normal de la implementación y proporcionar de Google Workspace. La revisión existente permanece implementada mientras se realiza la revisión nueva cuando se implementa un plan. Cuando se implementa la revisión nueva, se anula la implementación de la anterior. Usar en junto con el parámetro delay para controlar cuándo se anula la implementación de que ocurra.
delay

Para permitir que se complete el procesamiento de transacciones en la revisión existente antes de se anula la implementación y eliminan la posibilidad de que 502 Bad Gateway o 504 Gateway Timeout errors: configura este parámetro en la cantidad de segundos que deseas que dure la anulación de la implementación. retrasado. No hay límite para la cantidad de segundos que puedes configurar las ramificaciones del rendimiento para establecer una gran cantidad de segundos. Durante la demora, no habrá nuevas el tráfico se envía a la revisión anterior.

El valor predeterminado es 0 (cero) segundos. Cuando override se establece como verdadero y delay es 0, la revisión existente se anula inmediatamente después de la nueva se implementa la revisión. Los valores negativos se consideran como 0 segundos (cero).

Cuando se usa override=true junto con delay, 5XX HTTP durante la implementación se pueden eliminar. Esto se debe a que ambas revisiones del proxy de API implementada simultáneamente, y la revisión anterior se anuló después del retraso.

Ver todas las implementaciones de una API Revisión

A veces, es necesario recuperar una lista de todas las revisiones implementadas actualmente de una 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 respuesta anterior contiene muchas propiedades específicas de la infraestructura interna de Apigee Edge. No puedes cambiar esta configuración, a menos que uses Apigee Edge de forma local.

Las propiedades importantes que se incluyen en la respuesta son organization, environment, aPIProxy, name y state. De estos valores de propiedades, puedes confirmar que se está realizando una revisión específica de un proxy de API implementados en un entorno.

Consulta todas las implementaciones en la entorno de pruebas

También puedes recuperar el estado de implementación de un entorno específico (incluida la revisión del proxy de API implementado actualmente) con la siguiente llamada:

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

Se mostrará el mismo resultado que el ejemplo anterior para cada API implementada en el entorno de pruebas.

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, haz lo siguiente: 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 que se muestra arriba 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 un archivo 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 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. Una descripción de cada elemento del perfil sigue:

{
  "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 del proxy de API que se genera demuestra la estructura completa de una API proxy:

  • APIProxy revision: la iteración numerada de forma secuencial del proxy de API de servicio administrada por los servicios de API
  • APIProxy name: el nombre único del proxy de API
  • ConfigurationVersion: Es la versión de los servicios de API a la que el proxy de API. configuración se ajusta
  • CreatedAt: Hora en la que se generó el proxy de API, con el formato de hora UNIX
  • CreatedBy: Dirección de correo electrónico del usuario de Apigee Edge que creó la API proxy
  • DisplayName: Es un nombre fácil de usar para el proxy de API.
  • LastModifiedAt: Hora en la que se generó el proxy de API, con el formato de UNIX vez
  • LastModifiedBy: Dirección de correo electrónico del usuario de Apigee Edge que creó la API proxy
  • Policies: Una lista de las políticas que se agregaron a este proxy de API
  • ProxyEndpoints: Una lista de ProxyEndpoints con nombre
  • Resources: Una lista de recursos (JavaScript, Python, Java, XSLT) disponibles para en este proxy de API
  • TargetServers: una lista de TargetServers con nombre (que se pueden crear con el Management), que se usa en configuraciones avanzadas con fines de balanceo de cargas
  • TargetEndpoints: Una lista de TargetEndpoints con nombre

Ten en cuenta que muchos de los elementos de la configuración de proxy de API creados con el POST simple descrito arriba están vacíos. En los siguientes temas, aprenderás a agregar y configurar la clave y los componentes 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 página Cómo usar los proxies de API de muestra, disponibles en GitHub proporcionan secuencias de comandos de shell que unen la herramienta de implementación de Apigee. Si, por alguna razón, no puedes usar la herramienta de implementación de Python, entonces puedes llamar directamente a la API. Ambos enfoques son que se muestra en los guiones de muestra a continuación.

Une la herramienta de implementación

Primero, asegúrate de que la herramienta de implementación de Python esté disponibles en tu entorno local.

Luego, crea un archivo para guardar tus credenciales. Se importarán las secuencias de comandos de implementación que escribas estas opciones de configuración, lo que te ayudará a administrar de forma centralizada las credenciales de tu cuenta. En la API Este archivo de muestra de plataforma 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 implementación herramienta.

Ahora, crea una secuencia de comandos de shell que importe esos parámetros de configuración y los use para llamar a la herramienta de implementación. (Para ver un ejemplo, consulta ejemplos 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

Para facilitar mucho tu trabajo, crea también una secuencia de comandos para invocar y probar la API. sigue:

#!/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 la 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 de el proxy de API que estás actualizando crea un archivo ZIP desde el directorio /apiproxy. que contiene tus archivos de configuración del proxy y, luego, sube, importa e implementa el 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