【UiPath】APIトリガーのメリットと利用手順

はじめに

本記事は UiPath (produced with UiPath Friends) Advent Calendar 2023 の第10日目です。

今回はUiPath Automation Cloud (以下AC) にて利用可能なAPIトリガーのメリットと利用手順について説明します。

APIトリガーを利用することによって外部システムからACで管理されているUnattended Robot (以下UR) に対してジョブ実行命令を容易に実装することができます。

この機能はACリリースノート 2023年11月23日 の新機能として紹介されています。

API 呼び出しを介してジョブを実行する
Orchestrator で、好みのサードパーティ アプリケーションを使用して効率的にジョブを実行できるようになりました。

これに関連して、外部アプリケーションからジョブを実行できる API エンドポイントを生成する手段である API トリガーを導入しました。 プロセスに基づいてトリガーを作成し、結果の URL をコピーしてツールに貼り付け、要求を承認するだけで、定義したパラメーターでジョブが実行されます。

APIトリガー機能は2023年12月現在ではプレビューリリースです。今後の正式リリースにおいて仕様が変更される可能性がありますので最新情報は Automation Cloud リリースノート などをご参照ください。

APIトリガーのメリット

• APIトリガーを使用しない従来の方法では、URに対してジョブ実行する際には、まず Orchestrator APIとして提供されている /odata/Releases エンドポイントをコールして実行対象のプロセスIDを取得し、次に StartJobs エンドポイントをコールしてジョブ開始する必要がありました。このためスクリプトなどでロジックを書かなければなりませんでした。

• 一方APIトリガーを利用する方法では、プロセスごとに専用のエンドポイントを作ることができます。外部からはこのエンドポイントを直接コールするだけでジョブ開始することができます。よってロジックは不要になりますのでシステム連携が容易に実装できるようになります。

APIトリガーの利用手順

では早速APIトリガーを使ってみましょう。

APIトリガーの設定

まず下記手順にてAC管理画面にてAPIトリガーの設定を行います。

1. AC管理画面にログインし、Orchestrator > （フォルダー）> オートメーション > トリガー > APIトリガーを順にクリックします。あらかじめフォルダーには実行対象のプロセスを登録しておきます。

2. [新しいトリガーを追加] をクリックします。
   

3. それぞれのフィールドを入力して [追加] をクリックします。

   • 名前: トリガー名を入力します
   • プロセス名: 実行対象のプロセスを選択します
   • 動詞: 外部からコールする際のメソッドを指定します。GETでも良いですが本記事ではPOSTを使用します
   • スラグ: エンドポイント(URL)の一部となる文字列を入力します。管理の都合上プロセス名から類推できる名前にします
   • 既定の呼び出しモード: 詳細は後述しますが、基本的には既定値の「非同期ポーリング」を使用します
     ※ 上記以外のオプションはタイムトリガーと同じですので説明は省略します

   

4. APIトリガーが作成されましたら、完全なスラグURLをコピーしてメモします。

   

5. こちらの記事 を参考にして個人用アクセストークンを生成します。Orchestrator API Access リソースの OR.Jobs スコープを選択します。

   

6. 生成された個人用アクセストークンをコピーしてメモします。
   

APIトリガーの実行 (Postman)

次に実際に外部からAPIトリガーをコールしてURジョブ実行してみましょう。本記事ではデスクトップ版Postmanを使用します。

1. Postmanを起動し [+] をクリックし新規のHTTPリクエストを作成します。

2. メソッドとしてPOSTを選択し、先ほどメモした完全なURLスラグをペーストします。
   

3. [認証]タブをクリックし、タイプとして Bearerトークン を選択します。先ほどメモした個人用アクセストークンをペーストします。
   

4. [送信]をクリックし、ステータスコード202(Accepted)が返されることを確認します。
   

5. AC管理画面にてURジョブが開始されていることを確認します。
   

6. URジョブが開始した後、実行状態(ステータス)を取得するには、先ほどPostmanで送信したリクエストのレスポンスヘッダーのうち Location として返されるエンドポイントをコピーします。
   

7. Postmanにて [+] をクリックして新たなHTTPリクエストを作成し、GETメソッドで先ほどコピーしたエンドポイントを送信します。リクエストヘッダーにBearerトークンをセットすることを忘れずに！
   

注意
ステータスが保留中(Pending)または実行中(Running)の場合にはLocationエンドポイントのレスポンスBodyにジョブ詳細が返されますが、ジョブ完了後には何も返されないようです。

最終的なジョブ結果を取得するには従来通り /odata/Jobs({JobId}) エンドポイントをコールします。

呼び出しモードによる挙動の違い

補足としてAPIトリガーを作成する際に設定した「呼び出しモード」の違いについて説明したいと思います。
ジョブ実行のエンドポイント(完全なスラグURL)をコールしたあとのレスポンスに違いがあります。

• 非同期ポーリング (既定値): 上述の通りジョブは非同期で開始され、正常実行時にはステータスコード202が返されます。Locationレスポンスヘッダーをコールすることによってジョブの実行状態を知ることができます。
• 非同期で完了を待たずに実行 (fire & forget): 非同期ポーリングと同様に非同期でジョブが開始されますが、Locationレスポンスヘッダーは返されません。従来の StartJobs エンドポイントと同様の動作となり、ジョブの実行状態は /odata/Jobs(JobId) エンドポイントを使用します。
• 同期ロングポーリング: ジョブ実行は同期実行されます。つまりリクエスト送信後はジョブが完了するまでブロッキング(待機)されます。
  • Postmanで実行した場合、「リクエストを送信しています...」の画面で待機します。ジョブが完了しますとステータスコード200が返されます。
    
  • ただしジョブが長時間に渡って実行される場合には呼び出し元(今回はPostman)でタイムアウトしないかは要確認です。

引数の取り扱い

• 実行するプロセスに入力引数を渡す方法はメソッドによって異なります。

  • GET: クエリ文字列として渡します。つまり <Endpoint-URL>?<param01>=<value01>&<param02>=<value02>... の形式で実行します。
  • POST: ボディにパラメーターをKey-ValueペアにてJSON形式で記述し、Content-Type: application/json を指定して実行します。
    

• 出力引数を受け取る方法は呼び出しモードによって異なります。

  • 非同期ポーリング: ジョブ完了後にLocationレスポンスヘッダーをコールすることによってレスポンスボディで受け取ることができます。
  • 非同期で完了を待たずに実行 (fire & forget): 従来通り /odata/Jobs({JobId}) エンドポイントをコールして受け取ります。
  • 同期ロングポーリング: ジョブ完了まで待機した後、レスポンスボディで受け取ることができます

• APIトリガー一覧画面の [API定義] ボタンをクリックすることによって、Swaggerで詳細を確認することもできます。

参考リンク

• APIトリガーの詳細については Webガイド をご参照ください。

おわりに

• 本記事ではAPIトリガーのメリットと利用手順について説明しました。外部からUR実行する際の方法としてご検討いただけますと幸いです。