Power Automate のデスクトップフローを Web API から操作する

# はじめに

Power Automate for desktop と呼ばれる、Power Automate のデスクトップフローは、通常は [Power Automate ポータル](make.powerautomate.com)からフローを管理しますが、 

**Web API により、UIを使用せずにフローを管理/トリガーすることが可能です。**

その方法について、Postman による実行手順をまとめました。

詳細は、以下の Power Automate blog に記載があります。
（記載された手順では動作しない部分が数ヶ所ありますので、設定方法は当記事をご参考ください）

https://powerautomate.microsoft.com/ja-jp/blog/manage-your-power-automate-desktop-flows-using-web-apis/




# 注意
本機能を利用する場合、Power Automate の``アテンド型 RPA のユーザーごとのプラン`` が必要です。




# Web API によるデスクトップフローの管理について

Web API で、デスクトップフローに対して実行できるアクションは以下です

1. 使用可能なデスクトップフローを一覧表示する ←
1. デスクトップフローのスキーマを取得する
1. デスクトップフロー実行の状態を取得する ←
1. デスクトップフロー出力の取得
1. デスクトップフローの実行をトリガーする ←
1. デスクトップフローの実行を取り消す

当記事では、「←」を付けたものを記載しています。




# 1．Microsoft Dataverse で OAuth 認証を使用する

Web API でのデスクトップフロー実行は、Dataverse 認証を利用します。
Dataverse での認証は、Azure AD テナントにアプリケーション登録を行う必要があります。

###### 1-1. [Azure portal](https://portal.azure.com/) にサインインし、アプリの登録に移動 ⇒ [＋新規登録]。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/9f0c4c99-5677-7a75-7354-05bf45a8d8e0.png)



###### 1-2. 以下項目を設定し、[登録]ボタンを押下します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/70c54324-5562-f3b3-5fae-2b32d5df766c.png)
① 名前：任意
② 任意の組織ディレクトリ内のアカウント (任意の Azure AD ディレクトリ - マルチテナント) を選択
③ リダイレクトURL：「Web」を選択し、任意の URL ← 後ほど利用するので覚えておきます



###### 1-3. アプリが登録されたら、「概要」メニューで表示される、アプリケーション（クライアント）ID の値をコピーしておきます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/085710d0-9e73-854d-2d6e-29d583778840.png)



###### 1-4. 「認証」メニューに移動し、「暗黙的な許可およびハイブリッド フロー」にある、[アクセス トークン (暗黙的なフローに使用)]をチェックし［保存］します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/abd30ddb-feef-cfa1-5020-261a82de8da8.png)
また、1-2. の ③ で設定したリダイレクトURL もこの画面で表示されることを覚えておいてください。

###### 1-5. 「APIのアクセス許可」メニューから Dataverse にアクセス許可を追加します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/747aea2d-402a-4bda-ff9e-d9aca7967742.png)

① [APIのアクセス許可] を選択し、[＋アクセス許可の追加] を選択します
② [所属している組織で使用している API] を選択し、Dataverse を選びます（"Dataverse"で検索すると見つけやすいです）
③ 「user_impersonation」をチェックし、[アクセス許可の追加] を押下します
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/96188254-8fe2-ba5b-a37f-0b436d3dd00e.png)


# 2．Postman で認証

2-1. [Postman](https://www.postman.com/downloads/) をインストールします。

###### 2-2. Postman で、[Enviroments] ⇒ [＋] ⇒ [New Environment]を選択し、任意の名前を付けます。  
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/803c6a85-ecc4-918f-1108-e3f8b2114d08.png)




###### 2-3. 環境変数を設定し、[Save]後、画面右上の環境ドロップダウンでActiveな環境として選択します。
![{5DB2ECAB-E045-4E79-BEA6-90E21F38D16E}.tmp.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/f2b64f8f-d234-8d6b-40a7-58e722696f0d.png)


| VARIABLE | INITAL VALUE |
|:-----------|:------------|
| url        | 	https://< 組織名(※下記) >.dynamics.com (例:https://orgXXXXXX.api.crm7.dynamics.com)  |
| clientid   | <1-3. で取得したアプリケーション（クライアント）ID の値 >    |
| version    | 9.2        |
| webapiurl  | {{url}}/api/data/v{{version}}/          |
| callback   | <1-2. ③で設定したリダイレクトURL>       |
| authurl    | https://login.microsoftonline.com/common/oauth2/authorize?resource={{url}}     |



:::note info
**※ 組織名の調べ方**
[Power Apps ポータル](https://make.powerapps.com/)にサインインし、右上歯車メニュー ⇒ [開発者リソース]
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/06add430-5f8f-9e42-7851-c60ac8cc3ffc.png)

「Web API エンドポイント」のURLのうち、``orgXXXXXX.api.crmX`` の値になります。
![{5DB2ECAB-E045-4E79-BEA6-90E21F38D16E}.tmp.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/936a3fd7-9838-90c7-38b3-26c482ed83f8.png)
:::


###### 2-4. 以下手順に従い、環境で使用するアクセストークンの生成します
① 2-2. ～ 2-3. で作成した Environment のすぐ横にある + をクリックします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/a58fe933-7a33-d9f6-0e45-de732ae66dbe.png)

② 表示された「Untitled Request」で、「Authentication」タブを選択し、「Type」を ``[OAuth 2.0]``に、「Add authorization data to」を ``[Request Headers]``に設定します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/a0022c06-dbe8-f0e1-fedc-b4fb53dd2ef3.png)

③ 「Configure New Token」 で``[Configuration Options]``タブを選択し、以下の値を設定し、``[Get New Access Token]``ボタンを押下します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/1c95ba60-44f4-499b-e757-e1b29aa587e1.png)

| Name | VALUE |
|:-----------|:------------|
| Callback URL|	{{callback}}  |
| Auth URL    | {{authurl}}   |
| Client ID   | {{clientid}}  |

④ Azure Active Directory のサインインダイアログボックスが表示されるので、サインインし認証を完了すると次のダイアログが表示されます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/385ad272-50a3-1783-4fff-90350877b89c.png)

⑤ 「Manage Access Tokens」ウィンドウが表示されたら、``[Click Use Token]`` をクリックします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/c8e3ede3-a00d-c9b2-4c56-fa4c8acd1f36.png)

新しく生成されたトークンが「Available Tokens」に表示されます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/2717a89e-77e2-1b54-28f8-8ef4dd3e9861.png)



# 3．Postman で使用可能なデスクトップフローを一覧表示する

###### 3-1. 「Params」タブを選択し、HTTPメソッドに``[Get]`` ⇒ リクエストURLに下記の値を設定し、``[Send]`` ボタンをクリックします。
■ リクエストURL
```
{{webapiurl}}workflows?$filter=category+eq+6&$select=name,workflowid&$orderby=name
```
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/67f29565-86b4-b89f-da85-c8f51d749c6e.png)

応答として、デスクトップフローの一覧が返ります。
![{5DB2ECAB-E045-4E79-BEA6-90E21F38D16E}.tmp.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/f72d0fd9-ff3e-11e3-3b61-f0e78900c2a3.png)
``workflowid`` は、この後案内する「デスクトップフローの実行をトリガーする」で利用します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/4137b1d8-d411-3e46-b06b-3c464e7e3beb.png)



# 4．Postman でデスクトップフローの実行をトリガーする

###### 4-1. HTTPメソッドに``[POST]`` ⇒ リクエストURL と リクエストBody を設定し、``[Send]`` ボタンをクリックします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/258d148f-4e50-2e14-b71e-96a11f85f81b.png)
■ リクエストURL
```
{{webapiurl}}workflows(<3.で取得した workflowid>)/Microsoft.Dynamics.CRM.RunDesktopFlow
```
■ リクエストBody
```
{
    "runMode": "attended",
    "runPriority": "normal",
    "connectionName": "<Desktop flows コネクタの connectionName(※下記)>",
    "timeout": 7200
}
```

:::note info
**※ Desktop flows コネクタの connectionName の調べ方**
Power Automate ポータル (make.powerautomate.com)で「接続」メニューから、 Desktop flows コネクタを選択します。
![{5DB2ECAB-E045-4E79-BEA6-90E21F38D16E}.tmp.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/59d5679e-c9ba-dd0a-8403-93f0f18aef81.png)
クラウドフローからデスクトップフローの実行履歴が無い場合、コネクタが存在しない可能性があります。
その際は、Desktop flows で接続を作成してください。

URLから、``connectionName=``から続く値が、connectionName となります。
![{5DB2ECAB-E045-4E79-BEA6-90E21F38D16E}.tmp.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/62852521-bb56-c196-d229-182d891ad6aa.png)
:::

応答として、flowsessionId が返ります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/389e4086-9daf-8e75-e94c-a079e06d17fb.png)
これは後述の、「デスクトップフロー実行の状態を取得する」で、フローの状態コードを取得する際に利用します。
![{5DB2ECAB-E045-4E79-BEA6-90E21F38D16E}.tmp.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/8799dae2-c71a-0ade-f326-1a3511af0fed.png)



# 5．Postman でデスクトップフロー実行の状態を取得する
トリガーしたフローは非同期で実行されるため、終了ステータスを取得する方法も、APIで用意されています。

###### 5-1. ``[Params]`` を選択し、HTTPメソッドに``[Get]`` ⇒ リクエストURLに下記の値を設定し、``[Send]`` ボタンをクリックします。
■リクエストURL
```
{{webapiurl}}flowsessions(<4.で取得した flowsessionId>)?$select=statuscode,statecode,startedon,completedon
```
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/4b02b7b0-a6e4-4782-873f-23265afd6e8f.png)

応答の statuscode が終了コードです。
``4`` が返れば ``Succeeded`` です。
![{5DB2ECAB-E045-4E79-BEA6-90E21F38D16E}.tmp.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/480768/dc9f0c13-aeec-c822-07cd-e4d13fff0936.png)

他のコードは以下をご参照ください。

https://learn.microsoft.com/ja-jp/power-apps/developer/data-platform/reference/entities/flowsession#statuscode-%E3%81%AE%E9%81%B8%E6%8A%9E%E8%82%A2%E3%82%AA%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3

# まとめ
Power Automate のデスクトップフローを Power Automate ポータルやクラウドフローを介さずに、Web API から管理や実行する方法を説明しました。
Web API からデスクトップフローを実行できるということは、様々なシステムからフローのトリガーを組めるということです。
これは、業務システム等にデスクトップフローを組み込み、業務フローの一部をRPAに肩代わりさせる事が可能ということです。

使い方次第で、強力な機能となると思います。