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

# はじめに
本記事は [UiPath (produced with UiPath Friends) Advent Calendar 2023](https://qiita.com/advent-calendar/2023/uipath) の第10日目です。

https://qiita.com/advent-calendar/2023/uipath

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

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

この機能はACリリースノート [2023年11月23日](https://docs.uipath.com/ja/orchestrator/automation-cloud/latest/release-notes/november-2023#13-november-2023) の新機能として紹介されています。
> **API 呼び出しを介してジョブを実行する**
> Orchestrator で、好みのサードパーティ アプリケーションを使用して効率的にジョブを実行できるようになりました。
> 
> これに関連して、外部アプリケーションからジョブを実行できる API エンドポイントを生成する手段である API トリガーを導入しました。 プロセスに基づいてトリガーを作成し、結果の URL をコピーしてツールに貼り付け、要求を承認するだけで、定義したパラメーターでジョブが実行されます。

:::note warn
APIトリガー機能は2023年12月現在ではプレビューリリースです。今後の正式リリースにおいて仕様が変更される可能性がありますので最新情報は [Automation Cloud リリースノート](https://docs.uipath.com/ja/automation-cloud/automation-cloud/latest/release-notes/release-notes-2023) などをご参照ください。
:::

# APIトリガーのメリット
- APIトリガーを使用しない**従来の方法**では、URに対してジョブ実行する際には、まず Orchestrator APIとして提供されている `/odata/Releases` エンドポイントをコールして実行対象のプロセスIDを取得し、次に [`StartJobs` エンドポイント](https://docs.uipath.com/ja/orchestrator/automation-cloud/latest/api-guide/jobs-requests#starting-a-job)をコールしてジョブ開始する必要がありました。このためスクリプトなどでロジックを書かなければなりませんでした。

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

# APIトリガーの利用手順
では早速APIトリガーを使ってみましょう。

## APIトリガーの設定
まず下記手順にてAC管理画面にてAPIトリガーの設定を行います。
1. AC管理画面にログインし、Orchestrator > （フォルダー）> オートメーション > トリガー > APIトリガーを順にクリックします。あらかじめフォルダーには実行対象のプロセスを登録しておきます。
2. [新しいトリガーを追加] をクリックします。
    ![ApiTrigger01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/178312/5188f592-17d4-6de4-b48e-a39b7a13ef5c.png)

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

    ![ApiTrigger02b.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/178312/c5c5fac2-1bc5-e61c-300d-c2ff922f534b.png)

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

    ![ApiTrigger03.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/178312/72974eda-e01d-d1ac-8a55-98bf9aad9418.png)

4. [こちらの記事](https://qiita.com/hidecha/items/609dc6723dffb3bd81c6) を参考にして個人用アクセストークンを生成します。Orchestrator API Access リソースの **OR.Jobs** スコープを選択します。

    ![PAT01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/178312/da41ab2b-d5fc-ec46-553c-9da3cfaf230d.png)

5. 生成された個人用アクセストークンをコピーしてメモします。
    <img width="500" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/178312/a56850e9-5b01-5428-019e-9527e4623ade.png">

## APIトリガーの実行 (Postman)
次に実際に外部からAPIトリガーをコールしてURジョブ実行してみましょう。本記事ではデスクトップ版[Postman](https://www.postman.com/downloads/)を使用します。

1. Postmanを起動し [+] をクリックし新規のHTTPリクエストを作成します。
2. メソッドとして**POST**を選択し、先ほどメモした完全なURLスラグをペーストします。
    ![ApiTrigger04.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/178312/8a526a02-d63e-727c-1fdc-19988f18b474.png)

3. [認証]タブをクリックし、タイプとして **Bearerトークン** を選択します。先ほどメモした個人用アクセストークンをペーストします。
    ![ApiTrigger05.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/178312/63689675-e9e2-18d2-c1b8-0235f3192566.png)

4. [送信]をクリックし、ステータスコード202(Accepted)が返されることを確認します。
    ![ApiTrigger06a.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/178312/344b2209-46d7-fea3-1d77-a5a0269494d5.png)

5. AC管理画面にてURジョブが開始されていることを確認します。
    ![ApiTrigger07.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/178312/d47afa39-e389-9b93-8d2b-0be932488d45.png)

6. URジョブが開始した後、実行状態(ステータス)を取得するには、先ほどPostmanで送信したリクエストのレスポンスヘッダーのうち Location として返されるエンドポイントをコピーします。
    ![ApiTrigger08.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/178312/48ce1e1a-aa3e-81c7-61d8-d12814b53ca6.png)

7. Postmanにて [+] をクリックして新たなHTTPリクエストを作成し、**GET**メソッドで先ほどコピーしたエンドポイントを送信します。リクエストヘッダーにBearerトークンをセットすることを忘れずに！
    ![ApiTrigger09.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/178312/69338398-077e-0af7-d7a3-74c46b10842e.png)

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

![ApiTrigger10.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/178312/6f89a124-5676-c551-a720-991817828677.png)

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

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

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

# 引数の取り扱い
- 実行するプロセスに入力引数を渡す方法はメソッドによって異なります。
    - **GET**: クエリ文字列として渡します。つまり `<Endpoint-URL>?<param01>=<value01>&<param02>=<value02>...` の形式で実行します。
    - **POST**: ボディにパラメーターをKey-ValueペアにてJSON形式で記述し、`Content-Type: application/json` を指定して実行します。
    ![ApiTrigger13.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/178312/035e0c35-e28b-b510-0fe9-aa9628e76444.png)

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

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

![ApiTrigger12.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/178312/401d1715-899a-ee7c-bd6e-fa2c931ab36a.png)

# 参考リンク
- APIトリガーの詳細については [Webガイド](https://docs.uipath.com/ja/orchestrator/automation-cloud/latest/user-guide/managing-api-triggers) をご参照ください。

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