Se usó la API de Cloud Translation para traducir esta página.

Transmisión de eventos enviados por el servidor

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

Consulta la documentación de Apigee Edge.

Apigee admite la transmisión continua de respuestas desde extremos de eventos enviados por el servidor (SSE) a los clientes en tiempo real. La función de SSE de Apigee es útil para controlar las APIs de modelos de lenguaje grandes (LLM) que funcionan de manera más eficaz transmitiendo sus respuestas al cliente. La transmisión 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 o coordinadores de flujos de trabajo.

Para usar SSE con Apigee, simplemente apunta un proxy de API a un destino o extremo de proxy habilitado para SSE. Para lograr un control más detallado sobre la respuesta de SSE, Apigee proporciona un flujo de extremo especial llamado EventFlow. En el contexto de un EventFlow, puedes agregar un conjunto limitado de políticas para realizar operaciones en la respuesta de SSE, como filtrar, modificar o controlar errores. Para obtener más información sobre los flujos de proxy, consulta Controla proxies de API con flujos.

Crea un proxy de API para SSE

La IU de Apigee proporciona una plantilla para crear un proxy nuevo que incluye un EventFlow.

Nota: El uso de la plantilla de proxy de SSE es opcional. Te brinda acceso a variables de flujo específicas de SSE que pueden ser útiles para realizar ciertas 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 usando la IU de Apigee:

En la Google Cloud consola, ve a la página Proxy Development > API Proxies.

Ir a Proxies de API
En el panel Proxies de API, 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, ingresa lo siguiente:
- Nombre del proxy: Ingresa un nombre para el proxy, como myproxy.
- Ruta base: Se establece automáticamente en el valor que ingresas para Nombre del proxy. La ruta base es parte de la URL que se usa para realizar solicitudes a la API. Edge usa la URL para hacer coincidir solicitudes entrantes y enrutarlas al proxy de API adecuado.
- Descripción (Opcional): Ingresa una descripción para tu nuevo proxy de API, como "Prueba de Apigee con un proxy simple".
- Destino (API existente): Ingresa la URL de destino de SSE para el proxy de API. Por ejemplo: https://mocktarget.apigee.net/sse-events/5.
- Haz clic en Siguiente.
Implementa (opcional):
- Entornos de implementación: Opcional. Usa las casillas de verificación para seleccionar uno o más entornos en los que implementar tu proxy. Si prefieres no implementar el proxy en este punto, deja vacío el campo Entornos de implementación. Siempre 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 Integral. Consulta Tipos de entornos.
- 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. Esta es una función avanzada que puedes ignorar para los fines de este instructivo.
Los proxies de API implementados con una configuración de EventFlow se facturarán como extensibles.
Haz clic en Crear.

Consulta también Compila un proxy de API simple.

Cómo configurar un EventFlow

Para lograr un control más detallado sobre la respuesta de SSE, Apigee proporciona un flujo de extremo especial llamado EventFlow. En el contexto de un EventFlow, puedes agregar un conjunto limitado de políticas, que se enumeran 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 Controla proxies de API con flujos.

Colocación de un EventFlow

Un objeto EventFlow tiene dos atributos:

name: Es un 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 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 agregas varias secciones EventFlow a un extremo, solo se ejecutará la última en la definición del extremo. Se ignoran todos los párrafos EventFlow que aparecen antes del último.

También es importante tener en cuenta que, si bien puedes agregar 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 cláusulas EventFlow según la ubicación del extremo:

ProxyEndpoint	TargetEndpoint	EventFlow utilizado
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`

Agrega políticas a un EventFlow

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

Consulta también Adjunta y configura políticas en la IU y Adjunta y configura políticas en archivos XML.

En los siguientes ejemplos, se muestra un EventFlow con un paso de política RaiseFault condicional agregado:

<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 Ejemplos y casos de uso de EventFlow.

Variables de flujo

Un EventFlow propaga dos variables de flujo de respuesta. Ten en cuenta que estas variables solo se pueden usar dentro del alcance del evento actual que se procesa en EventFlow. Acceder a estas variables o establecerlas fuera del alcance de EventFlow no tiene ningún efecto. Solo tienen sentido en el contexto de EventFlow.

response.event.current.content: Es una cadena que contiene toda la respuesta del evento actual. Apigee no analiza la cadena de ninguna manera. 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 estableces el valor de esta variable en una cadena vacía (""), se evitará que el evento se envíe al cliente. Para ver un ejemplo, consulta Cómo filtrar una respuesta de SSE.
response.event.current.count: Cuenta de forma incremental la cantidad de eventos de respuesta enviados. Este valor se actualiza para cada evento recibido. El recuento será 1 para el primer evento y aumentará para los eventos posteriores.
Nota: Si accedes a este valor, por ejemplo, en una política de JavaScript, el primer evento tendrá un valor de 1; sin embargo, la cantidad de eventos enviados al cliente en este punto será 0.

Consulta también la Referencia de variables de flujo.

Casos de uso y ejemplos de EventFlow

En los siguientes ejemplos, se muestra cómo implementar casos de uso comunes para los proxies de SSE:

Cómo modificar una respuesta de SSE
Cómo filtrar una respuesta de SSE
Envía un evento de SSE a un sistema externo
Usa una política de Apigee Model Armor en EventFlows
Manejo de errores en EventFlow
Propaga mensajes de error en un EventFlow

Cómo modificar una respuesta de SSE

En este ejemplo, se muestra cómo quitar datos de una respuesta de SSE EventFlow antes de devolverla al cliente. El contenido de la respuesta de 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 nuevo con la plantilla de proxy de SSE. Consulta Crea un proxy de API con eventos enviados por el servidor (SSE).
Abre el proxy en el editor de proxy de Apigee y haz clic en la pestaña Develop.

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

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

Agrega 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-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 y, luego, 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 ejemplo con la política de JavaScript aplicada. Se quitó 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
        }
      ]
    }
  }

Cómo filtrar una respuesta de SSE

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

Al igual que en el ejemplo anterior, este ejemplo recupera el valor de la variable de flujo response.event.current.content, lo analiza en formato JSON y, luego, aplica la lógica para implementar el filtrado previsto.

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

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

<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 y, luego, 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 verse 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"
    }

Esta es otra respuesta de ejemplo después de que se aplicó el filtrado y se borró el mensaje de error.

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

Envía un evento de SSE a un sistema externo

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

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

Crea una política PublishMessage nueva 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>

Agrega la política PublishMessage como un 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>

Implementa y prueba el proxy de API.
Con el contenido generado agregado al tema de Pub/Sub, puedes, por ejemplo, crear una función de Cloud Run para procesar mensajes del tema.

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

Puedes usar la política SanitizeModelResponse para sanear los eventos entrantes enviados por el servidor en un EventFlow. Esta política protege tus aplicaciones de IA, ya que depura las respuestas de los modelos de lenguaje grandes (LLMs). Para obtener información sobre Model Armor, consulta la descripción general de Model Armor. Para obtener información sobre las políticas de Apigee Model Armor, consulta Comienza a usar las políticas de Apigee Model Armor.

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

Crea una nueva política de 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) Agrega una política de JavaScript para agrupar eventos antes de enviarlos a la política de 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>

Agrega las políticas de JavaScript y ModelArmor a un paso en el 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>

Implementa y prueba el proxy de API.

Control de errores en EventFlow

De forma predeterminada, el flujo de eventos finaliza cuando se produce una falla. Sin embargo, si deseas realizar una depuración adicional, puedes enviar información de errores a Cloud Logging, como se muestra en este ejemplo.

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

Crea una política RaiseFault nueva 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 de 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>

Agrega la política de MessageLogging a las FaultRules del extremo 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>

Implementa y prueba el proxy de API.

Propaga errores de fallas en un EventFlow

En este ejemplo, te mostramos cómo usar un EventFlow para propagar errores de falla al cliente. El proceso funciona para notificar al cliente sobre los errores de inmediato durante la ejecución de la política.

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

Crea una política de JavaScript nueva 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 está diseñada para arrojar un error cuando se cumple una condición específica.

Adjunta la política de JavaScript al EventFlow del proxy de SSE dentro de la configuración de TargetEndpoint o ProxyEndpoint. Este paso garantiza que EventFlow procese la política durante el control de la respuesta:

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

Implementa el proxy de API.

Prueba el comportamiento del proxy con el siguiente comando de 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."}]}]}'

Reemplaza ENVIRONMENT_GROUP_NAME por el nombre de tu grupo de entorno.

El resultado 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 de la falla y la envía al cliente como un evento.

Para obtener más información sobre el manejo de fallas en Apigee, consulta Cómo controlar las fallas.

Cómo ver los datos de SSE en Apigee Analytics

Los datos de los proxies de SSE aparecen en las estadísticas de Apigee como se espera para cualquier proxy de API. En la consola de Cloud, ve a Analytics > Métricas de API.

Cómo depurar proxies de SSE

Usa la herramienta de depuración de Apigee para depurar proxies de SSE. Los datos de depuración se capturan para EventFlow de la misma manera que para los otros tipos de flujos.

Soluciona problemas

Para problemas de 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:

Dado que los datos de Analytics se registran después de que se cierra la sesión de SSE, es posible que observes cierto retraso en los informes de datos de Analytics.
Las fallas dentro de un EventFlow hacen que el flujo salga de inmediato y arroje un error. Para obtener información sobre cómo registrar manualmente este tipo de errores o enviarlos al cliente, consulta Ejemplos y casos de uso de EventFlow.
Un cliente que recibe respuestas de SSE transmitidas recibirá los encabezados HTTP, incluidos los códigos de estado, al comienzo de la transmisión de eventos. Como resultado, 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 ver cuando se visualiza una sesión de depuración. En la sesión, es posible que observes que el código de estado HTTP para las transmisiones que ingresan al estado de error difiere de los códigos de estado que se envían al cliente. Esto puede ocurrir porque la entrada de la sesión de depuración se genera después de que se procesa toda la solicitud, en lugar de al comienzo 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 que se recibió inicialmente en los encabezados.

Transmisión de eventos enviados por el servidor Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Crea un proxy de API para SSE

Cómo configurar un EventFlow

Colocación de un EventFlow

<ProxyEndpoint>

<TargetEndpoint>

Agrega políticas a un EventFlow

<ProxyEndpoint>

<TargetEndpoint>

Variables de flujo

Casos de uso y ejemplos de EventFlow

Cómo modificar una respuesta de SSE

<ProxyEndpoint>

<TargetEndpoint>

Mostrar una respuesta de ejemplo

Cómo filtrar una respuesta de SSE

<ProxyEndpoint>

<TargetEndpoint>

Mostrar una respuesta de ejemplo

Envía un evento de SSE a un sistema externo

<ProxyEndpoint>

<TargetEndpoint>

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

Control de errores en EventFlow

<TargetEndpoint>

<ProxyEndpoint>

Propaga errores de fallas en un EventFlow

<TargetEndpoint>

<ProxyEndpoint>

Cómo ver los datos de SSE en Apigee Analytics

Cómo depurar proxies de SSE

Soluciona problemas

Limitaciones

Transmisión de eventos enviados por el servidor