はじめに
Orchestrator APIでのPOSTリクエストに必要な要求本文を作成する方法についてご紹介します。要求本文自体はJSON形式の文字列であるため、文字列として直接定義することも可能ですが、JSONオブジェクトとして取り扱った方がフィールドの定義や値の更新、繰り返し処理等の点で便利です。その点について本記事が参考になれば幸いです。
ここでは、例としてOrchestratorのジョブ実行のリクエストを送信する方法をご紹介します。
前提条件
- UiPath Studioから『OrchestratorへのHTTP要求』アクティビティを利用してPOSTリクエストを送信する
- UiPath Studio v2024.10.6を使用する
- Orchestrator API、JSONについては以下の記事を参照する
JSON操作方法
事前準備：UiPath.WebAPI.Activitiesパッケージのインストール
JSONオブジェクトを操作するために、NewtonSoft.JSONのアクティビティパッケージが必要です。それを依存関係に含むUiPath.WebAPI.Activitiesパッケージをインストールして、JSONオブジェクトを操作できるようにします。
Step1. POSTリクエストに必要なJSON本文の内容確認
POSTリクエストの内容を確認する方法として、以下のような方法が挙げられます。
- 公式ドキュメントを参照する（ドキュメントに記載がある場合）
- Swaggerで確認する
公式ドキュメントに対応する要求本文の記載がない場合、Swaggerの定義から確認できます。
Swaggerのページ > 対応するエンドポイント > Parameters > body の項目に定義すべき要求本文の例が記載されています。以下はジョブ実行のエンドポイント /odata/Jobs/UiPath.Server.Configuration.OData.StartJobs の当該箇所の例です。
Swaggerの利用方法については以下の記事に詳細が記載されています。
Step2. JSON本文の作成
公式ドキュメントに記載の要求本文の例は以下の通りです。
今回は、このJSON形式の要求本文をUiPath Studioのワークフロー上で定義することを考えます。
{
"startInfo": {
"ReleaseKey": "795cbab2-8008-4a54-b1cb-f9ff1ece139e",
"Strategy": "All",
"RobotIds": [],
"NoOfRobots": 0
}
}
手順は以下の通りです。要求本文が要求本文の中に複数のフィールドを含む"startInfo"という要素が入れ子になっている構造であるため、最初に"startInfo"の内容を格納したJObjectを作成し、それを要求本文のJObjectに格納します。
-
『代入』アクティビティを使用してJObject型の変数を定義する
左辺：startInfoJObj (JObject型)
右辺：New JObject
-
『代入』アクティビティでReleaseKeyの値を格納する
左辺：startInfoJObj("ReleaseKey")
右辺："{実行対象プロセスのReleaseKey}"
-
『代入』アクティビティで要求本文となるJObject型の変数を定義する
左辺：requestBodyJObj (JObject型)
右辺：New JObject
-
『代入』アクティビティでstartInfoJObjをrequestBodyJObjに格納する
左辺：requestBodyJObj("startInfo")
右辺：startInfoJObj
定義した要求本文の内容を確認するため、『メッセージをログ』アクティビティにrequestBodyJObj.ToStringを設定してログに出力する
要求本文に含まれる"ReleaseKey"は実行対象のプロセスを特定するために必要な情報です。取得方法については後述のReleaseKeyの取得方法の章をご確認ください。
動作確認したところ、ジョブ実行のために最低限必要なフィールドは"ReleaseKey"のみで、他の値は特に指定せずジョブの実行が可能です。
上記の例では『代入』アクティビティを使用して代入操作を行っていますが、『複数代入』アクティビティやコード化されたワークフロー等を使用しても同様の操作は可能です。
Step3. 『OrchestratorへのHTTP要求』アクティビティの設定
Step2で定義した要求本文を『OrchestratorへのHTTP要求』アクティビティに設定します。
設定内容は以下の通りです。"JSONペイロード"の項目はString型を受け付けるため、requestBodyJSON (JObject型)をToStringメソッドを使用してString型に変換します。
エンドポイントの相対パス："/odata/Jobs/UiPath.Server.Configuration.OData.StartJobs"
JSONペイロード: requestBodyJObj.ToString
上記の手順で構築したワークフローを実行すると、ReleaseKeyに指定されたプロセスが実行されます。
補足
ReleaseKeyの取得方法
上述のジョブ実行リクエストの要求本文に必要なReleaseKeyの値の取得方法についてご紹介します。
ReleaseKeyはOrchestrator上に登録されたプロセスに対して一意に与えられる値です。ReleaseKeyを使用して実行対象となるプロセスを指定します。
ReleaseKeyは /odata/Releases のエンドポイントにGETリクエストを送信することで取得できます。レスポンスの内、各プロセスの"Key"フィールドに格納されている値がReleaseKeyの該当します。
本記事で使用している『OrchestratorへのHTTP要求』アクティビティを使用してリクエストを送信することもできます。他の方法として、Swaggerを使用することでも簡単に確認できます。
以下にSwaggerでReleaseKeyを取得する方法について簡単にご紹介します。尚、ここではAutomation Cloud上のOrchesratorを前提とします。
-
https://cloud.uipath.com/{組織名}/{テナント名}/orchestrator_/swagger/にブラウザからアクセスする -
Swagger画面右上の"Authorize"のアイコンをクリックし、開いたウィンドウの内容を変更せずに"Authorize"をクリックして認証させる（鍵アイコンが閉じた状態になっていると、認証が通っている状態です。認証が出来ていない場合、鍵が開いた状態のアイコンになります）
-
Releases > /odata/Releases の項目を開き、 "Try it out"をクリックする
-
"Execute"をクリックしてリクエストを送信し、応答本文を確認する（各プロセスの"Key"フィールドに格納されている値が"ReleaseKey"です）
免責事項
本記事中でご紹介した内容は個人の見解および検証結果に基づくものであり、組織を代表した見解ではないこと、また動作を保証するものではないことをご了承ください。
おわりに
本記事ではOrchestrator APIのPOSTリクエストに必要なJSON要求本文の操作方法についてご紹介しました。日々の開発作業の参考になれば幸いです。