Utilisation de la nouvelle API REST de MOVEit 2018 avec PowerShell

La connexion à la console ou à l'interface Web de MOVEit fonctionne très bien pour les tâches de gestion au quotidien ou la configuration de workflows ponctuels. Toutefois, il est parfois nécessaire de recourir à l'automatisation avec MOVEit Automation!

Vous disposez peut-être d'un simple processus externe à MOVEit à partir duquel vous souhaitez déclencher une tâche de MOVEit  Automation. Ou peut-être MOVEit  Automation n'est-il que l'un des composants d'une orchestration beaucoup plus large d'étapes que vous devez accomplir. Dans tous les cas, une API est cruciale pour permettre d'invoquer à distance les fonctionnalités d'un produit, quel qu'il soit, sans avoir besoin d'une interface graphique utilisateur.

MOVEit  Automation a toujours intégré une API mais celle-ci n'a pas toujours été simple à utiliser. Cependant, avec MOVEit Automation 2018, nous sommes désormais en mesure d'utiliser une API REST moderne. Une API REST nous permet d'interagir avec MOVEit Automation via HTTP. Il n'y a pas de dépendances vis-à-vis du client, pour ainsi dire. Ceci signifie que, tant que nous pouvons rédiger du code dans le langage de notre choix, nous pouvons l'utiliser pour manipuler différentes choses dans MOVEit.

Dans cet article, nous allons nous concentrer sur l'utilisation de PowerShell avec l'API REST de MOVEit. Comme vous le verrez dans les prochains articles, PowerShell n'est pas obligatoire pour travailler avec l'API. Mais les professionnels de l'informatique qui souhaitent rédiger des scripts avec MOVEit Automation le choisissent souvent.

Pour comprendre comment utiliser PowerShell pour rédiger des scripts avec MOVEit Automation, vous devez d'abord comprendre les commandes PowerShell qui rendent tout cela possible. Ces commandes doivent être capables d'effectuer des requêtes HTTP avec différents verbes, tels que GET, POST, PUT, etc., que l'API de MOVEit peut comprendre.

PowerShell offre deux façons d'envoyer des requêtes HTTP : Invoke-RestMethod et Invoke-WebRequest. Ces deux commandes envoient des requêtes HTTP à l'API de la même façon. Toutefois, Invoke-RestMethod offre quelques fonctionnalités supplémentaires, comme l'analyse des résultats renvoyés par l'API REST. Les deux commandes conviennent ici. Mais si vous en êtes à vos débuts, il est probablement plus judicieux de vous en tenir à la commande Invoke-RestMethod. Il s'agit de la commande principale qui va coordonner toutes les activités depuis et vers l'API REST de MOVEit. Tout autre code n'est que préparation aux appels.

Mais assez de théorie, examinons un peu de code pour voir comment tout cela fonctionne !

Tout d'abord, c'est toujours une bonne idée de définir quelques attributs communs comme variables au début de votre script, puis d'y faire référence par la suite. Pour travailler avec l'API REST de MOVEit, vous devrez d'abord obtenir un jeton d'accès et utiliser celui-ci pour vous authentifier pendant toute la durée d'utilisation de l'API. Pour obtenir ce jeton d'accès, vous devez utiliser l'API Authorization Token. Cette API nécessite trois attributs : un nom d'utilisateur, un mot de passe et la méthode que vous allez authentifier.

Vous avez peut-être remarqué que j'ai mentionné le stockage de variables dans le script, mais qu'ensuite j'ai précisé qu'il fallait un mot de passe. Nous avons bien besoin d'un mot de passe et nous avons bien besoin d'y faire référence dans le script. En revanche, nous n'avons pas besoin de le stocker en texte normal. Pour contourner ceci, nous pouvons stocker des informations d'identification Powershell sur disque une fois, puis y faire référence autant de fois que nous le souhaitons.

Automatisez vos flux de travail sans devoir recourir à des scripts. Testez MOVEit Automation

Dans un premier temps, enregistrez votre nom d'utilisateur et votre mot de passe MOVEit sur disque. Ceci, vous ne devrez le faire qu'une seule fois. Ceci n'apparaîtra pas dans votre script.

PS> Get-Credential | Export-CliXml -Path 'C:\MOVEitAutomationCred.xml'

Une fois que vous fournissez le nom d'utilisateur et le mot de passe, tous deux seront sauvegardés sur disque. Nous avons maintenant un moyen d'y faire référence via notre script.

Ensuite, démarrons le script. Pour démarrer, je vais d'abord devoir déchiffrer le nom d'utilisateur et le mot de passe. Ensuite, je vais créer une table de hachage d'attributs afin de les stocker avec les autres attributs dont je vais avoir besoin.

PS> $cred = Import-CliXml -Path 'C:\MOVEitAutomationCred.xml'
 PS> $apiConfig = @{
 >>>    UserName = $cred.UserName
 >>>    Password = $cred.GetNetworkCredential().Password
 >>>    GrantType = 'password'
 >>>    MoveItHost = ''
 >>> }

À partir des attributs de notre table de hachage, nous pouvons alors déduire tous les autres composants dont nous avons besoin. D'abord, je crois créer l'URL appropriée pour le point de terminaison HTTP afin d'obtenir mon jeton d'accès.

PS> $authEndpointUrl = "https://$($apiConfig.MoveItHost)/webadmin/api/v1/token"
 PS> $authHttpBody = "grant_type=$($apiConfig.GrantType)&username=$($apiConfig.UserName)&password=$($apiConfig.Password)"

Après avoir créé tous les attributs, je peux maintenant effectuer mon premier appel de l'API MOVEit afin de recevoir mon jeton d'accès. Toutefois, avant de faire cela, je dois « duper » PowerShell afin qu'il interagisse avec mon API de démo, étant donné qu'il utilise un certificat auto-signé.

Comme l'API d'Automation dispose d'un cryptage SSL avec certificat, il est nécessaire d'utiliser une URL HTTPS. Cependant, dans certaines instances (mon environnement de démo), le certificat de mon serveur MOVEit Automation 2018 est auto-signé. Ceci signifie que mon client (PowerShell) ne lui fait pas confiance. Dans un environnement de production, ceci ne posera probablement pas de problème. Dans tous les cas, pour démontrer que je travaille avec l'API REST de MOVEit, je dois utiliser une ruse .NET.

PS> [System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $true }

Après avoir autorisé l'utilisation d'un certificat auto-signé, je peux réaliser mon premier appel à l'API d'authentification afin d'obtenir mon jeton d'accès. Vous pouvez voir que j'utilise la méthode HTTP POST au-dessous pour envoyer une requête POST au point de terminaison.

PS> $token = Invoke-RestMethod  -Uri $authEndpointUrl -Method 'POST' -Body $authHttpBody
 PS> $token = $token.access_token

À ce stade, nous disposons d'un jeton d'accès et pouvons faire appel à toutes les API de notre choix. Nous devons juste nous souvenir de toujours inclure le jeton d'accès dans tous les appels d'API, sinon il ne saura pas qui nous sommes. Ce jeton d'accès doit être transmis sous forme d'en-tête HTTP. Un moyen simple de s'en assurer est de créer une table de hachage avec le paramètre Headers dont Invoke-RestMethod aura besoin et de transmettre ceci à chaque référence en utilisant le « splatting ».

PS> $authParam = @{
 >>>    Headers = @{ 'Authorization' = "Bearer $token" }
 >>> }

Maintenant que nous avons créé le paramètre à transmettre à Invoke-RestMethod, en guise de démonstration, je vais juste récupérer toutes les tâches dans MOVEit  Automation. Cette API comporte un point de terminaison spécifique et une méthode HTTP (comme ce sera le cas de toutes les API). Je vais donc les indiquer avec Invoke-RestMethod directement et assigner le paramètre d'autorisation par « splatting ».

PS> $tasks = Invoke-RestMethod @authParam -Uri "https://$($apiConfig.MoveItHost)/webadmin/api/v1/tasks" -Method GET
 PS> $tasks
 paging                                                    sorting                                items
 ------                                                    -------                                -----
 @{page=1; perPage=2147483647; totalItems=3; totalPages=1} {@{sortField=Name; sortDirection=asc}} {@{Group=System.Object[]; I...

À présent, toutes les tâches sont stockées dans la propriété des éléments. Si vous souhaitez visualiser le résultat en JSON, vous pouvez convertir les objets en JSON au moyen de la commande ConvertTo-Json.

PS> $tasks | ConvertTo-Json
 {
     "paging":  {
                    "page":  1,
                    "perPage":  2147483647,
                    "totalItems":  3,
                    "totalPages":  1
                },
     "sorting":  [
                     {
                         "sortField":  "Name",
                         "sortDirection":  "asc"
                     }
                 ],
     "items":  [
                   {
                       "Group":  "",
                       "ID":  "222223",
                       "Name":  "Tamper Check",
                       "Info":  "@{Description=\n\t\t\t\t; Notes=\n\t\t\t\t}",
                       "Parameters":  "",
                       "Schedules":  "@{Schedule=System.Object[]}",
                       "steps":  "",
                       "Active":  1,
                       "CacheNames":  "random",
                       "NextEID":  15
                   }
     ]
 }

Nous avons abordé ici les bases de l'utilisation de l'API REST de MOVEit. Vous devez toujours obtenir un jeton d'accès et fournir ce jeton pour chaque appel d'API. Dans les prochains articles, nous verrons différents scénarios utilisant ces nouvelles connaissances.