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

（この記事は、2022/10/01に行われた「気ままに勉強会 #34」で使用したスライドを元にしています）

注意事項

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

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の基本構造

　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

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/

OASを書く

　代表的なツールは

• Swagger Editor (https://editor.swagger.io/)
• Stoplight Studio (https://stoplight.io/studio)
• Power Automate カスタムコネクタ (https://make.powerautomate.com/)

Swagger Editor

Stoplight Studio

Power Automate

OpenAPI 3 でのカスタム コネクタのサポート

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

OASからAzure Functionへの実装

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

まとめ