【UiPath】システム連携に使える同期ポーリングによるAPIトリガーの紹介

# １．はじめに
　UiPathのOrchestratorにはAPIトリガーという機能があります。同機能を利用すると、簡単にシステムなどからUnattended Robotを実行し結果を得ることができます。
　今回はAPIトリガーの中の１つの方式である「同期ポーリング」について、利用方法などについて、紹介したいと思います。
　なお、APIトリガーの機能に関する内容については以下の記事を参考にして頂ければと思います。
　・https://qiita.com/hidecha/items/5b0733639dcd1420531a

# ２．前提条件
　今回利用するAPIトリガーはAutomation Cloudにのみ存在する機能となっています。そのため、Automation Cloudを利用します。（2025年02月12日現在）
　その他の環境は以下の通りとなります。
| ソフトウェア名 | バージョン情報 |
| :--- | :--- |
| OS | Windows11 |
| UiPath Studio | 24.10.8 |
| UiPathプロジェクトの対応OS | Windows |
| UiPath.UIAutomation.Activities | 24.10.10 |
| UiPath.Mail.Activities | 1.24.2 |

また、開発環境以外にUR環境が必要となりますので、事前に接続をしておいてください。

# ３．実装方法
## ３．１．ワークフローの準備
　APIトリガーで実行するためのワークフローを準備します。今回はPost実行により引数を渡す方法となるため、以下のような4つ引数を持ったワークフローを考えます。呼び出し元からの内容を受け取るための引数と結果を返すための引数を用意する簡単なものとなり、通常のワークフロー作成と変わりありません。
#### 【引数設定】
| 名前 | 方向 | 型 |
| :--- | :--- | :--- |
| in_strEmailList | 入力 | String |
| in_strMessage | 入力 | String |
| out_boolRet | 出力 | Boolean |
| out_strMessage | 出力 | String |

#### 【ワークフロー】
　ワークフローの詳細は以下の通りとし、引数で受け取ったメールアドレスにメールを送信し、結果を返却するものとします。エラーが発生した場合は、失敗した旨を結果として返却します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3301393/abc71ae6-9e10-4114-bce2-2f7a904c312b.png)

　上記ワークフローができたら、Orchestratorにパブリッシュし、APIトリガーを設定したいフォルダーにデプロイを行います。（ここは通常のデプロイ作業のため、詳細割愛致します。）

## ３．２．Orchestrator側の設定
#### ①「新しいトリガーを追加」をクリックします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3301393/6e0b6256-1ba2-40f6-97ee-58a99b3e5278.png)
#### ②必要事項を入力し、「追加」をクリックします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3301393/26a0efb0-7f24-438e-a32b-a8737f9da1c5.png)
| 項目 | 値 | 備考 |
| :--- | :--- | :--- |
| 名前 | 任意の名前（例.Test012） |  |
| プロセス名 | 先ほどデプロイしたプロセス名（例.APIトリガー検証_20250212） |  |
| ジョブの優先度 | 任意（既定では継承） |  |
| ランタイムの種類 | Production（Unattended） | クロスプラットフォームの場合異なる |
| アカウント | 任意（例.指定済み） |  |
| マシン | 任意（例.指定済み） |  |
| ホスト名 | 任意 |  |
| 動詞 | POST |  |
| スラグ | 任意（例.send） |  |
| 既定の呼び出しモード | 任意（例.同期(ロングポーリング)） | 同期(ロングポーリング)の場合最大実行時間15分以内 |

#### ③「API定義」をクリックし、API定義を確認します
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3301393/2c941839-80f6-4be4-9673-e89de88633fe.png)
#### ④Swagger画面が開き、先ほど作成したAPIのBodyの形式などを確認することができます。（Try it outから実行の確認もできます。）
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3301393/30da6256-ba7a-4e58-8e8c-c70b6e10c63f.png)


## ３．３．シェルからの実行
　Orchestratorの画面上で、APIトリガーの3点リーダーをクリックすると、シェルの種類に応じたスラグをコピーし、利用することが可能となります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3301393/3298afee-7ee7-4ece-ad78-83ec47907aed.png)

以下は今回の内容をもとにトークン取得などを追加し、整形したものとなります。なお、トークンの取得は外部アプリケーションを用いています。★印の部分は自身の環境に併せて変更ください。
``` test.ps1
# -------------------
# トークン取得処理
# -------------------
# トークン取得URL
$uriToken = "https://cloud.uipath.com/identity_/connect/token"
# トークン取得Body定義
$bodyToken = @{
    "grant_type" = "client_credentials"
    "client_id" = "★外部アプリケーションのクライアントID"
    "client_secret" = "★外部アプリケーションのシークレット"
    "scope" = "OR.Jobs"
}
# トークン取得Request
$resToken = Invoke-RestMethod -Uri $uriToken -Method Post -Body $bodyToken -ContentType "application/x-www-form-urlencoded"
# レスポンスからトークン取得
$authKey = $resToken.access_token

# -------------------
# APIトリガー実行処理
# -------------------
# APIトリガー実行URL
$uriRequest = "★https://cloud.uipath.com/[組織URL]/[テナント名]/orchestrator_/t/[エンドポイントフォルダー識別ID]/send"
# APIトリガー実行Header定義
$headers = @{
    "Authorization" = "Bearer $authKey"
}
# APIトリガー実行Body定義
$body = @{
    "in_strEmailList" = "★自身のメールアドレスなど送信先"
    "in_strMessage" = "★メッセージ情報"
} | ConvertTo-Json -Compress
# APIトリガー実行Request
$response = Invoke-RestMethod -Uri $uriRequest -Method Post -Headers $headers -ContentType "application/json; charset=utf-8" -Body $body

# -------------------
# 結果の取得処理
# -------------------
# 標準出力
Write-Host $response
```

:::note info
今回は外部アプリケーションを利用していますが、ローカルユーザーの場合は個人アクセストークンの利用をするとより簡易に利用が可能となります。ただし、有効期限があるため、ご注意ください。
また、EntraIDなどと連携したディレクトリユーザーでは個人アクセストークンが利用できないことにご注意ください。
:::

# ４．本機能の有用性
　従来、StartJobsのAPIを呼び出しする場合、ユーザーやマシンテンプレートおよびマシンの指定などの際に複雑なBody（JSON）を記述する必要がありました。また、実行結果を受け取ることも困難でした。
　一方で、APIトリガーの場合はそれらのパラメータを呼び出し側は気にする必要がなく、URLとトークン及び引数の設定のみで実現することができ、かつ方式によっては実行結果を受け取ることも容易となります。
　上記のような特性から呼び出し側での設定が簡素化されることにより、以下2つのメリットが生じます。
　　・マシントラブルによるマシン故障時に呼び出し側の修正が不要となり、Orchestrator側のみの修正で対応ができる（耐障害性）
　　・ユーザーやマシン変更などに際し、同様に呼び出し側の修正が不要となり、Orchestrator側のみの修正で対応ができる（変更容易性）
　改めて同期ポーリングという呼び出しモードを利用しているため、ジョブの実行結果をもとに分岐したい場合、有用な手段になると考えています。

# ５．最後に
　RPAはシステム間連携の一部として使われていることもあるかと思いますが、連携の仕方を見直すことで障害に強い構成をとることができると考えています。
　本記事はあくまでも個人の見解を述べているものとなりますので、参考情報として頂ければと存じます。