はじめに
Power Automate for desktop と呼ばれる、Power Automate のデスクトップフローは、通常は Power Automate ポータルからフローを管理しますが、
Web API により、UIを使用せずにフローを管理/トリガーすることが可能です。
その方法について、Postman による実行手順をまとめました。
詳細は、以下の Power Automate blog に記載があります。
（記載された手順では動作しない部分が数ヶ所ありますので、設定方法は当記事をご参考ください）
注意
本機能を利用する場合、Power Automate のアテンド型 RPA のユーザーごとのプラン が必要です。
Web API によるデスクトップフローの管理について
Web API で、デスクトップフローに対して実行できるアクションは以下です
- 使用可能なデスクトップフローを一覧表示する ←
- デスクトップフローのスキーマを取得する
- デスクトップフロー実行の状態を取得する ←
- デスクトップフロー出力の取得
- デスクトップフローの実行をトリガーする ←
- デスクトップフローの実行を取り消す
当記事では、「←」を付けたものを記載しています。
1．Microsoft Dataverse で OAuth 認証を使用する
Web API でのデスクトップフロー実行は、Dataverse 認証を利用します。
Dataverse での認証は、Azure AD テナントにアプリケーション登録を行う必要があります。
1-1. Azure portal にサインインし、アプリの登録に移動 ⇒ [＋新規登録]。
1-2. 以下項目を設定し、[登録]ボタンを押下します。
① 名前：任意
② 任意の組織ディレクトリ内のアカウント (任意の Azure AD ディレクトリ - マルチテナント) を選択
③ リダイレクトURL：「Web」を選択し、任意の URL ← 後ほど利用するので覚えておきます
1-3. アプリが登録されたら、「概要」メニューで表示される、アプリケーション（クライアント）ID の値をコピーしておきます。
1-4. 「認証」メニューに移動し、「暗黙的な許可およびハイブリッド フロー」にある、[アクセス トークン (暗黙的なフローに使用)]をチェックし［保存］します。
また、1-2. の ③ で設定したリダイレクトURL もこの画面で表示されることを覚えておいてください。
1-5. 「APIのアクセス許可」メニューから Dataverse にアクセス許可を追加します。
① [APIのアクセス許可] を選択し、[＋アクセス許可の追加] を選択します
② [所属している組織で使用している API] を選択し、Dataverse を選びます（"Dataverse"で検索すると見つけやすいです）
③ 「user_impersonation」をチェックし、[アクセス許可の追加] を押下します
2．Postman で認証
2-1. Postman をインストールします。
2-2. Postman で、[Enviroments] ⇒ [＋] ⇒ [New Environment]を選択し、任意の名前を付けます。
2-3. 環境変数を設定し、[Save]後、画面右上の環境ドロップダウンでActiveな環境として選択します。
| 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}} |
※ 組織名の調べ方
Power Apps ポータルにサインインし、右上歯車メニュー ⇒ [開発者リソース]
「Web API エンドポイント」のURLのうち、orgXXXXXX.api.crmX の値になります。
2-4. 以下手順に従い、環境で使用するアクセストークンの生成します
① 2-2. ～ 2-3. で作成した Environment のすぐ横にある + をクリックします。
② 表示された「Untitled Request」で、「Authentication」タブを選択し、「Type」を [OAuth 2.0]に、「Add authorization data to」を [Request Headers]に設定します。
③ 「Configure New Token」 で[Configuration Options]タブを選択し、以下の値を設定し、[Get New Access Token]ボタンを押下します。
| Name | VALUE |
|---|---|
| Callback URL | {{callback}} |
| Auth URL | {{authurl}} |
| Client ID | {{clientid}} |
④ Azure Active Directory のサインインダイアログボックスが表示されるので、サインインし認証を完了すると次のダイアログが表示されます。
⑤ 「Manage Access Tokens」ウィンドウが表示されたら、[Click Use Token] をクリックします。
新しく生成されたトークンが「Available Tokens」に表示されます。
3．Postman で使用可能なデスクトップフローを一覧表示する
3-1. 「Params」タブを選択し、HTTPメソッドに[Get] ⇒ リクエストURLに下記の値を設定し、[Send] ボタンをクリックします。
■ リクエストURL
{{webapiurl}}workflows?$filter=category+eq+6&$select=name,workflowid&$orderby=name
応答として、デスクトップフローの一覧が返ります。
workflowid は、この後案内する「デスクトップフローの実行をトリガーする」で利用します。
4．Postman でデスクトップフローの実行をトリガーする
4-1. HTTPメソッドに[POST] ⇒ リクエストURL と リクエストBody を設定し、[Send] ボタンをクリックします。
■ リクエストURL
{{webapiurl}}workflows(<3.で取得した workflowid>)/Microsoft.Dynamics.CRM.RunDesktopFlow
■ リクエストBody
{
"runMode": "attended",
"runPriority": "normal",
"connectionName": "<Desktop flows コネクタの connectionName(※下記)>",
"timeout": 7200
}
※ Desktop flows コネクタの connectionName の調べ方
Power Automate ポータル (make.powerautomate.com)で「接続」メニューから、 Desktop flows コネクタを選択します。
クラウドフローからデスクトップフローの実行履歴が無い場合、コネクタが存在しない可能性があります。
その際は、Desktop flows で接続を作成してください。
URLから、connectionName=から続く値が、connectionName となります。
応答として、flowsessionId が返ります。
これは後述の、「デスクトップフロー実行の状態を取得する」で、フローの状態コードを取得する際に利用します。
5．Postman でデスクトップフロー実行の状態を取得する
トリガーしたフローは非同期で実行されるため、終了ステータスを取得する方法も、APIで用意されています。
5-1. [Params] を選択し、HTTPメソッドに[Get] ⇒ リクエストURLに下記の値を設定し、[Send] ボタンをクリックします。
■リクエストURL
{{webapiurl}}flowsessions(<4.で取得した flowsessionId>)?$select=statuscode,statecode,startedon,completedon
応答の statuscode が終了コードです。
4 が返れば Succeeded です。
他のコードは以下をご参照ください。
まとめ
Power Automate のデスクトップフローを Power Automate ポータルやクラウドフローを介さずに、Web API から管理や実行する方法を説明しました。
Web API からデスクトップフローを実行できるということは、様々なシステムからフローのトリガーを組めるということです。
これは、業務システム等にデスクトップフローを組み込み、業務フローの一部をRPAに肩代わりさせる事が可能ということです。
使い方次第で、強力な機能となると思います。