Power AutomateでプリザンターAPIのカスタムコネクタを作成する

この記事は、[OSSのノーコード・ローコード開発ツール「プリザンター」 Advent Calendar 2022](https://qiita.com/advent-calendar/2022/pleasanter) の17日目の記事です。

# はじめに

前回の記事では、プリザンターのAPIの実行するフローを作成しました。

https://qiita.com/pierusan2010/items/77ee509b3f709d5dbbac

前回はAPIの実行に組み込みのHTTPコネクタを利用しましたが、今回はプリザンターAPIに特化したコネクタを作成して使ってみたいと思います。

# OpenAPIでPleasanter.netの仕様を定義する
Power Automateのカスタムコネクタは OpenAPI の形式で記述されたREST APIの定義から作成できます。まずはこちらの作成から行います。
Power Automateでは、OpenAPIのバージョン2.0（Swagger2.0）のみ対応しています。

:::note
今回は既に作成している定義ファイルを利用します。OpenAPIの仕様や記述方法については割愛します。
:::

## OpenAPIの定義ファイル
今回使用するOpenAPIの定義ファイル(yaml)は、下記に置いてあります。こちらをご確認ください。

https://github.com/pierre3/PleasanterAPI/blob/main/pleasanterApi.yml

今回定義しているのは下記APIのみとなります。
- レコード取得（単一、複数）: Items Get
- レコード作成: Items Create
- レコード更新: Items Update
- レコード削除: Items Delete

なお、こちらはクラウドサービスのPleasanter.netを対象としています。オープンソース版で本記事の内容を試してみたい方は下記部分をご利用の環境に合わせて書き換えてください。

```yaml
host: pleasanter.net
basePath: /fs/api
```

:::note
また、GitHub Pagesにこちらの定義ファイルを使ったAPIドキュメントも併せて公開（非公式）しております。
https://pierre3.github.io/PleasanterAPI/

定義ファイルを使いたい場合は、リンク先ページにある「Download」ボタンから取得できます
:::

# カスタムコネクタの作成

- PowerAutomateのWebに行き、左側のメニューで「データ」-「カスタムコネクタ」を選択します
- 上部右側の「＋カスタムコネクタの新規作成」をクリックします
- 「一から作成」を選択します（OpenAPIファイルをインポートのメニューもありますが、こちらからだと何故か定義ファイル読み込み時にエラーとなってしましました。）
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/28805/e7146177-32e4-c323-af95-5becfc08de46.png)

- コネクタ名を入力して「続行」ボタンをクリックすると下記の画面になります。ここで「Swaggerエディター」のスイッチをONにします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/28805/64f0c5fc-58d7-08b6-01b6-9725488e3d66.png)

- 左側のエディタの中身を全て用意しておいた定義ファイル(yaml)の中身に置き換えます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/28805/3ee4efb2-3c21-45f2-b7f5-0631b1f792b5.png)

- 必要な設定は全て定義ファイルに記載されていますので、アイコン画像をアップロードして変更するくらいでOKです。「コネクタの作成」をクリックして保存します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/28805/56b27ea3-15a9-bf6e-7c3d-d85ad275578a.png)

# カスタムコネクタを使ってみる

それでは、前回作成したプリザンターのレコードを更新するフローを修正して、カスタムコネクタを利用するように変更してみましょう。

https://qiita.com/pierusan2010/items/77ee509b3f709d5dbbac


# レコード取得のHTTPアクションをItems Getアクションに変更する

前回作成したフローの最初のHTTPアクション（対象レコード取得用）とそれに続くJSON解析のアクションを削除し、代わりに今回作成したカスタムコネクタのItems Getアクションを挿入します。

- フローの (＋)ボタンから「アクションの追加」を選択し、「カスタム」タブをクリックします。
- 作成したPleasanter.net APIのコネクタをが表示されますので、これを選択します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/28805/bfde84c7-0795-db0e-1342-88bd4ae35213.png)

- ４つのアクションが表示されますので、ここではItems Getを選択します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/28805/dcec0602-bc6c-996c-8dcd-875caff2b255.png)

- 下図がItems Getアクションの設定画面になります。
  URLはコネクタで定義されているので入力不要になり、取得対象のサイトIDのみの入力となりました。
  また、これまでは全てJSON文字列として記述する必要がありましたが、多くのパラメータは項目ごとに入力枠が作られています。
- API Keyとフィルタ条件をColumnFilterHashに設定します。ColumnFilterHashはJSON形式で記述する必要があります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/28805/a16837da-a49d-6a88-bdd0-4f2da3daf5de.png)

- APIバージョンは「1.1, 1.0」と選択式になっています。固定値から選択するパラメータは全てドロップダウンから選択できるようになっています。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/28805/588a9b90-5795-0d51-5356-5bdb5098bb41.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/28805/54c915d8-4064-ed51-4f37-06eca66a3b7f.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/28805/a8e90baa-f868-2220-389a-58cc15dd0bd3.png)

### APIのレスポンスについて

レスポンスの形式もコネクタで定義済みのため、JSON解析は不要となります。

:::note warn

#### リクエストパラメータで`ApiDataType`を `KeyValues` とした場合

レスポンスは対象テーブルの設定に応じて動的に変化するため、コネクタの定義に含めることができません。その場合、部分的にJSON解析が必要になります。

レスポンスは下記のレイアウトとなりますが、`KeyValues`の場合はData配列の要素となるオブジェクトの構造がテーブルの定義によって異なります。
"Date"配列でループ処理を行い、その要素に対してJSON解析をかけることで`KeyValues`の結果も処理できるようになります。

```json
{
  "StatusCode":200,
  "LimitPerDate":10000,
  "LimitRemaining":5000,
  "Response": {
    "Offset": 0,
    "PageSize": 200,
    "TotalCount": 150,
    "Data":[
        {....},
        {....},
        {....}
    ]
  }
}
```
:::

# レコード更新のHTTPアクションをItems Updateアクションに変更する

次に、取得したレコードを更新するHTTPアクションをItems Updateアクションに変更します。

- 前回のループ処理「Apply to each」の「以前の手順から出力を選択」欄にカスタムコネクタの実行結果から`Data`を選択して入力します。
- また、既存のHTTPアクションとJSONの解析は削除しておきます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/28805/f2ea50c2-d27a-e144-69f9-396a42d6fa0f.png)


- 「アクションの追加」でカスタムコネクタのItems Updateを選択します
- Items Updateアクションの設定はItems Getよりもさらに簡単です。
  - recordIdにItems Getの結果のIssueId(Data配列の要素のオブジェクトから取得)を設定
  - Statusに900（完了）を入力
  
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/28805/ef74352a-caa8-100e-02ba-3a81803ee99f.png)

※ 今回は使用しませんでしたが、ClassHashなどの値は、JSONで指定します。
```json
{
    "ClassA": "更新後の文字列"
}
```

# 実行結果のメッセージの取得先を変更する

後はTeamsに送信する文字列の取得先をItems Updateのレスポンスの`Message`に置き換えればOKです。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/28805/8f2f4575-d93c-0478-d84a-f09a4dae7c64.png)

フローを保存し、前回と同じように動作すれば成功です！

# おわりに

カスタムコネクタを利用することで、フローの開発が少し楽になりました。

- 入力項目が用意されるようになったことで、下記のような問題が軽減されました。
  - どんなパラメータが使えるのか分からずマニュアルを探す
  - パラメータ名を間違えて記載してしまう（一部JSONで記載するパラメータでは解消されませんが）
- レスポンスの定義があることで、JSON解析にかける手間が省けるようになりました。

１つや２つのフローでは大きな効果はないかもしれませんが、同様のフローを多数作成する場合には威力を発揮するのではないでしょうか。