Cette page a été traduite par l'API Cloud Translation.

Flux d'événements envoyés par le serveur

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d' Apigee Edge.

Apigee est compatible avec le streaming continu des réponses à partir des points de terminaison d'événements envoyés par le serveur (SSE) vers les clients en temps réel. La fonctionnalité SSE d'Apigee est utile pour gérer les API de grands modèles de langage (LLM) qui fonctionnent plus efficacement en transmettant leurs réponses au client. Le streaming SSE réduit la latence, et les clients peuvent recevoir les données de réponse dès qu'elles sont générées par un LLM. Cette fonctionnalité permet d'utiliser des agents d'IA qui fonctionnent dans des environnements en temps réel, tels que des bots de service client ou des orchestrateurs de workflow.

Pour utiliser SSE avec Apigee, il vous suffit de pointer un proxy d'API vers un point de terminaison cible ou de proxy compatible avec SSE. Pour obtenir un contrôle plus précis sur la réponse SSE, Apigee fournit un flux de point de terminaison spécial appelé EventFlow. Dans le contexte d'un EventFlow, vous pouvez ajouter un ensemble limité de règles pour effectuer des opérations sur la réponse SSE, telles que le filtrage, la modification ou la gestion des erreurs. Pour en savoir plus sur les flux de proxy, consultez Contrôler des proxys d'API avec des flux.

Créer un proxy d'API pour SSE

L'interface utilisateur d'Apigee fournit un modèle pour créer un proxy incluant un EventFlow.

Remarque : L'utilisation du modèle de proxy SSE est facultative. Il vous donne accès à des variables de flux spécifiques à SSE qui peuvent être utiles pour effectuer certaines opérations de règle. Toutefois, vous n'avez pas besoin d'utiliser EventFlow pour utiliser SSE avec Apigee.

Pour créer un proxy d'API avec le modèle EventFlow à l'aide de l'interface utilisateur Apigee, procédez comme suit :

Dans la console Google Cloud , accédez à la page Développement de proxys > Proxys d'API.

Accéder aux proxys d'API
Dans le volet Proxys d'API, cliquez sur + Créer.
Dans le volet Créer un proxy, sous Modèle de proxy, sélectionnez Proxy avec événements envoyés par le serveur (SSE).
Sous Détails du proxy, saisissez les informations suivantes :
- Nom du proxy : saisissez un nom pour le proxy, tel que myproxy.
- Chemin de base : défini automatiquement sur la valeur que vous saisissez pour Nom du proxy. Le chemin de base fait partie de l'URL utilisée pour envoyer des requêtes à votre API. Apigee utilise l'URL pour mettre en correspondance et acheminer les requêtes entrantes vers le proxy d'API approprié.
- Description (facultatif) : saisissez une description pour votre nouveau proxy d'API, par exemple "Test Apigee avec un proxy simple".
- Target (Existing API) (Cible (API existante)) : saisissez l'URL cible SSE pour le proxy d'API. Par exemple : https://mocktarget.apigee.net/sse-events/5
- Cliquez sur Suivant.
Déployer (facultatif) :
- Environnements de déploiement : facultatif. Cochez les cases pour sélectionner un ou plusieurs environnements dans lesquels déployer votre proxy. Si vous préférez ne pas déployer le proxy à ce stade, laissez le champ Environnements de déploiement vide. Vous pourrez toujours déployer le proxy ultérieurement.
  Remarque : Pour les environnements facturés à l'usage, le seul type d'environnement compatible avec l'utilisation de SSE est Complet. Consultez la section Types d'environnement.
- Compte de service : facultatif. Un compte de service pour le proxy. Le compte de service représente l'identité du proxy déployé et détermine les autorisations dont il dispose. Il s'agit d'une fonctionnalité avancée que vous pouvez ignorer pour ce tutoriel.
Les proxys d'API déployés avec une configuration EventFlow seront facturés en tant qu'extensibles.
Cliquez sur Créer.

Consultez également Créer un proxy d'API simple.

Configurer un EventFlow

Pour obtenir un contrôle plus précis sur la réponse SSE, Apigee fournit un flux de point de terminaison spécial appelé EventFlow. Dans le contexte d'un EventFlow, vous pouvez ajouter un ensemble limité de règles, listées ci-dessous, pour modifier la réponse SSE avant qu'elle ne soit renvoyée au client. Pour en savoir plus sur les flux de proxy, consultez Contrôler des proxys d'API avec des flux.

Emplacement d'un EventFlow

Un EventFlow comporte deux attributs :

name : nom permettant d'identifier le flux.
content-type : la valeur de cet attribut doit être text/event-stream.

Consultez également la documentation de référence sur la configuration des flux.

Un EventFlow peut être placé dans une définition TargetEndpoint ou ProxyEndpoint, comme indiqué dans les exemples de code suivants :

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

Remarque : Si vous ajoutez plusieurs strophes EventFlow à un point de terminaison, seule la dernière de la définition du point de terminaison est exécutée. Toutes les strophes EventFlow qui apparaissent avant la dernière sont ignorées.

Il est également important de noter que, bien que vous puissiez ajouter un EventFlow à un TargetEndpoint, un ProxyEndpoint ou les deux, un seul EventFlow est exécuté.

Le tableau suivant montre l'exécution des strophes EventFlow en fonction de l'emplacement du point de terminaison :

ProxyEndpoint	TargetEndpoint	EventFlow utilisé
EventFlow dans `ProxyEndpoint`	EventFlow dans `TargetEndpoint`	EventFlow dans `TargetEndpoint`
Aucune configuration de type "`EventFlow`"	EventFlow dans `TargetEndpoint`	EventFlow dans `TargetEndpoint`
EventFlow dans `ProxyEndpoint`	Aucune configuration de type "`EventFlow`"	EventFlow dans `ProxyEndpoint`

Ajouter des règles à un EventFlow

Vous pouvez ajouter jusqu'à quatre règles à l'élément Response de EventFlow. Comme pour tous les flux, les règles sont exécutées dans l'ordre dans lequel elles sont ajoutées. Vous pouvez ajouter des étapes conditionnelles pour contrôler leur exécution. Il est important de noter que les types de règles que vous pouvez ajouter à un EventFlow sont limités aux suivants. Aucun autre type de règlement n'est autorisé dans un EventFlow :

Consultez également Associer et configurer des règles dans l'UI et Associer et configurer des règles dans des fichiers XML.

Les exemples suivants montrent un EventFlow avec une étape de règle RaiseFault conditionnelle ajoutée :

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

Pour obtenir d'autres exemples de code EventFlow, consultez la section Cas d'utilisation et exemples d'EventFlow.

Variables de flux

Un EventFlow insère deux variables de flux de réponse. Notez que ces variables ne sont utilisables que dans le champ de l'événement en cours de traitement dans EventFlow. L'accès à ces variables ou leur définition en dehors du champ d'application EventFlow n'a aucun effet. Elles n'ont de sens que dans le contexte de EventFlow.

response.event.current.content : chaîne contenant l'intégralité de la réponse de l'événement actuel. Apigee n'analyse pas la chaîne. Il contient l'intégralité de la réponse sans modification, y compris tous les champs de données.
Remarque : Apigee limite chaque événement de réponse à un maximum de 10 Mo de données.

Remarque : Si vous définissez la valeur de cette variable sur une chaîne vide (""), l'événement ne sera pas envoyé au client. Pour obtenir un exemple, consultez Filtrer une réponse SSE.
response.event.current.count : incrémente le nombre d'événements de réponse envoyés. Cette valeur est mise à jour pour chaque événement reçu. Le nombre est de 1 pour le premier événement et augmente pour les événements suivants.
Remarque : Si vous accédez à cette valeur dans une règle JavaScript, par exemple, le tout premier événement aura une valeur de 1. Toutefois, le nombre d'événements envoyés au client à ce stade sera de 0.

Consultez également la documentation de référence sur les variables de flux.

Cas d'utilisation et exemples d'EventFlow

Les exemples suivants montrent comment implémenter des cas d'utilisation courants pour les proxys SSE :

Modifier une réponse SSE
Filtrer une réponse SSE
Envoyer un événement SSE à un système externe
Utiliser une règle Apigee Model Armor dans un EventFlows
Gestion des erreurs dans EventFlow
Propager les messages d'erreur dans un EventFlow

Modifier une réponse SSE

Cet exemple montre comment supprimer des données d'une réponse SSE EventFlow avant de les renvoyer au client. Le contenu de la réponse SSE est stocké dans une variable de flux appelée response.event.current.content. Dans ce cas, nous utilisons une règle JavaScript pour récupérer la valeur de la variable de flux, l'analyser et la modifier. Consultez également Variables de flux.

Créez un proxy avec le modèle de proxy SSE. Consultez Créer un proxy d'API avec des événements envoyés par le serveur (SSE).
Ouvrez le proxy dans l'éditeur de proxy Apigee, puis cliquez sur l'onglet Développer.

Créez une règle JavaScript avec la définition suivante. Dans cet exemple, le code JavaScript est inclus directement dans la règle. Vous pouvez également configurer la règle en plaçant le code JavaScript dans un fichier de ressources.

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

Ajoutez la règle JavaScript au EventFlow du proxy. EventFlow est associé à TargetEndpoint ou ProxyEndpoint par défaut. Cet exemple utilise l'API Gemini dans Vertex AI pour générer du contenu.

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

Enregistrez le proxy et déployez-le.

Appelez le proxy déployé :

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."}]}]}'

Afficher un exemple de réponse

Il s'agit d'un exemple de réponse sans filtrage. Notez que la réponse inclut un attribut 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"
  }

Voici un autre exemple de réponse avec la règle JavaScript appliquée. L'attribut modelVersion est supprimé.

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

Filtrer une réponse SSE

Cet exemple montre comment filtrer les données d'une réponse SSE avant de les renvoyer au client. Dans ce cas, nous filtrons les données d'événement de la réponse à l'aide d'une règle JavaScript. La règle analyse la réponse de l'événement au format JSON, modifie le fichier JSON pour supprimer les données de l'événement, puis renvoie les données de réponse modifiées au client.

Comme dans l'exemple précédent, cet exemple récupère la valeur de la variable de flux response.event.current.content et l'analyse au format JSON, puis applique une logique pour implémenter le filtrage souhaité.

Créez un proxy avec le modèle de proxy SSE. Consultez Créer un proxy d'API avec des événements envoyés par le serveur (SSE).
Ouvrez le proxy dans l'éditeur de proxy Apigee, puis cliquez sur l'onglet Développer.

Créez une règle JavaScript avec la définition suivante. Dans cet exemple, le code JavaScript est inclus directement dans la règle. Une autre option pour configurer la règle consiste à placer le code JavaScript dans un fichier de ressources.

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

Enregistrez le proxy et déployez-le.

Appelez le proxy déployé :

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."}]}]}'

Afficher un exemple de réponse

Voici un exemple de réponse sans filtrage. Notez qu'il inclut des données d'erreur :

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

Voici un autre exemple de réponse après l'application du filtrage, avec le message d'erreur masqué.

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

Envoyer un événement SSE à un système externe

Dans cet exemple, nous associons la règle PublishMessage d'Apigee à EventFlow pour envoyer un événement SSE à un sujet Pub/Sub.

Créez un proxy avec le modèle de proxy SSE. Consultez Créer un proxy d'API avec des événements envoyés par le serveur (SSE).
Ouvrez le proxy dans l'éditeur de proxy Apigee, puis cliquez sur l'onglet Développer.

Créez une règle PublishMessage avec la définition suivante :

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

Ajoutez la règle PublishMessage en tant qu'étape dans le EventFlow du proxy d'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>

Déployez et testez le proxy d'API.
Une fois le contenu généré ajouté au sujet Pub/Sub, vous pouvez, par exemple, créer une fonction Cloud Run pour traiter les messages du sujet.

Utiliser une règle Apigee Model Armor dans un EventFlow

Vous pouvez utiliser la stratégie SanitizeModelResponse pour assainir les événements envoyés par le serveur entrants dans un EventFlow. Ce règlement protège vos applications d'IA en assainissant les réponses des grands modèles de langage (LLM). Pour en savoir plus sur Model Armor, consultez la présentation de Model Armor. Pour en savoir plus sur les règles Apigee Model Armor, consultez Premiers pas avec les règles Apigee Model Armor.

Créez un proxy avec le modèle de proxy SSE. Consultez Créer un proxy d'API avec des événements envoyés par le serveur (SSE).
Ouvrez le proxy dans l'éditeur de proxy Apigee, puis cliquez sur l'onglet Développer.

Créez une stratégie SanitizeModelResponse avec la définition suivante :

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

(Facultatif) Ajoutez une règle JavaScript pour regrouper les événements avant de les envoyer à la règle 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>

Ajoutez les règles JavaScript et ModelArmor à une étape du EventFlow du 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>

Déployez et testez le proxy d'API.

Gestion des erreurs dans EventFlow

Par défaut, le flux d'événements se termine lorsqu'une erreur se produit. Toutefois, si vous souhaitez effectuer un débogage supplémentaire, vous pouvez envoyer des informations sur les erreurs à Cloud Logging, comme indiqué dans cet exemple.

Créez un proxy avec le modèle de proxy SSE. Consultez Créer un proxy d'API avec des événements envoyés par le serveur (SSE).
Ouvrez le proxy dans l'éditeur de proxy Apigee, puis cliquez sur l'onglet Développer.

Créez une règle RaiseFault avec la définition suivante :

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

Associez la règle RaiseFault à l'élément EventFlow du proxy SSE :

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

Créez une règle MessageLogging pour consigner les erreurs. Exemple :

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

Ajoutez la règle MessageLogging aux FaultRules du point de terminaison cible ou de 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>

Déployez et testez le proxy d'API.

Propager les erreurs de défaut dans un EventFlow

Dans cet exemple, nous vous montrons comment utiliser un EventFlow pour propager les erreurs de défaillance au client. Ce processus permet d'informer immédiatement le client des erreurs lors de l'exécution des règles.

Créez un proxy avec le modèle de proxy SSE. Consultez Créer un proxy d'API avec des événements envoyés par le serveur (SSE).
Ouvrez le proxy dans l'éditeur de proxy Apigee, puis cliquez sur l'onglet Développer.

Créez une règle JavaScript avec la définition suivante :

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

Cette règle est conçue pour générer une erreur lorsqu'une condition spécifique est remplie.

Associez la règle JavaScript à l'EventFlow du proxy SSE dans la configuration TargetEndpoint ou ProxyEndpoint. Cette étape permet de s'assurer que l'EventFlow traite la règle lors de la gestion des réponses :

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

Déployez le proxy d'API.

Testez le comportement du proxy à l'aide de la commande curl suivante :

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."}]}]}'

Remplacez ENVIRONMENT_GROUP_NAME par le nom de votre groupe d'environnements.

Le résultat doit ressembler à l'exemple suivant :

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

Le résultat affiche le flux de données initial suivi d'un message fault. En cas d'erreur, Apigee capture les informations sur la défaillance et les envoie au client sous forme d'événement.

Pour en savoir plus sur la gestion des pannes dans Apigee, consultez Gérer les pannes.

Afficher les données SSE dans Apigee Analytics

Les données des proxys SSE s'affichent dans Apigee Analytics, comme prévu pour tout proxy d'API. Dans la console Cloud, accédez à Analytics > Métriques de l'API.

Déboguer les proxys SSE

Utilisez l'outil de débogage Apigee pour déboguer les proxys SSE. Les données de débogage sont capturées pendant EventFlow, comme pour les autres types de flux.

Dépannage

Pour les problèmes de trafic en temps réel, consultez les journaux d'accès Apigee pour en déterminer la cause.

Limites

Les limites suivantes s'appliquent aux proxys SSE :

Étant donné que les données analytiques sont enregistrées après la fermeture de la session SSE, vous constaterez peut-être un certain délai dans la création des rapports.
Les erreurs dans un EventFlow entraînent la fermeture immédiate du flux et génèrent une erreur. Pour savoir comment consigner manuellement ces types d'erreurs ou les envoyer au client, consultez Cas d'utilisation et exemples d'EventFlow.
Un client qui reçoit des réponses SSE en streaming recevra les en-têtes HTTP, y compris les codes d'état, au début du flux d'événements. Par conséquent, si le flux d'événements passe à un état d'erreur, le code d'état initialement reçu ne reflétera pas l'état d'erreur.
Cette limite est visible lorsque vous consultez une session de débogage. Dans la session, vous remarquerez peut-être que le code d'état HTTP pour les flux qui passent à l'état d'erreur diffère des codes d'état envoyés au client. Cela peut se produire, car l'entrée de la session de débogage est générée après le traitement de l'intégralité de la requête, plutôt qu'au début du flux d'événements. La session de débogage peut refléter le code d'erreur généré par l'erreur, tandis que le client ne voit que l'état 2xx initialement reçu dans les en-têtes.

Flux d'événements envoyés par le serveur Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Créer un proxy d'API pour SSE

Configurer un EventFlow

Emplacement d'un EventFlow

<ProxyEndpoint>

<TargetEndpoint>

Ajouter des règles à un EventFlow

<ProxyEndpoint>

<TargetEndpoint>

Variables de flux

Cas d'utilisation et exemples d'EventFlow

Modifier une réponse SSE

<ProxyEndpoint>

<TargetEndpoint>

Afficher un exemple de réponse

Filtrer une réponse SSE

<ProxyEndpoint>

<TargetEndpoint>

Afficher un exemple de réponse

Envoyer un événement SSE à un système externe

<ProxyEndpoint>

<TargetEndpoint>

Utiliser une règle Apigee Model Armor dans un EventFlow

Gestion des erreurs dans EventFlow

<TargetEndpoint>

<ProxyEndpoint>

Propager les erreurs de défaut dans un EventFlow

<TargetEndpoint>

<ProxyEndpoint>

Afficher les données SSE dans Apigee Analytics

Déboguer les proxys SSE

Dépannage

Limites

Flux d'événements envoyés par le serveur