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, sus actividades de desarrollo principales implican configurar proxies de API que funcionen como proxies para APIs 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, se recomienda que comiences con el tema Compila una API simple proxy.

Las formas más comunes de editar la configuración de proxy son la siguientes:

• Uso en el editor de XML en la IU de Edge
• Descarga la configuración y edítala de forma local, como se describe en Desarrollo local de opciones de configuración de proxy.

Desarrollo local de configuraciones de proxy

Puedes descargar la configuración del proxy para poder editarla en una máquina local. Cuándo cuando termines, subirás los resultados a Edge. Este enfoque te permite integrar el código del código fuente, el control de versiones y otros flujos de trabajo compartidos. Además, al si trabajas en una configuración de proxy de manera local, puedes usar tu propio editor de XML y con herramientas de visualización.

En esta sección, se describe cómo usar la IU para descargar una compilación de proxy existente, editarla y, luego, volver a subirlo a Edge para implementarla. 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 del proxy actual en la IU de Edge. (En los proxies de API selecciona Project > Descargar revisión).
2. En tu máquina local, crea un nuevo directorio y expande el archivo ZIP descargado en que la modifica.

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

   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 supervisión de estado en para tu proxy de API, edita el archivo de configuración de TargetEndpoint en la /apiproxy/targets/. El archivo predeterminado de este directorio es default.xml, aunque puede haber archivos con nombres diferentes si los 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 tus archivos de configuración del proxy. porque no quieres que el directorio /myappdir se incluya en el archivo ZIP. El directorio de nivel superior del archivo ZIP debe ser /apiproxy.

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

   zip my-new-proxy.zip -r .

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

   No hay requisitos especiales para el nombre del archivo ZIP. Por ejemplo, no es necesario aumentar el número de revisión o especificar la fecha en el nombre del archivo, pero esto se puede útiles para la depuración o para controlar el código fuente.

   Edge aumenta el número de revisión de la nueva configuración de proxy cuando subes que la modifica.

7. Sube la nueva configuración del proxy con la IU de Edge. (En los proxies de API selecciona Project > Sube una revisión nueva).

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

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

   Edge no implementará la revisión nueva por ti una vez que la subas con la IU.

8. Implementa la revisión nueva.

Para obtener más información, consulta 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:

Estructura del directorio del proxy de la API y contenidos

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

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 de directorios de un proxy de API.

• Configuración básica
• ProxyEndpoint
• TargetEndpoint
  • Configuración de TLS/SSL TargetEndpoint
• Políticas
• Flows
• Recursos

Configuración básica

/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

ProxyEndpoint

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

/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, estás estableciendo una configuración de red que define la manera en que las aplicaciones cliente (“aplicaciones”) 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

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 sentencias condicionales en Apigee Edge. Consulta Referencia de condiciones y Referencia de 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 el ProxyEndpoint realiza el procesamiento necesario, por ejemplo, mediante JavaScript para llamar a un servicio externo Recuperar datos de una búsqueda en los servicios de API de clave-valor.

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

Un TargetEndpoint es el equivalente saliente de un ProxyEndpoint. Un TargetEndpoint funciona como cliente a 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

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:

• HTTPTargetConnection para llamadas HTTP(S)
• LocalTargetConnection para el encadenamiento de proxy a proxy
• ScriptTarget para llamadas a un dispositivo alojado en Edge Secuencia de comandos de Node.js

Configura solo una de estas opciones en un TargetEndpoint.

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

<Ciphers>
 <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher>    
 <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher>
</Ciphers>

<Protocols>
 <Protocol>TLSv1.1</Protocol>
 <Protocol>TLSv1.2</Protocol>
</Protocols>

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

TargetEndpoint de muestra 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 Configurar TLS desde el perímetro hasta el backend (nube 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. Lo siguiente En el artículo de la comunidad de Apigee, se explica esta situación con más detalle y se proporciona una API implementable Ejemplos de proxy: 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 instancia de Edge para la instalación de nube privada, cuando se configura TLS/SSL con valores estáticos o mediante usando variables de flujo, es posible que debas reiniciar Message Processor.

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

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

Adjunto de política

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

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>

Configuración del adjunto de política Elements

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 solicitud de respuesta y el flujo de respuesta se subdividen en PreFlow, una o más o 'nombre' y un PostFlow.

• 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 video instructivo breve

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

Procesamiento por pasos

Apigee Edge aplica 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. Estas aparecen en la sección "Secuencias de comandos" sección de la 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 pasando de la API desde el proxy, el entorno y 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.