PowerApps / PowerAutomate カスタムコネクタを Postman コレクションから作成する
前回の記事では OpenAPI（Swagger）Specからカスタムコネクタを作る方法を解説しました。
今回は Postman コレクションからカスタムコネクタを作成する方法を見ていきます。
Postman とは？
Web API の開発者「提供する側・活用する側」双方にとってよりよい 開発・検証のエクスペリエンスを提供するクライアントアプリケーションです。
すごくたくさん機能が提供されていますが、とにかく API の検証・テスティング（API Client機能）がとっても楽にできるのが素晴らしいです。
以前Postmanをざっくり解説したスライドも公開しているので、よかったら参考にしてください。
また、今回のポイントでもあるのですが、実行してみたリクエストはコレクションという単位でまとめて、チームで共有したり、公開することができるようになっています。
このPostmanコレクションにはAPIのリクエスト定義やレスポンスの内容が含まれており、この定義を利用することで、カスタムコネクタの定義を生成できるようになっています。
対象のAPI
それでは実際に Postman コレクションを使って、カスタムコネクタを作ってみたいと思います。
今回対象にするAPIは前回と同じく、私が以前作成してパブリックに公開している O'Reilly Book List API です。作り方はこちら を参照してください。
- URL：https://decodeapiserverdemo.azurewebsites.net/api.rst
- ID：user（ReadOnly）
- Password：3s3E4a4r7Q7d2a1J0i4l
- AuthType：Basic
以下のようなO'Reilly Book List をJSONで返すAPIになっています。
出来上がるもの
最終的にはこのカスタムコネクタを使って、PowerApps で以下のような簡単なリストを表示するアプリの作成まで行います。これも前回の記事と同じです。
Postman コレクションサンプル
Postman コレクションのサンプルは以下のGithubページに格納しました。
とはいっても中身はシンプルなGETリクエストのみのAPIです。
ちなみに Postman コレクションは OpenAPI（Swagger）Specから生成することもできます。知っていると結構便利なので、オススメです。
Postman コレクションのエクスポート
Githubに公開しているものを使っても大丈夫ですが、コレクションファイルの作成方法は簡単です。対象のコレクションの「・・・」をクリックして「Export」を選択
次に出力するフォーマットのバージョンを選べる画面に移るので「Collection V1」を選択します。これは、現在PowerApps/AutomateのカスタムコネクタがCollection V1のみにしか対応していないためです。要注意。
カスタムコネクタの作成
それではカスタムコネクタを作成していきましょう。
PowerApps（またはAutomateの画面）にログインして、「カスタムコネクタ」から「Postmanコレクションをインポートします」をクリックします。
私の環境には前回作成したカスタムコネクタもあるのでコネクタ名を変えて、「OReilly Postman」という名称にしました。そして、先程エクスポートしておいたPostmanコレクションファイルをインポートします。
作り方はOpenAPI（Swagger）の時と同じです。カスタムコネクタは以下の3種類の要素を定義して構成します。
- 全般：カスタムコネクタの画像や説明、APIホスト先のベースURLなどを定義
- セキュリティ：対象のAPIが利用する認証方式：Basic、OAuthなどの定義
- 定義：カスタムコネクタによって利用可能となるAPIの操作、アクションの定義
全般は画像を設定したくらいで、あとはデフォルトのままです。
認証タイプはPostman コレクションをもとに設定されませんので、手動で定義する必要があります。
今回のAPIはBasic認証なので、以下のように認証タイプから「基本認証」を選択し、パラメータ名を設定しました。
次にアクションなどの操作内容を定義します。ここはOpenAPIと同様にPostmanコレクションをもとに自動的に設定されるので楽ちんです。
ただし、OpenAPIの時はすべてのエンドポイントが網羅されて、自動的に設定されましたが、Postmanコレクションの場合はコレクションに設定していたリクエストのみがアクションとして定義されます。
また、利用可能なパラメータもあらかじめPostmanで指定していなければ、設定されませんので要注意です。
あとはコネクタを作成し、接続テストを行えば、正常にカスタムコネクタが動作するかどうか確認できます。
「新しい接続」から、ユーザー情報を入力できます。
構成していた操作を実行してみると、以下のようにレスポンスが取得できました。
アプリの作成
それでは作成したカスタムコネクタをPowerAppsのキャンパスアプリで使ってみます。
キャンパスアプリを作成したら、新しい画面から以下のような一覧を作成し、データソースとして先程作成したカスタムコネクタを選択します。
リストのitems要素を選択して、「カスタムコネクタ名.GetOReillybooklist().value」を入力すれば、リストに取得されたデータがマッピングされます。
あとはそれぞれの要素（以下はImageUrl、Title、URL）をマッピングすればOKです。
簡単なものですが、O'Reilly Book List API から PowerApps のキャンパスアプリが作成できました。
作るアプローチは異なりましたが、前回とまったく同じですね。
おわりに
これでカスタムコネクタの主要な作成方法となる3パターンのうち、主に利用するであろうOpenAPI SpecとPostman Collectionの2パターンを見てみました。
個人的な感覚としては、OpenAPI Specが公開されていて、汎用的なカスタムコネクタを作成したい場合は OpenAPI Specによるカスタムコネクタ作成を行い
特定ユースケースの特化型カスタムコネクタを作りたい場合は、予めPostman コレクションでAPIをテストしておき、そのコレクションでカスタムコネクタを作成するのがいいのではないかと思いました。
どうしても、OpenAPI Specベースだと、操作が大量に作成されるので、調整が必要な場合のハンドリングがしにくくなります。
また、OpenAPI SpecはPostmanコレクションとして取り込むことも可能なので、そこで一度Postmanにコレクションとして取り込んでから、必要なリクエストのみに絞って、カスタムコネクタを作成するというアプローチもありかと思います。
Tips
応答に利用できるレスポンスを予め加えておく
今回上記手順からは割愛しましたが、アクションの応答要素は予めPostmanに加えておくことで、自動的に判別させることが可能になっています。
この応答要素はPostmanのリクエスト実行結果を保存・サンプリングしておくことができる「Save Response」で保存しておくことで、Postmanコレクションに含まれて、カスタムコネクタに識別させることが可能です。
動的URLを構成したい場合どうするの？
Postman リクエストでSending Parameter 「:Resource」といったコロン付きで指定することで利用できます。
ちなみに、環境変数として参照できる「{{Resource}}」のような指定はうまく解釈されないので、注意しましょう。
