MOVEit 2018 の REST API で PowerShell を使う

MOVEit の利用形態として、MOVEit コンソールや Web インタフェースからログインして日々の管理業務を行ったり、１回限りのワークフローを設定して操作する作業は理にかなっており、首尾よくいきます。一方、MOVEit Automation の自動化を活用したいケースもあります。

MOVEit Automation のタスクをトリガーするのに、MOVEit の外部にある簡単なプロセスを使いたい場合が考えられます。あるいは、もっと大規模なオーケストレーションの１つのコンポーネントとして、MOVEit Automation を使うことも可能です。どちらの場合でも、GUI インタフェースを必要とすることなく、製品の機能をリモートで呼び出せるようにするには、API が重要になります。

これまでの MOVEit Automation の API は、必ずしも使いやすいとは言えないところがありましたが、新しい MOVEit Automation 2018 では REST API を使用できるようになりました。 REST API を使用すると、HTTP 経由で MOVEit Automation とやりとりすることができます。つまり、言語に依存することなく好きな言語でコードを書いて、MOVEit でさまざまな操作を行うことができます。

このブログでは、MOVEit の REST API で PowerShell を使用する方法を説明します。API を利用するのに PowerShell が必須というわけではありませんが、MOVEit Automation に使えるスクリプトを作成したいIT管理者にとっては PowerShell が普通に考えられる選択でしょう。

PowerShell を使用して MOVEit Automation にスクリプトを書き込む方法を理解するには、まず PowerShell コマンドを理解する必要があります。

コマンドは、MOVEit の API で解析できる GET、POST、PUT などの異なる動詞を使用して HTTP リクエストを作成できる必要があります。PowerShell で HTTP リクエストを送信するには、2つの方法があります。Invoke-RestMethod と Invoke-WebRequest です。どちらも同じ方法で API に HTTP リクエストを送信しますが、Invoke-RestMethod には REST API が返すアウトプットを解析するといった追加機能があります。まだ始めたばかりだったり、特にこだわりがなければ、Invoke-RestMethod を使うようにした方がいいでしょう。このコマンドは、MOVEit の REST API との間のすべてのアクティビティを処理できる主要コマンドであり、他のコードは呼び出しへの準備をするだけです。

理論的な話はこれぐらいにして、これがどのように機能するか具体的にコードを見てみましょう。

はじめに、スクリプトの先頭に共通の属性を変数として設定し、全体を通してそれを参照するようにすることを推奨します。MOVEit の REST API で操作するには、最初にアクセストークンを取得し、API での作業中はずっと、認証のためにそのアクセストークンを使用することになります。アクセストークンを取得するには、Authorization Token API を使用する必要があります。この API には、ユーザー名、パスワード、認証用メソッドの3つの属性が必要です。

スクリプトに変数を格納することを推奨しましたが、上述のようにパスワードも必要です。パスワードは、スクリプト内で参照する必要がありますが、プレーンテキストで保存する必要はありません。PowerShell 資格情報をディスクに一度格納してから、何度でも参照することができます。

まず、MOVEit のユーザー名とパスワードをディスクに保存します。これは一度だけの操作で、スクリプトには含まれません。

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

ユーザー名とパスワードを入力すると、両方がディスクに保存されます。スクリプトでこれを参照することができます。

では、スクリプトにとりかかりましょう。まず、ユーザー名とパスワードを復号化する必要があります。その上で、必要な他の属性とともにそれらを格納するための属性のハッシュテーブルを作成します。

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

まず、アクセストークン取得用の HTTP エンドポイント URL を作成します。ハッシュテーブルの属性で、必要なコンポーネントがわかるようにします。

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

すべての属性を作成したら、アクセストークンを受け取るために MOVEit API への最初の呼び出しを行います。しかし、ここでは自己署名の証明書を使用しているので、デモ API とやりとりするために、その前にちょっとした「トリック」を PowerShell に対して行う必要があります。

MOVEit Automation の API は証明書つきで SSL 暗号化されているため、HTTPS URL を使用する必要があります。しかし、場合によっては（ここで使うデモ環境など）、MOVEit Automation 2018 サーバーの証明書が自己署名されているものもあります。クライアント（PowerShell）は自己署名の証明書を信用しません。実稼働環境では、これはおそらく問題にはなりませんが、MOVEit の REST API での操作をデモするために、.NETのトリックを使用します。

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

自己署名の証明書の使用を許可したら、アクセストークンを受け取るために認証 API への最初の呼び出しを行います。HTTP POST メソッドを使用して、エンドポイントに POST リクエストを送信しているのが確認できると思います。

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

アクセストークンが獲得できたので、どんな API でも呼び出すことができます。すべての API 呼び出しに常にアクセストークンを含めることを忘れないようにしてください。そうしないと、誰が呼び出しているのか認知されません。このアクセストークンは、HTTP ヘッダーとして渡す必要があります。これを確実に行う簡単な方法は、Invoke-RestMethod が必要とする Headers パラメータがあるハッシュテーブルを作成し、スプラッティングで各リファレンスに渡すことです。

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

デモ用として Invoke-RestMethod に渡すためのパラメータを作成したので、MOVEit Automation にすべてのタスクをプルします。この API には（すべての API と同様）特定のエンドポイントと HTTP メソッドがあるので、Invoke-RestMethod で直接指定し、スプラッティングで認証パラメータを割り当てます。

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...

この時点で、すべてのタスクは items プロパティに格納されます。JSON で出力を確認したい場合は、ConvertTo-Json コマンドを使用してオブジェクトを 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
                   }
     ]
 }

ここで取り上げたのは、MOVEit REST API を使用するための基本です。常にアクセストークンを取得し、すべての API 呼び出しでそのトークンを提供する必要があります。