【UiPath】Automation Cloudのプラットフォーム管理API (Platform Management API) を使ってみる

はじめに

• 本記事は、2023年4月時点の内容となります。今後の仕様変更等で動作が変わっている場合がある点、ご了承ください。
• 現時点ではプラットフォーム管理APIはプレビュー機能とされているので、今後仕様変更される可能性があります。

UiPath Automation Cloud とは

Automation Cloudは、UiPath社が提供している、クラウドベースのSaaS（Software as a Service）ソリューションです。Automation Cloudを利用することで、運用管理者は個別のプロダクトをオンプレミス環境に構築・維持するための手間から解放され、ロボットを管理するOrchestratorをはじめとした各種製品を、利用したいときに利用開始できます。Automation Cloudはコミュニティプランのユーザー、エンタープライズのユーザーそれぞれに対応しています。

Automation Cloudには無料のトライアルもあるので、詳しく知りたい方は公式サイトを確認しましょう。

プラットフォーム管理サービスとOrchestratorサービスの違い

Orchestratorをオンプレミス環境で使用している方は、Orchestrator上でユーザーやロボットアカウントを直接作成・管理していると思います。
Automation Cloudでは、まず最初にプラットフォーム管理サービス上でユーザーやロボットアカウントを登録し、次にOrchestratorなどの各UiPath製品で権限（ロール）を割り当てて利用します。こうすることで、各UiPath製品ごとにユーザーを管理する手間が解消し効率的な運用が可能になっています。
Orchestratorサービスを操作するAPIは、プラットフォーム管理APIとは異なります。Automation CloudのOrchestrator APIについてはこちらの公式ガイドに記載があります。

Automation Cloudのプラットフォーム管理APIとは

Automation Cloudを利用すると、運用管理者はおそらく日常的に以下例のような運用をすることになります。

• 利用者を登録する
• それぞれの利用者ごとにアクセスできる製品を制御したり、ライセンスを付与するためのグループを作成し、ユーザーを割り当てたり外したりする
• Automation Cloudの監査ログを取得して誰が・いつ・どのような操作を行ったか確認する
• 組織の設定を変更する

これらの作業は、すべてブラウザでAutomation Cloudにアクセスすれば、ポータル画面から実施することができます。ただし、大規模利用になってくると、これらの作業も自動化して行いたいニーズが出てきます。プラットフォーム管理APIは、Automation Cloudの共通管理部分を操作するAPIを提供しています。

使い方を確認してみる

プラットフォーム管理APIに関しては、以下公式ガイドに使い方が記載されています。
また、Swaggerにアクセスすることでより詳細を知ることができます。
https://cloud.uipath.com/組織名/identity_/swagger/index.html

事前に控えておくべき設定

確認しておく事項	確認方法
ベースURL	https://cloud.uipath.com/組織名/ （利用したいリソースによってベースURLが微妙に変わることがあるため、公式ガイドで確認する）
利用したいリソースリスト	アクセスしたいリソースのAPIのエンドポイント。公式ガイドから確認する
スコープ	アクセスしたいリソースに対して必要な権限。公式ガイドから確認する

ベースURLは以下のように、Automation Cloudの「管理」⇒「設定」から「URL」を見ることで確認も可能です。

また、プラットフォーム管理APIを利用する際に「partitionGlobalId」という値が必要になる場合があります。この値はAutomation Cloud画面から確認することができず、ブラウザの開発者ツールを開いてみる必要があります。こちらのUiPathフォーラムの記事に取得方法が記載されているのでご確認ください。

UiPath Studioでプラットフォーム管理APIを利用してみる

せっかく使い方を確認したので、UiPath Studioでプラットフォーム管理APIを利用して処理してみたいと思います。今回試すのは 「ロボットアカウントの取得」 とします。必要なスコープは 「PM.RobotAccount.Read」 です。

ちなみにロボットアカウントの情報は、ブラウザからは以下のように参照できます。下記の例だと、Robot01、Robot02、Robot03という３つのアカウントが作られています。

1. Automation Cloud側の作業

まず、Automation Cloud側で、外部アプリケーションを登録する作業を行います。

• Automation Cloudの「管理」⇒「外部アプリケーション」で「アプリケーションを追加」をクリックします。
  

• 「アプリケーション名」に任意の名前（GetRobotAccount）を設定し、「アプリケーションの種類」を機密アプリケーションとします。「スコープを追加」をクリックします。
  

• 「リソース」は、Platform Management API Accessを選びます。「アプリケーションスコープ」を選択し、必要なPM.RobotAccount.Read にチェックを入れ、保存します。（セキュリティ面を考慮し、なるべく必要なスコープだけに絞ります）
  
  

• 追加ボタンをクリックします。（リダイレクトURLは空のままで良いです）追加すると、アプリIDとアプリシークレットがポップアップ表示されます。アプリシークレットは再表示できないため、必ずテキストで控えておきます。
  
  

今回のトライでは、アプリIDとアプリシークレットをWindowsの資格情報マネージャーに保存しておこうと思います。コントロールパネルから資格情報マネージャーを開き、「汎用資格情報の追加」を行います。インターネットまたはネットワークのアドレスにGetRobotAccount、ユーザー名にアプリID、パスワードにアプリシークレットを入力しておきます。

2. Studio側の実装

Studioを開いて新しいプロジェクトを作成しました。パッケージ管理から、「UiPath.WebAPI.Activities」「UiPath.Credentials.Activities」をインストールしておきます。
大まかなフローとしては、以下をイメージしています。

1. アプリID/アプリシークレットを資格情報マネージャから取得
2. Automation Cloudと認証処理を行い応答を取得
3. 応答からトークンを取得
4. トークンを使ってロボットアカウントのリストを取得
5. 存在しているロボットアカウント名を表示

※トライのため、エラー処理の説明は割愛します

アプリID/アプリシークレットを資格情報マネージャから取得

• Get Secure Credentialsアクティビティを使ってみます。先ほど資格情報マネージャーに登録した名前をターゲットに設定し、ユーザー名（アプリID）、パスワード（アプリシークレット）を取得します
  

Automation Cloudと認証処理を行い応答を取得

• HTTP Requestアクティビティを使ってみます。最低限設定が必要な個所は赤枠の部分です

プロパティ名	値
本文形式	application/x-www-form-urlencoded
要求URL	https://cloud.uipath.com/identity_/connect/token
要求メソッド	POST
応答コンテンツ	String型で受けとれるように設定します
パラメーター	grant_type、client_id、client_secret、scopeを定義します（下の設定例を参照）

応答からトークンを取得

• Deserialize Jsonアクティビティを使用します。得られた応答をJsonにします
  
• Jsonにしたデータから、access_tokenを取り出してトークンにします
  

トークンを使ってロボットアカウントのリストを取得

• http requestアクティビティで、取得したトークンを付与してロボットアカウントのリストを受け取ります。最低限設定が必要な個所は赤枠の部分です

• プロパティの設定に必要な値は以下です。「ベースURL」と「partitionGlobalId」は、事前に控えておくべき設定で確認した値を使います

プロパティ名	値
OAuth2トークン	認証の処理で取得したトークン
本文形式	application/json
要求URL	ベースURL/portal_/api/identity/RobotAccount/確認しておいたpartitionGlobalId
要求メソッド	GET
応答コンテンツ	String型で受けとれるように設定します

存在しているロボットアカウント名を表示

• 応答コンテンツからnameを取得して、Write LineアクティビティでStudioの出力に表示させます。

応答コンテンツで得られる結果はString型ですが、Json形式で書かれています。Deserialize Jsonなどを使って逆シリアル化しておくと後で処理しやすくなると思います。

実行結果

Studio側で実装して取得した結果、以下のように、ロボットアカウント名が取得できました。

まとめ

• プラットフォーム管理APIを使って、Automation Cloudの「管理」から実施する操作の一部を自動化できました
• プラットフォームAPIを使うための流れが理解できました

現在はプレビューですが、Automation Cloud運用手法の1つの可能性として、今後の正式リリースに期待したい機能だと思います。