トライアルの開始

2020年6月4日

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

4 6月 2020

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

概要

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

免責

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

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

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

 

前提条件

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

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

 ・Cloud Orchestrator (https://platform.uipath.com, https://cloud.uipath.com など UiPath社が提供するSaaS型サービスであり、常に最新版に自動バージョンアップされる)

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

$host 

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

・Orchestrator v2020.4における注意点

 ・スクリプト実行用に新しい管理ユーザーを作成する際には、次の既知問題に注意してください:https://docs.uipath.com/orchestrator/lang-ja/docs/identity-server-troubleshooting#section-api-account-authenticate-calls-failing-for-users-who-changed-passwords-at-first-login

 

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

 

・ファイル名

 ・Orchestratorバージョンがv2018.4:orchestrator-schedule-v18.ps1
 ・Orchestratorバージョンがv2019.10以降またはCloud Orchestrator: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"

 

Cloud Orchestrator での実行手順

・オンプレミスと実行手順は同様ですが、管理ユーザーを指定するパラメーター adminName / adminPasswd の代わりに userKey / accountLogicalName / tenantLogicalName / clientId を使用します。

.\orchestrator-schedule.ps1 -disable -uriOrch "https://cloud.uipath.com" -userKey "abcde_123456789012345678901234567890123456789" -accountLogicalName "MyAccount" -tenantLogicalName "MyTenant" -clientId "12345678901234567890123456789012"

.\orchestrator-schedule.ps1 -enable -uriOrch "https://cloud.uipath.com" -userKey "abcde_123456789012345678901234567890123456789" -accountLogicalName "MyAccount" -tenantLogicalName "MyTenant" -clientId "12345678901234567890123456789012"

・これら4つの値を取得するには次のサイトをご参照ください: https://docs.uipath.com/orchestrator/lang-ja/reference/consuming-cloud-api

 

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

  • ・ファイル名
  •  ・Orchestratorバージョンがv2018.4:orchestrator-job-v18.ps1
  •  ・Orchestratorバージョンがv2019.10以降 または Cloud Orchestrator: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% にて取得することができます。

 

Cloud Orchestratorでの実行例

・実用例1と同様、オンプレミスと実行手順は同様ですが、管理ユーザーを指定するパラメーター adminName / adminPasswd の代わりに userKey / accountLogicalName / tenantLogicalName / clientId を使用します。

.\orchestrator-job.ps1 -uriOrch "https://cloud.uipath.com" -userKey "abcde_123456789012345678901234567890123456789" -accountLogicalName "MyAccount" -tenantLogicalName "MyTenant" -clientId "12345678901234567890123456789012"

.\orchestrator-job.ps1 -uriOrch "https://cloud.uipath.com" -userKey "abcde_123456789012345678901234567890123456789" -accountLogicalName "MyAccount" -tenantLogicalName "MyTenant" -clientId "12345678901234567890123456789012" -unit 1 -id 12345 -interval 30 -retry 60

 

・これら4つの値を取得するには次のサイトをご参照ください: https://docs.uipath.com/orchestrator/lang-ja/reference/consuming-cloud-api

 

オンプレミスでのログイン処理の解説

  • ・スクリプトを使用した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権限を持つ必要があります。

Cloud Orchestratorでのログイン処理の解説

・スクリプトを使用したCloud Orchestrator へのログイン方法について解説します。

・Orchestrator ベース URL に Account Logical Name と Tenant Logical Name を含めます。

$uriOrch += "/$accountLogicalName/$tenantLogicalName"

 

・Use Key および Client IDを JSON 形式でリクエストボディとして作成します。

$bodyAccount = @{
"grant_type" = "refresh_token"
"client_id" = $clientId
"refresh_token" = $userKey
} | ConvertTo-Json

 

・Cloud Orchestrator へのログインを行う API を POST で呼び出します。

$uriAccount = "https://account.uipath.com/oauth/token"
$resAccount = Invoke-RestMethod -Uri $uriAccount -Method Post -Body $bodyAccount -ContentType $contentType

 

$resAccount.access_token の値として認証キーが返された場合はログイン成功です。

X-UIPATH-TenantNameヘッダーに Tenant Logical Name、Authorizationヘッダーに"Bearer 認証キー"を埋め込んで、以降の API を実行します。

$authKey = $resAccount.access_token
$headers = @{"X-UIPATH-TenantName" = $tenantLogicalName; "Authorization"="Bearer $authKey"}

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

 


by Japan KB team

Show sidebar