Power AutomateとUiPathを連携する(Orchestrator API とくにWebhook APIの活用方法)

こんにちは。[UiPath Friendsコミュニティ](https://uipath-friends.doorkeeper.jp/)運営メンバの @masatomix です。

この投稿は[UiPath Advent Calendar (produced with UiPath Friends) Advent Calendar 2022](https://qiita.com/advent-calendar/2022/uipath) の13日目の投稿です。この前の記事は[私のUiPath資格合格体験記](https://qiita.com/megmeg278/items/9a5292df811616928478)です。

## イントロ

UiPath Orchestrator API やOAuth関連のよい活用例がないかなーって調査してて、**Power Automateと連携させる** って話を[UiPath Friends Festival 2022](https://manage.doorkeeper.jp/groups/uipath-friends/events/141998)でLTしました。ちなみに、そのときの資料はこちらです。[OrchestratorにOAuthがやってきた2022年版](https://speakerdeck.com/masatomix/orchestratornioauthgayatutekita2022nian-ban)

その内容の補足と、またその際に **Webhookの活用で面白いなーって思ったこと**があったので、その辺を備忘としてまとめておきます。 

あ、いちおうWebhookというのは、UiPath OC 2018.4くらいに実装された機構で、一言でいうと「**ジョブの完了など、Orchestrator上のなんらかのイベントが発生したとき、その情報を指定したURLに送信してくれる機構**」です。

![webhook_start](https://imgur.com/bs5gTWS.png)

ただ、Webhook機能がでてすぐ使ってみたとき、**SlackのAPIに連携して「Slackにジョブの完了を通知する」とかをやった程度**だったのですが、イマイチそれ以上よい使いみちがないなぁ、っておもってたんですね。

参考: [OrchestratorのWebhook連携](https://qiita.com/masatomix/items/90393bdbb7824c551106#orchestrator%E3%81%AEwebhook%E9%80%A3%E6%90%BA)

ところが先日Power Automate のカスタムコネクタ(後述)を作っていて、**Webhookってこういう使われ方するのか**、、ってアハ体験をしたので、そのご紹介をしたいとおもいます。



## Power Automate って

また、Power Automateってなに？ってはなしですがMicrosoftが提供するWEB上のサービスで「OneDriveのファイルが更新された」とき「Teamsに投稿する」など、対応したアプリケーションを連携させることができる仕組みです。

もう一度言うと

- **「あるサービスが○○した」とき「あるサービスの△△をする」とかができる**

機構だってことですね。あらかじめ対応しているサービスは下記のようにたくさんあります[^1]。
![sample](https://imgur.com/aYEawHE.png)


[^1]: UiPath社にも、MSのPower Automateに類似したサービスとして、UiPath Integration Serviceがあります


**サービスの一覧(ひとつひとつをコネクタといいます)をみると、UiPathはなさそう**ですね。もしUiPathのコネクタがあれば

- 「毎日、ある時刻がきた」ときに「OCのスケジュール情報を取得して、Excelでスケジュール一覧を更新する」
- 「OCのジョブが完了した」ときに「Teamsに通知する」

とかができそうですが....。

## コネクタは自作できる

実は、**一覧にないサービスはカスタムコネクタとして自作することが可能**です。自作したカスタムコネクタは、他の標準コネクタたちと同様に、アクションやトリガー(後述) として利用することができます。

下記は、自作したコネクタに含まれるアクションの一覧

![actions](https://imgur.com/52tYaKd.png)



下記は、自作したコネクタに含まれるトリガー(イベントを検知して動き出すモノ)の一覧

![triggers](https://imgur.com/PyjufiU.png)





> もしかしたらこの**カスタムコネクタの作成機能は、組織のアカウントでサインアップしたヒト向けの機能かも**しれません。
> Teamsも「チャット」と「チーム」があって、組織のアカウントじゃないと「チーム」が使えないとかありますが、同じ類のような気がします。
>
> 使えない環境の方はゴメンなさい。



## カスタムコネクタの作り方

さてさてUiPathのコネクタを自作して **「毎日、ある時刻がきた」ときに「OCのスケジュール情報を取得して、Excelにスケジュール一覧を追記する」** を実現しようとすると、流れはこんなかんじになりそうです。

- 「毎日、ある時刻がきたら(時刻トリガー)」
- 「OCのフォルダ一覧を取得」
- 「フォルダごとに、OCのスケジュール情報を取得」
- 「Excelにスケジュール一覧を追記する」

実際、カスタムコネクタを使って Power Automate上でフローをつくってみると下記のようになります。

![flow001](https://imgur.com/Z9jDZH3.png)





### コネクタの作り方:「OCのフォルダ一覧を取得」など(アクション)

自作できることがわかったカスタムコネクタですが、作成には**その使いたいサービス側が提供するAPIを使うのが一般的**です。つまりUiPathのコネクタを作るには、UiPath Orchestrator(以下OC) のAPI を活用すればOKってことです。具体的には


- 「毎日、ある時刻がきた」 ← Power Automate に備わってる時間トリガーで実現
- 「OCのフォルダ一覧を取得」 **← OC のフォルダ一覧取得API( /odata/Folders )を呼び出して情報を取得**
- 「フォルダごとに、OCのスケジュール情報を取得」 **←OC のスケジュール一覧取得API( /odata/ProcessSchedules ) を呼び出して情報を取得**
- 「Excelにスケジュール一覧を追記する」  ← Excel Online コネクタの機能を呼び出す

って感じになります[^2]。

[^2]: UiPathに限らず標準コネクタもそれぞれが提供するAPIを呼び出すことで実現しています。

実際、自作のアクティビティ(アクションという) のパラメタ詳細を見てみると
![foldersAPI](https://imgur.com/DGqlDh3.png)

これはAPIの情報を閲覧する[Swaggerで確認可能なAPI仕様](https://cloud.uipath.com/mvpjapankino/enterpriseTenant/orchestrator_/swagger/index.html#/Folders/Folders_Get)がそのまま表示されているのがわかります。
![swagger](https://imgur.com/UJh3h78.png)

というわけで「**呼び出したいAPIたちがどんな仕様なのか?**」をPower Automateに教えてあげないといけないのですが、SwaggerはAPI仕様を[定義ファイル](https://cloud.uipath.com/mvpjapankino/enterpriseTenant/orchestrator_/swagger/v15.0/swagger.json)として持っているので、それをダウンロードしてPower Automateに渡してあげればOKです。
![createConnector](https://imgur.com/XQCSR7d.png)

> 実際は多少の微調整が必要だったりします。
>
> - サイズがでかすぎると一度にImportできないから分割するとか
> - WebhookのAPIはこれだよって ``"x-ms-trigger"`` 属性を追記してあげるとか
>
> などなどがあるんですが、いったん細かい話は忘れます。
> いちおう、今回用に修正したファイルはこちらに置いておきました
>
> https://gist.githubusercontent.com/masatomix/9ca711a49490c87a5e04846f96493e15/raw/275beaf3effa9c5cd2c4017e0adb7e87d11312ec/Swagger



### コネクタの作り方:「OCのジョブが完了した」など(トリガー)

ここまでで

- 「OCのフォルダ一覧を取得」 **← OC のフォルダ一覧取得API( /odata/Folders )を呼び出す**
- 「フォルダごとに、OCのスケジュール情報を取得」 **←OC のスケジュール一覧取得API( /odata/ProcessSchedules ) を呼び出す**

のように、アクションについてはAPIを使えば実現できることがわかりました。

つづいて「OCのジョブが完了した」ときに「Teamsに通知する」などですが、こちらは

- 「OCのジョブが完了したのを検知して」 **← トリガーをどうつくるか？？**
- 「Teamsにメッセージを送信する」 ← Teams コネクタの機能

と整理できそうです。この **「OCのジョブが完了したのを検知してフローを開始する」部分をトリガー** と呼ぶのですが、それを実現するのにWebhookを活用します。**Webhookとは、あるイベントが発生したときにどこかに情報を送信してくれる仕組み**でしたよね。なので、**OC上でジョブが完了するなどイベントが発生したときに、 Power Automateにその情報を送信してくれる**ように動いてくれればよさそうです。

Webhookを活用したトリガーが実現できると、画面上にこんな感じに表示されます。
![flow002](https://imgur.com/3kiSkP0.png)



さてその作り方ですが、多少ややこしいのですこしだけ。下記の画面たちは先ほどのJSONファイルをImportして、トリガーの定義を記述する画面のイメージです。Webhookを登録するAPIのURLなども指定していますね。

![00webhook](https://imgur.com/Gv8aWy1.png)

下記の画面は、Webhookを登録するために必要なパラメタを定義しています。
![01body](https://imgur.com/gZ7qL2f.png)

上記のパラメタのうち、Webhookの送信先を指定するパラメタはどれか？を教えてあげないといけないですよね。その画面。
![02trigger_url](https://imgur.com/bFzs5wb.png)

最後に、実際にイベントが発生したときに送信される情報のデータ構造を設定しています。
![03webhook_response](https://imgur.com/5B1q11G.png)

ちなみに[Swagger上でWebhookのAPI仕様](https://cloud.uipath.com/mvpjapankino/enterpriseTenant/orchestrator_/swagger/index.html#/Webhooks/Webhooks_Post)を確認できます。こちらです。
![swagger_webhook](https://imgur.com/5Z5PBwz.png)


### トリガーが稼働する仕組み

このようにいろいろと定義しておくことで、トリガーとしてこんなのが配置できるようになります。
![trigger](https://imgur.com/CAyU2VG.png)

このトリガーをフローで使用すると、

- フローを保存したときに、さきのWebhookのAPIが呼び出されて、「Power Automateに情報を送信するWebhook」がOrchestratorに登録される[^3]
- 実際にOC上でジョブが動き出すと
  - 上記のWebhookによりOrchestratorからPower Automateサーバへ情報が送信される
  - その結果、Power Automateサーバがこのフローを開始してくれる

[^3]: (もちろん Power Automateでトリガーを削除して保存したときに Webhookの削除、もする)

という動きをします。
![ppt](https://imgur.com/BZlXWz3.png)

なるほどなぁ、って感じです。**Webhookの登録・削除がAPIで動的にできて、どんなメリットがあるのかなぁ、、っておもってたんですが、こうやってトリガーとして使われるために存在**しているって事が分かりました。



## 動画にしました

参考1: Webhookが自動で登録されたり、削除されたりする様子を動画にしました。

https://youtu.be/ypJWFkwo-Lk

参考2: ジョブが開始・終了すると、都度Teamsに通知されるところを動画にしました。

https://youtu.be/bNOpBjad3GM




## 蛇足: ちなみにAPIを動かすための認証はどうなっているか

APIを呼び出すときにはふつう認証が必要なわけですが、Power AutomateはOAuth/OpenID Connectの認証に対応しているので、それらに対応しているAPI なら、認証のことは何も考えなくてもOKです。

OCのAPIはOAuthに対応しているので、特に設定しなくてもこのように、画面上で「OAuthの認証認可画面を呼び出して認証する」ことができます。冒頭のLTでもお話しましたが、OC APIがOAuthに対応したのはこういったサービスと繋がるためだったんですね。

![oauth](https://imgur.com/9msfmsF.png)



## まとめ

- Orchestrator API をつかって、Power Automateのような外部のサービスとOrchestratorが連携できることがわかりました。
- Webhookについては、OC上のイベント発生時に情報を送信することで、他のサービス(Power Automate) を起動するトリガーの役割として活用できることがわかりました。
- カスタムコネクタを作成する際にSwaggerの情報をたくさん活用できることがわかりました。
- Orchestrator APIがOAuth対応になったことで、認証も含めて外部サービスとの連携がしやすくなりました。

ところでUiPathにも、 Power Automateに似た機構として、[UiPath Integration Serivce](https://www.uipath.com/ja/blog/corporate/introducing-uipath-integration-service)というのがあります。対比してみるとMicrosoftが 「Power Automateという"**WEB上のサービス連携機能**"と"**フローをWeb上で記述できる仕組み**"から始まって、"**Power Automate Desktopが発表されてデスクトップ側のRPA**"に拡張された」のに対して、UiPathは「"**UiPath というデスクトップRPA**"から始まって、"**WEB上のサービスをトリガーにできるUiPath Integration Service**"と"**フローをWeb上で記述する仕組み(Studio Web)**"に拡張された」と、ベクトルが対照的であるところが興味深いです。

UiPath Integration Serviceも少しだけ触ってみましたが、Swaggerの取り込みがまだまだだったり、Studio WebがPower Automate のフロー記述ほどこなれていないのが課題かなって思いましたが、今後が楽しみなサービスです。

以上、お疲れさまでした！！



## 関連リンク


- [UiPath Friends Festival 2022](https://manage.doorkeeper.jp/groups/uipath-friends/events/141998) 本記事は、このFesでLTしたときの補足の記事となっています。
- [OrchestratorにOAuthがやってきた2022年版](https://speakerdeck.com/masatomix/orchestratornioauthgayatutekita2022nian-ban) そのときの資料です
- [Webhookのイベントの種類](https://docs.uipath.com/orchestrator/lang-ja/docs/types-of-events)
- [WebhookをAzure Functionで受けるという公式のサンプル記事(2019年で結構まえの記事)](https://www.uipath.com/ja/blog/developer/serverless-webhook) 


https://twitter.com/masatomix/status/1580496471228489728