[Power Automate] カスタムコネクタをOpenAPI Specification (OAS) で学ぶ

（この記事は、2022/10/01に行われた[「気ままに勉強会 #34」](https://kimamani.connpass.com/event/261425/)で使用したスライドを元にしています）

### 注意事項
> - この記事は、実用性を目指しておりません。何かを解決できる話ではありません。
> - この記事は、私が付け焼き刃で仕入れた知識を披露しているだけで、多くの誤りや、個人の見解が含まれていると思われます。
> - この記事の内容を鵜呑みにしないでください。

# APIはいろいろなものをつなぐ
- APIとは **Application Programming Interface**
- 「ソフトウエア」のための「インターフェイス」
- 以下のもので構成されています。
    - **「仕様」(Specification)**
    - **「インターフェイス」(Interface)**

# Web APIはHTTP(HTTPS)を使う
- Web APIとは**HTTP(HTTPS)プロトコル**を使って **「リモート」** でソフトウエア／サービスを操作するためのインターフェース
- 設備投資は比較的安いコスト、あるいは追加投資無しで実装できます
- HTTP(HTTPS)は既存の技術なので学習コストを低くできます
- その自由さのために統一されたインターフェース、すなわち標準化が求められました。

# REST APIとは
　REST原則にのっとったAPIは **「RESTful API」** と呼ばれます

- **Addressability** （アドレス可能性）
    - Uniform Resource Identifier (URI) を使用して、リクエストはリソースを特定します
- **Uniform Interface**　（統一インターフェース）
    - 情報への操作(取得、作成、更新、削除)は、HTTPメソッド(GET、POST、PUT、DELETE)を利用します
- **Client-Server/Stateless**　（ステートレス性）
    - 個々のリクエストは独立しており、リクエストがどのような順番で行われても、同一リクエストは同じ結果を返します。
- **Connectability**　（接続性）
    - アプリケーションと状態遷移の「ハイパーリンク」を動的に作成し送信することで、より多くの情報を情報を取得します

　**RESTful** は原則であり、実装ではないので、開発者の解釈によるところがあります。

　雑に説明するのに **「データ形式をXMLやJSONにしておけば大体REST」** などと言われることもありますが、以下の様なことを気にかけておくのが重要です。

- GET, POST, PUT, DELTEの使い分けを考えておく
- URLは、わかりやすいものにしておく
- ハイパーリンクを使うと便利なこともある
- ステートレスのほうが作りやすい、分かりやすいから「ステートレス」にしておく

# RESTful APIを記述する言語
- WSDL2.0とWADL →　可読性が低く、あまり採用されていない
- Google Cloud Endpoints
- Open Data Protocol (OData)
- OpenAPI Specification (OAS)
- RESTful Service Description Language (RSDL)
- RESTful API Modeling Language (RAML) 
- Apache Avro


# OpenAPI 仕様（OpenAPI specificatgion: OAS)とは
### 歴史
- Tony Tamによって2011年にSwagger APIプロジェクトが開始。
- 2015年、SmartBear SoftwareがSwaggerを買収。
- 2015年、SmartBearは、Google, IBM, Microsoftなどの企業とOpenAPI Initiativeを創設。
- 2016年1月1日、Swagger仕様はOpenAPI仕様(OpenAPI Specification OAS)に改名。
    - Swagger 2.0 → OAS 2.0
- 2017年7月、OpenAPI Initiativeは、OAS 3.0.0をリリース
- 2021年2月、OAS 3.1.0をリリース

### OASの特徴
- プログラミング言語に依存しない
- クライアントはサーバの実装を知らなくても、サービスを使用できる
- ドキュメント、クライアントライブラリ、ソースコードの同期が保たれる

# OASの基本構造
<img width="260" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/864075/97fa5163-d896-4fda-4beb-dec08e777480.png"/>

　OASファイルはJSONかYAML形式で記述されます。

- Info
    - title, version, descriptionなどのメタデータ
- Paths
    - APIのパスと仕様を定義する
    - Operation, Parameter, Schema
- Server
    - サーバーのURLなどを記載できる
- Components, Reference
    - リクエスト／レスポンスのセットを定義し、参照する

※ 参照 > "OpenAPI Specification入門", Akinari Tsugo, 2020-05-08, https://garafu.blogspot.com/2020/05/how-to-use-oas.html

https://garafu.blogspot.com/2020/05/how-to-use-oas.html

# YAMLとは
　YAMLとは「YAML Ain't Markup Language（YAMLはマークアップ言語ではない）」

- YAMLはカッコではなくインデントでまとまりを表す。
- JSONとYAMLとの交互の変換は比較的カンタン

※　参照 > "YamlとJsonの比較", TAKIGAWA MEMO, 2020-01-26, https://www.takigawa-memo.com/compare-yaml-json/

https://www.takigawa-memo.com/compare-yaml-json/

# OASを書く

　代表的なツールは
- [**Swagger Editor** (https://editor.swagger.io/)](https://editor.swagger.io/)
- [**Stoplight Studio** (https://stoplight.io/studio)](https://stoplight.io/studio)
- [**Power Automate カスタムコネクタ** (https://make.powerautomate.com/)](https://make.powerautomate.com/)

## Swagger Editor
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/864075/0c77e868-2d6d-5e75-783a-ee14349dcb77.png)

## Stoplight Studio
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/864075/8f5fd469-f091-30e0-90f3-123a00c9c950.png)

## Power Automate
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/864075/bd7626aa-bb63-5e4a-bfc6-fa95fc8c899e.png)

### OpenAPI 3 でのカスタム コネクタのサポート
　Power Automateのカスタムコネクタで自動で作成されるのはSwagger 2.0 (OAS 2.0)ですが、Swagger エディッタで **OAS 3.0.n** の記述ができるようになりました。

https://learn.microsoft.com/ja-jp/power-platform-release-plan/2022wave1/power-platform-pro-development/openapi-3-support-custom-connectors

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/864075/1e2f15b3-e05b-c7bb-2151-44bdd0eb35e6.png)

# OASからAzure Functionへの実装

https://azure.microsoft.com/en-us/updates/generate-a-new-function-app-from-an-openapi-specification/

　Azure Functions VS Code 拡張機能またはコマンド ラインを使ってOASをインポートすることで、Azure Functionアプリケーションを生成できます。生成後、必要に応じてC#、Python、TypeScript、Javaでビジネスロジックを追加します。

# まとめ
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/864075/d9939507-2bba-f996-10e7-7578eafe7984.png)
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/864075/00b44c82-dc98-79e2-06db-8baa34d562ec.png)