Morning Girl

Web API, Windows, C#, .NET, Dynamics 365/CRM etc..

PowerApps / PowerAutomate カスタムコネクタを Postman コレクションから作成する

前回の記事では OpenAPI(Swagger)Specからカスタムコネクタを作る方法を解説しました。

kageura.hatenadiary.jp

今回は Postman コレクションからカスタムコネクタを作成する方法を見ていきます。

docs.microsoft.com

Postman とは?

Web API の開発者「提供する側・活用する側」双方にとってよりよい 開発・検証のエクスペリエンスを提供するクライアントアプリケーションです。

https://www.getpostman.com/

f:id:sugimomoto:20200114122759p:plain

すごくたくさん機能が提供されていますが、とにかく API の検証・テスティング(API Client機能)がとっても楽にできるのが素晴らしいです。

f:id:sugimomoto:20200114122806p:plain

以前Postmanをざっくり解説したスライドも公開しているので、よかったら参考にしてください。

speakerdeck.com

また、今回のポイントでもあるのですが、実行してみたリクエストはコレクションという単位でまとめて、チームで共有したり、公開することができるようになっています。

f:id:sugimomoto:20200114122840p:plain

このPostmanコレクションにはAPIのリクエスト定義やレスポンスの内容が含まれており、この定義を利用することで、カスタムコネクタの定義を生成できるようになっています。

docs.microsoft.com

対象のAPI

それでは実際に Postman コレクションを使って、カスタムコネクタを作ってみたいと思います。

今回対象にするAPIは前回と同じく、私が以前作成してパブリックに公開している O'Reilly Book List API です。作り方はこちら を参照してください。

f:id:sugimomoto:20200114122944p:plain

以下のようなO'Reilly Book List をJSONで返すAPIになっています。

f:id:sugimomoto:20200114122950p:plain

出来上がるもの

最終的にはこのカスタムコネクタを使って、PowerApps で以下のような簡単なリストを表示するアプリの作成まで行います。これも前回の記事と同じです。

f:id:sugimomoto:20200114122955p:plain

Postman コレクションサンプル

Postman コレクションのサンプルは以下のGithubページに格納しました。

github.com

とはいっても中身はシンプルなGETリクエストのみのAPIです。

f:id:sugimomoto:20200114123001p:plain

ちなみに Postman コレクションは OpenAPI(Swagger)Specから生成することもできます。知っていると結構便利なので、オススメです。

kageura.hatenadiary.jp

Postman コレクションのエクスポート

Githubに公開しているものを使っても大丈夫ですが、コレクションファイルの作成方法は簡単です。対象のコレクションの「・・・」をクリックして「Export」を選択

f:id:sugimomoto:20200114123017p:plain

次に出力するフォーマットのバージョンを選べる画面に移るので「Collection V1」を選択します。これは、現在PowerApps/AutomateのカスタムコネクタがCollection V1のみにしか対応していないためです。要注意。

f:id:sugimomoto:20200114123023p:plain

カスタムコネクタの作成

それではカスタムコネクタを作成していきましょう。

PowerApps(またはAutomateの画面)にログインして、「カスタムコネクタ」から「Postmanコレクションをインポートします」をクリックします。

f:id:sugimomoto:20200114123029p:plain

私の環境には前回作成したカスタムコネクタもあるのでコネクタ名を変えて、「OReilly Postman」という名称にしました。そして、先程エクスポートしておいたPostmanコレクションファイルをインポートします。

f:id:sugimomoto:20200114123036p:plain

作り方はOpenAPI(Swagger)の時と同じです。カスタムコネクタは以下の3種類の要素を定義して構成します。

  • 全般:カスタムコネクタの画像や説明、APIホスト先のベースURLなどを定義
  • セキュリティ:対象のAPIが利用する認証方式:Basic、OAuthなどの定義
  • 定義:カスタムコネクタによって利用可能となるAPIの操作、アクションの定義

全般は画像を設定したくらいで、あとはデフォルトのままです。

f:id:sugimomoto:20200114123042p:plain

認証タイプはPostman コレクションをもとに設定されませんので、手動で定義する必要があります。

今回のAPIBasic認証なので、以下のように認証タイプから「基本認証」を選択し、パラメータ名を設定しました。

f:id:sugimomoto:20200114123048p:plain

次にアクションなどの操作内容を定義します。ここはOpenAPIと同様にPostmanコレクションをもとに自動的に設定されるので楽ちんです。

ただし、OpenAPIの時はすべてのエンドポイントが網羅されて、自動的に設定されましたが、Postmanコレクションの場合はコレクションに設定していたリクエストのみがアクションとして定義されます。

また、利用可能なパラメータもあらかじめPostmanで指定していなければ、設定されませんので要注意です。

f:id:sugimomoto:20200114123055p:plain

あとはコネクタを作成し、接続テストを行えば、正常にカスタムコネクタが動作するかどうか確認できます。

f:id:sugimomoto:20200114123100p:plain

「新しい接続」から、ユーザー情報を入力できます。

f:id:sugimomoto:20200114123132p:plain

構成していた操作を実行してみると、以下のようにレスポンスが取得できました。

f:id:sugimomoto:20200114123136p:plain

アプリの作成

それでは作成したカスタムコネクタをPowerAppsのキャンパスアプリで使ってみます。

f:id:sugimomoto:20200114123143p:plain

キャンパスアプリを作成したら、新しい画面から以下のような一覧を作成し、データソースとして先程作成したカスタムコネクタを選択します。

f:id:sugimomoto:20200114123148p:plain

リストのitems要素を選択して、「カスタムコネクタ名.GetOReillybooklist().value」を入力すれば、リストに取得されたデータがマッピングされます。

f:id:sugimomoto:20200114123153p:plain

あとはそれぞれの要素(以下はImageUrl、Title、URL)をマッピングすればOKです。

f:id:sugimomoto:20200114123158p:plain

簡単なものですが、O'Reilly Book List API から PowerApps のキャンパスアプリが作成できました。

作るアプローチは異なりましたが、前回とまったく同じですね。

f:id:sugimomoto:20200114123204p:plain

おわりに

これでカスタムコネクタの主要な作成方法となる3パターンのうち、主に利用するであろうOpenAPI SpecとPostman Collectionの2パターンを見てみました。

個人的な感覚としては、OpenAPI Specが公開されていて、汎用的なカスタムコネクタを作成したい場合は OpenAPI Specによるカスタムコネクタ作成を行い

特定ユースケースの特化型カスタムコネクタを作りたい場合は、予めPostman コレクションでAPIをテストしておき、そのコレクションでカスタムコネクタを作成するのがいいのではないかと思いました。

どうしても、OpenAPI Specベースだと、操作が大量に作成されるので、調整が必要な場合のハンドリングがしにくくなります。

また、OpenAPI SpecはPostmanコレクションとして取り込むことも可能なので、そこで一度Postmanにコレクションとして取り込んでから、必要なリクエストのみに絞って、カスタムコネクタを作成するというアプローチもありかと思います。

Tips

応答に利用できるレスポンスを予め加えておく

今回上記手順からは割愛しましたが、アクションの応答要素は予めPostmanに加えておくことで、自動的に判別させることが可能になっています。

f:id:sugimomoto:20200114123212p:plain

この応答要素はPostmanのリクエスト実行結果を保存・サンプリングしておくことができる「Save Response」で保存しておくことで、Postmanコレクションに含まれて、カスタムコネクタに識別させることが可能です。

f:id:sugimomoto:20200114123218p:plain

docs.microsoft.com

動的URLを構成したい場合どうするの?

Postman リクエストでSending Parameter 「:Resource」といったコロン付きで指定することで利用できます。

learning.getpostman.com

f:id:sugimomoto:20200114123223p:plain

f:id:sugimomoto:20200114123228p:plain

ちなみに、環境変数として参照できる「{{Resource}}」のような指定はうまく解釈されないので、注意しましょう。

f:id:sugimomoto:20200114123233p:plain