Orchestrator API の自動化

今回の記事はロボットにREST APIを実行させる方法をご紹介します。

簡単に実現できる上に一度覚えてしまえば色々と応用が効いて自動化できる幅がグッと広がります。

本記事では、トークンの取得やID/パスワードの指定をHTTPパラメータの一部として直接的に取得／指定する方法を解説します。

接続するシステムによってはOAuth1、OAuth2、簡易認証、といったActivityに備え付けの認証機能も利用できる可能性がありますので、是非合わせてお試しください。

サンプルとしては、せっかくですのでOrchestratorの各種操作をAPI経由で実行してみたいと思います。 ロボットからOrchestratorのAPIを呼び出すための専用のActivityはいくつか用意されていますが、今回はそういったActivityが用意されていないAPIを呼び出します。

※注：Orchestrator 20.10より認証用のベアラートークン取得のAPIがJSON形式のみ受け付けるように変更されています。 以前の記事ではパラメータプロパティを使った方法をご紹介していましたが、この方法は20.10から使えなくなっているのでご注意ください。 本記事では20.10、またそれ以前のOrchestratorで動作するJSON形式のAPI呼び出しに更新しています。

※注：ロボットの権限で実行できるAPIであれば「OrchestratorへのHTTPリクエスト」を利用することができます。 アセット、キュー、ジョブ、プロセスなどに関する処理を行うActivityもそれぞれ用意されています。

※注：SOAPやSwaggerベースのWebサービスと連携する場合は、より簡単にワークフローを開発することができます。詳細についてはこちらの記事をご覧ください。 https://forum.uipath.com/t/featureblog-19-4-soap-swagger-web/174925

本記事はOrchestrator 2019.4.3と2020.10.2を元に執筆しておりますので最新のバージョンにおいて内容が異なる可能性があります。あらかじめご了承ください。 Orchestrator APIの最新の仕様については以下を参照してください。 https://docs.uipath.com/orchestrator/lang-ja/reference#api-references

ベアラートークンの取得：

Orchestrator APIの認証システムは、ベアラートークンを使用します。 他のAPIを呼び出すために必要なので、まずは「HTTP要求」Activityを使ってトークンを取得しましょう。

※注：「HTTP要求」Activityを利用するためには、UiPath.Web.Activitiesパッケージのインストールが必要です。 必要に応じて「パッケージを管理」機能からインストールしてください。

今回はシンプルに行きたいので、必要最低限なパラメータだけ埋めます。事前に必要な情報は、テナント名とOrchestratorユーザのIDとパスワードです。 「HTTP要求」Activityのプロパティのうち赤枠で囲んだ箇所に必要な情報を入力していきます。

・本文

下記の図のように本文パラメータにJSON形式で、tenancyName、usernameOrEmailAddress、passwordのバリューを指定します。 図ではテキストで直接書き込んでいるため、ダブルクオーテーションのエスケープが必要です。 今回はパラメータが少ないので直接テキストで指定していますが、情報量が多いJSONテキストを作る際、私は普段以下のように一旦Dictionary型で作成してからJSONへSerializeしています。 ※ なお、文字列処理は人によって好みが分かれるところだと思いますので、ご参考までに留めてください。

1. Microsoft.Activities.Extensions.Statements.AddToDictionaryアクティビティでKeyとValueをDictionary型の変数に追加

2. Newtonsoft.Json.JsonConvert.SerializeObject([Dictionaryの変数名])を使ってJSON形式のString型へ変換

なお、tenancyName（＝テナント名）と usernameOrEmailAddress（＝ユーザID）は設定ファイルから読み込むようにしておくと何かと融通が効くので、ユーザビリティの観点からお勧めです。 passwordについては現場のセキュリティポリシーに依るので一概には言えませんが、設定ファイル等への保存が難しい場合は、例えば「入力ダイアログ」Activityで稼働のたびに利用者に入力してもらう方法も考えられます。 その際はプロパティ「パスワード入力」を有効にすることをお忘れなく。

・本文形式

本文のフォーマットに合わせて、application/jsonを指定します。

・エンドポイント、メソッド、応答形式

エンドポイントにはOrchestrator APIのURLを指定します。例示のままでは使えないので、[Orchestratorのホスト名]の部分を環境に合ったホスト名に入れ替えてください。

・出力

状態コードはレスポンスのHTTPステータスコード、結果にはレスポンスのBODYがJSON形式のString型で返ります。 String型のままでは使いづらいので「JSONをデシリアライズ」Activityを使ってレスポンスのString型をJsonObject型に変換するのがお勧めです。ベアラートークンは"result"keyに対するvalueですのでGetValue("result")でトークンを取り出せます。

※注：20.10より古いOrchestratorではパラメータプロパティを用いたテナント名、ID、パスワードの指定が可能です。 ただし20.10より利用不可となるため、パラメータプロパティの利用は非推奨です。

 Orchestrator ユーザの追加：

では次にAPI経由でOrchestratorユーザを追加します。HTTPメソッドは先程と同じくPOSTです。今回も「HTTP要求」Activityを使いますが、少し趣向を変えて、「HTTP要求」Activityの本文プロパティを使ってみます。 以下の図の赤枠で囲んだ箇所に必要な情報を指定します。

・ヘッダー

APIを呼び出すには、"Authorization"ヘッダにベアラトークンを指定することで、APIを呼び出すユーザがきちんと承認されたユーザであることをOrchestratorに伝える必要があります。 値の"Bearer"は最後に半角空白が入っているのでご注意を。[Token]の部分は適時、先程取得したベアラートークン（String型）に入れ替えてください。

・本文

requestBodyという名前のString型を指定していますが、中身は以下の通りです。 ここではAddToDirectoryとSerializeObjectを使って、Dictionary型の変数をJSON形式のString型へ変換しています。

{ "UserName" :"Test User", "Name" : "名前", "Surname" : "姓", "RolesList": [ "Robot" ], "OrganizationUnits" : [ { "Id" : 1, "DisplayName" : "unit001" }, { "Id": 2, "DisplayName": "unit002" } ], "CreationTime": "2019-XX-XXTXX:XX:XXZ", "Id": 10, "EmailAddress": "" }

その他のプロパティはベアラートークンの取得と大差ないので割愛させていただきます。 APIが成功すれば指定したユーザがOrchestratorに追加されます！

最後に：

今回の記事では、Orchestrator APIを使ってユーザ認証とユーザの追加作業を行う自動化をご紹介しました。 この他にもユーザ情報の変更・削除、ロボットの管理、OUの管理、ロールの管理などなど、自動化可能なOrchestratorの処理は沢山あります。

今回はOrchestratorのAPIしかできませんでしたが、他のWeb APIも同様に呼び出すことが可能です。その際は冒頭に書いたように、それぞれのサービスに合った認証方法（OAuth1、OAuth2、簡易認証）を利用してください。

是非、「HTTP要求」Activityを利用して幅広くUiPathをご活用いただければと思います。