Événements de moniteur d'interrogation

Un moniteur d'interrogation est un mécanisme permettant de récupérer des informations de services en ligne sur une base planifiée, dans les situations où la prise en charge d'un flux d'événement webhook n'est pas disponible ou souhaitée.

À mesure que des événements spécifiques se produisent sur le service distant, ils sont suivis et enregistrés. Ensuite, lorsqu'un flux de moniteur d'interrogation planifié s'exécute, Okta interroge le service distant et récupère toutes les informations enregistrées depuis le dernier appel du service distant.

Ce mécanisme est couramment utilisé pour automatiser des processus et garder différents systèmes synchronisés sans requérir d'intervention manuelle constante.

Vue d'ensemble du moniteur d'interrogation

La configuration d'un flux de moniteur d'interrogation comprend plusieurs étapes générales :

  1. Configurez le moniteur d'interrogation. Le moniteur d'interrogation compose une requête GET qui appelle une ressource d'API spécifique à l'aide d'un filtre basé sur le temps qui est mis à jour après chaque exécution planifiée.

    Par exemple, un administrateur Okta peut configurer un moniteur d'interrogation pour recevoir des notifications quotidiennes sur les nouveaux employés que son entreprise a ajoutés dans Workday.

  2. Définissez une valeur d'incrémentation stockée, appelée curseur. Cette valeur stockée est mise à jour à chaque exécution du moniteur d'interrogation planifié. Dans Workflows Okta, cette valeur stockée, généralement un horodatage, est mise à jour et accessible à l'aide d'une carte de fonction Curseur. Chaque fois que le flux compose la requête GET, il utilise cette valeur pour récupérer les enregistrements du service distant. Consultez la carte Fonction Curseur pour plus d'informations sur l'implémentation.

  3. Planifiez le déclenchement de l'événement. Les moniteurs d'interrogation utilisent la même boîte de dialogue de configuration qu'un flux planifié. Vous pouvez configurer votre moniteur d'interrogation pour appeler le service distant à n'importe quelle fréquence, de 5 minutes à 30 jours.

  4. Récupéez la charge utile. Okta envoie la requête GET contenant la requête filtrée au service distant, qui renvoie une charge utile des enregistrements qui se sont produits dans le délai imparti.

  5. Traitez la charge utile. L'application réceptrice traite les enregistrements renvoyés par la requête GET. Elle analyse la charge utile JSON et termine le flux de l'événement.

    Lors de la gestion des charges utiles, il y a deux aspects du traitement à prendre en compte :

    • Agrégation de la demande. Les charges utiles entrantes sont reçues sous forme de lot d'éléments collectés.

    • Traitement des requêtes par lots. Bien que les charges utiles entrantes arrivent sous forme de lot collecté, le flux d'événement peut traiter chaque élément individuellement ou gérer le lot complet comme un seul élément.

    Consultez Activer le mode exécution pour les moniteurs d'interrogation.

Cas d'utilisation

L'implémentation la plus simple d'un événement de moniteur d'interrogation consiste à utiliser un horodatage enregistré dans le cadre de la requête envoyée à l'API du service distant. Cette méthode renvoie tous les enregistrements qui ont été créés ou mis à jour depuis cet horodatage.

Si une requête d'horodatage n'est pas prise en charge, il est possible que vous deviez récupérer tous les enregistrements et filtrer manuellement la collection. En outre, pour des scénarios plus complexes, par exemple le suivi d'utilisateurs supprimés, vous pouvez avoir besoin d'un objet curseur complexe qui conserve les métadonnées supplémentaires entre les exécutions du moniteur d'interrogation.

Enregistrements créés

Dans ce cas d'utilisation, la requête de filtre envoyée à l'API contient une date de début (l'horodatage d'exécution précédent) et une date de fin (l'horodatage d'exécution actuel). L'API renvoie tous les enregistrements ajoutés par le service distant au cours de la période spécifiée.

Votre flux de moniteur d'interrogation ressemblerait à l'exemple suivant. La Date de début est l'horodatage de l'exécution précédente, qui est extrait du Curseur. La Date de fin est l'heure actuelle. Ces valeurs sont ajoutées à une carte Composer pour constituer la chaîne de requête. La chaîne est envoyée à une carte Construire qui crée l'entrée de requête pour la carte Flux d'appel.

La requête renvoie les enregistrements en tant qu'objet de lot dans le corps de la carte Flux d'appel, qui est transmis à la carte Renvoyer des objets. La carte Curseur est mise à jour avec le nouvel horodatage à utiliser lors de la prochaine exécution de l'événement du moniteur d'interrogation.

Enregistrements mis à jour

De la même manière que pour l'interrogation des enregistrements créés, vous pouvez spécifier les horodatages avant et après pour rechercher les utilisateurs mis à jour, si l'API prend en charge le filtrage à l'aide d'un horodatage lastUpdated.

La seule différence dans le flux pour ce cas d'utilisation est que la chaîne de la carte de fonction Composer utilise updated au lieu de created pour la requête.

Lorsqu'il est exécuté, votre moniteur d'interrogation récupère toutes les modifications apportées aux utilisateur depuis la dernière mise à jour.

Enregistrements supprimés

Un scénario plus avancé consiste à utiliser un moniteur d'interrogation pour suivre les utilisateurs supprimés sur le service à distance. L'exemple suivant explique une façon de gérer ce cas d'utilisation en utilisant le curseur comme objet pour stocker les informations d'utilisateur avec un horodatage pour le suivi des exécutions.

Lors de la configuration de cette carte d'événement Moniteur d'interrogation, les sorties de la carte sont définies comme objet de groupe de sortie statique. Chaque utilisateur dans un objet Deleted User renvoyé est défini avec sa valeur User ID comme valeur de texte :

La requête API interroge le point de terminaison /v1/users pour renvoyer une liste d'objets contenant tous les utilisateurs actuels du système distant. Une fois ces informations renvoyées, le flux effectue les étapes suivantes :

  1. La liste des users renvoyés dans le corps de la requête API est transmise à une carte de fonction Extraire.

  2. La carte Extraire utilise la clé ID dans la liste users, renvoyant ainsi une liste de valeurs actuelles de l'ID utilisateur comme sortie. Cette currentUserList contient uniquement les utilisateurs actifs dans le système distant.

  3. L'objet curseur (tiré de la carte Moniteur d'interrogation du flux) contient également une liste d'utilisateurs à l'emplacement userList. Cet objet Cursor Properties correspond à une entrée pour une carte de fonction Objet - Obtenir. Cette carte de fonction génère un objet de liste appelé previous list of IDs qui contient tous les utilisateurs précédemment connus dans le système distant.

  4. Pour l'opération de comparaison, le flux compare la différence entre la liste d'ID précédente et la liste actuelle. Les ID qui ne se trouvent pas sur la liste actuelle sont envoyés dans une nouvelle liste appelée Deleted User IDs. Cette liste de sortie comprend toutes les valeurs d'ID qui ne se trouvent plus dans le système distant.

  5. Le flux crée ensuite un objet à transmettre à la carte Contrôle de flux - Curseur. La carte de fonction Objet - Construire prend comme entrée l'horodatage actuel ainsi que la liste qui vient d'être créée des utilisateurs actuels.

  6. L'objet output est ensuite transmis au champ Propriétés de la carte Curseur. L'objet curseur est enregistré en tant que métadonnées en vue de la prochaine exécution de ce moniteur d'interrogation.

  7. Cependant, la liste Deleted User IDs doit être formatée comme une liste d'objets à renvoyer à l'utilisateur du moniteur d'interrogation. Pour ce faire, le flux comprend une carte de fonction Liste - Mapper. La carte invoque un petit flux d'aide appelé Reshape Deleted Users pour chaque entrée de la liste Deleted User IDs.

    Le flux d'aide Reshape Deleted Users traite chaque élément de la liste Deleted User IDs. Chaque valeur ID transmise au flux est envoyée à une carte Objet - Construire. Cela crée un objet unique pour chaque utilisateur, au format { "User ID" : "ID" }.

  8. À mesure que chaque entrée de la liste Deleted User IDs est traitée, le flux l'ajoute à la liste d'objets Reshaped Outputs.

  9. Lorsque le flux d'aide est terminé, la liste d'objets Reshaped Outputs est transmise à la carte Contrôle de flux - Sorties de retour. Cela correspond à la sortie définie sur la carte Moniteur d'interrogation et termine l'exécution du moniteur d'interrogation. L'utilisateur reçoit la liste attendue des utilisateurs supprimés du service distant.