Referencia de la configuración del proxy de API

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Como desarrollador que trabaja con Apigee, tus actividades de desarrollo principales implican la configuración de 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 aprendes a compilar proxies de API, te recomendamos que comiences con el tema Compila un proxy de API simple.

Edita la configuración del proxy de API mediante uno de los siguientes métodos:

Estructura del directorio de configuración del proxy de API

A continuación, se muestra la estructura del directorio de la configuración del proxy de API:

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.

Una configuración de proxy de API consta de los siguientes contenidos:

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

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

Nombre Descripción Valor 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_-. N/A Sí
revision La cantidad de revisiones de la configuración del proxy de API. No es necesario que configures explícitamente la cantidad de revisiones, ya que Apigee hace un seguimiento automático de la revisión actual del proxy de API. N/A 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 Apigee. N/A No
DisplayName Un nombre fácil de usar que puede ser diferente del atributo name de la configuración del proxy de API. N/A 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 Apigee. Esta es simplemente una configuración de manifest, diseñada para proporcionar visibilidad del contenido del proxy de API. N/A No
ProxyEndpoints Una lista de extremos de proxy 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 Apigee. Esta es simplemente una configuración de manifest, diseñada para proporcionar visibilidad del contenido del proxy de API. N/A 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 Apigee. Esta es simplemente una configuración de manifest, diseñada para proporcionar visibilidad del contenido del proxy de API. N/A 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.
 N/A No
TargetServers Una lista de servidores de destino a los que se hace referencia en cualquier extremo de destino de este proxy de API. Por lo general, solo verás este elemento cuando se haya creado el proxy de API con Apigee. Esta es simplemente una configuración de manifest, diseñada para proporcionar visibilidad del contenido del proxy de API. N/A No
TargetEndpoints Una lista de extremos de destino en el directorio /targets de este proxy de API. Por lo general, solo verás este elemento cuando se cree el proxy de API mediante la IU de Apigee. Esta es simplemente una configuración de manifest, diseñada para proporcionar visibilidad del contenido del proxy de API. N/A 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 extremo de proxy, estableces una configuración de red que define cómo las aplicaciones cliente (apps) deben invocar la API de proxy.

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

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

Los elementos de configuración necesarios en un extremo de proxy básico son los siguientes

Elementos de configuración de ProxyEndpoint

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

Una string obligatoria que identifica de forma exclusiva la ruta de URI que Apigee usa 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 Apigee identifica las rutas válidas.

 / Sí
Properties Un conjunto de ajustes de HTTP opcionales se puede definir como propiedades de un <ProxyEndpoint>.

Usa la propiedad request.queryparams.ignore.content.type.charset para indicarle al proxy que ignore el parámetro charset del encabezado Content-Type cuando procese la URL de la solicitud. Por ejemplo: 

<Property name= \
"request.queryparams.ignore.content.type.charset">true</>

En la siguiente tabla, se muestra un resultado de ejemplo según la configuración de la propiedad charset y la presencia del parámetro charset del encabezado Content-Type.

Configuración de la propiedad Valor de encabezado Resultado de ejemplo
charset=false No se estableció el parámetro charset john.doe+test@gmail.com
charset=false charset=utf-8 john.doe test@gmail.com
charset=true y no hay un parámetro charset en el encabezado. No se estableció el parámetro charset john.doe+test@gmail.com
charset=true Se estableció el parámetro charset=utf-8 john.doe+test@gmail.com
N/A No
FaultRules
Define cómo reacciona el extremo de proxy 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.

 N/A 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.

 N/A 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 un extremo de destino con nombre, un IntegrationEndpoint o 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. N/A Sí
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. N/A No
TargetEndpoint

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

Cuando nombras un extremo de destino, 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 extremo de proxy puede llamar directamente a una URL. Por ejemplo, un recurso de JavaScript o Java, que funciona en el rol de un cliente HTTP, puede realizar el deber básico de un extremo de destino, que es reenviar solicitudes a un servicio de backend.

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

Cómo configurar RouteRules

Un extremo de destino 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 extremo de proxy 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 extremo de proxy también puede invocar directamente un servicio de backend. La invocación de URL directa omite cualquier configuración de TargetEndpoint 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 extremo de proxy.

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 declaraciones condicionales en Apigee. Consulta la referencia de condiciones y la referencia de variables de flujo.

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 extremo de destino 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 extremo de destino. Esto es útil cuando el extremo de proxy realiza todo el procesamiento necesario, por ejemplo, mediante el uso de JavaScript para llamar a un servicio externo o la recuperación de datos desde una búsqueda al almacén de clave-valor de Apigee.

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 extremo de destino es el equivalente saliente de un extremo de proxy. Un extremo de destino funciona como el cliente de un servicio de backend o una API: envía solicitudes y recibe respuestas.

Un proxy de API no necesita tener extremos de destino. Los extremos de proxy se pueden configurar para que llame a las URLs directamente. Por lo general, un proxy de API sin extremos de destino contiene un extremo de destino 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 extremo de destino define la conexión saliente de Apigee 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/>
    <Authentication/>
  </HTTPTargetConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <ScriptTarget/>
  <LocalTargetConnection/>
</TargetEndpoint>

Elementos de configuración de TargetEndpoint

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

  • HTTPTargetConnection para las llamadas HTTP o HTTPS
  • LocalTargetConnection para el encadenamiento de proxy a proxy

Configura solo una de estas opciones en un extremo de destino.

Nombre Descripción Valor predeterminado ¿Es obligatorio?
TargetEndpoint
name El nombre del extremo de destino, que debe ser único dentro de la configuración del proxy de API El nombre del extremo de destino 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._\-$ %. N/A Sí
PreFlow Define las políticas en el flujo PreFlow de una solicitud o respuesta. N/A Sí
Flows
Define las políticas en los flujos condicionales de una solicitud o respuesta.
 N/A Sí
PostFlow
Define las políticas en el flujo PostFlow de una solicitud o respuesta.
 N/A Sí
HTTPTargetConnection

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

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

Puedes usar el elemento secundario <Authentication> para realizar llamadas autenticadas a servicios de Google o servicios personalizados que se ejecutan en ciertos productos de Google Cloud, como Cloud Functions y Cloud Run. El uso del elemento <Authentication> requiere los pasos de configuración y de implementación descritos en Usa la autenticación de Google. Con una configuración adecuada, la política crea un token de autenticación y lo agrega a la solicitud de servicio. Consulta también el uso del elemento <Authentication>.
URL Define la dirección de red del servicio de backend al que el destino extremo de destino le reenvía los mensajes. N/A 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 servidores de destino para separar las opciones de configuración del proxy de API de las URLs de extremos de servicio de backend concretas.

 N/A No
Properties Un conjunto de ajustes de HTTP opcionales se puede definir como propiedades de un <TargetEndpoint>. N/A No
SSLInfo De manera opcional, puedes definir la configuración de TLS/SSL en un extremo de destino para controlar la conexión TLS/SSL entre el proxy de API y el servicio de destino. Consulta Configuración de TLS/SSL TargetEndpoint. N/A No
LocalTargetConnection Con sus elementos secundarios, especifica un recurso al que se debe llegar de forma local, sin tener en cuenta las 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. N/A No
ProxyEndpoint Se usa con APIProxy para especificar el nombre del extremo de proxy del proxy de destino. N/A 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. N/A No
FaultRules
Define cómo reacciona extremo de proxy 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.

 N/A 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.

 N/A No

Uso del elemento <Authentication>

El uso del elemento <Authentication> en <TargetEndpoint> es idéntico al uso del elemento <Authentication> en la política ServiceCallout. En <TargetEndpoint> y en ServiceCallout, <Authentication> es un subelemento de <HttpTargetConnection>. Para obtener detalles, consulte el elemento Autenticación en la Referencia de la política ServiceCallout.

Referencia de error del elemento <Authentication>

Si usas el elemento <Authentication>, puedes encontrar posibles mensajes de error y sugerencias para solucionar problemas de errores de implementación y entorno de ejecución en la sección Errores de la documentación de la política ServiceCallout.

Ejemplos de elementos <Authentication>

En el siguiente ejemplo, se muestra cómo llamar a un servicio implementado en Cloud Run como destino mediante el elemento Authentication a fin de generar un token de OpenID Connect necesario para autenticar la llamada: 

<TargetEndpoint name="TargetEndpoint-1">
  <HTTPTargetConnection>
      <Properties/>
      <URL>https://cloudrun-hostname.a.run.app/test</URL>
      <Authentication>
          <GoogleIDToken>
             <Audience>https://cloudrun-hostname.a.run.app/test</Audience>
          </GoogleIDToken>
     </Authentication>
  </HTTPTargetConnection>
</TargetEndpoint>

En el siguiente ejemplo, se muestra cómo llamar a un TargetService que apunta a Cloud Run mediante el elemento Authentication a fin de generar un token de OpenID Connect necesario para autenticar la llamada. El elemento HeaderName agrega el token del portador generado a un encabezado llamado X-Serverless-Authorization que se envía al sistema de destino. El encabezado Authorization, si está presente, se deja sin modificar y también se envía en la solicitud. 

<TargetEndpoint name="TargetEndpoint-1">
   <HTTPTargetConnection>
     <Authentication>
        <HeaderName>X-Serverless-Authorization</HeaderName>
        <GoogleIDToken>
            <Audience ref="flow.variable.audience">https://cloudrun-hostname.a.run.app</Audience>
        </GoogleIDToken>
     </Authentication>
      <LoadBalancer>
         <Server name="cloud-run-target" />
      </LoadBalancer>
   </HTTPTargetConnection>
</TargetEndpoint>

En el siguiente ejemplo, se muestra cómo llamar a un TargetService que apunta al servicio de Secret Manager de Google. En este ejemplo, el elemento GoogleAccessToken está configurado para generar un token de autenticación de Google a fin de autenticar la solicitud de destino: 

<HTTPTargetConnection>
   <Authentication>
      <GoogleAccessToken>
        <Scopes>
          <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
      </GoogleAccessToken>
    </Authentication>
    <URL>
      https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id
    </URL>
</HTTPTargetConnection>

En el siguiente ejemplo, se muestra cómo configurar automáticamente el público del GoogleIDToken. Cuando useTargetUrl es true y la variable a la que se hace referencia no se resuelve como una variable válida, se usa la URL del destino (sin incluir los parámetros de consulta) como el público. Supongamos que la ruta de la solicitud es /foobar y la URL de servidor de destino es https://xyz.com; el público del GoogleIDToken se configurará automáticamente como https://xyz.com/foobar. 

<TargetEndpoint name="TargetEndpoint-1">
  <HTTPTargetConnection>
    <Authentication>
      <GoogleIDToken>
        <Audience ref='myvariable' useTargetUrl="true"/>
      </GoogleIDToken>
    </Authentication>
    <LoadBalancer>
      <Server name="TS" />
    </LoadBalancer>
  </HTTPTargetConnection>
</TargetEndpoint>

Configuración de TargetEndpoint de TLS/SSL

Los extremos de destino 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 Valor predeterminado ¿Es obligatorio?
SSLInfo

El bloque <SSLInfo> se puede usar para TLS/SSL unidireccional y bidireccional.
Enabled

Si se establece en true, <Enabled> especifica que se debe usar el bloque <SSLInfo>. Cuando se establece en false, se ignora el bloque <SSLInfo>.

El valor predeterminado de <Enabled> es true si <URL> especifica el protocolo HTTPS, y false si <URL> especifica HTTP.

 Verdadero si <URL> especifica HTTPS No
Enforce

Aplica un SSL estricto entre Apigee y el backend de destino.

Si se establece en true, las conexiones fallarán para los destinos con certificados no válidos, certificados vencidos, certificados autofirmados, certificados con una discrepancia de nombres de host y certificados con una raíz no confiable. Se muestra un código de error de 4xx o 5xx.

Si no se establece o se establece en false, el resultado de las conexiones a backends de destino con certificados problemáticos depende de la configuración de <IgnoreValidationErrors> (consulta a continuación). Una respuesta exitosa (2xx) puede ocurrir en ciertas condiciones, si <IgnoreValidationErrors> se configura como true.

 false No
TrustStore

Un almacén de claves que contiene certificados de servidor raíz. Apigee tratará al par remoto como de confianza si la cadena de certificados que envía finaliza en un certificado que se encuentra en este almacén de claves.

 N/A No
ClientAuthEnabled

Si se establece en true, habilita TLS bidireccional (también conocida como TLS mutua o mTLS) entre Apigee y el par remoto, ya sea el cliente de API o el backend de destino.

Por lo general, la habilitación de TLS bidireccional requiere que configures un almacén de certificados de confianza y un almacén de claves en Apigee.

 false No
KeyStore Un almacén de claves que contiene claves privadas usadas para la autenticación de clientes salientes N/A Sí (si ClientAuthEnabled es verdadero)
KeyAlias El alias de clave de la clave privada que se usa para la autenticación del cliente saliente N/A Sí (si ClientAuthEnabled es verdadero)
IgnoreValidationErrors

Indica si los errores de validación se ignoran. Si el sistema de backend usa SNI y muestra un certificado con un nombre distinguido (DN) del asunto que no coincide con el nombre de host, no hay manera de ignorar el error, y la conexión falla.

Nota: Si <Enforce> se establece en true, se ignora el valor de <IgnoreValidationErrors>.

 false No
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>
 		N/A 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, especifícalos de forma explícita. Por ejemplo, para permitir solo TLS v1.2 o TLS v1.3:

<Protocols>
 <Protocol>TLSv1.2</Protocol>
 <Protocol>TLSv1.3</Protocol>
</Protocols>
 		N/A No
CommonName

Apigee verifica el valor aquí en función del CN (nombre común) o los SANs (nombres alternativos de sujeto) en el certificado del par remoto.

 N/A No

El extremo de destino de muestra con la autenticación de cliente saliente habilitada

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

Para obtener instrucciones detalladas, consulta Opciones para configurar TLS.

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 artículo de la comunidad de Apigee SSLInfo dinámico para TargetEndpoint mediante referencia de variable, se explica esta situación con más detalle y se proporcionan ejemplos de proxy de API que se pueden implementar.

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 AssignMessage. 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 extremo de destino 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.

Para obtener más información, consulta Controla los certificados vencidos.

Sin embargo, puedes configurar el extremo de destino de forma opcional para usar una referencia al almacén de claves o almacén de certificados 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 extremo de destino 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 "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>'

En el ejemplo anterior, $TOKEN está configurado como tu token de acceso de OAuth 2.0, como se describe en Obtén un token de acceso de OAuth 2.0. Para obtener información sobre las opciones de curl que se usan en este ejemplo, consulta Usa curl. Para obtener una descripción de las variables de entorno utilizadas, consulta Configura variables de entorno para solicitudes a la API de Apigee.

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 "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \
  -H "Authorization: Bearer $TOKEN"

En el ejemplo anterior, $TOKEN está configurado como tu token de acceso de OAuth 2.0, como se describe en Obtén un token de acceso de OAuth 2.0. Para obtener información sobre las opciones de curl que se usan en este ejemplo, consulta Usa curl. Para obtener una descripción de las variables de entorno utilizadas, consulta Configura variables de entorno para solicitudes a la API de Apigee.

curl "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \
  -H "Authorization: Bearer $TOKEN"

En el ejemplo anterior, $TOKEN está configurado como tu token de acceso de OAuth 2.0, como se describe en Obtén un token de acceso de OAuth 2.0. Para obtener información sobre las opciones de curl que se usan en este ejemplo, consulta Usa curl. Para obtener una descripción de las variables de entorno utilizadas, consulta Configura variables de entorno para solicitudes a la API de Apigee.

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 "https://apigee.googleapis.com/v1/organizations/{org}/environments/{org}/references/keystoreref" \
  -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'

En el ejemplo anterior, $TOKEN está configurado como tu token de acceso de OAuth 2.0, como se describe en Obtén un token de acceso de OAuth 2.0. Para obtener información sobre las opciones de curl que se usan en este ejemplo, consulta Usa curl. Para obtener una descripción de las variables de entorno utilizadas, consulta Configura variables de entorno para solicitudes a la API de Apigee.

TargetEndpoint con balanceo de cargas objetivo

Los extremos de destino admiten el balanceo de cargas en varios servidores de destino con nombres mediante tres algoritmos de balanceo de cargas.

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

IntegrationEndpoint

Un extremo de integración es un extremo de destino que ejecuta específicamente integraciones de Apigee. Si configuraste un IntegrationEndpoint, Apigee envía el objeto de solicitud a la plataforma de integración de Apigee para su ejecución. Para ejecutar la integración, además de configurar el IntegrationEndpoint, también debes agregar la política SetIntegrationRequest en tu flujo de proxy.

Puedes configurar la integración para que se ejecute de forma síncrona o asíncrona. Para ello, configura el elemento <AsyncExecution> en la configuración de IntegrationEndpoint. Para obtener más información, consulta La ejecución síncrona frente a la asíncrona. Después de ejecutar la integración, Apigee guarda la respuesta en el mensaje de respuesta.

Configura IntegrationEndpoint

Para configurar un extremo de integración como tu extremo de destino, agrega el elemento IntegrationEndpoint a tu configuración de ProxyEndpoint. La siguiente es una configuración de ProxyEndpoint de muestra:

<ProxyEndpoint name="default">
    <Description/>
    <FaultRules/>
    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Name>my-set-integration-request-policy</Name>
            </Step>
        </Request>
    </PreFlow>
    <Flows/>
    <PostFlow name="PostFlow"/>
    <HTTPProxyConnection>
        <BasePath>/integration-endpoint-test</BasePath>
        <Properties/>
    </HTTPProxyConnection>
    <RouteRule name="default">
        <IntegrationEndpoint>my-int-endpoint</IntegrationEndpoint>
    </RouteRule>
</ProxyEndpoint>

En la configuración de ProxyEndpoint de muestra, Apigee realiza las siguientes tareas:

  1. En el PreFlow, ejecuta la política llamada my-set-integration-request-policy, que establece el objeto de la solicitud de integración y las variables de flujo de integración.
  2. Usa my-int-endpoint como el extremo de destino, como se especifica en la RouteRule.
  3. Lee el objeto de solicitud de integración que my-set-integration-request-policy creó.
  4. Envía la solicitud a la plataforma de integración de Apigee mediante el objeto de solicitud y las variables de flujo establecidas por la política SetIntegrationRequest.
  5. Guarda la respuesta de la integración en el mensaje de respuesta.

El archivo XML que contiene la declaración <IntegrationEndpoint> estará disponible en el directorio APIGEE_BUNDLE_DIRECTORY/apiproxy/integration-endpoints/. Si creas el proxy de API con la opción Develop > API Proxies > CREATE NEW > Integration target, Apigee almacena la declaración en el archivo /apiproxy/integration-endpoints/default.xml. Si creas el XML de extremo de integración desde la IU, puedes proporcionar un nombre personalizado para el archivo XML.

En el siguiente ejemplo, se muestra la declaración del elemento <IntegrationEndpoint> en el archivo XML:

<IntegrationEndpoint name="my-int-endpoint">
    <AsyncExecution>false</AsyncExecution>
</IntegrationEndpoint>

Elementos de configuración de IntegrationEndpoint

Nombre Descripción Valor predeterminado ¿Es obligatorio?
IntegrationEndpoint
name El nombre del IntegrationEndpoint. Los caracteres que puedes usar en el nombre están restringidos a los siguientes: A-Za-z0-9._\-$ % N/A Sí
AsyncExecution Un valor booleano que especifica si la integración debe ejecutarse en modo síncrono o asíncrono. Para obtener más información, consulta La ejecución síncrona frente a la asíncrona. false No

La ejecución síncrona frente a la asíncrona

Puedes configurar la integración para que se ejecute en modo síncrono o asíncrono. Para comprender la diferencia entre los modos de ejecución síncrono y asíncrono, consulta <AsyncExecution>.

Usa el elemento <AsyncExecution> dentro de </IntegrationEndpoint> para especificar la ejecución síncrona o asíncrona. Si <AsyncExecution> se configura como true, la integración se ejecuta de forma asíncrona. Si lo configuras como false, la integración se ejecuta de forma síncrona.

En el siguiente ejemplo, se establece true en AsyncExecution:

<IntegrationEndpoint name="my-int-endpoint">
    <AsyncExecution>true</AsyncExecution>
</IntegrationEndpoint>

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 Valor 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 Apigee aplica restricciones adicionales, como quitar automáticamente los caracteres que no son alfanuméricos.

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

 N/A Sí
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

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

Política adjunta

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 el extremo de proxy y el extremo de destino, que contienen pasos que activan las políticas. Después de que el servicio HTTP muestra la respuesta, el extremo de destino procesa la respuesta y, luego, el extremo del proxy 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 del adjunto de política

Nombre Descripción Valor predeterminado ¿Es obligatorio?
Step
Name El nombre de la política que se ejecutará mediante esta definición de paso. N/A Sí
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. N/A 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 respuesta se subdivide en un PreFlow, uno o más flujos condicionales o con nombre opcionales, 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 extremo de destino, que se ejecuta después de que la respuesta se muestra a la app cliente solicitante. Solo se puede adjuntar la política de MessageLogging a este flujo. PostClientFlow reduce la latencia del proxy de API y pone a disposición la información para el registro que no se calcula hasta después de 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.

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

Los extremos de proxy y los extremos de destino 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 del flujo

Nombre Descripción Valor predeterminado ¿Es obligatorio?
Flow Una canalización de procesamiento de solicitud o respuesta definida por un extremo de proxy o extremo de destino
Name El nombre único del flujo. N/A Sí
Condition Una declaración condicional que evalúa una 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. Sin embargo, si incluyes un solo flujo sin una condición al final de una secuencia de flujos, este actuará como la sentencia "Else" al final de la secuencia de flujos. N/A Sí
Request La canalización asociada con el procesamiento de mensajes de solicitud N/A No
Response La canalización asociada con el procesamiento de mensajes de respuesta N/A No

Procesamiento por pasos

Apigee aplica el orden secuencial de 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 Apigee.

Consulta Administra recursos para conocer los tipos de recursos compatibles.

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. Apigee resuelve el nombre mediante el cambio del proxy de API al entorno, 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.