Referencia de la configuración del proxy de API

Estás viendo la documentación de Apigee X.
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 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.

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

• Usa la IU o la API de Apigee.
• Descarga el paquete de configuración de proxy de API, edítalo manualmente y sube la configuración nueva a Apigee, como se describe en Descarga y sube un paquete de configuración de proxy de API.

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:

Una configuración de proxy de API consiste en el siguiente contenido:

Configuración base>	Configuración principal para un proxy de API
ProxyEndpoint	Configuración para la conexión HTTP entrante (desde la solicitud de apps a Apigee), los flujos de solicitud y respuesta, y los adjuntos de políticas.
TargetEndpoint	Configuración para la conexión HTTP saliente (de Apigee al servicio de backend), flujos de solicitud y respuesta, y adjuntos de políticas.
Flujos	Canalizaciones de solicitud y respuesta de ProxyEndpoint y TargetEndpoint 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 para un proxy de API, que define el nombre de este. 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	Predeterminada	¿Es obligatorio?
APIProxy
name	El nombre del proxy de API, que debe ser único en una 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 cree el proxy de API con la IU de Apigee. Esta es simplemente una configuración de manifiesto, diseñada para proporcionar visibilidad del contenido del proxy de API.	N/A	No
ProxyEndpoints	Una lista de ProxyEndpoints en el directorio /proxies de este proxy de API. Por lo general, solo verás este elemento cuando el proxy de API se haya creado con la IU de Apigee. Esta es simplemente una configuración de manifiesto, diseñada para proporcionar visibilidad del contenido del proxy de API.	N/A	No
Resources	Una lista de recursos (JavaScript, Python, Java, DLP) en el directorio /resources de este proxy de API. Por lo general, solo verás este elemento cuando se creó el proxy de API con la IU de Apigee. Esta es simplemente una configuración de manifiesto, diseñada para proporcionar visibilidad del contenido del proxy de API.	N/A	No
Spec	Identifica la especificación de OpenAPI asociada al 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 TargetServers a las que se hace referencia en cualquier proxy de API de este destino. Por lo general, solo verás este elemento cuando el proxy de API se haya creado con Apigee. Esta es simplemente una configuración de manifiesto, diseñada para proporcionar visibilidad del contenido del proxy de API.	N/A	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 cree el proxy de API con la IU de Apigee. Esta es simplemente una configuración de manifiesto, 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/respuesta:

/apiproxy/proxies/default.xml

La configuración de ProxyEndpoint define la interfaz entrante (del lado del cliente) para un proxy de API. Cuando configuras un ProxyEndpoint, estás configurando una configuración de red que define cómo las aplicaciones cliente (apps) deben invocar la API con proxy.

La siguiente configuración de ProxyEndpoint de muestra 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 ProxyEndpoint básico son los siguientes:

Elementos de configuración de ProxyEndpoint

Nombre	Descripción	Predeterminada	¿Es obligatorio?
ProxyEndpoint
name	El nombre de ProxyEndpoint. Debe ser único dentro de la configuración del proxy de API, cuando se definen varios proxies de Endpoints (en casos excepcionales). 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 única dentro de un entorno. La singularidad se valida cuando se genera o se importa un proxy de API. Usa un comodín en las rutas 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 primer elemento de una ruta base. Por ejemplo, esto NO se admite: /*/search. Iniciar la ruta base con un “*” puede dar lugar a errores inesperados debido a la forma en que Apigee identifica rutas de acceso válidas.	/	Sí
Properties	Un conjunto de ajustes de HTTP opcionales se puede definir como propiedades de un <ProxyEndpoint>.	N/A	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.	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 del procesamiento mediante la canalización de solicitudes de ProxyEndpoint. Por lo general, RouteRule apunta a una configuración de TargetEndpoint, 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.	N/A	Sí
Condition	Una declaración condicional opcional que se usa para el enrutamiento dinámico durante el tiempo de ejecución. Las RouteRules condicionales son útiles, por ejemplo, para habilitar el enrutamiento basado en el contenido a fin de admitir el control de versiones de backend.	N/A	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. Mediante la asignación de nombres a un TargetEndpoint, indica dónde se deben reenviar los mensajes de solicitud después del procesamiento mediante la canalización de solicitudes de ProxyEndpoint. Ten en cuenta que esta es una configuración opcional. Un ProxyEndpoint puede llamar a una URL directamente. Por ejemplo, un recurso JavaScript o Java, que funciona en la función de un cliente HTTP, puede realizar el dese básico de un TargetEndpoint, que reenvía las solicitudes a un servicio de backend.	N/A	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 directa de URL omite cualquier configuración llamada TargetEndpoints en /apiproxy/targets. Por este motivo, TargetEndpoint es una configuración opcional de proxy de API, aunque 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 declaraciones condicionales en Apigee. Consulta la Referencia de condiciones y la referencia de variables de flujo.

Por ejemplo, la siguiente combinación de RouteRule primero evalúa 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>

Nota: Enrutamiento más dinámico

En el artículo de la comunidad de Apigee que se especifica el extremo del proxy, se muestra el enrutamiento dinámico a diferentes regiones del mundo según las variables extraídas del URI de solicitud.

Rutas nulas

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

Por ejemplo, lo siguiente define una ruta nula:

<RouteRule name="GoNowhere"/>

Las rutas condicionales nulas pueden ser útiles. En el siguiente ejemplo, se configura una ruta nula para que se ejecute cuando un encabezado HTTP request.header.X-DoNothing tiene 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 en estado condicional sería compatible con el almacenamiento en caché. Si usas el valor de la variable que establece la política de caché, puedes configurar un proxy de API para que ejecute la ruta nula cuando se entregue una entrada desde la caché.

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

TargetEndpoint

Un TargetEndpoint es el equivalente de salida de un ProxyEndpoint. Un TargetEndpoint funciona como un cliente a un servicio de backend o a la API, envía solicitudes y recibe respuestas.

Un proxy de API no necesita ningún TargetEndpoints. ProxyEndpoints se puede configurar para llamar directamente a las URL. Un proxy de API sin TargetEndpoints, por lo general, contiene un ProxyEndpoint que llama directamente a un servicio de backend o que está configurado para llamar a un servicio con Java o JavaScript.

Configuración de TargetEndpoint

/targets/default.xml

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

Esta es una configuración de muestra de 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 objetivo de una de las siguientes maneras:

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

Configura solo uno de estos en un TargetEndpoint.

Nombre	Descripción	Predeterminada	¿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._\-$ %.	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 alcance del recurso de backend a través de HTTP. Si usas HTTPTargetConnection, no configures otros tipos de conexiones de destino (ScriptTarget o LocalTargetConnection). Nota: Los elementos <LocalTargetConnection> admiten la función de sustitución de string dinámica llamada plantilla de mensajes.
URL	Define la dirección de red del servicio de backend al que el destino TargetEndpoint 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 TargetServers para separar las opciones de configuración del proxy de API de las URL 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 forma 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/TargetEndpoint Configuration. Nota:El elemento <SSLInfo> admite la función de sustitución dinámica de string llamada plantillas de mensajes.	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 usar como destino de solicitudes. El proxy de destino debe estar en la misma organización y entorno que la proxy que envía solicitudes. Esta es una alternativa al uso del elemento Path.	N/A	No
ProxyEndpoint	Se usa con APIProxy para especificar el nombre del ProxyEndpoint del proxy de destino.	N/A	No
Path	Especifica la ruta de acceso de extremo de un proxy de API para usar como destino de las solicitudes. El proxy de destino debe estar en la misma organización y entorno que la proxy que envía solicitudes. Esta es una alternativa al uso de APIProxy.	N/A	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.	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

Configuración de TargetEndpoint de TLS/SSL

TargetEndpoints a menudo necesita administrar conexiones HTTPS con infraestructura de backend heterogénea. Por esta razón, se admiten varios ajustes de configuración TLS/SSL.

Nota:Debido a que Apigee admite originalmente SSL, verás algunas instancias en la IU de Apigee y en el XML de Apigee que usa el término SSL. Por ejemplo, la entrada del menú en la IU de Apigee que usas para ver certificados se llama Certificados SSL.

Elementos de configuración de TargetEndpoint de TLS/SSL

Nombre	Descripción	Predeterminada	¿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.	N/A	No
ClientAuthEnabled	Una configuración que active la autenticación del cliente saliente (TLS/SSL bidireccional)	falso	No
KeyStore	Un almacén de claves que contiene claves privadas usadas para la autenticación del cliente saliente	N/A	Sí (si ClientAuthEnabled es verdadero)
KeyAlias	El alias de la clave privada que se usa para la autenticación del cliente saliente	N/A	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>	N/A	No
Protocols	Protocolos compatibles para TLS/SSL saliente. Si no se especifican protocolos, se permitirán todos los protocolos disponibles para la JVM. Para restringir los protocolos, agrega los siguientes elementos que enumeran los protocolos compatibles: <Protocols> <Protocol>TLSv1.1</Protocol> <Protocol>TLSv1.2</Protocol> </Protocols>	N/A	No

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 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 un objetivo de producción), puedes hacer que el proxy de la API detecte de manera programática a qué entorno llama y configura las referencias dinámicamente al almacén de claves y almacén de confianza adecuado. En el artículo Dynamic SSLInfo for TargetEndpoint que usa la referencia de variables de la Comunidad de Apigee, se explica esta situación en más detalle y se proporcionan ejemplos del proxy de API implementable.

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.

Solo se permiten variables en los siguientes elementos.

Nota: Estos elementos admiten la función de sustitución de string dinámica llamada plantillas de mensajes.

<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>

Nota: El reemplazo de variables de valores TLS/SSL solo se puede usar para un TargetEndpoint. Cualquier intento de utilizar variables en cualquier otro contexto, como el registro de mensajes, causará errores de validación.

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

Cuando configuras un TargetEndpoint que usa HTTPS, debes tener en cuenta el caso en el que vence el certificado TLS/SSL, 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 de manera opcional el TargetEndpoint 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 los procesadores de mensajes.

Nota: Solo puedes usar una referencia al almacén de claves y al almacén de confianza; no puedes usar una referencia al alias. Cuando cambies la referencia a un almacén de claves, asegúrate de que el nombre de alias del certificado sea el mismo que en el almacén de claves anterior.

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 "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.

La referencia 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 la referencia más adelante y que apunte a un almacén de claves diferente, asegúrate de que el alias tenga el mismo nombre. Para ello, 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

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	Predeterminada	¿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.	falso	No
async	Nota: Este atributo no hace que la política se ejecute de forma asíncrona. En la mayoría de los casos, deje esto con el valor predeterminado false. Cuando se configura en true, la ejecución de la política se descarga en un subproceso diferente, lo que deja el subproceso principal libre para manejar solicitudes adicionales. Cuando se completa el procesamiento sin conexión, el subproceso principal regresa y termina de manejar el flujo de mensajes. En algunos casos, configurar el asíncrono para true mejora el rendimiento del proxy de API. Sin embargo, el uso excesivo de async puede perjudicar el rendimiento con demasiados cambios de subprocesos. Para usar el comportamiento asíncrono en los proxies de API, consulta el modelo de objetos de JavaScript.	falso	No

Política adjunta

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

Como se muestra más arriba:

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 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 los adjuntos de políticas

Nombre	Descripción	Predeterminada	¿Es obligatorio?
Step
Name	Es el nombre de la política que ejecutará la definición de este paso.	N/A	Sí
Condition	Una declaración condicional que determina si la política se aplica 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 solicitudes y respuestas. Una canalización de procesamiento consta de un flujo de solicitudes y un flujo de respuesta. Cada flujo de solicitud y flujo de respuesta se subdivide en un flujo de flujo previo, uno o más condicional o con nombre opcional, y un flujo de flujo de flujo.

• PreFlow: Siempre se ejecuta. Se ejecuta antes que 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 la política de MessageLogging se puede adjuntar a este flujo. 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

Video: Mira este video breve sobre cómo usar un registro de mensajes en el PostClientFlow.

A continuación, se muestra 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 la 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 solicitud 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íticas deben configurarse en las configuraciones de ProxyEndpoint o TargetEndpoint. Solo es necesario especificar PreFlow y PostFlow en una configuración de ProxyEndpoint o TargetEndpoint cuando se debe aplicar una política 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 en el flujo condicional. Si no se cumple la condición, se omiten los pasos de procesamiento en el flujo condicional. Los flujos condicionales se evalúan en el orden definido en el proxy de API y en el primero en el que se ejecuta la condición.

Mediante la definición de flujos condicionales, obtienes la capacidad de aplicar los pasos de procesamiento en un proxy de API basado en 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, el siguiente flujo condicional especifica que se ejecuta solo cuando la ruta de acceso al recurso de solicitud es /accesstoken. Una solicitud entrante con la ruta de acceso /accesstoken hace que este flujo se ejecute, junto con cualquier política adjunta al flujo. Si la ruta de la solicitud no incluye el sufijo /accesstoken, el flujo no se ejecuta (aunque podría ser otro flujo condicional).

<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	Predeterminada	¿Es obligatorio?
Flow	Una canalización de procesamiento de solicitudes o respuestas definida por un ProxyEndpoint o TargetEndpoint
Name	El nombre único del flujo.	N/A	Sí
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.	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 de pasos

El orden secuencial de flujos condicionales se aplica por Apigee. Los flujos condicionales se ejecutan de arriba abajo. El primer flujo condicional cuya condición se evalúa como true se ejecuta 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 pueden almacenarse en un proxy de API, un entorno o una organización. En cada caso, se hace referencia a un recurso por su nombre en una política. Apigee resuelve el nombre mediante el cambio del proxy de API al entorno y 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.