Esta página se ha traducido con Cloud Translation API.

Transmitir eventos enviados por el servidor

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

Consulta la documentación de Apigee Edge.

Apigee admite el streaming continuo de respuestas desde endpoints de eventos enviados por el servidor (SSE) a los clientes en tiempo real. La función SSE de Apigee es útil para gestionar APIs de modelos de lenguaje extensos (LLMs) que funcionan de forma más eficaz transmitiendo sus respuestas al cliente. El streaming de SSE reduce la latencia y los clientes pueden recibir datos de respuesta en cuanto los genera un LLM. Esta función admite el uso de agentes de IA que operan en entornos en tiempo real, como bots de atención al cliente u orquestadores de flujos de trabajo.

Para usar SSE con Apigee, solo tienes que dirigir un proxy de API a un endpoint de destino o de proxy habilitado para SSE. Para conseguir un control más detallado sobre la respuesta de SSE, Apigee proporciona un flujo de endpoint especial llamado EventFlow. En el contexto de un EventFlow, puedes añadir un conjunto limitado de políticas para realizar operaciones en la respuesta de SSE, como filtrar, modificar o gestionar errores. Para obtener más información sobre los flujos de proxy, consulta el artículo Controlar proxies de APIs mediante los flujos.

Crear un proxy de API para SSE

La interfaz de usuario de Apigee proporciona una plantilla para crear un proxy que incluye un EventFlow.

Nota: El uso de la plantilla de proxy de SSE es opcional. Te da acceso a variables de flujo específicas de SSE que pueden ser útiles para realizar determinadas operaciones de políticas. Sin embargo, no es necesario que uses EventFlow para usar SSE con Apigee.

Sigue estos pasos para crear un proxy de API con la plantilla EventFlow mediante la interfaz de usuario de Apigee:

En la Google Cloud consola, ve a la página Desarrollo de proxy > Proxies de API.

Ir a Proxies de API
En el panel Proxies de APIs, haz clic en + Crear.
En el panel Crear un proxy, en Plantilla de proxy, selecciona Proxy con eventos enviados por el servidor (SSE).
En Detalles del proxy, introduce lo siguiente:
- Nombre del proxy: introduce un nombre para el proxy, como myproxy.
- Ruta base: se asigna automáticamente el valor que introduzcas en Nombre de proxy. La ruta base forma parte de la URL que se usa para enviar solicitudes a tu API. Apigee usa la URL para hacer coincidir y enrutar las solicitudes entrantes al proxy de API adecuado.
- Descripción (opcional): introduce una descripción para el nuevo proxy de API, como "Prueba de Apigee con un proxy sencillo".
- Destino (API actual): introduce la URL de destino de SSE del proxy de API. Por ejemplo: https://mocktarget.apigee.net/sse-events/5
- Haz clic en Siguiente.
Implementar (opcional):
- Entornos de implementación: opcional. Usa las casillas para seleccionar uno o varios entornos en los que quieras implementar tu proxy. Si prefieres no implementar el proxy en este momento, deja el campo Entornos de implementación vacío. Puedes implementar el proxy más adelante.
  Nota: En los entornos de pago por uso, el único tipo de entorno compatible con el uso de SSE es Completo. Consulta Tipos de entorno.
- Cuenta de servicio: opcional. Una cuenta de servicio para el proxy. La cuenta de servicio representa la identidad del proxy implementado y determina qué permisos tiene. Se trata de una función avanzada que, para los fines de este tutorial, puedes ignorar.
Los proxies de API implementados con una configuración EventFlow se facturarán como extensibles.
Haz clic en Crear.

Consulta también Desarrollar un proxy de APIs sencillo.

Configurar un EventFlow

Para conseguir un control más detallado sobre la respuesta de SSE, Apigee proporciona un flujo de endpoint especial llamado EventFlow. En el contexto de un EventFlow, puedes añadir un conjunto limitado de políticas, que se indican a continuación, para modificar la respuesta de SSE antes de que se transmita al cliente. Para obtener más información sobre los flujos de proxy, consulta el artículo Controlar proxies de APIs mediante los flujos.

Colocación de un EventFlow

Un EventFlow tiene dos atributos:

name: nombre para identificar el flujo.
content-type: el valor de este atributo debe ser text/event-stream.

Consulta también la referencia de configuración de flujo.

Se puede colocar un EventFlow dentro de una definición de TargetEndpoint o de ProxyEndpoint, como se muestra en los siguientes ejemplos de código:

<ProxyEndpoint>

<ProxyEndpoint name="default">
  <Description/>
  <FaultRules/>
  <PreFlow name="PreFlow">
    <Request/>
    <Response/>
  </PreFlow>
  <PostFlow name="PostFlow">
    <Request/>
    <Response/>
  </PostFlow>
  <Flows/>
  <EventFlow name="EventFlow" content-type="text/event-stream">
    <Response/>
  </EventFlow>
  <HTTPProxyConnection>
    <Properties/>
    <URL>https://httpbin.org/sse</URL>
  </HTTPProxyConnection>
</ProxyEndpoint>

<TargetEndpoint>

<TargetEndpoint name="default">
  <Description/>
  <FaultRules/>
  <PreFlow name="PreFlow">
    <Request/>
    <Response/>
  </PreFlow>
  <PostFlow name="PostFlow">
    <Request/>
    <Response/>
  </PostFlow>
  <Flows/>
  <EventFlow name="EventFlow" content-type="text/event-stream">
    <Response/>
  </EventFlow>
  <HTTPTargetConnection>
    <Properties/>
    <URL>https://httpbin.org/sse</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Nota: Si añade varias estrofas EventFlow a un endpoint, solo se ejecutará la última de la definición del endpoint. Se ignorarán las estrofas EventFlow que aparezcan antes de la última.

También es importante tener en cuenta que, aunque puedes añadir un EventFlow a un TargetEndpoint, un ProxyEndpoint o ambos, solo se ejecuta un EventFlow.

En la siguiente tabla se muestra la ejecución de las estrofas EventFlow en función de la ubicación del endpoint:

ProxyEndpoint	TargetEndpoint	EventFlow usado
EventFlow en `ProxyEndpoint`	EventFlow en `TargetEndpoint`	EventFlow en `TargetEndpoint`
No`EventFlow`	EventFlow en `TargetEndpoint`	EventFlow en `TargetEndpoint`
EventFlow en `ProxyEndpoint`	No`EventFlow`	EventFlow en `ProxyEndpoint`

Añadir políticas a un EventFlow

Puedes añadir hasta cuatro políticas al elemento Response de la EventFlow. Al igual que con todos los flujos, las políticas se ejecutan en el orden en que se añaden y puedes añadir pasos condicionales para controlar su ejecución. Es importante tener en cuenta que los tipos de políticas que puedes añadir a un EventFlow se limitan a los siguientes. No se permiten otros tipos de políticas en un EventFlow:

Consulta también Vincular y configurar políticas en la interfaz de usuario y Vincular y configurar políticas en archivos XML.

En los siguientes ejemplos se muestra un EventFlow con un paso de política RaiseFault condicional añadido:

<ProxyEndpoint>

<ProxyEndpoint name="default">
  <EventFlow content-type="text/event-stream">
    <Response>
      <Step>
        <Name>Raise-Fault-Cred-Invalid</Name>
        <Condition>fault.name equals "invalid_access_token"</Condition>
      </Step>
    </Response>
  </EventFlow>
  <HTTPProxyConnection>
</ProxyEndpoint></pre>

<TargetEndpoint>

<TargetEndpoint name="default">
  <EventFlow content-type="text/event-stream">
    <Response>
      <Step>
        <Name>Raise-Fault-Cred-Invalid</Name>
        <Condition>fault.name equals "invalid_access_token"</Condition>
      </Step>
    </Response>
  </EventFlow>
  <HTTPTargetConnection>
</TargetEndpoint></pre>

Para ver más ejemplos de código de EventFlow, consulta la sección Casos prácticos y ejemplos de EventFlow.

Variables de flujo

Un EventFlow rellena dos variables de flujo de respuesta. Ten en cuenta que estas variables solo se pueden usar en el ámbito del evento actual que se está procesando en EventFlow. Acceder a estas variables o definirlas fuera del ámbito de EventFlow no tiene ningún efecto. Solo tienen sentido en el contexto de EventFlow.

response.event.current.content: cadena que contiene la respuesta completa del evento actual. Apigee no analiza la cadena de ninguna forma. Contiene toda la respuesta sin cambios, incluidos todos los campos de datos.
Nota: Apigee limita cada evento de respuesta a un máximo de 10 MB de datos.

Nota: Si asignas a esta variable una cadena vacía (""), se evitará que el evento se envíe al cliente. Para ver un ejemplo, consulta Filtrar una respuesta de SSE.
response.event.current.count: cuenta de forma incremental el número de eventos de respuesta enviados. Este valor se actualiza con cada evento recibido. El recuento será 1 para el primer evento y aumentará en 1 para los eventos posteriores.
Nota: Si accedes a este valor, por ejemplo, en una política de JavaScript, el primer evento tendrá el valor 1. Sin embargo, el número de eventos enviados al cliente en este punto será 0.

Consulta también la referencia de variables de flujo.

Casos prácticos y ejemplos de EventFlow

En los siguientes ejemplos se muestra cómo implementar casos prácticos habituales de proxies SSE:

Modificar una respuesta de SSE
Filtrar una respuesta de SSE
Enviar un evento SSE a un sistema externo
Usar una política Apigee Model Armor en EventFlows
Gestión de errores en EventFlow
Propagar mensajes de error en un EventFlow

Modificar una respuesta SSE

En este ejemplo se muestra cómo eliminar datos de una respuesta de SSE EventFlow antes de devolverla al cliente. El contenido de la respuesta SSE se almacena en una variable de flujo llamada response.event.current.content. En este caso, usamos una política de JavaScript para recuperar el valor de la variable de flujo, analizarlo y modificarlo. Consulta también Variables de flujo.

Crea un proxy con la plantilla de proxy SSE. Consulta Crear un proxy de API con eventos enviados por el servidor (SSE).
Abre el proxy en el editor de proxies de Apigee y haz clic en la pestaña Desarrollar.

Crea una política de JavaScript con la siguiente definición. En este ejemplo, el código JavaScript se incluye directamente en la política. Otra opción para configurar la política es colocar el código JavaScript en un archivo de recursos.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript continueOnError="false" enabled="true" timeLimit="200" name="js-update-resp">
  <DisplayName>js-update-resp</DisplayName>
  <Properties/>
  <Source>
    var event = JSON.parse(context.getVariable("response.event.current.content"));
    event.modelVersion = null;
    context.setVariable("response.event.current.content",JSON.stringify(event));
  </Source>
</Javascript>

Añade la política de JavaScript al EventFlow del proxy. El EventFlow se adjunta al valor predeterminado TargetEndpoint o ProxyEndpoint. En este ejemplo se usa la API de Gemini en Vertex AI para generar contenido.

<ProxyEndpoint>

<ProxyEndpoint name="default">
  <EventFlow content-type="text/event-stream">
    <Response>
      <Step>
        <Name>js-update-resp</Name>
      </Step>
    </Response>
  </EventFlow>
  <HTTPProxyConnection>
    <URL>https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?key=GEMINI_API_KEY&alt=sse</URL>
  </HTTPProxyConnection>
</ProxyEndpoint>

<TargetEndpoint>

<TargetEndpoint name="default">
  <EventFlow content-type="text/event-stream">
    <Response>
      <Step>
        <Name>js-update-resp</Name>
      </Step>
    </Response>
  </EventFlow>
  <HTTPTargetConnection>
    <URL>https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?key=GEMINI_API_KEY&alt=sse</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Guarda el proxy e impleméntalo.

Llama al proxy implementado:

curl -X POST -H 'Content-Type: application/json'  \
  "https://YOUR_APIGEE_ENVIRONMENT_GROUP_HOSTNAME/YOUR_API_PATH" \
  -d '{ "contents":[{"parts":[{"text": "Write a story about a magic pen."}]}]}'

Mostrar una respuesta de ejemplo

Esta es una respuesta de ejemplo sin ningún filtro aplicado. Ten en cuenta que la respuesta incluye un atributo modelVersion": "gemini-2.5-flash".

data: {
    "candidates": [
      {
        "content": {
          "parts": [
            {
              "text": "ara found the pen tucked away in a dusty antique shop, nestled amongst chipped tea"
            }
          ],
          "role": "model"
        }
      }
    ],
    "usageMetadata": {
      "promptTokenCount": 8,
      "totalTokenCount": 8
    },
    "modelVersion": "gemini-2.5-flash"
  }

Esta es otra respuesta de muestra con la política de JavaScript aplicada. Se ha quitado el atributo modelVersion.

data: {
    "candidates": [
      {
        "content": {
          "parts": [
            {
              "text": " the fantastical creatures of her imagination.  The quiet beauty of a simple life was a magic all its own.\n"
            }
          ],
          "role": "model"
        },
        "finishReason": "STOP"
      }
    ],
    "usageMetadata": {
      "promptTokenCount": 8,
      "candidatesTokenCount": 601,
      "totalTokenCount": 609,
      "promptTokensDetails": [
        {
          "modality": "TEXT",
          "tokenCount": 8
        }
      ],
      "candidatesTokensDetails": [
        {
          "modality": "TEXT",
          "tokenCount": 601
        }
      ]
    }
  }

Filtrar una respuesta SSE

En este ejemplo se muestra cómo filtrar datos de una respuesta SSE antes de devolverlos al cliente. En este caso, filtramos los datos de eventos de la respuesta mediante una política de JavaScript. La política analiza la respuesta del evento en JSON, modifica el JSON para eliminar los datos del evento y, a continuación, envía los datos de respuesta modificados al cliente.

Al igual que en el ejemplo anterior, este ejemplo obtiene el valor de la variable de flujo response.event.current.content, lo analiza en JSON y, a continuación, aplica la lógica para implementar el filtrado deseado.

Crea un proxy con la plantilla de proxy SSE. Consulta Crear un proxy de API con eventos enviados por el servidor (SSE).
Abre el proxy en el editor de proxies de Apigee y haz clic en la pestaña Desarrollar.

<Javascript continueOnError="false" enabled="true" timeLimit="200" name="js-filter-resp">
  <DisplayName>js-filter-resp</DisplayName>
  <Properties/>
  <Source>
    var event = JSON.parse(context.getVariable("response.event.current.content"));
    if("error" in event){
      // Do not send event to customer
      context.setVariable("response.event.current.content", "");
    }
  </Source>
</Javascript>

Añade la política de JavaScript al EventFlow del proxy. El EventFlow se adjunta al TargetEndpoint o ProxyEndpoint predeterminado. En este ejemplo se usa la API de Gemini en Vertex AI para generar contenido.

<ProxyEndpoint>

<ProxyEndpoint name="default">
  <EventFlow content-type="text/event-stream">
    <Response>
      <Step>
        <Name>js-filter-resp</Name>
      </Step>
    </Response>
  </EventFlow>
  <HTTPProxyConnection>
	  <URL>https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?key=GEMINI_API_KEY&alt=sse	</URL>
  </HTTPProxyConnection>
</ProxyEndpoint>

<TargetEndpoint>

<TargetEndpoint name="default">
  <EventFlow content-type="text/event-stream">
    <Response>
      <Step>
        <Name>js-filter-resp</Name>
      </Step>
    </Response>
  </EventFlow>
  <HTTPTargetConnection>
	  <URL>https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?key=GEMINI_API_KEY&alt=sse	</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Guarda el proxy e impleméntalo.

Llama al proxy implementado:

curl -X POST -H 'Content-Type: application/json'  \
    "https://YOUR_APIGEE_ENVIRONMENT_GROUP_HOSTNAME/YOUR_API_PATH" \
    -d '{ "contents":[{"parts":[{"text": "Write a story about a magic pen."}]}]}'

Mostrar una respuesta de ejemplo

A continuación se muestra un ejemplo de cómo podría ser la respuesta sin aplicar ningún filtro. Observa que incluye datos de error:

data: {
    "candidates": [
      {
        "content": {
          "parts": [
            {
              "text": "El"
            }
          ],
          "role": "model"
        }
      }
    ],
    "usageMetadata": {
      "promptTokenCount": 8,
      "totalTokenCount": 8
    },
    "modelVersion": "gemini-2.5-flash"
  }
    data: {
    "error": "Service temporarily unavailable. We are experiencing high traffic.",
    "modelVersion": "gemini-2.5-flash"
    }

Aquí tienes otra respuesta de ejemplo después de aplicar el filtro, con el mensaje de error oculto.

data: {
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "El"
          }
        ],
        "role": "model"
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 8,
    "totalTokenCount": 8
  },
  "modelVersion": "gemini-2.5-flash"
}
data: {
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "ara found the pen tucked away in a dusty antique shop, nestled amongst chipped tea"
          }
        ],
        "role": "model"
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 8,
    "totalTokenCount": 8
  },
  "modelVersion": "gemini-2.5-flash"
}

Enviar un evento SSE a un sistema externo

En este ejemplo, adjuntamos la política PublishMessage de Apigee al EventFlow para enviar un evento SSE a un tema de Pub/Sub.

Crea un proxy con la plantilla de proxy SSE. Consulta Crear un proxy de API con eventos enviados por el servidor (SSE).
Abre el proxy en el editor de proxies de Apigee y haz clic en la pestaña Desarrollar.

Crea una política PublishMessage con la siguiente definición:

<PublishMessage continueOnError="false" enabled="true" name="PM-record-event">
  <DisplayName>PM-record-event</DisplayName>
  <Source>{response.event.current.content}</Source>
  <CloudPubSub>
    <Topic>projects/<customer_project>/topics/<topic_name></Topic>
  </CloudPubSub>
</PublishMessage>

Añade la política PublishMessage como paso en el EventFlow del proxy de API.

<ProxyEndpoint>

<ProxyEndpoint name="default">
  <EventFlow content-type="text/event-stream">
    <Response>
      <Step>
        <Name>PM-record-event</Name>
      </Step>
    </Response>
  </EventFlow>
  <HTTPProxyConnection>
</ProxyEndpoint>

<TargetEndpoint>

<TargetEndpoint name="default">
  <EventFlow content-type="text/event-stream">
    <Response>
      <Step>
        <Name>PM-record-event</Name>
      </Step>
    </Response>
  </EventFlow>
  <HTTPTargetConnection>
</TargetEndpoint>

Despliega y prueba el proxy de API.
Una vez que hayas añadido el contenido generado al tema de Pub/Sub, puedes, por ejemplo, crear una función de Cloud Run para procesar los mensajes del tema.

Usar una política de Apigee Model Armor en un EventFlow

Puedes usar la política SanitizeModelResponse para sanear los eventos enviados por el servidor entrantes en un EventFlow. Esta política protege tus aplicaciones de IA desinfectando las respuestas de los modelos de lenguaje extensos (LLMs). Para obtener información sobre Model Armor, consulta el artículo Descripción general de Model Armor. Para obtener información sobre las políticas de Model Armor de Apigee, consulta el artículo Empezar a usar las políticas de Model Armor de Apigee.

Crea un proxy con la plantilla de proxy SSE. Consulta Crear un proxy de API con eventos enviados por el servidor (SSE).
Abre el proxy en el editor de proxies de Apigee y haz clic en la pestaña Desarrollar.

Crea una política SanitizeModelResponse con la siguiente definición:

  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <SanitizeModelResponse async="false" continueOnError="false" enabled="true" name="SMR-modelresponse">
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <DisplayName>SMR-modelresponse</DisplayName>
    <ModelArmor>
      <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
    </ModelArmor>
    <LLMResponseSource>{response_partial}</LLMResponseSource>
    <!-- Use the below settings if you want to call a Model Armor policy on every event -->
    <LLMResponseSource>{response.event.current.content}</LLMResponseSource>
  </SanitizeModelResponse>

(Opcional) Añade una política de JavaScript para agrupar eventos antes de enviarlos a la política Apigee Model Armor.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript continueOnError="false" enabled="true" timeLimit="200" name="JS-combine-resp">
  <DisplayName>JS-combine-events</DisplayName>
  <Properties/>
  <Source>
    var eventText = JSON.parse(context.getVariable("response.event.current.content").substring(5)).candidates[0].content.parts[0].text;
    var finishReason = JSON.parse(context.getVariable("response.event.current.content").substring(5)).candidates[0].finishReason;
    var idx = context.getVariable("response.event.current.count");
    if(idx%5==0 || finishReason=="STOP") {
      context.setVariable("response_partial", context.getVariable("tmp_buffer_pre"));
      context.setVariable("buff_ready", true);
      context.setVariable("tmp_buffer_pre", "");
    } else {
      context.setVariable("buff_ready", false);
      context.setVariable("response_partial", "");
      var previousBufferVal = context.getVariable("tmp_buffer_pre");
      if(previousBufferVal) {
        context.setVariable("tmp_buffer_pre", previousBufferVal+eventText);
      } else {
        context.setVariable("tmp_buffer_pre", eventText);
      }
    }
  </Source>
</Javascript>

Añade las políticas de JavaScript y ModelArmor a un paso del EventFlow del proxy:

<EventFlow name="EventFlow" content-type="text/event-stream">
  <Request/>
  <Response>
    <Step>
      <Name>JS-combine-resp</Name>
    </Step>
    <Step>
      <!-- Remove below Condition if you want to call model armor policy on every event -->
      <Condition> buff_ready = true </Condition>
      <Name>SMR-modelresponse</Name>
    </Step>
  </Response>
</EventFlow>

Despliega y prueba el proxy de API.

Gestión de errores en EventFlow

De forma predeterminada, el flujo de eventos finaliza cuando se produce un error. Sin embargo, si quieres depurar más, puedes enviar información sobre errores a Cloud Logging, como se muestra en este ejemplo.

Crea un proxy con la plantilla de proxy SSE. Consulta Crear un proxy de API con eventos enviados por el servidor (SSE).
Abre el proxy en el editor de proxies de Apigee y haz clic en la pestaña Desarrollar.

Crea una política RaiseFault con la siguiente definición:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RaiseFault continueOnError="false" enabled="true" name="RF-Empty-Event">
  <DisplayName>RF-Empty-Event</DisplayName>
  <Properties/>
  <FaultResponse>
    <AssignVariable>
      <Name>faultReason</Name>
      <Value>empty-event</Value>
    </AssignVariable>
  </FaultResponse>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>

Adjunta la política RaiseFault al EventFlow del proxy de SSE:

<EventFlow content-type="text/event-stream">
  <Response>
    <Step>
      <Name>RF-Empty-Event</Name>
      <Condition>response.event.current.content ~ "data: "</Condition>
    </Step>
  </Response>
</EventFlow>

Crea una política MessageLogging para registrar errores. Por ejemplo:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging continueOnError="false" enabled="true" name="ML-log-error">
  <DisplayName>ML-log-error</DisplayName>
  <CloudLogging>
    <LogName>projects/{organization.name}/logs/apigee_errors</LogName>
    <Message contentType="text/plain">Request failed due to {faultReason}.</Message>
    <ResourceType>api</ResourceType>
  </CloudLogging>
  <logLevel>ALERT</logLevel>
</MessageLogging>

Añade la política MessageLogging a las reglas FaultRules del endpoint de destino o del proxy:

<TargetEndpoint>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TargetEndpoint name="TargetEndpoint-1">
  <Description/>
  <FaultRules>
    <FaultRule name="default-fault">
      <Step>
        <Name>ML-log-error</Name>
      </Step>
    </FaultRule>
  </FaultRules>
  ...
</TargetEndpoint>

<ProxyEndpoint>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ProxyEndpoint name="ProxyEndpoint-1">
  <Description/>
  <FaultRules>
    <FaultRule name="default-fault">
      <Step>
        <Name>ML-log-error</Name>
      </Step>
    </FaultRule>
  </FaultRules>
  ...
</ProxyEndpoint>

Despliega y prueba el proxy de API.

Propagar errores de fallo en un EventFlow

En este ejemplo, te mostramos cómo usar un EventFlow para propagar errores de fallo al cliente. El proceso notifica al cliente los errores inmediatamente durante la ejecución de la política.

Crea un proxy con la plantilla de proxy SSE. Consulta Crear un proxy de API con eventos enviados por el servidor (SSE).
Abre el proxy en el editor de proxies de Apigee y haz clic en la pestaña Desarrollar.

Crea una política de JavaScript con la siguiente definición:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <Javascript continueOnError="false" enabled="true" timeLimit="200" name="js-error">
    <DisplayName>js-error</DisplayName>
    <Properties/>
    <Source>
      if(context.getVariable("response.event.current.count")=="2") {
        throw new Error("Internal Error");
      }
      context.setVariable("response.event.current.content", context.getVariable("response.event.current.content"));
    </Source>
  </Javascript>

Esta política se ha diseñado para generar un error cuando se cumpla una condición específica.

Adjunta la política de JavaScript al EventFlow del proxy de SSE en la configuración TargetEndpoint o ProxyEndpoint. Este paso asegura que EventFlow procese la política durante la gestión de respuestas:

<TargetEndpoint>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TargetEndpoint name="default">
  <EventFlow content-type="text/event-stream">
    <Response>
      <Step>
        <Name>js-error</Name>
      </Step>
    </Response>
  </EventFlow>
  <HTTPTargetConnection>
    <URL>https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:streamGenerateContent</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

<ProxyEndpoint>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ProxyEndpoint name="default">
  <EventFlow content-type="text/event-stream">
    <Response>
      <Step>
        <Name>js-error</Name>
      </Step>
    </Response>
  </EventFlow>
  <HTTPProxyConnection>
    <URL>https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:streamGenerateContent</URL>
  </HTTPProxyConnection>
</ProxyEndpoint>

Despliega el proxy de API.

Prueba el comportamiento del proxy con el siguiente comando curl:

curl -X POST -H 'Content-Type: application/json'  "https://ENVIRONMENT_GROUP_NAME/llm-api" -d '{ "contents":[{"parts":[{"text": "Write a story about a magic pen."}]}]}'

Sustituye ENVIRONMENT_GROUP_NAME por el nombre de tu grupo de entornos.

La salida debería ser similar al siguiente ejemplo:

data: {"candidates": [{"content": {"parts": [{"text": "El"}],"role": "model"}}],"usageMetadata": {"promptTokenCount": 8,"totalTokenCount": 8},"modelVersion": "gemini-2.5-flash"}
data: {"fault":{"faultstring":"Execution of JS-error failed with error: Exception thrown from JavaScript : Error: Internal Error (Resource_1_js#2)","detail":{"errorcode":"steps.javascript.ScriptExecutionFailed"}}}

El resultado muestra el flujo de datos inicial seguido de un mensaje fault. En caso de error, Apigee captura la información del fallo y la envía al cliente como un evento.

Para obtener más información sobre la gestión de errores en Apigee, consulta el artículo Gestión de errores.

Ver datos de SSE en las analíticas de Apigee

Los datos de los proxies de SSE se muestran en Analíticas de Apigee como en cualquier proxy de API. En la consola de Cloud, ve a Analytics > Métricas de API.

Depurar proxies SSE

Usa la herramienta de depuración de Apigee para depurar proxies SSE. Los datos de depuración se registran en EventFlow del mismo modo que en los demás tipos de flujo.

Solución de problemas

Si tienes problemas con el tráfico en tiempo real, consulta los registros de acceso de Apigee para determinar la causa.

Limitaciones

Se aplican las siguientes limitaciones a los proxies de SSE:

Como los datos analíticos se registran después de que se cierre la sesión de SSE, puede que haya un pequeño retraso en los informes de datos analíticos.
Los errores dentro de un EventFlow provocan que el flujo se cierre inmediatamente y genere un error. Para obtener información sobre cómo registrar manualmente este tipo de errores o enviarlos al cliente, consulta Casos prácticos y ejemplos de EventFlow.
Un cliente que reciba respuestas SSE transmitidas recibirá los encabezados HTTP, incluidos los códigos de estado, al principio del flujo de eventos. Por lo tanto, si el flujo de eventos entra en un estado de error, el código de estado recibido inicialmente no reflejará el estado de error.
Esta limitación se puede observar al ver una sesión de depuración. Durante la sesión, puede que observes que el código de estado HTTP de las emisiones que pasan al estado de error es diferente de los códigos de estado enviados al cliente. Esto puede ocurrir porque la entrada de la sesión de depuración se genera después de que se haya procesado toda la solicitud, en lugar de al principio del flujo de eventos. La sesión de depuración puede reflejar el código de error generado por el error, mientras que el cliente solo ve el estado 2xx recibido inicialmente en los encabezados. .

Transmitir eventos enviados por el servidor Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Crear un proxy de API para SSE

Configurar un EventFlow

Colocación de un EventFlow

<ProxyEndpoint>

<TargetEndpoint>

Añadir políticas a un EventFlow

<ProxyEndpoint>

<TargetEndpoint>

Variables de flujo

Casos prácticos y ejemplos de EventFlow

Modificar una respuesta SSE

<ProxyEndpoint>

<TargetEndpoint>

Mostrar una respuesta de ejemplo

Filtrar una respuesta SSE

<ProxyEndpoint>

<TargetEndpoint>

Mostrar una respuesta de ejemplo

Enviar un evento SSE a un sistema externo

<ProxyEndpoint>

<TargetEndpoint>

Usar una política de Apigee Model Armor en un EventFlow

Gestión de errores en EventFlow

<TargetEndpoint>

<ProxyEndpoint>

Propagar errores de fallo en un EventFlow

<TargetEndpoint>

<ProxyEndpoint>

Ver datos de SSE en las analíticas de Apigee

Depurar proxies SSE

Solución de problemas

Limitaciones

Transmitir eventos enviados por el servidor