OpenAPI（Swagger） Spec のバージョンを 3.0 から 2.0 に変換したい：API MATIC を試してみた
2.0 から 3.0 に上げたいならまだしも、3.0 から 2.0 に下げたい？ 何をバカなことを言っているのだ？ と思われるかもしれないんですがちゃんとした理由がありまして
PowerApps のカスタムコネクタが OpenAPI Spec から生成できるんですが、現在 2.0 しかサポートしていないんですね。
でも、私が個人的に作っていた API が OpenAPI Spec 3.0 なのですね。（わかってたのにー (ﾉｼ 'ω')ﾉｼ ﾊﾞﾝﾊﾞﾝ）
なので、変換できるツール無いかなーと探していたら、ありました！
API MATIC
「API MATIC」という API定義から各言語のSDKを生成するサービスがあるんですが
その機能の中に「API Transformer」というものがありまして、OpenAPI以外にも、各種API Specを相互変換！
しかも、Postman Collection までサポート・・・！！！！！
素晴らしい！！！
なお、基本的には Web API を提供している側向けのサービスなので、お値段は月々 $9.9 ～。
今回はとりあえず Trial で試してみました。
使い方
使い方は簡単です。サインアップしたら、ダッシュボードの画面右上に「Transform API」というボタンがあるので、これをクリック。
あとは対象となる YAML を選んで、Export Format から OpenAPI/Swagger v2.0 を選べばOK！
ValidationがOKだったら、Proceed をクリックすると、OpenAPI/Swagger v2.0 の Spec がダウンロードされてきます。
やったね！
Postman Documentation / API Network が便利だよ！
この記事は「Postman Documentation / API Network が便利だよ！ 」ということを言いたいだけの記事です。
Postman Documentation / API Network とは？
Postman には Webベースのドキュメントを公開する機能があります。
作成すると以下のような見やすい API リファレンス と APIテスティング が行えるWebSiteが自動的に作成されます。
もちろん、Postmanコレクションも取得して、ローカルのPostmanで実行することも可能です。
ちなみに、私の観測範囲で、このPostman Documentation を使ってAPI ドキュメントを公開している日本のクラウドサービスは「Bカート」さんくらい。
ちなみに、Postman では生成したドキュメントをPostmanの サイト上で公開・共有できる仕組みを提供しています。
それが Postman API Network です。
現在、470種類ほどのAPIが公開されており、APIドキュメントの参照、Postman Collectionの入手が可能になっています。
APIを検証する時、Postmanコレクションを毎回手作業でがつがつ作るんですが、予めこういうサイトで公開されていると、すごく楽で助かります。
最後に
パブリックなAPIは、みんな Postman API Network で API documentを公開してくれればいいのに！！！
Postman Collectionは OpenAPI SpecやRAMLからも取り込めるので、敷居は低いと思うんですが。
PowerApps / PowerAutomate カスタムコネクタを Postman コレクションから作成する
OpenAPI（Swagger）Spec から Postman Collection を生成すると楽にAPIテストができる
Postman で API を実行するのは結構手軽にできるんですが、エンドポイントが多かったり、URLパラメータやヘッダーを逐次、ドキュメントから持ってくるのは結構面倒です。
もし、そのAPIがOpenAPI（Swagger） Specを公開していたら、それを取り込むと簡単にPostmanコレクションを生成できます。
OpenAPI Spec って何？
ここを参照しましょう。
OpenAPI Specification（OAS）は、ソースコードへのアクセス、追加ドキュメント、またはネットワークトラフィックの検査を必要とせずに、人間とコンピュータの両方がサービスの機能を発見して理解することを可能にする、 プログラミング言語に依存しないREST APIの標準的なインターフェイス記述を定義します。
対象のAPI
今回対象にするAPIは私が以前作成して、パブリックに公開している O'Reilly Book List API です。作り方はこちら を参照してください。
- URL：https://decodeapiserverdemo.azurewebsites.net/api.rst
- ID：user（ReadOnly）
- Password：3s3E4a4r7Q7d2a1J0i4l
- AuthType：Basic
以下のURLからOpenAPI Specをダウンロードできます。
http://decodeapiserverdemo.azurewebsites.net/api.rsc/$oas
取り込み方
取り込み方は簡単です。Postmanを立ち上げて、「Import」ボタンをクリックし
事前にダウンロードしておいた、OpenAPI（Swagger）Specのファイルをドラッグ・アンド・ドロップするだけです。
あとはTeamで共有するかどうかと、コレクションを作成するかどうかを決めて、Nextをクリックすれば完了です。
以下のようにコレクションが生成されて、
手軽にAPIを試せる状態が整います。
Reference
PowerApps / PowerAutomate カスタムコネクタを OpenAPI（Swagger）Specから作成する
最近、少し PowerApps / PowerAutomate のカスタムコネクタ周りについてまとめていました。
現在何種類かの作り方があるんですが、それぞれの特徴を捉えるために、何回かに分けて記事にして行こうと思います。
- PowerApps / PowerAutomate カスタムコネクタって何？
- 現在カスタムコネクタがサポートしている作り方
- OpenAPI（Swagger）って何？
- OpenAPI（Swagger）で公開されているサービス
- 対象のAPI
- 出来上がるもの
- OpenAPI（Swagger）Specのダウンロード
- カスタムコネクタの作成
- カスタムコネクタを使ってみる
- おわりに
自分のはてなブログの投稿状況データをPowerBIで可視化する：CData XML ODBC Driver
先日公開した以下の記事で書いたのですが、自分のはてなBlogでどんな投稿をしているかPowerBIで可視化してみました。
最終的にできあがったのは以下のようなレポートです。
この記事ではこのようなレポートを作成するためのデータ取得方法について解説していきます。
その前にちょっとAPIの解説
はてなBlogにはいくつか外部からはてなBlogにアクセスするためのAPIが提供されています。
- Atom https://help.hatenablog.com/entry/feed
- RSS https://help.hatenablog.com/entry/feed
- AtomPub http://developer.hatena.ne.jp/ja/documents/blog/apis/atom
- oEmbed API http://developer.hatena.ne.jp/ja/documents/blog/apis/oembed
最初２つのAtomやRSSはおそらく使ったことがある方も多いと思いますが、Blogの更新状況を取得するためのAPIプロトコルです。
AtomPubはAtomのように外部からBlog記事を参照できる機能はもちろんですが、記事の登録や更新にも対応しているのがポイントとなるAPIです。
最後のoEmbed APIはこちらの解説記事がわかりやすいかと思いますが、名前の通り外部コンテンツへの埋め込みおよびその記事の参照用に特化したプロトコルです。
今回APIとして必要な要件は、過去の全記事に関する情報が参照でき、かつカテゴリ情報も取得する必要がありました。
そして、実はその要件を満たしたAPIは「AtomPub」一択です。
前２つのAtomとRSSは参照用としては優れているのですが、最新の記事参照のみに特化しているため、ページネーション、つまり過去記事の参照ができません。
oEmdedは参照するためにどの記事を参照したいか、といったURLが必要となるため、言わずもがな。
AtomPubはページネーションをサポートし、カテゴリも取得できるので、今回のようなユースケースにはうってつけのAPIとなっていました。
実装方法
それでは実際に実現する方法なのですが、この記事でははてなBlogデータをAtomPub経由で取得するためのコネクタを使うので、特にプログラミングの要素は出てきません。
なので必要なものは、以下の「CData XML ODBC Driver」と
XML ODBC Driver - ODBC | ODBC Drivers | ODBC Connection | ODBC API
XML ODBC Driverを通じてはてなBlog AtomPubに接続できるようにするための設定ファイルだけです。
あとは分析用に Microsoft Power BIを使いました。Tableauなどでも同じ用に実施できると思います。
API Keyと接続URLの取得方法
それでは実際にデータの取得を行っていきたいと思いますが、AtomPub APIは接続するために「接続用URL」と「API Key」が必要となります。
はてなBlogの管理画面から「設定」→「詳細設定」に移動
AtomPubにルートエンドポイントとAPIキーの情報があるので、これを利用します。
設定ファイルをダウンロード
次に接続用の設定ファイルをダウンロードします。通常設定ファイルは「CData XML Driver」用で都度カスタマイズする必要があるのですが、今回は私が作成してしまっているので、以下のURLからダウンロードして利用できます。
上記URLから「HatenaBlogFeeds.rsd」というファイルをダウンロードし、任意のフォルダに配置（例：C:\CData_REST\Hatena）します。
CData XML ODBC Driverのインストールとセットアップ
続いて「CData XML ODBC Driver」をインストールします。有償の製品ですが、30日間のトライアルバージョンがあるので、今回はそれを利用します。
以下のURLから評価版をダウンロードし
http://www.cdata.com/jp/drivers/xml/odbc/
ダウンロードしたexeファイルを実行して、セットアップを行います。
セットアップ完了後、DSN構成画面が表示されるので、以下のように必要な情報を入力します。
- URI：管理画面から入手したAtomPub用URLの末尾にentryを付与したものを入力（例：https://blog.hatena.ne.jp/sugimomoto/kageura.hatenadiary.jp/atom/entry）
- Auth Scheme：Basic
- Password：管理画面から入手したAtomPub用API Keyを入力
- User：はてなBlogのログインユーザーIDを指定
- Location：設定ファイルのフォルダパスを指定（例：C:\CData_REST\Hatena）
以上で下準備は完了です。
PowerBI からはてなBlog AtomPub APIに接続
それではPowerBIに はてなBlogのデータをロードしてみましょう。
PowerBIを立ち上げて、「データを取得」をクリックし
「ODBC」接続を選択します。
先程設定したDSN名を選択して「OK」をクリックすると
以下のようにはてなBlogのデータがフラット化されて取得できるテーブルが選択できるようになっています。これを読み込みます。
以下のような感じでデータが取得されました。設定ファイルが自動的にAtomPubのページネーションもするようになっているので、過去の全記事を取得してくるようになっています。
あとはこのデータを使って、PowerBIの機能でビジュアライズするだけです。
その他：カテゴリの取り方
ちなみに、デフォルト状態のカテゴリ情報は以下のようにカンマ区切りになっているのですが、
これだとリレーショナルなデータになっていないので、うまく可視化できない部分が出てきますよね？
これを以下のようにBlogIDとリレーションされた形式にする方法もあります。
方法は簡単で、まず元になっているクエリを複製し、適当に「Category」といった名前に変更、IdとCategoryTerm以外の列を削除します。
次に「列の分割」から「区切り記号による分割」を選択し
「コンマ」の区切りごとで列を分割します。
以下のようなデータができあがるので、この項目を選択して、「列のピボット解除」を実行します。
すると以下のようにIDに各カテゴリがリレーションされた形のデータができあがります。「属性」列は最終的に消してしまっても大丈夫です。
2019年の活動棚卸しと2020年の方針をまとめてみる
あけましておめでとうございます！
去年に引き続き2019年も活動の棚卸しと2020年の方針をまとめてみようと思います。
ちなみに、去年はちょっと手軽にExcelで済ませてしまったので、今回はしっかりとPowerBIでやってみました。
2019年の棚卸し
Blogの状況
一応私は自分自身のBlogと会社のBlogの両方で記事を投稿しているのですが、とりあえずメインのMorningGirlの投稿状況を見てみます。
去年は43件とちょっと少なめとなったのですが、今年は51件と2015年に次ぐ件数となり、結構精力的にBlog活動ができました。ただ、月別の投稿件数を見ると1月が14件と圧倒的なのに、それ以降が伸び悩み。
カテゴリはAPIが2018年と変わらないですが、ZOZO前澤社長のツイート収集などをしたことや、JJUGでの登壇をまとめた記事を書いたことなどもあって、TwitterやJavaのコンテンツが増えていることがわかります。
あとは意外とDynamicsに関する発信もしていたなと思ったり。PowerBIの方が多いかなというイメージでしたが。
PVベースでは前年比意外と伸び悩み。14%増に留まりました。人気記事の傾向を見ると、2018年に投稿したRESTとはなんぞや、MongoDBやRedisの事始め記事が強いのがよくわかります。このあたりは確かにあまり書いてなかったなぁと思ったり。
ちなみに今年一番はてなブックマークがついた記事は「無料の API 自動生成ツールを使って、Excelファイルから REST API を生成してみる：CData API Server」でした。199ブクマ。
タイトル的に伸びるかなと思っていましたが、想定以上に大きな反響があってよかったです。
次にブックマークが多かったのは「500万件を超えるTwitter のリツイート データを取得・分析する方法 -Twitter Premium Search API を実際に使ってみてわかった嵌りポイントとその対策-」
かなり挑戦的な取り組みだったと個人的にも思っていたので、よかったなーと思っています。
- 会社のBlog
ちなみに、会社のBlogには「33件」投稿していました。自分のBlogと併せてトール「84件」だったので、来年は100を目指してもいいかもですね。
SNS・Twitter
Blogは伸び率がそこまででもありませんでしたが、ツイッターは結構頑張っていたみたいでした。ツイート数だけでも、去年の2倍くらい。そこまで意識していたわけでも無いので意外でした。
ただ、後述の勉強会への参加数が大きく伸びていたので、それに伴うツイート数の増加が大きな要因ではないかなと見ています。
あと、APIに関するツイート数が1000を超えていたのはいいですね。関連のニュース・トピックに関しては積極的に発信していくようにしましたが、去年に比べて3倍の発信量でした。
勉強会・コミュニティ
個人的に一番大きく変わったなーと思ったのは、勉強会・コミュニティに対する参加・登壇状況でした。
2018年が22参加でそれでも結構多いなと思っていたのですが、2019年は36個になっていました。
プラス、それよりも登壇数の大幅増加が凄まじい。2018年5個だったのに、2019年が19と3倍強に。
もうちょっとちまちまLTをしているのかなと思いきや、実はメイン登壇がほとんどで、そこもまたびっくり。
ちなみに表には出していないのですが、主催イベントも合計5個と、よくやったなーと改めて思います。
なお、仕事の登壇も「3件」ほどあったので、トータル「22件」発表していたようです。
Youtube
途中からやり始めたYoutubeは合計5つとまだまだこれから感。
基本的にイベントの登壇を編集して公開しているだけだったので、視聴数的にもこんな感じかなというところに留まりました。
イベントの配信は2回ほど行いましたが、GoProでの配信はそれなりによかった感です。
来年はもう少し仕事としてもうまく活用していきたいと思っています。
API
今年もいろんなAPIを触って、CData Driverとコラボレーションしていきました。
いくつか公開している、CData Driverでのプロトタイプは公開していないものも含めてトータル20個近く作ったみたいでした。
公開しているメインどころは以下のようなサービスです。
- BackLog https://www.cdatablog.jp/entry/2019/12/24/113651
- Bizer team https://www.cdatablog.jp/entry/2019/12/18/110759
- CallConnect http://kageura.hatenadiary.jp/entry/callconnect02
- LineWorks https://www.cdatablog.jp/entry/2019/12/10/231250
- SmartHR http://bit.ly/2FcH1NI
PostmanのAPI検証を行ったコレクションもトータル49個と多くなっています。2018年からの差分は取っていないので、このあたりは来年の伸び率もウォッチしていきたいところですね。
2020年に向けて
Blog
Blogの投稿はイベントへの参加と併せてもうちょっと伸ばしたいところです。登壇をスライドで済ますだけでなく、記事にもしておくサイクルが2019年は確立できたかなーというところなので、そこは引き続き同じ用に注力。
API検証記事＋反響が良かったAPI公開記事を別データソースや別シナリオ・クライアントとのコラボレーションで増やして、トータル60くらいを目指せればというところでしょうか。
コミュニティ
登壇は引き続き頑張っていきたいところですが、量的には今の数くらいがやれる範囲かなとも思ったりです。
それよりも、BlogやSNS・Youtubeによるアウトプットの質を高めて行く感じかなとも考えていたりですね。
SNS・Twitter
Twitter の投稿は今まで通り、API注力で。もう少しシナリオペインで、発信していきたいところ。そこまで2019年で意識してツイートしていたわけでも無いので、API検証と併せて1500ぐらいは目指せるんじゃないかなと思ったりです。
Youtube
Youtubeはもうちょっとちゃんとやろうと思ったりでした。
今までは勉強会での登壇を記録したものベースでしたが、そもそも勉強会やイベント登壇前にランスルーをするので、それをYoutube用にキレイに編集して公開していきたいなと考えています。
トータル12本（月1）くらいかなー。
API
個人的に今年一番注力したいのはここですね。
存在を知っていながらも、まだ API 検証が済んでいないものは以下の通りかなーと。このあたりを引き続きCDataも含めてコラボレーションしていきたいところなので、2019年は20件でしたが、2020年は40件ほどを目標にしていく心づもりです。
- esa.io https://docs.esa.io/posts/102
- SenseWay https://www.senseway.net/
- Chatwork http://developer.chatwork.com/ja/
- cacoo https://developer.nulab.com/docs/cacoo/#cacoo-api-overview
- Typetalk https://developer.nulab.com/docs/typetalk/#api-overview
- OKBIZ https://okwave.co.jp/press/20181029-2/ API仕様は未公開
- Connpass https://connpass.com/about/api/
- kibela https://docs.kibe.la/en/collections/211130-api-documents
- Rakuten API https://webservice.rakuten.co.jp/document/
- YahooShopping 商品検索API https://developer.yahoo.co.jp/webapi/shopping/shopping/v1/itemsearch.html
- Waiter https://waiter.smaregi.jp/
- TeamSpirit https://www.teamspirit.com/ja-jp/
- NHK 番組表API http://api-portal.nhk.or.jp/
- 図書館検索API https://calil.jp/doc/api.html
- HotPepper API https://webservice.recruit.co.jp/hotpepper/reference.html
- ぐるなびAPI https://api.gnavi.co.jp/api/
- Line Pay API https://pay.line.me/jp/developers/documentation/download/tech?locale=ja_JP
- GMO Agree https://ir.gmocloud.com/news/press/gmo-hs/170215_2691.html API仕様は非公開？
- MicroCMS https://microcms.io/
- Talknote API https://developer.talknote.com/doc/
その他
Blazor の取り組みは個人的に大きなターニングポイントでした。今まで個人としてWebサービス・アプリを公開したことが無かったんですが、私自身が持っているスキルをうまく活用しながら公開できることもあり、この辺を組み合わせて何か面白いアプリを作って、公開していければなと。
VS Code Snippet も私が今までやっていたものとは大きく違った取り組みでした。拡張機能開発にも興味があるので、会社の製品とも組み合わせて何か公開できればとも画策したり。
Dynamics + PowerPlatformは、社内でCDSを使おうかなーとも考えていることもあり、APIと組み合わせた取り組みを発信していければなと考えています。
