UiPath OrchestratorのAPIをSwaggerで簡単に試してみる

この記事ではUiPathのCloud Orchestratorを利用することを想定しています。

UiPath OrchestratorはAPIを使って情報の取得、更新、挿入、削除などの操作を実施することが可能です。
UiPath Orchestratorでは、APIが実際にどのように動作するものかを簡単に試すことができる Swagger という仕組みが用意されています。
この記事ではSwaggerを利用するための準備と、Swaggerの操作の基本について記載しています。

事前準備

1. https://cloud.uipath.com に管理者でログインし、 [管理] > [外部アプリケーション] を選択し、[アプリケーションを追加] をクリックします。
2. 任意のアプリケーション名を入力します。（今回は Swagger と入力）
3. アプリケーションの種類を以下から選択します。（今回は [機密アプリケーション] を選択）　

   アプリケーションの種類	説明
   機密アプリケーション	付与方式として認可コードまたはクライアントクレデンシャルを使用する場合
   非機密アプリケーション	付与方式として認可コード + PKCE を使用する場合

4. [スコープを追加] をクリックし、 リソースとして [Orchestrator API Access] を選択します。
5. スコープを選択します。(今回はアプリケーションスコープを選択)

   スコープ	説明
   アプリケーションスコープ	付与方式としてクライアントクレデンシャルを使用する場合
   ユーザースコープ	付与方式として認可コード + PKCE を使用する場合

6. 保護対象リソースに許可する操作をスコープとして選択します(複数選択可能)。今回は以下の3つを選択しました。各APIにはそれを呼び出すのに必要なスコープが決められています。スコープの確認方法については後述します。
   • OR.Folders.Read
   • OR.Jobs.Read
   • OR.Robots.Read

不要な権限の付加はセキュリティ上の懸念となりますので、必要最低限の権限を与えるようにしましょう

1. リダイレクトURLは以下の値を設定（今回は設定不要）

   条件	設定値
   クライアントがWebアプリケーションの場合	Identity Serverからの応答として認可コードが返されトークン取得の処理を行うためにコールバックされるURLを設定
   スクリプトから認可コードを取得する場合	Automation Cloud / Orchestrator など任意のURLを設定し、スクリプトから呼び出す際に同じ値を指定
   クライアントクレデンシャル付与方式	リダイレクトURLの設定は不要

2. [追加] をクリックし、アプリケーション設定を保存します。
3. ポップアップで表示されるアプリシークレットをメモします。アプリシークレットは再表示できないため、万が一紛失してしまった場合にはアプリケーションを編集し、 [新しく作成] をクリックして再生成してください。

アプリシークレットは重要なセキュリティ情報です。誰かに教えたり、複数人で共有したりしないようにしてください

ログイン

1. https://cloud.uipath.com/アカウント名/テナント名/orchestrator_/swagger/index.html にアクセスします。
2. 右上の[Authorize]をクリックします。
3. ポップアップ画面のclient_secretに事前準備手順でメモしたアプリシークレットの値を入力し、ポップアップ画面下部の[Authorize]をクリックします
4. 正しくLoginできると以下のような画面になりますので[Close]をクリックし、ポップアップ画面を閉じます。
   

実行例1.

1. Swagger画面からフォルダー一覧を取得してみます。[Folders]をクリックし、フォルダー関連のAPI一覧を表示します。
   

2. フォルダーの一覧取得は GET /odata/Folders ですので、それをクリックし展開します。
   　この画面に、このAPIを呼び出すのに必要なスコープが "OAuth Required scopes" として表示されます。
   

3. APIコール時に各種パラメーターを指定できますが、まずはパラメーターを指定せずにAPIをコールしてみます。[Try it out]をクリックします。
   

4. [Execute]ボタンが表示されますのでクリックします。

5. Response bodyに実行結果が表示されます。合わせてResponse headerや、Curlコマンドで同じ結果を得るためのコマンドなどが表示されます。
   

6. 次の手順のために適当なフォルダーのIdをメモしておきます。
   

実行例2.

1. パラメーターを利用する例として指定したフォルダ内のプロセス一覧を取得します。

2. Swagger画面の[Release] → [GET /odata/Releases] → [Try it out] の順にクリックし プロセス一覧取得の画面を展開します。
   

3. X-UIPATH-OrganizationUnitId に 実行例1．でメモしたFolder Idを入力し、[Execute]をクリックします。
   

4. 指定したフォルダ内のプロセス一覧を取得することができます。

実行例3.

1. パラメーターを利用する別の例として、API呼び出しでより多くの情報を取得する例をあげます。ここではJOBの実行履歴とともにそのJOBが実行されたRobotの情報も取得してみます。

2. JOBの実行履歴を取得するために使用する API は [GET /odata/Jobs] です。Swagger画面で Jobsをクリックしジョブの一覧取得の画面を展開します。

3. このままこのAPIを呼び出した場合、Robotの情報は取得できませんが、パラメータの $expand に Robot を指定することで Robot情報も同時に取得できます。
   

4. 結果のJSONのにRobotの情報も含まれていることを確認してください。

OrchestratorのAPIを調べる方法

Orchestratorの画面がどのAPIを使用してしているかを調べる方法です。これによって自分がOrchestratorに対して行いたい操作がどのAPIによって実現できるかを知ることができます。

1. ブラウザの開発者ツールを起動します。
   • Edgeの場合、F12を押したあとで、[Dev Toolを開く]をクリックします。
     
   • Chromeの場合もF12を押して開発者ツールを起動します。
2. OrchestratorでAPIを確認したい画面に遷移します。
3. 開発者ツールでネットワークタブを選択し、クリアボタンを押します。
   
4. Orchestrator画面をリロードし、ログの先頭行を確認します。この例では GET processes APIが呼び出されていることが分かります。
5. 全般（Genetral）の要求URL(Request URL)に、呼び出されたAPIの情報が表示されます
   • Edge
     
   • Chrome
     

まとめ

OrchestratorのAPIを利用することで、RobotやProcess、Packageの管理をより効率化することができます。
今回はAPIのお試しということでSwaggerを使ってみましたが、もちろんスクリプトやUiPathのワークフローからもAPIを呼び出すことができます。それらの方法については以下のUiPath Knowledge Baseの記事が役に立つと思います。こちらの記事もぜひ読んでみてください。
外部アプリケーション機能(OAuth)によるOrchestrator APIコール実装方法