Orchestrator API PowerShell サンプルスクリプト[v2020.10 対応版]

概要

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

オンプレミスOrchestrator v2021.4以降およびAutomation Cloudではアクセスをトークン取得するために外部アプリケーション機能を使用してください。詳細は次のサイトをご参照ください: https://www.uipath.com/ja/community-blog/knowledge-base/implementing-orchestrator-api-with-oauth

免責

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

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

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

前提条件

Orchestrator 環境/バージョンが下記のいずれか

• オンプレミス Orchestrator v2018.4, v2019.10 または v2020.10 (オンプレミスまたはクラウド環境において自前でインストールされたOrchestrator)

PowerShell 4.0 以上

• PowerShell のバージョンを確認するには、PowerShell コンソールにて $host とタイプして、Version が 4.0 以上であることを確認します。

• PowerShell 3.0 以下の場合には、WMF (Windows Management Framework) 4.0 以上をインストールします。

Orchestrator v2020.10における注意点

• スクリプト実行用に新しい管理ユーザーを作成する際には、次の既知問題に注意してください: https://docs.uipath.com/ja/orchestrator/standalone/2020.10/installation-guide/identity-server-troubleshooting#%2Fapi%2Faccount%2Fauthenticate-calls-failing-for-users-who-changed-passwords-at-first-login

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

ファイル名

• Orchestratorバージョンがv2018.4: orchestrator-schedule-v18.ps1

• Orchestratorバージョンがv2019.10以降: orchestrator-schedule.ps1

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

オンプレミスでの実行手順

• API を実行する Orchestrator 管理ユーザーを準備します。必要なロールは、トリガー(スケジュール) に対する閲覧および編集権限です。

• Orchestrator v2019.10以降ではスケジュール (トリガー) が定義されているフォルダーへのアクセス権も必要となります。

• 下記のコマンドでスケジュールを無効化します。 .\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バージョンがv2018.4: orchestrator-job-v18.ps1

• Orchestratorバージョンがv2019.10以降: orchestrator-job.ps1

このスクリプトでは、プロセスを手動実行します。

外部システムによってバッチファイルとして起動し、Orchestrator API を経由してロボットでプロセスを手動実行する場合に役立ちます。

またプロセスの実行結果を戻り値として受け取り、次に実行するプロセスを決定することも可能です。

実行手順

まずは API を実行する Orchestrator 管理ユーザーを準備します。必要なロールは下記の通りです。

• プロセスに対する閲覧権限

• ジョブに対する閲覧および作成権限

• ユニットまたは フォルダーに対する閲覧権限 (v2018.4で組織単位を使用していない場合は不要)

下記のコマンドでプロセス実行をインタラクティブに行います。

.\orchestrator-job.ps1 -uriOrch "https://your-orchestrator-url" -adminName "job-admin" -adminPasswd "password" 

• 最初に管理ユーザーに参照権限がある組織単位(クラシックフォルダー) 一覧が表示されますので、プロンプトで実行するユニット/フォルダーID (先頭の [ ] で囲まれた数字) を指定します。

• 管理ユーザーに参照権限があるプロセス一覧が表示されますので、プロンプトで実行するプロセス ID (先頭の [ ] で囲まれた数字) を指定します。

• プロセス開始後、一定間隔でプロセスの実行状態をチェックし、プロセスが終了または中断した場合、あるいは状態チェックが一定回数超えた場合にスクリプト実行が終了します。

• 状態チェックの間隔は -interval オプション (既定値は3秒)、チェック回数は -retry オプション (既定値では20回) で指定します。

• 初回実行でプロセス ID が確認できますので、2回目以降は -id オプションを指定してバッチモードで実行することができます。

• 次のコマンド実行例では、フォルダーID1におけるプロセス ID 12345 を実行し 30秒ごとの状態チェックを 60回繰り返します。(v2018.4では -folderの代わりに -unit を使用し、ユニットIDを指定します) .\orchestrator-job.ps1 -uriOrch "https://your-orchestrator-url" -adminName "job-admin" -adminPasswd "password" -folder 1 -id 12345 -interval 30 -retry 60
• 外部システムと連携するには次のバッチファイルを準備します。 @echo off powershell "C:\Scripts\orchestrator-job.ps1" -uriOrch "https://your-orchestrator-url" -adminName "job-admin" -adminPasswd "password" -folder 1 -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/authenticate" $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権限を持つ必要があります。

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