ナレッジベース

Orchestrator API PowerShell サンプルスクリプト

概要

本記事では Powershell スクリプトにて Orchestrator API を呼び出す実用例を紹介します。

免責

本記事に掲載したスクリプトは Orchestrator API の使用方法をご理解いただくためのサンプルであるため、お客様の実環境での動作を保証するものではありません。

あくまでもお客様ご自身で Orchestrator API を使用したスクリプトを実装していただき、検証環境にて十分テストを行った上で実環境へ適用していただきますようお願いいたします。

またスクリプトの内容について弊社テクニカルサポートにお問い合わせいただいてもお答えできない場合がありますので、あらかじめご了承ください。

前提条件

PowerShell 3.0 以上
PowerShell のバージョンを確認するには、PowerShell コンソールにて

$host 

とタイプして、Version が 3.0 以上であることを確認します。
PowerShell 2.0 以下の場合には、WMF (Windows Management Framework) 3.0 以上をインストールします。

 

実用例 1 (プロセススケジュールの一括無効化/有効化)

 

  • ファイル名: orchestrator-schedule.ps1
  • このスクリプトでは、Orchestrator で設定されているプロセススケジュールを一括して無効化または有効化します。
    Orchestrator のメンテナンス時などに、スケジュールによるプロセス実行を抑止したい時に役立ちます。

実行手順

  • API を実行する Orchestrator 管理ユーザーを準備します。必要なロールは Schedules に対する View および Edit 権限です。
  • 下記のコマンドでスケジュールを無効化します。
.\orchestrator-schedule.ps1 -disable -uriOrch "https://your-orchestrator-url" -adminName "schedule-admin" -adminPasswd "password"

 

  • 同じディレクトリにデバッグログと、スケジュール一覧が CSV ファイルで出力され、スケジュールがすべて無効化されます。
  • 下記のコマンドでスケジュールを有効化します。上記手順で作成された CSV を読み込み、最初の状態に戻します。
.\orchestrator-schedule.ps1 -enable -uriOrch "https://your-orchestrator-url" -adminName "schedule-admin" -adminPasswd "password"

 

実用例 2 (プロセス手動実行)

  • ファイル名: orchestrator-job.ps1
  • このスクリプトでは、プロセスを手動実行します。
  • 外部システムによってバッチファイルとして起動し、Orchestrator API を経由してロボットでプロセスを手動実行する場合に役立ちます。
  • またプロセスの実行結果を戻り値として受け取り、次に実行するプロセスを決定することも可能です。

 

実行手順

  • まずは API を実行する Orchestrator 管理ユーザーを準備します。必要なロールは Processes に対する View と Jobs に対する View および Create 権限です。
  • 下記のコマンドでプロセス実行をインタラクティブに行います。
.\orchestrator-job.ps1 -uriOrch "https://your-orchestrator-url" -adminName "job-admin" -adminPasswd "password"

 

  • 管理ユーザーに参照権限があるプロセス一覧が表示されますので、プロンプトで実行するプロセス ID (先頭の [ ] で囲まれた数字) を指定します。
  • プロセス開始後、一定間隔でプロセスの実行状態をチェックし、プロセスが終了または中断した場合、あるいは状態チェックが一定回数超えた場合にスクリプト実行が終了します。
  • 状態チェックの間隔は -interval オプション (既定値は3秒)、チェック回数は -retry オプション (既定値では20回) で指定します。
  • 初回実行でプロセス ID が確認できますので、2回目以降は -id オプションを指定してバッチモードで実行することができます。
  • 次のコマンド実行例では、プロセス ID 12345 を実行し 30秒ごとの状態チェックを 60回繰り返します。
.\orchestrator-job.ps1 -uriOrch "https://your-orchestrator-url" -adminName "job-admin" -adminPasswd "password" -id 12345 -interval 30 -retry 60

 

  • 外部システムと連携するには次のバッチファイルを準備します。
@echo off
powershell "C:\Scripts\orchestrator-job.ps1" -uriOrch "https://your-orchestrator-url" -adminName "job-admin" -adminPasswd "password" -id 12345 -interval 30 -retry 60

 

  • C:\Scripts は PowerShell スクリプトが配置されているディレクトリです。引数は適宜変更します。
  • プロセス実行が成功した場合は戻り値として 0、失敗または中断した場合は 1 が返されます。
  • 戻り値は環境変数 %errorlevel% にて取得することができます。

 

ログイン処理の解説

  • スクリプトを使用したOrchestrator へのログイン方法について解説します。
  • テナント名 (既定値: default)、管理ユーザー名、管理ユーザーパスワードを JSON 形式でリクエストボディとして作成します。
$bodyAccount = @{
"tenancyName" = $tenantName
"usernameOrEmailAddress" = $adminName
"password" = $adminPasswd
} | ConvertTo-Json
  • 日本語を正しく処理するために文字コードはUTF-8を指定します。
$contentType = "application/json;charset=utf-8"
  • 次に Orchestrator へのログインを行う API を POST で呼び出します。
$uriAccount = "$uriOrch/api/Account"
$resAccount = Invoke-RestMethod -Uri $uriAccount -Method Post -Body $bodyAccount -ContentType $contentType

 

  • $resAccount.success の値として True が返された場合はログイン成功です。
  • その場合、$resAccount.result に認証キーが返されますので Authorization ヘッダーに "Bearer <認証キー>" を埋め込んで、以降の API を実行します。
$authKey = $resAccount.result
$headers = @{"Authorization"="Bearer $authKey"}
  • たとえば Robot 一覧を取得するには、下記のように実行します。
$resRobots = Invoke-RestMethod -Uri "$uriOrch/odata/Robots" -Method Get -ContentType $contentType -Headers $headers
$resRobots.value | foreach {$_.Name}

管理ユーザーは Robot に対して View 権限を持つ必要があります。

※サンプルのファイルはこちらよりダウンロードください。