Morning Girl

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

PowerApps / PowerAutomate カスタムコネクタを OpenAPI(Swagger)Specから作成する

最近、少し PowerApps / PowerAutomate のカスタムコネクタ周りについてまとめていました。

現在何種類かの作り方があるんですが、それぞれの特徴を捉えるために、何回かに分けて記事にして行こうと思います。

PowerApps / PowerAutomate カスタムコネクタって何?

PowerApps / PowerAutomate ではデフォルトでもたくさんの種類のコネクタを提供して、独自アプリケーションの作成や、自動化・ワークフローの構成ができるようになっていますが、現在世界中に存在するすべてのAPI、もしくは標準のコネクタがあったとしてもそこで実装されているすべてのAPIの機能をサポートしているわけではありません。

f:id:sugimomoto:20200114103605p:plain

しかし、そんな API に対して PowerApps / PowerAutomate の機能を活用するために、カスタムコネクタという仕組みが提供されています。

https://docs.microsoft.com/ja-jp/connectors/custom-connectors/

f:id:sugimomoto:20200114103612p:plain

現在サポートされるAPIの種類は REST API (RESTといっても広義ですが)と SOAP API(LogicAppsのみが現在プレビュー段階)、そしてWebHook の3種類あります。

今回の記事ではREST APIベースのカスタムコネクタに標準を絞って、解説していきます。

https://docs.microsoft.com/ja-jp/connectors/custom-connectors/use-custom-connector-powerapps

現在カスタムコネクタがサポートしている作り方

現在カスタムコネクタがサポートしている作り方は以下の3種類(+α)です。(SOAPは含めず)

  1. OpenAPI定義からカスタムコネクタを作成(URLからのインポートとAzure サービスからの作成もこれに含みます。)

  2. Postmanコレクションからカスタムコネクタを作成

  3. 1からカスタムコネクタを作成

しかしなが、REST APIベースで作成したカスタムコネクタの中身は「カスタムコネクタ」+「OpenAPI定義」によって作られているようです。

ですので、1から作成しようと、Azureから取り込もうと、Postmanコレクションを元にしようと、すべてはOpenAPI(Swagger)の定義がベースとなります。

そして今回の記事では OpenAPI(Swagger)ベースでの作り方を見ていきます。

OpenAPI(Swagger)って何?

実際の作り方に入る前に、少しだけOpenAPI(Swagger)とは何か? についておさえておきます。

OpenAPI(OpenAPI Specification)は私の解釈も交えながらざっくり言ってしまえば、「REST APIのインターフェースの記述定義(OpenAPI Spec)」であり、そこから派生する「ツールや開発環境などのエコシステム」のことを指します。

f:id:sugimomoto:20200114103621p:plain

OpenAPI Specification(OAS)は、ソースコードへのアクセス、追加ドキュメント、またはネットワークトラフィックの検査を必要とせずに、人間とコンピュータの両方がサービスの機能を発見して理解することを可能にする、  プログラミング言語に依存しないREST APIの標準的なインターフェイス記述を定義します。

引用元:https://github.com/OAI/OpenAPI-Specification

ベースとなる考えは、REST API の仕様(URLパラメータや認証方式、HTTPメソッドは何を使うのか、レスポンスの仕様、JSON構造はどうなっているのか?等)を記述するための仕様であるということです。

以下のよなYAML(もしくはJSON ベース)でその仕様を記述します。

paths:
  /categories:
    get:
      summary: Return categories
      description: >-
        Returns records from the categories entity that match the specified
        query parameters.  All records will be returned when no parameters are
        specified.
      tags:
        - categories
      operationId: getAllcategories
      parameters:
        - name: $select
          in: query
          type: string
          description: >-
            A comma-separated list of properties to include in the results. When
            this field is left empty, all properties will be returned.
        - name: $filter
          in: query
          type: string
          description: >-
            Use this to filter the results by specific property values. For
            example, you can use the following filter to retrieve records with
            the name 'John': $filter=Name eq 'John'
      responses:
        '200':
          description: categories response
          schema:
            type: object
            properties:
              value:
                type: array
                items:
                  $ref: '#/definitions/categories'

通常 REST APIアーキテクチャスタイルの一種であり、そのAPIの仕様を外部から参照する仕組み(コンピューターやプログラムが識別可能な仕組み)は提供されていません。

しかし、この OpenAPI でREST APIを外部から定義することにより、APIの開発者・利用者・サードパーティが相互に扱いやすいAPIを成立させ、API ドキュメントの自動生成やテスト・ライブラリの生成などを実現することが可能になっています。

f:id:sugimomoto:20200114103630p:plain

上記のTool群はどちらかといえば、OpenAPI公式によるツール郡ですが、他にも便利にこの仕様を活用できるサードパーティツール郡が公開されており、広義にはこのカスタムコネクタもこのエコシステムに則ったツール郡の一つであると捉えることができます。(私はここに掲載してもいいと思うんですけどね?)

https://openapi.tools/

f:id:sugimomoto:20200114103637p:plain

余談ですが、OpenAPI Specification のサイトを見ると、Microsoft のメンバー(Darrel Miller, PM for Microsoft Graph developer tooling)もこの仕様の策定に大きく関わっていることがわかります。

https://www.openapis.org/blog/2017/03/01/openapi-spec-3-implementers-draft-released

f:id:sugimomoto:20200114103645p:plain

OpenAPI(Swagger)で公開されているサービス

最近はOpenAPIベースでAPIドキュメントを公開している国内サービスが増えているのも特徴であり、大きなメリットの一つです。国産クラウドサービスですと、「freee」や「CloudSign」「SmartHR」など

また、SendgridもSwaggerベースでドキュメントが公開されています。

ですので、公開されているところから OpenAPI Spec を取得して、自身が使っているツールやサービスへ簡単につなげることができるようになっています。

対象のAPI

それでは実際に OpenAPI(Swagger)Specを使って、カスタムコネクタを作ってみたいと思います。

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

f:id:sugimomoto:20200114103654p:plain

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

f:id:sugimomoto:20200114103700p:plain

出来上がるもの

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

f:id:sugimomoto:20200114103705p:plain

OpenAPI(Swagger)Specのダウンロード

まず、対象のAPIからOpenAPI(Swagger)Specをダウンロードしましょう。Swagger Specは以下のURLからダウンロードできます。

http://decodeapiserverdemo.azurewebsites.net/api.rsc/$swagger

ちなみに、以下のエンドポイントでもダウンロードできますが、バージョンが3.0で、PowerAppsカスタムコネクタ側がサポートしていないため、今回のユースケースでは利用できません。

http://decodeapiserverdemo.azurewebsites.net/api.rsc/$oas

カスタムコネクタの作成

次にPowerAppsの画面に移動して、「カスタムコネクタ」→「OpenAPI ファイルをインポートします」を選択します。

f:id:sugimomoto:20200114103712p:plain

コネクタ名は任意の名称を入力し、先程ダウンロードしておいた、OpenAPI Specファイルをインポートします。

f:id:sugimomoto:20200114103720p:plain

カスタムコネクタは以下の3種類の要素を定義して構成します。

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

f:id:sugimomoto:20200114103726p:plain

認証タイプは OpenAPI(Swagger)Specが適切に書かれていれば、そこから自動的に設定されます。便利ですね。ただし、OpenAPI Specの記述量や内容も個々のAPIでばらつきがあるので、対象のAPIによっては個別に設定する必要が出てくると思います。(細かな認証方式の設定方法は別記事で書こうかな)

今回はユーザー名:パスワードで行う基本認証(Basic)で設定しています。

f:id:sugimomoto:20200114103732p:plain

最後にこのカスタムコネクタで実施できる操作・アクションなどを定義します。基本的にOpenAPI(Swagger)Specが適切であれば、ここで特に設定の調整などは発生しません。

利用できるREST APIのリソースURI・HTTPメソッドごとにアクションが定義されます。

f:id:sugimomoto:20200114103738p:plain

あとはカスタムコネクタを保存して、接続を作成すれば、テストを行えます。

f:id:sugimomoto:20200114103744p:plain

接続を追加すると、以下のようにID・パスワードをの入力が求められます。

f:id:sugimomoto:20200114103750p:plain

試しに「getAllOReillyBookList」をパラメータなしで実行すると

f:id:sugimomoto:20200114103755p:plain

以下のようにデータが取得でき、正常にカスタムコネクタが構成されていることが確認できました。

f:id:sugimomoto:20200114103802p:plain

このようにOpenAPI(Swagger)Specベースでカスタムコネクタを作ることで、簡単にそれぞれの定義を生成できます。

1から作成する場合、アクションなどは膨大な量の定義が必要となる場合があるので、すでに公開されているOpenAPI(Sweagger)Specがある場合は、是非それを活用するのがおすすめです。

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

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

f:id:sugimomoto:20200114103807p:plain

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

f:id:sugimomoto:20200114103812p:plain

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

f:id:sugimomoto:20200114103821p:plain

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

f:id:sugimomoto:20200114103826p:plain

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

f:id:sugimomoto:20200114103832p:plain

おわりに

次回はPostmanコレクションからの作成方法も見ていきます。