Générer un flux d'événement de moniteur d'interrogation

Les événements de moniteur d'interrogation sont conçus pour s'exécuter automatiquement à intervalles réguliers, en interrogeant une API pour les enregistrements qui ont changé depuis la dernière exécution. Voici comment ils fonctionnent :

• Initialisation et exécution : Lorsqu'il est activé, l'événement de moniteur d'interrogation appelle l'API pour récupérer une collection d'enregistrements et définit un curseur (typiquement un horodatage) pour marquer le point actuel dans le temps. Lors des exécutions suivantes, le curseur est utilisé pour modifier l'appel API afin qu'il ne retourne que les enregistrements modifiés après la dernière exécution.

• Fonctionnalité du curseur : Le curseur est une métadonnée persistante qui aide à filtrer les données entre les itérations. Par exemple, si chaque enregistrement inclut un horodatage createdAt, le curseur garantit que seuls les enregistrements ayant un horodatage postérieur à la dernière valeur de curseur enregistrée sont traités. Après chaque itération, le curseur se met à jour à la nouvelle heure d'exécution.

• Cas d'utilisation : Les événements de moniteur d'interrogation sont utiles pour les API de services distants qui ne prennent pas en charge les webhooks en temps réel. Ils permettent des vérifications régulières d'événements comme la création d'utilisateur en interrogeant les enregistrements dans une plage temporelle spécifiée (à l'aide de paramètres comme startAt et endAt).

• Applications pratiques : Dans Workflows Okta, ces événements vous permettent de créer des cartes d'événement pour les connecteurs qui se déclenchent sur de nouveaux événements, comme la création, la mise à jour ou la suppression d'enregistrements.

  Remarque :

  La taille d'un curseur est limitée à 10 ko. L'utilisation de curseurs pour stocker de grandes quantités de données peut provoquer des erreurs qui obligent vos utilisateurs à réactiver leur flux et à réinitialiser le curseur.

En somme, les événements de moniteur d'interrogation fournissent une approche systématique pour gérer les enregistrements nouveaux et modifiés en utilisant des appels API planifiés et un curseur persistant pour garantir que seuls les changements récents sont traités.

Exemple

Cet exemple de flux de moniteur d'interrogation utilise un objet curseur pour stocker un horodatage et enregistrer des informations sur les nouveaux utilisateurs ajoutés à un service distant.

Il s'agit de la vue initiale lorsque vous créez une carte d'événement Moniteur d'interrogation. Elle contient la carte d'événement Moniteur d'interrogation, ainsi que les cartes Contrôle de flux, Curseur et Sorties de retour.

L'exemple suivant décrit la manière de construire ce flux d'événement de moniteur d'interrogation :

1. Sur la carte d'événement Moniteur d'interrogation, le type de champ Curseur est un Object, car le curseur contient des informations d'enregistrement en plus de l'horodatage.

2. Une carte de fonction Objet Obtenir récupère l'horodatage de l'objet curseur, qui est stocké dans une clé appelée cursor_value.

   Dans cet exemple, la sortie de la carte est un champ de type Date et heure appelé saved start date.

3. Une carte Date et heure Maintenant génère un nouvel horodatage pour cette exécution du moniteur d'interrogation. Pour plus de commodité, le nom du champ est modifié en date - New end date.

4. Les champs saved start date et date - New end date se combinent en une carte Objet Construire pour créer un objet de requête appelé output.

5. La carte Contrôle de flux Flux d'appel effectue un appel vers l'API externe. Elle utilise le flux httpHelper pour votre connecteur, avec un appel GET au point de terminaison /v1/users.

   Construisez votre filtre de requête API pour sélectionner les enregistrements avec une fenêtre de temps. Par exemple, voici un objet de requête qui vérifie les événements de création d'utilisateur dans une période d'un mois :

   {
     "createdBefore": 2025-02-01T00:00:00.000Z,
     "createdAfter": 2025-01-01T00:00:00.000Z
   }

   La carte Contrôle de flux Flux d'appel utilise la connexion fournie sur la carte Moniteur d'interrogation pour l'autorisation de la connexion.

   Dans l'exemple, cette carte renvoie une liste d'objets appelée newUsersList.

6. Les cartes mentionnées aux étapes 4 et 5 sont incluses dans le bloc Essai d'une carte Branche Si erreur.

   Si l'appel d'API aboutit, la sortie de la carte Essai est une liste de nouveaux utilisateurs. Cette liste d'objets est envoyée à la carte Sorties de retour.

   Le bloc Si erreur de cette fonction n'est pas affiché. Cependant, il spécifie un processus qui gérera les erreurs rencontrées lors de la définition de l'objet curseur ou de l'appel d'API.

7. La carte Objet Construire met à jour l'objet curseur. Elle remplace la valeur de l'horodatage précédent stockée dans la clé cursor_value avec la valeur date - New end date. Il s'agit de l'horodatage le plus récent, et la prochaine itération du moniteur d'interrogation utilisera cette valeur pour le champ saved start date.

8. La carte Contrôle de flux Curseur met à jour la valeur Propriétés pour le curseur du flux de moniteur d'interrogation de cet utilisateur.

9. La carte Sorties de retour renvoie la liste des nouveaux utilisateurs au flux qui a appelé le moniteur d'interrogation et termine cette exécution.

Tester un événement de moniteur d'interrogation

Pour tester votre événement de moniteur d'interrogation dans Connector Builder, vous pouvez définir la valeur Curseur dans la boîte de dialogue Exécuter.

Saisissez une valeur provenant d'une itération précédente de l'exécution de moniteur d'interrogation pour simuler la valeur du curseur.

Vous pouvez également laisser le curseur sous forme de valeur nulle pour simuler la première exécution du moniteur d'interrogation.