|
Dépannage |
Scroll |
Comment fonctionne la fonctionnalité « Appeler une fonction » ?
Pour résoudre les problèmes, vous devez maîtriser les concepts de base du fonctionnement d'« Appeler une fonction ». Le diagramme suivant illustre les interactions entre les différents composants.
Lorsque la tâche « Appeler une fonction » est exécutée dans le moteur de workflow, une requête POST HTTPS est envoyée à la fonction. Si l'appel aboutit, la fonction appelée est exécutée et appelle probablement Therefore™ Server à l'aide de Web API pour récupérer des documents, des données d'index ou toute autre information complémentaire requise.
La fonction appelée peut être une fonction Azure, un service Web ou tout code exécutable capable de répondre à une requête POST HTTPS. Il est toutefois nécessaire que la fonction appelée renvoie un objet JSON contenant la chaîne « TheError » et soit la valeur booléenne « TheRoutingDone », soit l'entier « TheRetryAfterMin ». Si une fonction a été développée par Therefore™, elle peut être hébergée dans l'abonnement Azure de Therefore™ Online.
Pour raisons de sécurité, les fonctions développées par les clients doivent s'exécuter dans leur propre abonnement Azure ou dans leur infrastructure.
Comme indiqué dans le diagramme, toutes les connexions entre Therefore™ et la fonction appelée ne sont que des requêtes POST HTTPS et des appels (Web) API. Aucun code client n'est directement exécuté par le service du serveur, et aucun code client ne s'exécute au sein de l'environnement Therefore™ Online. Toutes les permissions doivent être vérifiées normalement pour les appels Web API. Le jeton d'accès fourni avec la requête HTTPS se limite à l'instance de workflow en cours uniquement. En raison de cette architecture, l'utilisation de workflows personnalisés dans Therefore™ Online est sécurisée.
Comment sont signalés les messages d'erreur ?
Tous les messages d'erreur générés doivent être consignés dans l'historique de workflow.
Comme illustré dans le diagramme d'architecture, Therefore™ se contente d'envoyer une requête HTTPS. La partie la plus importante (c'est-à-dire le code client) est exécutée au sein de la fonction appelée.
Si la fonction échoue, toutes les erreurs générées doivent être signalées à Therefore™, pour pouvoir être consignées dans l'historique de workflow. Si la fonction donne lieu à une erreur, l'entrée de l'historique de workflow débute par « La fonction appelée a renvoyé une erreur. ». Si la fonction se bloque en raison d'une exception non gérée ou ne renvoie pas l'information, Therefore™ ne peut rien consigner. Si une fonction ne renvoie qu'un objet avec une chaîne « TheError » vide et que la valeur booléenne « TheRoutingDone” est réglée sur false, le résultat est assimilé à une réussite, car l'appel HTTPS a fonctionné et aucune erreur n'a été signalée.
Le tableau ci-dessous contient quelques erreurs susceptibles de se produire lors de l'appel d'une fonction :
|
|---|
Comment fonctionne la surveillance dans le portail Azure ?
Configurez le service « Application Insights » de Microsoft pour surveiller les fonctions Azure. Pour afficher la liste des appels de fonction récents, cliquez sur « Surveiller » après avoir sélectionné une fonction dans le portail Azure.
Les appels de fonction sont considérés comme « réussis » s'il ne s'est pas produit d'exception non gérée, quel que soit le code de résultat ou les exceptions interceptées. Therefore™ adopte un comportement similaire. Si une exception a été interceptée, elle doit être signalée avec le code d'état 200, plus les informations correspondantes dans la chaîne de retour « TheError ».
S'il se produit une exception non gérée, la fonction ne renvoie rien à Therefore™ et Web Service se contente d'envoyer le code d'état 500. Dans ce cas de figure, aucune information autre que le code d'état 500 ne s'affiche dans Therefore™ et vous devez vérifier les détails correspondants dans Azure Monitoring.
La valeur « ID d'opération » permet de rechercher des détails dans la table d'exceptions et d'inspecter les traces de pile. Copiez l'« ID d'opération » et cliquez sur « Exécuter dans Application Insights » pour l'ouvrir dans un nouvel onglet.
Collez l'« ID d'opération » dans la fenêtre de requête et structurez une requête comme suit :
exceptions | where operation_Id == "IDOpération"
| limit 50
Lorsque vous cliquez sur « Exécuter », les informations relatives aux exceptions associées à l'« ID d'opération » sont affichées.
Une ligne au moins contient des informations relatives aux exceptions.
Exportez toutes les lignes et envoyez-les au développeur responsable de la fonction Azure.
Vérifiez également la table des traces pour vérifier si elle contient des informations complémentaires relatives au workflow. Si vous avez utilisé un exemple, chaque appel de fonction est consigné avec le numéro d'instance; de jeton, de dossier ou de document.
Copiez la requête précédente et remplacez « exceptions » par « traces » :
traces | where operation_Id == "IDOpération"
| limit 50
Incluez également ces informations lorsque vous contactez le développeur.
Si la fonction effectue des tâches de conversion, ajoutez également le document.
Foire aux questions relative au développement
Comment et où développer une fonction Azure ?
Le développement d'une fonction Azure peut être effectué du début à la fin dans Visual Studio et ne nécessite pas d'abonnement Azure. Lorsque vous avez créé une fonction Azure à l'aide de l'assistant de projet, appuyez sur F5 pour la démarrer. Le débogueur avec points d'arrêt fonctionne comme pour toute autre application.
Un abonnement Azure est-il nécessaire ?
À des fins de test ou de développement, non. Les fonctions Azure peuvent être écrites et exécutées directement dans Visual Studio. Si le système de développement est accessible publiquement via http, il peut même être utilisé avec Therefore™ Online. Pour exécuter la fonction Azure dans un environnement de production, vous devez disposer d'un abonnement Azure. Vous pouvez également créer une fonction pour un service Web non hébergé dans Microsoft Azure. Dans ce cas de figure, aucun abonnement n'est nécessaire.
Pourquoi ma fonction ne renvoie-t-elle pas un paramètre obligatoire ?
Toutes les fonctions appelées par la tâche « Appeler une fonction » doivent renvoyer un objet JSON contenant la chaîne « TheError » et soit la valeur booléenne « TheRoutingDone », soit l'entier « TheRetryAfterMin ».
S'il ne se produit pas d'erreur, « TheError » doit être vide, mais doit exister dans l'objet JSON. Particulièrement en cas d'erreur, il est important d'intercepter l'exception et de la transmettre à Therefore™ à l'aide de « TheError » pour que l'information soit consignée correctement.
Comment tester ma fonction (Azure) sans Therefore™ ?
En particulier si vous manquez d'expérience en matière de développement de fonctions (Azure), il peut s'avérer plus rapide d'appeler directement la fonction pour la tester. Avec cURL, utilisez la commande suivante :
curl –d “” –i –X POST http://localhost:Port/api/Route
Si la fonction a déjà été déployée dans Azure, utilisez la commande suivante :
curl –d “” –i –X POST “https://AppName.azurwebsites.net/api/Route?code=FunctionKey”
L'itinéraire peut être défini dans le code. S'il n'est pas défini, le nom de la fonction est utilisé.
L'appel de Web API génère des messages de type « Accès refusé » ou « Vous n'êtes pas autorisé à... ».
Pour raisons de sécurité, le jeton JWT fourni possède des permissions très limitées et vous risquez donc de rencontrer des problèmes de droits d'accès. Si d'autres permissions sont nécessaires, un utilisateur interne disposant de toutes les permissions requises doit être généré. Les coordonnées d'identification peuvent ensuite être transmises à la fonction à l'aide de « WebAPIUser » et « WebAPIPassword » en les ajoutant en tant que paramètres d'application dans le portail Azure ou, en cas de développement local, au fichier « local.settings.json ».
Est-il possible d'utiliser Therefore™ API pour ma fonction ?
Cela dépend de la plateforme utilisée. Si vous utilisez des fonctions Azure, vous devez faire appel à Therefore™ Web API, car l'API normale possède trop de dépendances.
