Déclencheur d’interrogation
Un déclencheur d’interrogation est une implémentation qui appelle régulièrement votre service d’API REST et recherche de nouvelles données. Une fois que la plateforme a déterminé que de nouvelles données sont disponibles, le déclencheur se déclenche et transmet les nouvelles données collectées à un flux de cloud ou à un flux de travail Logic Apps.
Le schéma suivant montre un flux de processus de base illustrant la façon dont un déclencheur d’interrogation acquiert de nouvelles données.
Un déclencheur d’interrogation commence par récupérer les données et définir un état. Ensuite, il recherche régulièrement les mises à jour en demandant toutes les données depuis la dernière mise à jour de l’état. Une fois les nouvelles données récupérées, le nouvel état est défini et le processus se poursuit. L’API doit pouvoir renvoyer les données de manière incrémentielle, en fonction d’une valeur de paramètre. Power Automate ou Azure Logic Apps conserve l’état afin que l’API n’ait pas d’exigences de gestion d’état spéciales.
Contrairement à un déclencheur Webhook, un déclencheur d’interrogation n’a pas d’exigences de configuration ou de suppression, et le traitement peut être arrêté à tout moment. La simplicité des exigences est l’un des principaux avantages du déclencheur d’interrogation.
Exigences relatives à l’API
Un déclencheur d’interrogation a uniquement besoin qu’une API dispose d’une méthode d’extraction de données capable de filtrer les données à l’aide d’un paramètre de chaîne de requête. Il doit également exister un moyen d’extraire la valeur suivante du paramètre à partir des données renvoyées. L’implémentation peut être fournie par une méthode d’action dédiée ou existante.
Prenons l’exemple de l’implémentation d’une boutique en ligne où les numéros des commandes sont toujours croissants. L’API de la boutique peut inclure une méthode appelée ListOrders qui renvoie les commandes créées dans la boutique.
ListOrders renvoie les commandes triées par ordre décroissant selon leur numéro de commande. Par conséquent, le numéro de commande le plus élevé est le premier de la liste.
ListOrders accepte un paramètre de chaîne de requête permettant de récupérer les commandes dont le numéro de commande est supérieur à la valeur du paramètre.
Ces deux qualités permettent à l’action d’être utilisée comme déclencheur d’interrogation. La plateforme peut extraire le numéro de commande le plus élevé des données renvoyées et le transmettre en tant que paramètre dans la requête suivante. Dans les faits, la méthode « sélectionnera toutes les commandes créées depuis la dernière ».
Implémentation
Un déclencheur d’interrogation est créé à l’aide d’un assistant dans Power Automate. Le processus comprend les étapes suivantes :
Définissez la requête HTTP qui sera utilisée pour récupérer les données.
La chaîne de requête de la requête comprend le paramètre fromWidget, qui permet la pré-génération de la définition du paramètre. Ce paramètre garantit que les données renvoyées sont incrémentielles, qu’il « renverra tous les widgets créés depuis celui spécifié par le paramètre ».
Modifiez la visibilité des paramètres en Interne, ce qui va empêcher les utilisateurs d’apporter des modifications à ce paramètre qui n’est utilisé qu’en interne par le connecteur.
Définissez les données renvoyées par le service. Ces données doivent inclure la propriété à utiliser comme valeur pour fromWidget dans les requêtes consécutives.
Dans cet exemple, la propriété est appelée ID.
Effectuez la configuration du déclencheur. Sélectionnez le paramètre de requête, définissez une valeur ou une expression qui renvoie une valeur, puis sélectionnez une collection qui contient les données du déclencheur.
Cet exemple inclut les paramètres suivants :
fromWidget est sélectionné comme paramètre de requête qui recevra la valeur extraite des résultats de l’exercice.
L’expression @{triggerBody().widgets[0].id} extrait l’ID de widget actuel le plus élevé. Étant donné que la collection retournée est triée par ordre décroissant en fonction de la valeur d’ID, l’extraction de la valeur du premier élément permet de garantir qu’il s’agit de l’ID actuel le plus élevé.
L’expression @triggerBody().widgets définit la collection de données.
Les paramètres doivent être extraits et traités, et cette transformation ne peut être implémentée qu’à l’aide d’une stratégie de connecteur. Par conséquent, la configuration du déclencheur d’interrogation est stockée en tant que modèle de stratégie distinct de la définition du connecteur OpenAPI. L’une des implications est qu’il n’est pas possible de modifier manuellement toutes les configurations de déclencheur d’interrogation dans l’éditeur Swagger.
Une limitation dont vous devez être conscient est que le corps du déclencheur ne peut pas être un tableau. Prenons l’exemple d’une méthode appelée ListOrders qui renvoie les données suivantes :
[
{"value" : 42.00, "id" : "2", ... },
{"value" : 10.00, "id" : "1", ... }
]
Ce corps de déclencheur ne sera pas traité et le déclencheur générera une erreur dans le flux Power Automate ou le flux de travail Logic Apps au moment de l’exécution.
Au lieu de cela, la méthode doit renvoyer une propriété qui contient le tableau des enregistrements, par exemple :
{
"orders": [
{ "value" : 42.00, "id" : "2", ... },
{ "value" : 10.00, "id" : "1", ... }
]
}
Cette structure de données peut être utilisée dans le cadre de l’implémentation du déclencheur d’interrogation.
Traitement par lots
Comme le déclencheur Webhook, le déclencheur d’interrogation est défini par l’extension x-ms-trigger sur OpenAPI. La valeur définie par un déclencheur d’interrogation est un lot, ce qui indique que la méthode renverra un tableau plutôt qu’un objet individuel, comme elle le fait dans une réponse du webhook.
/trigger/ListInvoices:
post:
x-ms-trigger: batch
Ce processus se produit, car il est possible que plusieurs enregistrements soient renvoyés à partir d’un seul appel au service. Lorsqu’un déclencheur d’interrogation est utilisé dans Power Automate ou Logic Apps, le paramètre Fractionner sur du déclencheur vous permet de configurer le mode de traitement.
Le fractionnement du tableau entrant en plusieurs implémentations parallèles est effectué pour des raisons de performances. Chaque instance du flux de cloud dans ce scénario recevra un seul objet. Si l’option SplitOn n’est pas définie, une seule instance du flux de cloud recevra un tableau de valeurs.
Les déclencheurs d’interrogation sont plus faciles à définir que les déclencheurs Webhook ; cependant, ils sont moins granulaires et souvent ne fonctionnent pas aussi bien. La décision de créer et d’utiliser un type de déclencheur ou un autre dépend des fonctionnalités, de la structure et du fonctionnement de l’API de service.