Referencia de la configuración del proxy de API

Estás viendo la documentación de Apigee Edge.
Ve a la documentación de Apigee X.
Información

Como desarrollador que trabaja con Apigee Edge, tus actividades principales de desarrollo implican configurar proxies de API que funcionan como proxies para API o servicios de backend. Este documento es una referencia de todos los elementos de configuración disponibles para ti a fin de compilar proxies de API.

Si estás aprendiendo a compilar proxies de API, te recomendamos que comiences con el tema Compila un proxy de API simple.

Las formas más comunes de editar los parámetros de configuración del proxy son las siguientes:

Desarrollo local de configuraciones de proxy

Puedes descargar la configuración del proxy para editarla en una máquina local. Cuando termines, sube los resultados a Edge. Este enfoque te permite integrar la configuración del proxy en el control de origen, el control de versiones y otros flujos de trabajo compartidos. Además, si trabajas en una configuración de proxy de manera local, puedes usar tu propio editor de XML y herramientas de validación.

En esta sección, se describe cómo usar la IU para descargar una confuración de proxy existente, editarla y, luego, volver a subirla a Edge para la implementación. También puedes usar apigeetool para descargar y, luego, implementar una configuración de proxy nueva (mediante los comandos fetchproxy y deployproxy, respectivamente).

Para editar una configuración de proxy de forma local con la IU, haz lo siguiente:

  1. Descarga la configuración actual del proxy en la IU de Edge. (En la vista Proxies de API, selecciona Proyecto > Descargar revisión).
  2. En tu máquina local, crea un directorio nuevo y expande el archivo ZIP descargado en él.

    Para expandir el archivo ZIP, puedes usar una utilidad como unzip, como se muestra en el siguiente ejemplo:

    mkdir myappdir
    unzip ./my-app_app_rev3_2019_04_20.zip -d myappdir

    El contenido expandido del archivo ZIP debe ser similar a la estructura descrita en Estructura del proxy de la API.

  3. Edita los archivos fuente, según sea necesario. Para obtener una descripción de los archivos fuente en una configuración de proxy, consulta Archivos de configuración y estructura de directorio de un proxy de API.

    Por ejemplo, para habilitar la supervisión de estado en tu proxy de API, edita el archivo de configuración TargetEndpoint en el directorio /apiproxy/targets/. El archivo predeterminado de este directorio es default.xml, aunque puede haber archivos con diferentes nombres si usas destinos condicionales.

    En este caso, si el archivo de configuración TargetEndpoint y su directorio no existen, créalos.

  4. Cuando termines de editar los archivos de configuración del proxy, asegúrate de guardar los cambios.
  5. Cambia al directorio nuevo que creaste cuando expandiste los archivos ZIP (la raíz de los archivos de configuración expandidos).

    Por ejemplo, si expandiste los archivos al directorio /myappdir, cambia a ese directorio, como se muestra en el siguiente ejemplo:

    cd myappdir

    Debes cambiar a este directorio antes de volver a archivar los archivos de configuración del proxy, ya que no deseas que el directorio /myappdir se incluya en el archivo ZIP. El directorio de nivel superior en el archivo ZIP debe ser /apiproxy.

  6. Vuelve a archivar los archivos de configuración del proxy, incluidos los archivos nuevos o modificados. Puedes usar una utilidad, como zip, como se muestra en el siguiente ejemplo:
    zip my-new-proxy.zip -r .

    El directorio de nivel superior en el archivo ZIP debe ser /apiproxy.

    No hay requisitos especiales para el nombre de archivo ZIP. Por ejemplo, no necesitas aumentar el número de revisión ni especificar la fecha en el nombre del archivo, pero hacerlo puede ser útil para la depuración o el control del código fuente.

    Edge incrementa el número de revisión de la nueva configuración del proxy cuando la subes.

  7. Sube la nueva configuración del proxy con la IU de Edge. (En la vista Proxies de API, selecciona Project > Upload a New Revision).

    Si recibes un error como Bundle is invalid. Empty bundle., asegúrate de que el directorio de nivel superior de tu archivo ZIP sea /apiproxy. Si no es así, vuelve a archivar los archivos de configuración del proxy desde la raíz del directorio expandido.

    Después de subir la nueva configuración del proxy, Edge incrementa el número de revisión y lo muestra en la vista Resumen de revisión.

    Edge no implementa la revisión nueva después de que la subes con la IU.

  8. Implementa la revisión nueva.

Para obtener más información, consulta el Instructivo: Cómo descargar un proxy con la IU y la API de administración en la Comunidad de Apigee.

Estructura del proxy de API

Un proxy de API consta de la siguiente configuración:

Configuración básica Configuración principal para un proxy de API Consulta Configuración básica.
Configuración de ProxyEndpoint Configuración para la conexión HTTP entrante (de solicitudes de apps a Apigee Edge), flujos de solicitud y respuesta, y adjuntos de políticas. Consulta ProxyEndpoint.
Configuración de TargetEndpoint Configuración de la conexión HTTP saliente (de Apigee Edge al servicio de backend), los flujos de solicitud y respuesta, y los adjuntos de políticas. Consulta TargetEndpoint.
Flujos ProxyEndpoint y TargetEndpoint solicitan canalizaciones y respuestas a las que se pueden adjuntar políticas. Consulta Flujos.
Políticas Archivos de configuración con formato XML que cumplen con los esquemas de políticas de Apigee Edge. Consulta Políticas.
Recursos Secuencias de comandos, archivos JAR y archivos XSLT a los que hacen referencia las políticas para ejecutar la lógica personalizada. Consulta recursos.

Estructura y contenido del directorio del proxy de API

Los componentes de la tabla anterior se definen mediante los archivos de configuración en la siguiente estructura de directorio:

Muestra la estructura del directorio en la que apiproxy es la raíz. Directamente en el directorio de apiproxy, se encuentran las políticas, los proxies, los recursos y los directorios de destino, además del archivo weatherapi.xml.

Archivos de configuración y estructura de directorios de proxy de API

En esta sección, se explican los archivos de configuración y la estructura del directorio de un proxy de API.

/apiproxy/weatherapi.xml

La configuración base de un proxy de API, que define el nombre del proxy de API. El nombre debe ser único dentro de una organización.

Configuración de ejemplo

<APIProxy name="weatherapi">
</APIProxy>

Elementos de la configuración base

Nombre Descripción Predeterminado ¿Es obligatorio?
APIProxy
name El nombre del proxy de API, que debe ser único dentro de la organización. Los caracteres que puedes usar en el nombre están restringidos a los siguientes: A-Za-z0-9_-. No disponible
revision La cantidad de revisiones de la configuración del proxy de API. No necesitas establecer el número de revisión de forma explícita, ya que Apigee Edge realiza un seguimiento automático de la revisión actual del proxy de API. No disponible No
ConfigurationVersion La versión del esquema de configuración del proxy de API a la que se ajusta este proxy de API. Por el momento, los únicos valores admitidos son majorVersion 4 y minorVersion 0. Esta configuración se puede usar en el futuro para habilitar la evolución del formato del proxy de API. 4.0 No
Description Una descripción textual del proxy de API. Si se proporciona, la descripción se mostrará en la IU de administración de Edge. No disponible No
DisplayName Un nombre fácil de usar que puede ser diferente del atributo name de la configuración del proxy de API. No disponible No
Policies Una lista de políticas en el directorio /policies de este proxy de API. Por lo general, solo verás este elemento cuando se haya creado el proxy de API con la IU de administración perimetral. Se trata de una configuración del "manifiesto" diseñada para proporcionar visibilidad del contenido del proxy de API. No disponible No
ProxyEndpoints Una lista de ProxyEndpoints en el directorio /proxies de este proxy de API. Por lo general, solo verás este elemento cuando se haya creado el proxy de API con la IU de administración perimetral. Se trata de una configuración del “manifiesto” diseñada para proporcionar visibilidad del contenido del proxy de API. No disponible No
Resources Una lista de recursos (JavaScript, Python, Java y XSLT) en el directorio /resources de este proxy de API. Por lo general, solo verás este elemento cuando se haya creado el proxy de API con la IU de administración perimetral. Esta es simplemente una configuración del "manifiesto" diseñada para proporcionar visibilidad del contenido del proxy de API. No disponible No
Spec Identifica la especificación de OpenAPI que está asociada con el proxy de API. El valor se establece en una URL o en una ruta de acceso en el almacén de especificaciones.

Nota: El almacén de especificaciones solo está disponible en la nueva experiencia de Edge. Para obtener más información sobre el almacén de especificaciones, consulta Cómo administrar y compartir especificaciones.
No disponible No
TargetServers Una lista de TargetServers a los que se hace referencia en cualquier TargetEndpoints de este proxy de API. Por lo general, solo verás este elemento cuando se haya creado el proxy de API con la IU de administración perimetral. Se trata de una configuración del "manifiesto" diseñada para proporcionar visibilidad del contenido del proxy de API. No disponible No
TargetEndpoints Una lista de TargetEndpoints en el directorio /targets de este proxy de API. Por lo general, solo verás este elemento cuando se haya creado el proxy de API con la IU de administración perimetral. Se trata de una configuración del “manifiesto” diseñada para proporcionar visibilidad del contenido del proxy de API. No disponible No

ProxyEndpoint

En la siguiente imagen, se muestra el flujo de solicitud y respuesta:

Muestra un cliente que llama a un servicio HTTP. La solicitud pasa por el extremo del proxy y, luego, el extremo objetivo antes de que el servicio de HTTP los procese. La respuesta pasa por el extremo de destino y, luego, el extremo del proxy antes de que se muestre al cliente.

/apiproxy/proxies/default.xml

La configuración de ProxyEndpoint define la interfaz entrante (dirigida al cliente) para un proxy de API. Cuando configuras un ProxyEndpoint, estableces una configuración de red que define cómo las aplicaciones cliente (“apps”) deben invocar la API con proxy.

La siguiente configuración de muestra de ProxyEndpoint se almacenará en /apiproxy/proxies:

<ProxyEndpoint name="default">
  <PreFlow/>
  <Flows/>
  <PostFlow/>
  <HTTPProxyConnection>
    <BasePath>/weather</BasePath>
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

Los elementos de configuración necesarios en un ProxyEndpoint básico son los siguientes:

Elementos de configuración de ProxyEndpoint

Nombre Descripción Predeterminado ¿Es obligatorio?
ProxyEndpoint
name El nombre del ProxyEndpoint. Debe ser único en la configuración del proxy de API, cuando (en casos excepcionales) se definen varios ProxyEndpoints. Los caracteres que puedes usar en el nombre están restringidos a los siguientes: A-Za-z0-9._\-$ %. No disponible
PreFlow Define las políticas en el flujo PreFlow de una solicitud o respuesta. No disponible
Flows
Define las políticas en los flujos condicionales de una solicitud o respuesta.
No disponible
PostFlow
Define las políticas en el flujo PostFlow de una solicitud o respuesta.
No disponible
HTTPProxyConnection Define la dirección de red y la ruta de URI asociadas con el proxy de API.
BasePath

Una string obligatoria que identifica de manera inequívoca la ruta de acceso del URI que usa Apigee Edge para enrutar los mensajes entrantes al proxy de API adecuado.

BasePath es un fragmento de URI (por ejemplo /weather) agregado a la URL base de un proxy de API (por ejemplo, http://apifactory-test.apigee.net). BasePath debe ser único dentro de un entorno. La unicidad se valida cuando se genera o se importa un proxy de API.

Usa un comodín en rutas de acceso base

Puedes usar uno o más comodines “*” en las rutas base del proxy de API. Por ejemplo, una ruta base de /team/*/members permite que los clientes llamen a https://[host]/team/blue/members y a https://[host]/team/green/members sin necesidad de crear proxies de API nuevos para admitir equipos nuevos. Ten en cuenta que no se admite /**/.

Importante: Apigee NO admite el uso de un comodín “*” como el primer elemento de una ruta base. Por ejemplo, NO se admite: /*/search. Iniciar la ruta base con un “*” puede generar errores inesperados debido a la forma en que Edge identifica las rutas válidas.

/
VirtualHost

Asocia un proxy de API con URLs base específicas para un entorno. Un VirtualHost es una configuración con nombre que define una o más URLs para un entorno.

Los VirtualHosts nombrados de un ProxyEndpoint determinan los dominios y los puertos en los que se expone un proxy de API y, por extensión, la URL que usan las apps para invocar un proxy de API.

De forma predeterminada, se definen dos VirtualHosts con nombre para un entorno: default y secure. Una organización también puede definir dominios personalizados. Para asegurarte de que un proxy de API solo esté disponible a través de HTTPS, por ejemplo, configura VirtualHost en HTTPProxyConnection como secure.

predeterminado No
Properties Un conjunto de ajustes de HTTP opcionales se puede definir como propiedades de un <ProxyEndpoint>. No disponible No
FaultRules
Define cómo reacciona ProxyEndpoint a un error. Una regla de falla especifica dos elementos:
  • Una condición que especifica la falla que se manejará según la categoría, la subcategoría o el nombre predefinidos de la falla.
  • Una o más políticas que definen el comportamiento de la regla de falla para la condición correspondiente

Consulta Controla errores.

No disponible No
DefaultFaultRule

Controla cualquier error (sistema, transporte, mensajería o política) que no se controle explícitamente mediante otra regla de falla.

Consulta Controla errores.

No disponible No
RouteRule Define el destino de los mensajes de solicitud entrantes después de que los procesa la canalización de solicitud de ProxyEndpoint. Por lo general, la RouteRule apunta a una configuración de TargetEndpoint con nombre, pero también puede apuntar directamente a una URL.
Name Atributo obligatorio, que proporciona un nombre para RouteRule. Los caracteres que puedes usar en el nombre están restringidos a los siguientes: A-Za-z0-9._\-$ %. Por ejemplo, Cat2 %_ es un nombre legal. No disponible
Condition Una declaración condicional opcional que se usa para el enrutamiento dinámico en el entorno de ejecución Las RouteRules condicionales son útiles, por ejemplo, para habilitar el enrutamiento basado en el contenido y admitir el control de versiones de backend. No disponible No
TargetEndpoint

Una string opcional que identifica una configuración TargetEndpoint con nombre. Un TargetEndpoint con nombre es cualquier TargetEndpoint definido en el mismo proxy de API en el directorio /targets.

Cuando nombras un TargetEndpoint, indicas dónde se deben reenviar los mensajes de la solicitud después del procesamiento por la canalización de solicitud ProxyEndpoint. Ten en cuenta que esta es una configuración opcional.

Un ProxyEndpoint puede llamar directamente a una URL. Por ejemplo, un recurso de JavaScript o Java, que funciona de la función de un cliente HTTP, puede realizar el deber básico de un TargetEndpoint, que es reenviar solicitudes a un servicio de backend.

No disponible No
URL Una string opcional que define una dirección de red saliente que llama el ProxyEndpoint y omite cualquier configuración de TargetEndpoint que podría almacenarse en /targets. N/A No

Cómo configurar RouteRules

Un TargetEndpoint con nombre hace referencia a un archivo de configuración en /apiproxy/targets al que la RouteRule reenvía una solicitud después de que el ProxyEndpoint la procesa.

Por ejemplo, la siguiente RouteRule hace referencia a la configuración /apiproxy/targets/myTarget.xml:

<RouteRule name="default">
  <TargetEndpoint>myTarget</TargetEndpoint>
</RouteRule>

Invocación de URL directa

Un ProxyEndpoint también puede invocar directamente un servicio de backend. La invocación de URL directa omite cualquier configuración de TargetEndpoints con nombre en /apiproxy/targets. Por este motivo, TargetEndpoint opcional es una configuración de proxy de API, aunque, en la práctica, no se recomienda la invocación directa desde ProxyEndpoint.

Por ejemplo, la siguiente RouteRule siempre realiza una llamada HTTP a http://api.mycompany.com/v2.

<RouteRule name="default">
  <URL>http://api.mycompany.com/v2</URL> 
</RouteRule>

Rutas condicionales

RouteRules se puede encadenar para admitir el enrutamiento dinámico en el entorno de ejecución. Las solicitudes entrantes se pueden enrutar a las opciones de configuración de TargetEndpoint con nombres, directamente a las URL, o a una combinación de ambas, en función de encabezados HTTP, contenido de mensajes, parámetros de consulta o información contextual, como la hora del día, configuración regional, etcétera.

Las RouteRules condicionales funcionan como otras instrucciones condicionales en Apigee Edge. Consulta Referencia de las condiciones y Referencia de las variables.

Por ejemplo, la siguiente combinación de RouteRule evalúa primero la solicitud entrante para verificar el valor de un encabezado HTTP. Si el encabezado HTTP routeTo tiene el valor TargetEndpoint1, la solicitud se reenvía al TargetEndpoint llamado TargetEndpoint1. De lo contrario, la solicitud se reenvía a http://api.mycompany.com/v2.

<RouteRule name="MyRoute">
  <Condition>request.header.routeTo = "TargetEndpoint1"</Condition>
  <TargetEndpoint>TargetEndpoint1</TargetEndpoint>
</RouteRule>
<RouteRule name="default">
  <URL>http://api.mycompany.com/v2</URL>
</RouteRule>

Rutas nulas

Se puede definir una RouteRule nula para admitir situaciones en las que no sea necesario reenviar el mensaje de solicitud al TargetEndpoint. Esto es útil cuando ProxyEndpoint realiza todo el procesamiento necesario, por ejemplo, mediante JavaScript para llamar a un servicio externo o recuperar datos de una búsqueda en el almacén de clave-valor de los Servicios de la API.

Por ejemplo, lo siguiente define una ruta nula:

<RouteRule name="GoNowhere"/>

Las rutas nulas condicionales pueden ser útiles. En el siguiente ejemplo, se configura una ruta nula para ejecutarse cuando un encabezado HTTP request.header.X-DoNothing tenga un valor distinto de null.

<RouteRule name="DoNothingOnDemand">
  <Condition>request.header.X-DoNothing != null</Condition>
</RouteRule>

Recuerda que RouteRules se puede encadenar, por lo que una ruta nula condicional generalmente sería un componente de un conjunto de RouteRules diseñadas para admitir el enrutamiento condicional.

Un uso práctico de una ruta nula condicional sería compatible con el almacenamiento en caché. Mediante el valor de la variable que establece la política de caché, puedes configurar un proxy de API para ejecutar la ruta nula cuando se entrega una entrada desde la caché.

<RouteRule name="DoNothingUnlessTheCacheIsStale">
  <Condition>lookupcache.LookupCache-1.cachehit is true</Condition>
</RouteRule>

TargetEndpoint

Muestra un cliente que llama a un servicio HTTP. La solicitud pasa por el extremo del proxy y, luego, el extremo objetivo antes de que el servicio de HTTP los procese. La respuesta pasa por el extremo de destino y, luego, el extremo del proxy antes de que se muestre al cliente.

Un TargetEndpoint es el equivalente saliente de un ProxyEndpoint. Un TargetEndpoint funciona como cliente para un servicio de backend o una API: envía solicitudes y recibe respuestas.

Un proxy de API no necesita tener TargetEndpoints. ProxyEndpoints se pueden configurar para que llame a las URL directamente. Por lo general, un proxy de API sin TargetEndpoints contiene un ProxyEndpoint que llama directamente a un servicio de backend o que está configurado para llamar a un servicio mediante Java o JavaScript.

Configuración de TargetEndpoint

/targets/default.xml

El TargetEndpoint define la conexión saliente de Apigee Edge a otro servicio o recurso.

Esta es una muestra de configuración del TargetEndpoint:

<TargetEndpoint name="default">
  <PreFlow/>
  <Flows/>
  <PostFlow/>
  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
    <SSLInfo/>
  </HTTPTargetConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <ScriptTarget/>
  <LocalTargetConnection/>
</TargetEndpoint>

Elementos de configuración de TargetEndpoint

Un TargetEndpoint puede llamar a un destino de una de las siguientes maneras:

Configura solo una de estas opciones en un TargetEndpoint.

Nombre Descripción Predeterminado ¿Es obligatorio?
TargetEndpoint
name El nombre del TargetEndpoint, que debe ser único dentro de la configuración del proxy de API El nombre del TargetEndPoint se usa en la RouteRule ProxyEndpoint para dirigir solicitudes de procesamiento saliente. Los caracteres que puedes usar en el nombre están restringidos a los siguientes: A-Za-z0-9._\-$ %. No disponible
PreFlow Define las políticas en el flujo PreFlow de una solicitud o respuesta. No disponible
Flows
Define las políticas en los flujos condicionales de una solicitud o respuesta.
No disponible
PostFlow
Define las políticas en el flujo PostFlow de una solicitud o respuesta.
No disponible
HTTPTargetConnection

Con sus elementos secundarios, especifica el alcance de un recurso de backend a través de HTTP.

Si usas HTTPTargetConnection, no configures otros tipos de conexiones de destino (ScriptTarget o LocalTargetConnection).

URL Define la dirección de red del servicio de backend al que el destino TargetEndpoint le reenvía los mensajes. No disponible No
LoadBalancer

Define una o más opciones de configuración de TargetServer con nombre. Las opciones de configuración de TargetServer con nombre se pueden usar para el balanceo de cargas que define 2 o más conexiones de configuración de extremos.

También puedes usar TargetServers para separar las opciones de configuración del proxy de API de las URL de extremos de servicio de backend concretas.

Consulta Balanceo de cargas entre servidores de backend.

No disponible No
Properties Un conjunto de ajustes de HTTP opcionales se puede definir como propiedades de un <TargetEndpoint>. No disponible No
SSLInfo De manera opcional, puedes definir la configuración de TLS/SSL en un TargetEndpoint para controlar la conexión TLS/SSL entre el proxy de API y el servicio de destino. Consulta Configuración de TLS/SSL TargetEndpoint. No disponible No
LocalTargetConnection Con sus elementos secundarios, especifica un recurso al que se accederá de forma local y omite características de la red, como el balanceo de cargas y los procesadores de mensajes.

Para especificar el recurso de destino, incluye el elemento secundario de APIProxy (con el elemento ProxyEndpoint) o el elemento secundario de la ruta de acceso.

Para obtener más información, consulta Encadena los proxies de API.

Si usas LocalTargetConnection, no configures otros tipos de conexiones de destino (HTTPTargetConnection o ScriptTarget).

APIProxy Especifica el nombre de un proxy de API para usarlo como destino de solicitudes. El proxy de destino debe estar en la misma organización y entorno que el proxy que envía solicitudes. Esta es una alternativa al uso del elemento de Ruta. No disponible No
ProxyEndpoint Se usa con APIProxy para especificar el nombre del ProxyEndpoint del proxy de destino. No disponible No
Path Especifica la ruta de acceso del extremo de un proxy de API que se usa como destino para las solicitudes. El proxy de destino debe estar en la misma organización y entorno que el proxy que envía solicitudes. Esta es una alternativa al uso de APIProxy. No disponible No
FaultRules
Define cómo reacciona ProxyEndpoint a un error. Una regla de falla especifica dos elementos:
  • Una condición que especifica la falla que se manejará según la categoría, la subcategoría o el nombre predefinidos de la falla.
  • Una o más políticas que definen el comportamiento de la regla de falla para la condición correspondiente

Consulta Controla errores.

No disponible No
DefaultFaultRule

Controla cualquier error (sistema, transporte, mensajería o política) que no se controla de forma explícita por otra FaultRule.

Consulta Controla errores.

No disponible No
ScriptTarget
ResourceURL

Define el tipo de recurso (nodo) y el nombre de la secuencia de comandos principal de Node.js que implementa la funcionalidad TargetEndpoint.

<ResourceURL>node://server.js</ResourceURL>

La secuencia de comandos debe incluirse en los archivos de recursos del proxy de API. Consulta Cómo agregar Node.js a un proxy de API existente.

Si usas ScriptTarget, no configures otros tipos de conexiones de destino (HTTPTargetConnection o LocalTargetConnection).

No disponible
EnvironmentVariable

De manera opcional, puedes pasar las variables de entorno a la secuencia de comandos principal de Node.js.

Consulta Comprende la compatibilidad de Edge para los módulos de Node.js.

No disponible No
Arguments

De manera opcional, pasa los argumentos a la secuencia de comandos principal de Node.js.

Consulta Comprende la compatibilidad de Edge para los módulos de Node.js.

No disponible No

Configuración de TargetEndpoint de TLS/SSL

TargetEndpoints a menudo necesita administrar conexiones HTTPS con infraestructura de backend heterogénea. Por este motivo, se admiten varios parámetros de configuración de TLS/SSL.

Elementos de configuración de TargetEndpoint de TLS/SSL

Nombre Descripción Predeterminado ¿Es obligatorio?
SSLInfo
Enabled Indica si TLS/SSL está habilitado para el extremo. El valor predeterminado es true si <URL> especifica el protocolo HTTPS y false si <URL> especifica HTTP. Verdadero si <URL> especifica HTTPS No
TrustStore Un almacén de claves que contiene certificados de servidor de confianza. No disponible No
ClientAuthEnabled Una configuración que active la autenticación del cliente saliente (TLS/SSL bidireccional) false No
KeyStore Un almacén de claves que contiene claves privadas usadas para la autenticación de clientes salientes No disponible Sí (si ClientAuthEnabled es verdadero)
KeyAlias El alias de clave de la clave privada que se usa para la autenticación del cliente saliente No disponible Sí (si ClientAuthEnabled es verdadero)
Ciphers

Algoritmos de cifrado admitidos para TLS/SSL saliente. Si no se especifican algoritmos de cifrado, se permitirán todos los algoritmos de cifrado disponibles para la JVM.

Para restringir los algoritmos de cifrado, agrega los siguientes elementos que enumeran los algoritmos de cifrado admitidos:

<Ciphers>
 <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher>    
 <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher>
</Ciphers>
No disponible No
Protocols

Protocolos admitidos para TLS/SSL de salida. Si no se especifican protocolos, se permitirán todos los protocolos disponibles para la JVM.

Para restringir los protocolos, agrega los siguientes elementos contienen una lista con los protocolos compatibles:

<Protocols>
 <Protocol>TLSv1.1</Protocol>
 <Protocol>TLSv1.2</Protocol>
</Protocols>
No disponible No
CommonName

Si se especifica, un valor con el que se valida el nombre común del certificado de destino. Este valor solo es válido para las configuraciones de TargetEndpoint y TargetServer. No es válida para la configuración de VirtualHost.

Según la configuración predeterminada, el valor especificado coincide exactamente con el nombre común del certificado de destino. Por ejemplo, usar *.myhost.com como valor de <CommonName> solo coincidirá y validará el nombre de host de destino si se especifica el valor exacto *.myhost.com como nombre común en el certificado de destino.

De forma opcional, Apigee puede realizar la coincidencia con comodines mediante el atributo wildcardMatch.

Por ejemplo, un nombre común especificado como abc.myhost.com en un certificado de destino coincidiría y validaría si el elemento <CommonName> se especifica de la siguiente manera:

<CommonName wildcardMatch="true">*.myhost.com</CommonName>

No disponible No

Ejemplo de TargetEndpoint con la autenticación de cliente saliente habilitada

<TargetEndpoint name="default">
  <HttpTargetConnection>
        <URL>https://myservice.com</URL>
    <SSLInfo>
      <Enabled>true</Enabled>
      <ClientAuthEnabled>true</ClientAuthEnabled>
      <KeyStore>myKeystore</KeyStore>
      <KeyAlias>myKey</KeyAlias>
      <TrustStore>myTruststore</TrustStore>
    </SSLInfo>
  </HttpTargetConnection>
</TargetEndpoint>

Para obtener instrucciones detalladas, consulta Configura TLS desde Edge al backend (Cloud y nube privada).

Usa variables de flujo para configurar valores TLS/SSL de forma dinámica

También puedes establecer de forma dinámica los detalles de TLS/SSL para admitir requisitos de entorno de ejecución flexibles. Por ejemplo, si tu proxy se conecta a dos objetivos potencialmente diferentes (un destino de prueba y uno de producción), puedes hacer que tu proxy de API detecte de manera programática a qué entorno llama y configure referencias de forma dinámica para el almacén de claves y el almacén de confianza adecuados. En el siguiente artículo de la comunidad de Apigee, se explica esta situación con más detalle y se proporcionan ejemplos de proxy de API implementables: https://community.apigee.com/articles/21424/dynamic-sslinfo-for-targetendpoint-using-variable.html.

En el siguiente ejemplo de cómo se configuraría la etiqueta <SSLInfo> en una configuración de TargetEndpoint, los valores se pueden proporcionar en el entorno de ejecución, por ejemplo, a través de un texto destacado de Java, una política de JavaScript o una política de asignación de mensajes. Usa las variables de mensajes que contengan los valores que deseas establecer.

Las variables solo se permiten en los siguientes elementos.

<SSLInfo>
    <Enabled>{myvars.ssl.enabled}</Enabled>
    <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled>
    <KeyStore>{myvars.ssl.keystore}</KeyStore>
    <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias>
    <TrustStore>{myvars.ssl.trustStore}</TrustStore>
</SSLInfo>

Usa referencias para establecer valores TLS/SSL de forma dinámica

Cuando configuras un TargetEndpoint que usa HTTPS, debes tener en cuenta el caso cuando el certificado TLS/SSL vence o un cambio en la configuración del sistema requiere que actualices el certificado. En una instalación de Edge para la nube privada, cuando configuras TLS/SSL con valores estáticos o variables de flujo, existe la posibilidad de que debas reiniciar Message Processor.

Para obtener más información, consulta Actualiza un certificado TLS.

Sin embargo, puedes configurar TargetTarget de forma opcional para usar una referencia al almacén de claves o almacén de confianza. La ventaja de usar una referencia es que puedes actualizar la referencia para que apunte a un almacén de claves o almacén de confianza diferente a fin de actualizar el certificado TLS/SSL sin tener que reiniciar Message Processors.

Por ejemplo, a continuación se muestra un TargetEndpoint que usa una referencia al almacén de claves:

<SSLInfo> 
    <Enabled>true</Enabled> 
    <ClientAuthEnabled>false</ClientAuthEnabled> 
    <KeyStore>ref://keystoreref</KeyStore> 
    <KeyAlias>myKeyAlias</KeyAlias> 
</SSLInfo>

Usa la siguiente llamada a la API de POST para crear la referencia llamada keystoreref:

curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
-d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u email:password

En la referencia, se especifica el nombre del almacén de claves y su tipo.

Usa la siguiente llamada a la API de GET para ver la referencia:

curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password

Para cambiar más adelante la referencia a fin de que apunte a un almacén de claves diferente, asegúrate de que el alias tenga el mismo nombre, usa la siguiente llamada PUT:

curl -X PUT -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references/keystoreref \
-d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u email:password

TargetEndpoint con balanceo de cargas objetivo

TargetEndpoints admite el balanceo de cargas en varios TargetServers con nombres mediante tres algoritmos de balanceo de cargas.

Para obtener instrucciones detalladas, consulta Balanceo de cargas en los servidores de backend.

Políticas

El directorio /policies en un proxy de API contiene todas las políticas disponibles para adjuntar a flujos en el proxy de API.

Elementos de configuración de la política

Nombre Descripción Predeterminado ¿Es obligatorio?
Policy
name

El nombre interno de la política. Los caracteres que puede usar en el nombre están restringidos a: A-Za-z0-9._\-$ %. Sin embargo, la IU de administración perimetral aplica restricciones adicionales, como la eliminación automática de caracteres que no son alfanuméricos.

De manera opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

No disponible
enabled

Configúralo como true para aplicar la política.

Configúralo como false para “desactivar” la política. La política no se aplicará incluso si permanece adjunta a un flujo.

true No
continueOnError

Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas.

Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle.

false No
async

Nota: Este atributo no hace que la política se ejecute de forma asíncrona. En la mayoría de los casos, deja este valor con el valor predeterminado de false.

Cuando se configura en true, la ejecución de políticas se descarga en un subproceso diferente, lo que permite que el subproceso principal esté libre para manejar solicitudes adicionales. Cuando se completa el procesamiento sin conexión, el subproceso principal regresa y termina de controlar el flujo de mensajes. En algunos casos, establecer un valor asíncrono con true mejora el rendimiento del proxy de API. Sin embargo, el uso asíncrono excesivo puede afectar el rendimiento con demasiados cambios de subproceso.

Para usar el comportamiento asíncrono en los proxies de API, consulta Modelo de objetos de JavaScript.

false No

Adjunto de política

En la siguiente imagen, se muestra la secuencia de ejecución de flujos del proxy de API:

Muestra un cliente que llama a un servicio HTTP La solicitud encuentra los ProxyEndpoint y TargetEndpoint, que contienen pasos que activan las políticas. Después de que el servicio HTTP muestra la respuesta, el TargetEndpoint procesa la respuesta y, luego, el ProxyEndpo antes de mostrarla al cliente. Al igual que con la solicitud, las políticas procesan la respuesta dentro de los pasos.

Como se mostró antes:

Las políticas se adjuntan como pasos de procesamiento a Flujos. El nombre de la política se usa para hacer referencia a la política que se aplicará como un paso de procesamiento. El formato de un adjunto de política es el siguiente:

<Step><Name>MyPolicy</Name></Step>

Las políticas se aplican en el orden en que se adjuntan a un flujo. Por ejemplo:

<Step><Name>FirstPolicy</Name></Step>
<Step><Name>SecondPolicy</Name></Step>

Elementos de configuración de adjuntos de políticas

Nombre Descripción Predeterminado ¿Es obligatorio?
Step
Name El nombre de la política que se ejecutará mediante esta definición de paso. No disponible
Condition Una declaración condicional que determina si la política se aplica de forma forzosa o no. Si una política tiene una condición asociada, la política solo se ejecuta si la declaración condicional se evalúa como verdadera. No disponible No

Flujos

ProxyEndpoint y TargetEndpoint definen una canalización para el procesamiento de mensajes de solicitud y respuesta. Una canalización de procesamiento consiste en un flujo de solicitud y un flujo de respuesta. Cada flujo de solicitud y de respuesta se subdivide en un flujo previo, uno o más flujos opcionales “condicionales” o “con nombre”, y un flujo posterior.

  • PreFlow: Siempre se ejecuta. Se ejecuta antes de cualquier flujo condicional.
  • PostFlow: Siempre se ejecuta. Se ejecuta después de cualquier flujo condicional.

Además, puedes agregar un PostClientFlow al ProxyEndpoint, el cual se ejecuta una vez que la respuesta se muestra a la app cliente solicitante. Solo se puede adjuntar a este flujo la política de MessageLogging y la extensión de Google Stackdriver Logging. PostClientFlow reduce la latencia del proxy de la API y pone a disposición la información para el registro que no se calcula hasta que se muestra la respuesta al cliente, como en client.sent.start.timestamp y client.sent.end.timestamp El flujo se usa principalmente para medir el intervalo de tiempo entre las marcas de tiempo de inicio y de finalización del mensaje de respuesta.

Mira un breve video instructivo

Video: Mira este breve video sobre el uso de un registro de mensajes en PostClientFlow.

Este es un ejemplo de un PostClientFlow con una política de registro de mensajes adjunta.

    ...
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <PostClientFlow>
        <Request/>
        <Response>
            <Step>
                <Name>Message-Logging-1</Name>
            </Step>
        </Response>
    </PostClientFlow>
    ...

La canalización de procesamiento del proxy de API ejecuta flujos en la siguiente secuencia:

Canalización de solicitud:

  1. PreFlow de solicitud de proxy
  2. Flujos condicionales de solicitud de proxy (opcional)
  3. PostFlow de solicitud de proxy
  4. PreFlow de solicitudes de destino
  5. Flujos condicionales de solicitudes de destino (opcional)
  6. PostFlow de solicitud de destino

Canalización de respuesta:

  1. PreFlow de la respuesta de destino
  2. Flujos condicionales de respuesta de destino (opcional)
  3. PostFlow de respuesta de destino
  4. PreFlow de respuesta de proxy
  5. Flujos condicionales de respuesta del proxy (opcional)
  6. PostFlow de respuesta del proxy
  7. Respuesta de PostClientFlow (opcional)

Solo los flujos con adjuntos de política deben configurarse en ProxyEndpoint o TargetEndpoint. Solo es necesario especificar PreFlow y PostFlow en una configuración ProxyEndpoint o TargetEndpoint cuando una política debe aplicarse durante el procesamiento de PreFlow o PostFlow.

A diferencia de los flujos condicionales, el orden de los elementos PreFlow y PostFlow no es importante; el proxy de la API siempre se ejecutará cada uno en el punto apropiado de la canalización, sin importar dónde aparezcan en la configuración del extremo.

Flujos condicionales

ProxyEndpoints y TargetEndpoints admiten una cantidad ilimitada de flujos condicionales (también conocidos como “flujos con nombre”).

El proxy de API prueba la condición especificada en el flujo condicional y, si se cumple la condición, el proxy de API ejecuta los pasos de procesamiento. Si no se cumple la condición, se omiten los pasos de procesamiento del flujo condicional. Los flujos condicionales se evalúan en el orden definido en el proxy de API y se ejecuta el primero cuya condición se cumple.

Cuando defines flujos condicionales, obtienes la capacidad de aplicar pasos de procesamiento en un proxy de API en función de lo siguiente:

  • URI de solicitud
  • Verbo HTTP (GET/PUT/POST/DELETE)
  • Valor de un parámetro de búsqueda, un encabezado y un parámetro de forma
  • Muchos otros tipos de condiciones

Por ejemplo, en el siguiente flujo condicional, se especifica que se ejecuta solo cuando la ruta del recurso de solicitud es /accesstoken. Cualquier solicitud entrante con la ruta de acceso /accesstoken hace que este flujo se ejecute, junto con cualquier política que esté conectada al flujo. Si la ruta de acceso de la solicitud no incluye el sufijo /accesstoken, el flujo no se ejecuta (aunque otro flujo condicional podría hacerlo).

<Flows>
  <Flow name="TokenEndpoint">
    <Condition>proxy.pathsuffix MatchesPath "/accesstoken"</Condition>
    <Request>
      <Step>
        <Name>GenerateAccessToken</Name>
      </Step>
    </Request> 
  </Flow>
</Flows>   

Elementos de configuración de flujo

Nombre Descripción Predeterminado ¿Es obligatorio?
Flow Una canalización de procesamiento de solicitud o respuesta definida por un ProxyEndpoint o TargetEndpoint
Name El nombre único del flujo. No disponible
Condition Una declaración condicional que evalúa las variables o más variables que se evalúan como verdaderas o falsas. Todos los flujos distintos de los tipos predefinidos de PreFlow y PostFlow deben definir una condición para su ejecución. No disponible
Request La canalización asociada con el procesamiento de mensajes de solicitud No disponible No
Response La canalización asociada con el procesamiento de mensajes de respuesta No disponible No

Procesamiento por pasos

Apigee Edge aplica de manera forzosa el orden secuencial de los flujos condicionales. Los flujos condicionales se ejecutan de arriba abajo. Se ejecuta el primer flujo condicional cuya condición se evalúa como true y solo se ejecuta un flujo condicional.

Por ejemplo, en la siguiente configuración de flujo, cualquier solicitud entrante que no incluya el sufijo de ruta /first o /second hará que se ejecute ThirdFlow, y que se aplique la política llamada Return404.

<Flows>
  <Flow name="FirstFlow">
    <Condition>proxy.pathsuffix MatchesPath "/first"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="SecondFlow">
    <Condition>proxy.pathsuffix MatchesPath "/second"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
      <Step><Name>SecondPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="ThirdFlow">
    <Request>
      <Step><Name>Return404</Name></Step>
    </Request>
  </Flow>
</Flows>

Recursos

Los “recursos” (archivos de recursos para usar en proxies de API) son secuencias de comandos, código y transformaciones XSL que se pueden adjuntar a flujos mediante políticas. Estos aparecen en la sección "Secuencias de comandos" del editor de proxy de API, en la IU de administración.

Consulta Archivos de recursos para conocer los tipos de recursos admitidos.

Los recursos se pueden almacenar en un proxy de API, un entorno o una organización. En cada caso, se hace referencia a un recurso por nombre en una política. Los servicios de API resuelven el nombre cambiando del proxy de API al entorno y al nivel de la organización.

Se puede hacer referencia a un recurso almacenado en el nivel de la organización mediante las políticas en cualquier entorno. Se puede hacer referencia a un recurso almacenado en el nivel del entorno mediante las políticas en ese entorno. Solo puede hacer referencia a un recurso almacenado en el nivel del proxy de API mediante las políticas en ese proxy de API.