|
Didacticiels > Solution Designer > Workflow > Personnalisation des workflows dans Therefore™ Online Développement d'une nouvelle fonction Azure |
Scroll |
Comment développer une nouvelle fonction Azure ?
Bien que de nombreux langages et outils soient pris en charge, ce guide se limite à la création de fonctions Azure avec C# dans Visual Studio. Cette méthode est recommandée car les fonctions Azure peuvent être testées et déboguées localement sans disposer d'un abonnement Azure en appuyant simplement sur F5. Il est également possible de la déployer dans Azure depuis Visual Studio.
Veillez à installer Visual Studio avec la charge de travail de développement Azure.
Dans Visual Studio, cliquez sur le menu « Tools », puis sur « Get Tools and Features... » pour ouvrir le programme d'installation.
Ouvrez l'onglet « Workloads » et recherchez « Azure development ». Cochez la case en haut à droite et cliquez sur « Modify » pour activer les modifications.
|
|---|
Comment créer une fonction Azure ?
Si l'installation de la charge de travail de développement Azure a abouti, l'option « Azure Functions » est disponible lors de la création d'un projet dans Visual Studio. Il est toutefois recommandé de débuter par l'exemple « EmptyFunctionApp » plutôt que de démarrer de toutes pièces le développement.
Veillez à sélectionner « Azure Functions v2 » (car « v1 » deviendra à un moment ou à un autre obsolète) et « Http trigger », car Therefore™ prend actuellement en charge l'appel des fonctions Azure à l'aide de requêtes HTTP(S) uniquement.
Les droits d'accès ne sont appliqués que lorsque la fonction est publiée et non dans le cadre d'un développement local. Si vous choisissez « Anonymous », aucune clé n'est requise. « Function » nécessite la clé de fonction, tandis qu'« Admin » nécessite la clé Function App. La clé principale peut également être utilisée. |
|---|
Comment utiliser REST pour les appels Web API ?
Ajoutez le répertoire « Therefore » à votre projet depuis l'exemple « EmptyFunctionApp ».
Les fichiers ne sont pas obligatoires, mais le développement est ainsi plus simple et plus rapide.
Si des modifications apportées à Web API nécessitent la mise à jour de WebAPIContract.cs, procédez comme suit :
1.Téléchargez et installez Silverlight 5.0 ou ultérieur. 2.Assurez-vous que le service XML est en cours d'exécution. 3.Créez un répertoire temporaire (« C:\WebAPI », par exemple). 4.Ouvrez une ligne de commande et accédez à « C:\Program Files (x86)\Microsoft SDKs\Silverlight\v5.0\Tools ». 5.Exécutez la commande suivante : SlSvcUtil.exe http://servername:8000/theservice/v0001?singlewsdl /out: C:\WebAPI \WebAPIContract.cs /config: C:\WebAPI \output /namespace:http://schemas.therefore.net/webservices/interop/v0001/types,Therefore.WebAPI 6. Accédez à « C:\WebAPI » et copiez WebAPIContract.cs dans le répertoire « Therefore\WebAPI » en replaçant la version existante.
Comme indiqué dans l'exemple de projet, vous pouvez utiliser la fonction SendRequest appartenant à la classe Therefore.WebAPI.WebApiClient pour envoyer une requête. Pour obtenir la liste de toutes les commandes disponibles, consultez la documentation Web API.
Pour utiliser WebAPIContract.cs, vous devez disposer du package NuGet « System.ServiceModel.Http ». Pour plus d'informations, reportez-vous à Dépendances.
|
|---|
Comment utiliser SOAP pour les appels Web API ?
Ajoutez le répertoire « Therefore » à votre projet depuis l'exemple « EmptyFunctionApp », puis supprimez le sous-répertoire « WebAPI », car il est nécessaire pour les appels REST uniquement. Étant donné qu'il n'est pas recommandé d'utiliser SOAP, la valeur de « UseREST » dans la classe TheConfig doit être réglée sur « false », sous peine que la propriété WebAPIBaseUrl soit incorrecte.
Ajoutez Therefore™ Web API en tant que service connecté :
En tant que service connecté, choisissez « Microsoft WCF Web Service Reference Provider ».
Insérez l'URL de l'emplacement où s'exécute Web Service et appuyez sur « Go (OK) ». Si le service est en cours d'exécution, il figure dans la liste Services sous le nom « ThereforeService ».
Entrez un espace de nom pertinent tel que « Therefore.WebAPI » et appuyez sur Terminer.
La classe Therefore.WebAPI.ThereforeServiceClient permet d'effectuer des appels Web API.
Pour plus d'informations sur le package NuGet « System.ServiceModel.Http », reportez-vous à Dépendances.
|
|---|
Pour ajouter le package NuGet « System.ServiceModel.Http », cliquez avec le bouton droit de la souris sur votre projet et sélectionnez « Manage NuGet Packages… ».
Accédez à l'onglet Browse et recherchez « System.ServiceModel.Http », sélectionnez-le et cliquez sur Installer.
Si le message d'erreur suivante s'affiche en cours de création, un bogue n'est pas encore résolu :
System.IO.FileNotFoundException: Could not load file or assembly 'System.Private.ServiceModel, Version=4.5.0.3, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a'. The system cannot find the file specified.
Pour résoudre le problème, modifiez le fichier .csproj et ajoutez la configuration suivante en tant qu'enfant du nœud racine « Project » :
<!--this is temporary workaround for issue https://github.com/dotnet/wcf/issues/2824 also requires nuget package--> <Target Name="CopySPSM" BeforeTargets="Build"> <Copy SourceFiles="$(USERPROFILE)\.nuget\packages\system.private.servicemodel\ </Target> <ItemGroup> <None Include="$(USERPROFILE)\.nuget\packages\system.private.servicemodel\ </ItemGroup> <!--end workaround-->
Notez que vous devrez peut-être modifier les numéros de version et les sauts de ligne. |
|---|
L'exemple EmptyFunctionApp est une petite fonction Azure qui récupère les paramètres transmis de Therefore™, configure l'objet WebApiClient pour qu'il soit prêt à l'emploi et renvoie les paramètres requis, une fois l'opération terminée. Il a été conçu pour servir de point de départ d'un développement complémentaire.
public static async Task<IActionResult> Run( [HttpTrigger(AuthorizationLevel.Function, "post", Route = "v1/Function1")] HttpRequest req, ILogger log) { string errMsg = ""; // error message that will be returned to Therefore for logging Exception logEx = null; // exception details for logging bool routingDone = false; // false: WF instance will be routed to the next task. // true: WF instance will not be routed because routing was done by WebAPI call try…
if (!String.IsNullOrWhiteSpace(errMsg) || logEx != null) log.LogError(logEx, errMsg); // log the error so it can be viewed in the Azure Portal
TheRespParams respParams = new TheRespParams(errMsg, routingDone); return new OkObjectResult(respParams.Serialize());
La fonction « Run » est la fonction principale appelée pour une requête HTTP.
L'élément « AuthorizationLevel » défini dans HttpTrigger n'est appliqué que lorsque la fonction est publiée et non dans le cadre d'un développement local. Si vous choisissez « Anonymous », aucune clé n'est requise, tandis que « Function » nécessite la clé de fonction et « Admin » la clé Function App. La clé principale peut également être utilisée.
L'élément « Route » défini dans HttpTrigger sous la forme « v1/Function1 » prend en charge le suivi des versions. Supposons qu'une nouvelle version de workflow nécessite une nouvelle version de la fonction, mais que certaines instances doivent continuer à utiliser l'ancienne version. Vous pourriez copier la fonction et remplacer l'itinéraire « v1 » par « v2 » dans le code et dans la configuration des nouvelles tâches pour répondre à ce besoin. Une instance de Function App peut contenir de multiples fonctions.
À la fin de l'exemple, toute erreur qui s'est éventuellement produite est consignée dans Azure et est transmise à un objet de la classe « TheRespParams ». La classe « TheRespParams » gère la conversion des paramètres de retour obligatoires associés à Therefore™ en objet JSON.
Un élément « OkObjectResult » est toujours généré et renvoie l'objet JSON avec le code d'état HTTP 200. Tout message d'erreur entré dans « errMsg » est renvoyé à Therefore™ pour être consigné dans l'historique de workflow. Côté Therefore™, l'appel de fonction a abouti s'il ne s'est pas produit d'erreur (en d'autres termes, errMsg est vide). |
|---|
try { // read parameters passed by Therefore string requestBody = await new StreamReader(req.Body).ReadToEndAsync(); TheReqParams reqParams = TheReqParams.Deserialize(requestBody); if (reqParams == null || reqParams.TheInstanceNo <= 0 || reqParams.TheTokenNo <= 0) return new BadRequestObjectResult("Mandatory parameter not set"); // function was not called by Therefore, return HTTP error 400 reqParams.LogWFInfo(log); // log workflow information now, in case the function crashes later
// configuration TheConfig config = TheConfig.Instance; config.WebAPIBaseUrl = reqParams.TheWebAPIUrl; config.Tenant = reqParams.TheTenant;
// Web API connection WebApiClient client; // specify a user name and password if the permissions from the accessToken would not be sufficient if (!String.IsNullOrEmpty(config.UserName) && !String.IsNullOrEmpty(config.Password)) // connection with user name and password/token: client = new WebApiClient(config.UserName, config.Password, config.IsToken, config.WebAPIUrl, config.Tenant, config.Language, config.RequestTimeout, config.ClientTimezoneIANA); else // connection with JWT Bearer token 'accessToken' client = new WebApiClient(reqParams.TheAccessToken, config.WebAPIUrl, config.Tenant, config.Language, config.RequestTimeout, config.ClientTimezoneIANA);
// Add your code here }
L'élément « TheReqParams » est chargé de lire tous les paramètres de requêtes issus de Therefore™ transmis.
La classe « TheConfig » possède diverses propriétés requises pour l'appel WebAPI, telles que la langue, le fuseau horaire, le délai imparti à la requête, etc. Vous pouvez les configurer en fonction de vos besoins ou conserver les valeurs par défaut.
Deux propriétés ne possèdent pas de valeur par défaut, pourtant utile : « WebAPIBaseUrl » et « Tenant ». Les valeurs sont transmises depuis le serveur Therefore™ et doivent juste être assignées à l'objet « TheConfig ».
La classe TheConfig lit les propriétés UserName et Password dans « local.settings.json » en cas de développement local, ou dans les paramètres d'application en cas d'exécution dans Azure.
L'objet WebApiClient peut être instancié à l'aide des coordonnées de connexion des utilisateurs ou du jeton JWT.
La solution retenue varie selon que les coordonnées sont vides ou non. Si aucune coordonnée de connexion n'est configurée, le jeton JWT est utilisé.
Vous pouvez utiliser la fonction SendRequest appartenant à la classe WebApiClient pour envoyer une requête. Pour obtenir la liste de toutes les commandes disponibles, consultez la documentation Web API.
Au niveau du commentaire « Add your code here », vous pouvez formuler des requêtes Web API et mettre en œuvre votre logique métier.
En cas d'échec, une erreur est renvoyée, en cas de réussite, une chaîne vide. L'application Therefore™ est donc avertie si la fonction s'exécute comme prévu (hors de l'instruction try/catch). |
|---|
Cette documentation se limite à expliquer en termes généraux comment envoyer des requêtes à l'aide de Web API, mais ne décrit pas chaque fonction disponible. Pour savoir comment utiliser les diverses fonctions, reportez-vous à la documentation Web API.
Vous pouvez appeler les fonctions Web API à l'aide de la classe Therefore.WebAPI.WebApiClient.
La création d'une instance nécessite quelques paramètres. Comme indiqué dans l'exemple de code EmptyFunctionApp, l'objet « TheConfig » vous facilite la tâche. Lorsque vous configurez une propriété requestTimeout, n'oubliez pas que la fonction en tant que telle est appelée par une requête HTTP et expire après 230 secondes au plus. Informations d'identification : WebApiClient client = new WebApiClient(username, password, isToken, webApiUrl, tenant, language, requestTimeout, clientTimezoneIANA);
Jeton porteur JWT : WebApiClient client = new WebApiClient(bearerToken, webApiUrl, tenant, language, requestTimeout, clientTimezoneIANA);
Lorsque l'objet WebApiClient est créé, vous pouvez envoyer des requêtes à l'aide de la fonction « SendRequest ». Task<TResp> SendRequest<TReq, TResp>(TReq requestData)
Cette fonction unique couvre l'ensemble des fonctionnalités Web API. La requête est déterminée par le type de paramètre de requête et de réponse. La requête et la réponse doivent être identiques. À titre d'exemple, GetDocumentParams peut être utilisé avec GetDocumentResponse pour formuler une requête « GetDocument ».
Exemple : récupération d'un document (contenant des fichiers) :
Vous pouvez récupérer des documents à l'aide de GetDocumentParams en spécifiant GetDocumentResponse dans la fonction SendRequest.
Vous devez spécifier le numéro du document dans le paramètre de requête GetDocumentParams.
Si les fichiers du document doivent également être récupérés, vous devez régler la propriété « IsStreamsInfoAndDataNeeded » sur true. Si les informations de flux sans les données en tant que telles sont suffisantes, vous pouvez régler « IsStreamsInfoNeeded » sur true.
// Create request parameters GetDocumentParams parameters = new GetDocumentParams(); parameters.DocNo = docNo; parameters.IsStreamsInfoAndDataNeeded = true; parameters.IsIndexDataValuesNeeded = true;
// Send the request GetDocumentResponse docResp = client.SendRequest<GetDocumentParams, GetDocumentResponse>(parameters).Result;
// Extract all file streams to the specified directory string extractDir = Path.GetTempPath(); foreach (var streamInfo in docResp.StreamsInfo) { string extractFileName = Path.Combine(extractDir, streamInfo.FileName); File.WriteAllBytes(extractFileName, streamInfo.StreamData); } |
|---|
Réponse : Chaque fonction appelée par la nouvelle tâche de workflow « Appeler une fonction » doit renvoyer quelques paramètres de retour obligatoires au format JSON dans la réponse HTTP : •TheError : valeur de chaîne obligatoire. Si la chaîne n'est pas vide, elle s'affiche dans l'historique du workflow. L'instance est marquée comme erronée, à moins qu'une nouvelle tentative ultérieure soit demandée. •TheRetryAfterMin : valeur entière facultative. Permet de demander une nouvelle tentative à Therefore™. Si elle est réglée sur une valeur supérieure à zéro, la tâche « Appeler une fonction » se comporte comme une tâche « Attendre » et envoie une nouvelle requête après l'intervalle de temps (approximatif) exprimé en minutes spécifié. Si la valeur « TheError » est définie, elle est traitée comme un avertissement et l'instance de workflow n'est pas marquée comme erronée. •TheRoutingDone : valeur booléenne obligatoire, à moins que la valeur « TheRetryAfterMin » ne soit spécifiée. Vous pouvez la régler sur « true » pour indiquer que l'acheminement de l'instance de workflow a déjà été effectué par la fonction à l'aide de la fonction Web API « FinishCurrentWorkflowTask ». Si elle est réglée sur « false », Therefore™ achemine l'instance de workflow vers la tâche suivante. Si vous spécifiez « TheRetryAfterMin », l'acheminement n'est pas encore exécuté et, dans ce cas de figure, le paramètre est donc facultatif. La classe « TheRespParams » a été créée pour simplifier le renvoi de ces paramètres. Elle contient tous ces paramètres sous forme de propriétés et fournit la fonction « Serialize » permettant de créer un objet JSON. Il existe deux méthodes d'initialisation d'un objet de cette classe : •Utilisation de « TheError » et « TheRoutingDone » TheRespParams respParams = new TheRespParams(errMsg, routingDone); À utiliser par défaut ou s'il se produit une erreur. Les deux valeurs sont facultatives.
L'élément errMsg est vide et routingDone est réglé sur false par défaut.
•Utilisation de « TheError » et « TheRetryAfterMin » TheRespParams respParams = new TheRespParams(retryAfterMin, errMsg);
L'application Therefore™ est ainsi obligée de retenter ultérieurement l'appel de fonction. Le paramètre entier retryAfterMin doit être supérieur à zéro. Le paramètre errMsg est facultatif et sera consigné en tant qu'information complémentaire (en non en tant qu'erreur) dans l'historique de workflow.
Requête :
À chaque appel de fonction, Therefore™ envoie les paramètres suivants à la fonction sous forme de jeton JSON avec la requête HTTPS :
•TheWebAPIUrl : contient le paramètre de serveur « URL Web API », que vous pouvez configurer sur l'onglet « XML Web Service » ou dans les paramètres avancés. Ce paramètre est déjà configuré correctement si vous utilisez Therefore™ Online, mais peut rester vide s'il n'est pas configuré. •TheTenant : nom du locataire en cours. Ce paramètre est vide si le système n'utilise pas plusieurs locataires. •TheAccessToken : jeton JWT permettant de se connecter à Therefore™ à l'aide de Web API. Le jeton est configuré de sorte à permettre à l'utilisateur associé à « $TheWFSystem » d'accéder au document ou au dossier relatif à l'instance de workflow en cours, ainsi qu'à l'instance de workflow et au jeton en cours. Avec les permissions dont il dispose, il peut modifier le document associé, le dossier ou les documents associés au dossier. Les permissions dont il dispose lui permettent également d'autoriser l'acheminement de l'instance de workflow vers une autre tâche. Il n'est pas autorisé à créer des documents ou des dossiers ni à exécuter des requêtes. Il n'est pas non plus autorisé à supprimer le dossier ou le document principal associé à l'instance de workflow, ni l'instance de workflow en tant que telle. •TheInstanceNo : numéro de l'instance de workflow en cours. •TheTokenNo : numéro de jeton de l'instance de workflow en cours. •TheCaseNo : numéro du dossier associé à l'instance de workflow. Ce paramètre est réservé aux workflows associés aux dossiers. •TheDocNo : numéro du document principal associé à l'instance de workflow. Ce paramètre est réservé aux workflows associés aux documents. •TheSettings : objet JSON (transmis sous forme de chaîne) de tous les « paramètres de fonction personnalisés » configurés.
Cet objet peut être vide ou utilisé pour transmettre d'autres paramètres à la fonction appelée. Vous pouvez sélectionner le nom et la valeur de votre choix pour chaque paramètre, mais les noms doivent être uniques conformément aux spécifications JSON. Toutes les valeurs sont traitées comme des valeurs de chaîne et doivent être converties dans un autre type au sein de la fonction, si besoin est.
La classe « TheReqParams » a été créée pour simplifier la lecture de ces paramètres depuis la chaîne JSON. Elle contient tous ces paramètres sous forme de propriétés et fournit la fonction « Deserialize » permettant de créer un objet depuis une chaîne JSON.
Vous pouvez utiliser le code de la classe « TheReqParams » à titre d'exemple pour vos paramètres personnalisés.
Supposons que vous avez assigné à « TaskNo » une valeur entière dans la configuration de la tâche de workflow en tant que « paramètre de fonction personnalisé ». Vous pouvez alors utiliser la classe suivante pour la lire.
class CustomSettings { public string taskNo; public int TaskNo { get { return int.Parse(taskNo); } set { taskNo = value.ToString(); } } public static CustomSettings Deserialize(string json) { return JsonConvert.DeserializeObject<CustomSettings>(json); } }
|
|---|
Comment spécifier un nom d'utilisateur et un mot de passe pour la connexion à Web API ?
Le code de l'exemple de projet vérifie principalement que le nom d'utilisateur et le mot de passe ont été spécifiés, et utilise le jeton d'accès fourni en tant solution de repli uniquement. La valeur par défaut correspond ainsi toujours au jeton, à moins que vous ne spécifiiez le nom d'utilisateur et le mot de passe. Ces coordonnées de connexion peuvent être nécessaires si les permissions requises dépassent les permissions fournies par le jeton.
TheConfig.cs utilise ConfigurationBuilder pour accéder à « local.settings.json » et aux variables d'environnement pour rechercher la configuration.
Si vous exécutez localement la fonction Azure, le paramètre est lu dans « local.settings.json ». Pour ajouter le paramètre, insérez les paramètres « WebAPIUser » et « WebAPIPassword » à l'objet JSON « Values » comme suit : { "IsEncrypted": false, "Values": { "AzureWebJobsStorage": "UseDevelopmentStorage=true", "FUNCTIONS_WORKER_RUNTIME": "dotnet", "WebAPIUser": "Domain\\TestUser1", "WebAPIPassword": "secretpassword" } }
Lorsque la fonction est déployée dans Azure, les paramètres sont lus dans Paramètres de l’application.
Pour ajouter le nom d'utilisateur et le mot de passe, sélectionnez Function App dans le portail Azure et cliquez sur « Paramètres de l’application ». Pour ajouter de nouveaux paramètres, cliquez sur « Nouveau paramètre d'application ». Une fois l'opération terminée, cliquez sur « Enregistrer ».
|
|---|
Les fonctions Azure peuvent être déployées sur la plateforme Microsoft Azure directement depuis Visual Studio.
Cliquez avec le bouton droit de la souris sur le projet et cliquez sur « Publier » pour publier votre fonction Azure.
Sélectionnez « Application Azure Function » pour la charger dans Azure directement depuis Visual Studio.
Si vous choisissez « Dossier », vous devez la charger manuellement à l'aide de FTP.
Le nom de l'application de fonction doit être unique à l'échelle globale, car le petit site Web « https://NomAppFonction.azurewebsites.net » créé est accessible publiquement, que la fonction soit déclenchée par HTTP ou non (le déclencheur HTTP utilise la même URL). Chaque application de fonction Azure doit disposer d'un compte de stockage, dans lequel sont stockés aussi bien les fonctions que les journaux. Vous disposez de deux options pour héberger une application de fonction :
•Plan Consommation
•Plan de service d'application
Une fois le déploiement terminé, l'appel de la fonction donne lieu à une erreur « 401 Non autorisé ».
Une clé de fonction est utilisée par défaut pour l'autorisation à fournir à chaque appel.
Vous obtenez cette clé de fonction sur le portail Azure.
Une fois l'application de fonction ouverte, cliquez sur « Manage (Gérer) » et copiez la clé « par défaut ».
Un appel issu de Therefore™ inclut la clé en tant que « x-functions-key » dans l'en-tête de la requête si elle est configurée.
Pour tester sans Therefore™ que le déploiement aboutit, utilisez cURL ou un programme similaire.
curl –d “” –i –X POST “https://AppName.azurwebsites.net/api/Route?code=FunctionKey”
Si aucun itinéraire n'est défini, le nom de la fonction est utilisé.
|
|---|
© 2024 Therefore Corporation, tous droits réservés.
