Shiftup! JP_Getshifter Vol5! にて「Shifter + SSG の世界」について発表をしました

2019年8月7日に開催された「Shiftup! JP_Getshifter Vol5 暑気払い!WordPressとJAMstackの夕べ」で『Shifter + SSG(Static Site Generator) が生み出す、新しい WordPress の世界』と題して、WordPress の新しい世界について発表をしました。そのサマリーです。

第3回のイベント Shiftup! JP_Getshifter Vol3! で JAMStack な サーバーレス ウェブフロント に ついて発表 をした際に、Shifter から SSG(Static Site Generator) でサイト生成できたらよいという話で盛り上がり、Shiftup! JP_Getshifter Vol3! 振り返り、Shifter の HeadlessCMS 化に思いを馳せる という記事を書きました。

そしたら Shifter さんの神対応があり「Shifter Webhooksで Netlify上のGatsbyサイトにWordPressコンテンツをインポート可能になりました - 株式会社デジタルキューブ」というアップデートが即だされました。Shifter スゴイ!

その流れから、Shifter で SSG が使えると何が嬉しいのか、どんな世界が描けるのか、当初考えていたことを整理し発表しました。

シリーズの記事

“Shiftup! JP_Getshifter Vol5 暑気払い!WordPressとJAMstackの夕べ” 概要

発表したイベント Shiftup! JP_Getshifter Vol5 暑気払い!WordPressとJAMstackの夕べ は、サーバーレスな WordPress ホスティング Shifter のユーザーコミュニティの勉強会です。

会場は決済サービスの Stripe さん。原宿は竹下口交差点のステキなロケーション&最高な眺めのオフィスです。ちょうど Stripe さんのセッション中に「神宮花火ナイター」の花火が上がり、絶好の眺めとなりました。花火が見えるオフィス、いいなぁ。

発表資料

Shifter + SSG(Static Site Generator) が生み出す、新しい WordPress の世界』の発表資料はこちらになります。(下記、スライド埋め込み)

サマリー

発表の主旨は「Shifter と SSG を使って、WordPress のウェブフロントの新しい考え方を作ろう」です。

おおきく3つのテーマで発表しました。

  1. Shifter が もたらした、新世界
  2. Shifter + SSG が 生み出す、さらなる新世界
  3. Shifter + SSG の 可能性

前半は Shifter の機能やメリットを振り返る内容で、後半から SSG と組み合わせた場合の世界、メリットの話になります。

Shifter が もたらした、新世界

まずは、WordPress と Shifter の違いについてです。WordPress は言わずと知れた世界でもっとも使われている CMS。ウェブサイトの 30% は WordPress と言われているぐらいだそうです。

そんな、すごい WordPress の世界ですが少し困り事も。WordPress サイトの立ち上げまでは、ある程度情報があるし楽しめるところもあります。しかしながら、セキュリティ対策は難しい面もありますし、なにより運用段階での各種バージョンアップ対応が大変。ウェブサイトなので、どうしても不特定多数からアクセスされるのでセキュリテ対策と継続的なバージョンアップは必須です。

そうした中、Shifter は “Serverless WordPress”、”JAMStack WordPress” という形で困り事に対処してくれます。

ひとつは、Serverless WordPress (または Managed WordPressWordPress SaaS)。
Shifter へサインアップしてサイトを作るだけで WordPress の環境が構築される、そして構築された環境のバージョンアップなどのメンテは Shifter がやってくれる。これにより、どれだけの困り事がなくなるか。

もう1つは、JAMStack WordPress
これも Shifter のスゴイところ。「JAMstack 公式」では、WordPress は JAMSstack ではない “A site built with a server-side CMS like WordPress, Drupal, Joomla, or Squarespace. - JAMStack“ と言っています。しかしながら Shifter は JAMSstack として実現しています。
これによりパフォーマンスとスケーリングを実現し、WordPress として本体をさわる人を限定することでセキュリテ問題を局所化&Serverless WordPressでセキュリティ対策をしています。

Shifter + SSG が 生み出す、さらなる新世界

ここまで「”至れり尽くせり” な WordPress = Shifter」ですが、あと1つ。ウェブフロントの開発を WordPress Theme だけでなく、何とかしたい。JAMSstack の技術にしたいというがあります。

それが Shiftup! JP_Getshifter Vol3! で、参加者の皆さま、Shifter の中の人と、お話しさせていただいた「Shifter の WordPress HeadlessCMS 化に思いを馳せる」であり、神対応していただいた Shifter Webhooks + SSG です!

こちらの機能が欲しかったのは、PHP の中に HTML/CSS/JavaScript を書くのが大変、つまり JAMSstack(の “Better Developer Experience”) でない最後の困り事を解決したかった。もし JAMSstack 系の技術だけで WordPress のウェブフロントを作れたらすごいのではないか?そして、その先に?ということです。

Shifter + SSG の 可能性

ウェブフロントの世界では JAMSstack という考えが広まりつつあります。詳しくは JAMStack、それはハイパフォーマンスなウェブフロントを実現するアーキテクチャ を、ご参照ください。

一方で JAMSstack なウェブサイトとはいえデータソースは必要です。JAMSstack が、一番得意なのは情報発信サイト。つまり WordPress のような CMS に投稿された情報発信するようなサイト。

CMS といえば?= WordPress、これまでの話の通り WordPress を使うなら Shifter のメリットを生かすとよいでしょう。そして、ウェブフロントを GridsomeGatsbyJS といった SSG を使って作る。これにより、ウェブ・フロントエンドの技術者が WordPress のサイトでありながら、ウェブ・フロントエンドの技術だけウェブサイトを実現できるようになります。新しい世界が作られ、新たな市場が生まれるといっても過言ではないでしょう。

これまでにも WordPress の Theme を SSG 系の技術(の要素技術といったほうが正しいかな)を使って作る方法はありましたが、SSG だけで作るケースは少なかったと思います。それは WordPress の REST API を使う必要があるからです。そうなると結局 WordPress を運用するので、あえて SSG を使うよりも WordPress の技術スタックで作るほうがよいです。

Shifter により WordPress の構築・運用から解放されることで WordPress + SSG が急浮上します。むしろ通常のウェブフロントの開発と同じになります。純粋にウェブフロントだけを管理するようなモデルが生まれるのではないでしょうか。


Shifter + SSG、新しいウェブサイト開発の潮流になるのではないかと思っています。

SSG を使った JAMSstack サイトの開発としては、データの投入として Headless CMS を使うケースがあります。最近は Headless CMS である Contentful などの名前を聞くケースが増えてきました。

新しいサービスはもちろんウェルカムなのですが、1つだけ困ることがあります。記事を書く人が「そのサービスを使い倒すことができるか?」です。

個人やエンジニアブログなどでしたらよいのですが、技術系ではない人が使うには難しかったり、情報が少なくて調べられない、知ってる人や使ってる人が少ないなどの問題が出てきます。その点で WordPress は No.1 CMS であり多くの情報や利用者がいます。このアドバンテージを生かしつつ、WordPress の構築・運用からは手離れ、ウェブフロントをモダンな技術で手早く作る。

まだ Shifter Webhooks + SSG も出たばかりですし、これからだと思いますが新しい流れができたら、おもしろいですね。

OpenAPI (Swagger) 3.0 で Bearer トークンの使用を定義する

Bearer トークンを使用して WebAPI 呼び出しをする場合、OpenAPI (Swagger) 3.0 ではどのように記述するのでしょうか。

OpenAPI (Swagger) で WebAPI の仕様を記述する際、HTTP 認証・認可を行うための手段として Basic 認証・Bearer スキーム・API キー等の使用を定義することができます。この記事ではアクセストークン等による Bearer スキームの記述方法について紹介します。

※ OpenAPI (Swagger) については以下の記事で取り上げていますので、合わせてご確認ください。

Bearer スキームとは

HTTP 認証スキームの一つで、WebAPI へアクセスするためのセキュリティトークン(アクセストークン等)を Authorization: Bearer {トークン} という形で HTTP ヘッダーにセットし、トークンの受け渡しを行う仕組みです。ここでは詳細を割愛させていただきますが、気になる方は以下をご参考ください。


やりたいこと

WebAPI の仕様として Bearer トークンの使用を明記し、Swagger UI の動作に反映させることです。Swagger UI で見ると、以下のように Authorize ボタンが表示されます。

赤枠のボタンをクリックすると以下のダイアログが表示され、Bearer トークンを入力することができます。

トークンを入れて Authorize ボタンをクリックすると、Bearer スキームが指定されている API は Swagger UI 上から Bearer トークン付きでリクエストが送信されます。

Bearer スキームの Authorization ヘッダーがついていますね。

Bearer という文字列も挿入されますので、こちらで入れる必要はありません。

記述方法

ここでは OpenAPI の記述に YAML 形式を使用します。

  1. components.securitySchemes に Bearer スキームを追加します。
    1
    2
    3
    4
    5
    6
    components:  
    securitySchemes:
    Bearer:
    type: http
    scheme: bearer
    description: Credentials or access token for API

2. Bearer スキームを使用する API を指定します。
1
2
3
4
5
6
paths:
/users/me:
get:
# ...
security:
- Bearer: []

※ ルートレベルの security を定義すると、すべての API に適用されます。

1
2
security:
- Bearer: []

記述する場所を分かりやすくするため、簡単な図で表現すると以下のようになります。
OpenAPI Object の詳細はこちらでご確認ください。

ご参考までに、OpenAPI (Swagger) 2 では、ルートレベルに securityDefinitions を定義して各 API に指定します。OpenAPI 3 になって項目が多少変わっていますので注意が必要です。

いかがだったでしょうか。

前回の記事に続き、Swagger UI を利用する便利さをお伝えしたく、WebAPI 呼び出しに Bearer トークンが必要となる場合の API 定義について記事にしてみました。最後まで読んでいただきありがとうございました。

レイアウト微調整に便利な Spacing Helper (Vuetify) を使ってみる

Web UI を実装する時、追加したパーツが思った通りの位置に定まらず、どうしても微調整をしたくなることがあります。

Vuetify のような UI フレームワークを使用している場合、自前で CSS を書き足したり修正するようなカスタマイズは最小限にしておくことが良いと考えられますが、それでも「ここだけなんとかしたい」という場面が出てくると思います。具体的には margin や padding を指定して要素間の間隔を整えたりすることで、例えば以下のように Helper CSS を定義して対応することが多いのではないでしょうか。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
.p-0 {
padding: 0px;
}

.pt-0 {
padding-top: 0px;
}

.pb-0 {
padding-bottom: 0px;
}

.pl-0 {
padding-left: 0px;
}

.pr-0 {
padding-right: 0px;
}

...

しかし、Bootstrap や Material-UI など、最近のメジャーな UI フレームワークには上記のような CSS Helper Class が予め用意されているので、これらを上手く活用することで、作業効率を高めることができ、きれいなレイアウトに仕上げることができます。この記事では、こういった UI フレームワークの一つ、Vuetify の Spacing Helper Class について紹介します。
※ 詳細は Vuetify 公式ドキュメント にて確認いただけます。

使い方

微調整を行いたい要素に、下記フォーマットを用いてクラスを指定します。

1
{property}{direction}-{size} // e.g. <p class="mt-1" ...

property

margin か padding のどれかを指定します。

  • m : margin
  • p : padding

direction

direction は指定した property の方向を定めます。

direction方向
ttop(トップ)
bbottom(ボトム)
lleft(左)
rright(右)
xleft と right
ytop と bottom
aleft, right, top, bottom 全てに適用

size

size は property のサイズが 4px 単位で指定されます。0 - 12 の数字が指定できます。
くっつけたい場合は 0 を指定します。

サンプルコード

以下、Title + Description 構成のリストに使用したサンプルです。各項目には py-5 を適用して、間隔を広くしています。また description の行には ml-5 を適用して、インデントを作ってみました。

See the Pen [Vuetify] Arrange components with spacing helpers by lopburny (ロップバーニー) (@lopburny) on CodePen.

このサンプルは挙動を確認するためのシンプルなものですが、v-layout や v-card など色んなコンポーネントに適用できますので、何かと微調整が必要な場合に使用してみると便利だと思います。

いかがだったでしょうか。

この Spacing Helper については、前述のように Vuetify に限らず色んな UI フレームワークで提供されています。個人的には特にデザインの要件が無い限り自前で CSS を書きたくない人なのでこういう機能を重宝しますが、好き嫌いに関係なく必要に応じて便利な機能を使っていく姿勢が大事だと思います。記事を読んでいただきありがとうございました。

v-form (Vuetify) の submit イベントによってページがリロードされないようにする

今回は Vuetify でシンプルな入力画面を実装するといった時に遭遇するかもしれない挙動の一つとその対応について紹介します。
v-form の中に一つの v-text-field を配置し、フォーカスを当てた状態で Enter キーを押すとページがリロードされることがあります。
投稿されて1年以上経過しているものですが、以下 Vuetify の GitHub Issue にも Bug Report がありました。


リロードされる原因

この問題、実は Vuetify に限った話ではなく、前からある Implicit submission (暗黙の submit)という HTML の仕様によるもので、バグということではありません。

具体的にはデフォルトボタンによる submit が適用される場合で、入力中に Enter キーによって submit イベントが発火します。HTML の仕様書を読んでみると多少ややこしい記述にはなっていますが、少し抜粋して要約・補足すると下記のようになります。
🔗https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#implicit-submission

If the form has no submit button, then the implicit submission mechanism must do nothing if the form has more than one field that blocks implicit submission, and must submit the form element from the form element itself otherwise.

form内に submit ボタンがない時、

  • 暗黙の submit をブロックする項目が2つ以上ある場合:暗黙の submit は動作しない
  • 暗黙の submit をブロックする項目が1つある場合:Form document の URI へ submit する

と定義されています。

For the purpose of the previous paragraph, an element is a field that blocks implicit submission of a form element if it is an input element whose form owner is that form element and whose type attribute is in one of the following states: Text, Search, URL, Telephone, E-mail, Password, Date, Month, Week, Time, Local Date and Time, Number

暗黙の submit をブロックする項目とは、form の中にある input 要素で、type 属性が Text, Search, URL, Telephone, E-mail, Password, Date, Month, Week, Time, Local Date and Time, Number というものです。

つまり、HTMLとしては「一つのテキストフィールドがある」及び「submit ボタン ( type="submit" ) がない」状態では、 Enter キーを押すことで sutmit するのが正しい仕様ということですね。

v-form コンポーネントを使用する場合、ボタンに v-btn を利用すると type="button" となるため、ブラウザによって暗黙の submit として扱われるようになることが原因となります。

CodePen で再現してみると以下のようになります。
※ Vue.js 2.6, Vuetify 2.0 を使っています。

See the Pen (Vuetify) v-form reload issue sample by lopburny (ロップバーニー) (@lopburny) on CodePen.

解決方法

以下のように submit イベントを抑えてしまいます。

1
2
<v-form ref="form" @submit.prevent>
<v-text-field ...

CodePen のサンプルはこちらです。
※ Vue.js の省略記法を使っています。

See the Pen (Vuetify) v-form reload issue sample - resolved by lopburny (ロップバーニー) (@lopburny) on CodePen.

Vue.js 公式ドキュメント にも、ピンポイントで対応方法が記載されています。

1
2
<!-- submit イベントによってページがリロードされません -->
<form v-on:submit.prevent="onSubmit"></form>

ユーザーに対して明示的に submit ボタンを押してもらうアクションを期待している場合は、これで解決します。
form 要素の submit イベントを抑制し、ボタンを押したときのクリックイベントで対応する形です。

しかし、あえて Enter キーを押した場合に submit イベントを発火したいということもあります。
Vuetify の場合、v-form コンポーネントと各入力要素の rule 属性によるバリデーションを実装することが多いので、このケースはあまりないかと思いますが、一応上記に加え下記のように対応することで実現できます。

1
<v-text-field @keyup.enter="customMethod()"></v-text-field>

いかがだったでしょうか。

今回紹介した挙動については、古くからある HTML の仕様なので Vuetify に限らず多くの記事が出ておりますが、
Vuetify 特有のバグや癖だと思ってハマることもあるかと思い、記事にしてみました。
最後まで読んでいただきありがとうございました。

Vuetify 2.0 で追加された v-banner を使ってユーザーのアクションを促すボタン付きバナーを作る

先日、Vuetify 2.0 がリリースされ、新しく追加されたコンポーネントの中で個人的にほしかったものを一つ紹介したいと思います。
※ 2.0のリリースで追加された機能とコンポーネントの一覧は、こちら🔗で確認できます。

Material Design 2 で登場した Banner ですが、ユーザーに「確認してほしい」メッセージと、「やってほしい」アクションのボタンを組み合わせて提示するコンポーネントです。Dialog や Snackbar でも似たようなことは実現できますが、その使い方については以下のように定義されています。

コンポーネント優先度ユーザーアクション
Snackbar任意。Snackbar は自動で表示されなくなる。
Banner任意。Banner はユーザーによって非表示ボタンが押されるか、Banner を出す原因となった状態が解決されるまで表示される
Dialog必須。Dialog はユーザーが提示されたアクションを実行するか閉じるまでアプリの使用をブロックする。

※ Material Design 2 > Banners > Usage 抜粋 🔗

Banner は画面に一つのみ表示されるものとして、ユーザーにとって見やすい場所、つまり Top App Bar とコンテンツの間に配置されることが想定されています。Material Design 公式ドキュメントで紹介されている使い方の他にも、重要なメンテナンス予定の告知、アンケートやフィードバックの依頼、キャンペーン等の用途にも応用できるので、結構助かります。わざわざ Dialog を実装するほどでもないし、自動で表示されなくなる Snackbar だとユーザーに気づかれない場合に Banner を使うと便利かなと思います。

VBanner (v-banner)

Vuetify 2.0 のリリースにて VBanner コンポーネントが追加され、Web UI で使えるようになりました。Vuetify では、single-line / two-line / multi-line とメッセージの行数を指定、メッセージとボタンに加えてアイコンを表示することができます。下記、一般的に使われそうな用例を2つ紹介します。

single-line + アクションボタン

画面イメージ

サンプルコード

1
2
3
4
5
6
7
8
9
<v-banner single-line>
ここにバナーのメッセージが入ります。
メッセージが長くなれば文末が ... という感じで省略されます。

<template v-slot:actions>
<v-btn text color="deep-purple">DISMISS</v-btn>
<v-btn text color="deep-purple">RETRY</v-btn>
</template>
</v-banner>

アイコン + two-line + アクションボタン

画面イメージ

サンプルコード

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<v-banner two-line>
<v-avatar slot="icon" color="deep-purple" size="40">
<v-icon color="white">
device_unknown
</v-icon>
</v-avatar>

デバイスの画面サイズに合わせてメッセージの文字数を確認しておく必要があります。
通常は 1-2 行が望ましく、簡潔で理解しやすい文章にすることが重要です。

<template v-slot:actions>
<v-btn text color="deep-purple">LEARN MORE</v-btn>
<v-btn text color="deep-purple">GOT IT</v-btn>
</template>
</v-banner>

いかがだったでしょうか。

Vuetify の公式ドキュメントには色んな設定値を適用して表示を確認できる Playground🔗 が提供されています。是非試してみてください。

現時点(2019年7月下旬)では Vuetify 2.0 がリリースされて間もないので、いきなり更新すると色々問題もあったりするみたいですが、そのうち改善されることを期待しています。これからのアップデートも楽しみですね!

CloudNative Days Tokyo 2019 にて「サーバレス・ネイティブ が お伝えする、フルサーバレス開発の魅力」の発表をしました

2019年7月23日に開催された「CloudNative Days Tokyo 2019」で『サーバレス・ネイティブ が お伝えする、フルサーバレス開発の魅力』と題して、サーバーレスの魅力について発表しました。その発表サマリーです。

“CloudNative Days” 概要

発表したイベント CloudNative Days Tokyo 2019 は、元は ContainerDays というイベントで今年の4月から CloudNative Days と名称が変わりました。また今回は OpenStack Days Tokyo 2019 との共同開催です。4月の福岡をスタートに、7月の東京、11月の大阪と続きます。

会場は虎ノ門ヒルズフォーラム。はじめて行きました。地下鉄虎ノ門駅から細い歩道なので少し距離がある感じはしますが、新橋にも出られたりといい感じの場所です。

発表資料

サーバレス・ネイティブ が お伝えする、フルサーバレス開発の魅力』の発表資料はこちらになります。(下記、スライド埋め込み)

サマリー

発表の主旨は「コンテナーもいいけど、サーバーレスもスゴクいいからね。ぜひ!」です。
大きく4つの観点からサーバーレスの魅力をお話しました。

  • アイデアを即、形にできる 魅力
  • アプリの開発に専念できる 魅力
  • ピタゴラ装置を組み立てる 魅力
  • JAMStack な サイト管理の 魅力

アイデアを即、形にできる 魅力

モバイルアプリのハッカソンで、ラップバトルの動画中継と配信をするアプリを作ったのを例に、いかに高速でアプリが開発できるかを話しました。

動画の取り扱いとなると、かなり手間がかかるのですが SkyWay - Enterprise Cloud WebRTC Platform を使うことで容易に動画中継と配信を実装できました。

また対戦ルーム管理などは Lambda と DynamoDB で構築しています。Web API を簡単に構築できる基本的な構成になります。「👍」やチャットなどのリアルタイムのコミュニケーションは Fibrebase を使い、マルチクラウドの構成となっています。

クラウドがさまざまな機能を用意してくれ、また SaaS によって必要な機能を組み合わせられるので、24時間という限られた時間でも動画を扱うようなアプリを作ることができます。この高速な開発力はアイデアをすぐに形にできる、サーバーレスの魅力のひとつといえるでしょう。

アプリの開発に専念できる 魅力

IoT 製品のバックエンドを構築した際に、実行ランタイム(= 開発言語) を切り替えるというケースがあったのを例に、その様な事態でもアプリの開発(コーディング)だけに注力できるという話をしました。

このプラットフォーム開発当時、Lambda の Java ランタイムは初期起動(コールドスタート)が遅いという問題がありました。それでも多くの場合、処理が遅いと感じるレベルで大問題にはならないのです。しかしながら私たちの場合はマイクロサービスとして、いくつもの Web API を相互呼出しする形になっていました。そのため初期スタートに当たる確率も高くなり、また初期スタートに当たるとリクエストがタイムアウトしてしまう問題へつながってしまいました。

いくつかあった解決策から実行ランタイムを Java から Node.js へ切り替えるという決断をします。開発言語が Java から JavaScript へ変わるのですが、TypeScript を導入することで Java チームとしても静的型付けによる親和性により切り替えに成功し、問題を解決しました。

実行ランタイムを変えるのはかなりの変更となりますが、AWS では監視やログなどが構成済みのため変更箇所はプログラムの再実装だけになります。ミドルウェアやスケールアウトさせるための仕組みなどを考える必要がないので、アプリ開発に専念できる魅力があります。

※ 補足
2019年7月現在、Lambda の起動が高速化され Java ランタイムのコールドスタートでも1秒ぐらいで起動しています。Java 実装が残っている部分で処理速度の確認があり気づきました。簡易で調べた結果なので、きちんとした検証は必要ですが、かなり改善されたのではないでしょうか。
またサービス提供者が性能を向上させてくれることで、システムのパフォーマンスが自動的によくなるメリットもあるとも言えるでしょう。

ピタゴラ装置を組み立てる 魅力

クラウドの機能や SaaS の機能を組み合わせることを「ピタゴラ装置」に見立てて、お話しました。”ピタゴラ装置は NHK Eテレの番組『ピタゴラスイッチ』に登場するからくり装置 - Wikipedia“ です。最初のきっかけ以降は運動エネルギーを引き継いで流れていくもので、いわゆるドミノの複雑版といった感じです。

サーバーレスのイベント駆動でつながる処理がまさにピタゴラ装置的で、最初のイベントを受けて以降、次々と処理が流れていきます。たとえばラップバトルのピタゴラ装置は以下です。

スマホアプリからルームの作成処理を API Gateway へリクエストします。API Gateway から Lambda が起動し、DynamoDB へルームのデータを登録します。
続いて通知を送るのですが、よくあるのが Lambda で「DB登録 ⇒ 通知」と処理を続けること。しかしイベント駆動で流すので、ここは DynamoDB Streams を使ってデータ登録のイベントから Lambda を起動して通知の処理をします。

このような形でクラウドの機能や SaaS を活用してアプリやシステムを組み立てていきます。これにより実装がシンプルになります。さまざまな機能を組み合わせつつ、シンプルな作りをする。これは楽しくもあり、多くのメリットを享受できる魅力とも言えます。

JAMStack な サイト管理の 魅力

JAMStack、最近 話題になりつつあり、フロントエンドやウェブの開発などで見聞きする機会が多いキーワードです。

サーバーサイドをサーバーレスで構築していても、フロントのためにウェブサーバー(動的な処理ができるサーバー)を用意するケースが多く、どうしてもシステム全体でサーバーレスにできないケースがあり、最近は JAMStack を推進しています。

JAMStack を簡単に言ってしまうと、HTML は事前生成してリクエスト時には動的に生成しない。動的要素はブラウザ(クライアントサイド)の JavaScript で Web API 等を呼び出して作るようにするということです。

これにより、HTML は CDN に配置されウェブサーバーは必要としません。フロントを含めてサーバーレスにできます。サーバーレスであれば JAMStack でなくともよいのですが「フロントもサーバーレスで」というより「JAMStack で」といったほうがわかりやすいので、そのように言っています。

また JAMStack という観点からは、Serverless WordPress の Shifter という素晴らしいサービスがあるので紹介します。

利用者としては、Shifter で WordPress を起動してコンテンツを編集。コンテンツの編集が完了したらサイト生成して、コンシューマー向けの静的サイトを作り、そちらへアクセスしてもらいます。これにより WordPress 本体へアクセスされないのでセキュリティを高められますし、静的サイトなので高速です。まさに JAMStack の思想を実現したサービスといえます。

コンテンツ管理はさまざまなサービスがあり、最近では「ヘッドレス CMS」なども登場していますが、やはり WordPress の使いやすいさ、そして認知度の高さは外せません。コンテンツ管理の仕組みが必要な場合は検討したいサービスです。

8/7(水) には、Shifter と Static Site Generator を組み合わせた、WordPress の新しい活用についてお話しますので、良かったらご参加ください。

まとめ

サーバーレスに興味を持っていただけましたら、ぜひ 10月の ServerlessDays Tokyo へお越しください。国内最大のサーバーレスのイベントです。


元が ContainerDays という名前の通り、Docker や Kubernetes のセッションが多い構成の中、「サーバレス・ネイティブ」だの「フルサーバレス」というかなりイキり気味のセッションを採用いただけ、そして当日も空いているのが数えられるくらいの数席を、満席でのご参加いただきありがとうございます!

サーバーレスへの関心につながりましたら幸いです。

共有:

OpenAPI (Swagger) を利用して効率よく WebAPI の仕様を管理する

Web 開発の現場でよく耳にする言葉として Swagger というものがあります。アプリケーション開発においてサーバー(WebAPI)とデータの送受信を行う機能は不可欠なものとなっている現在、多くの現場ではそのための設計モデルとして REST (REpresentational State Transfer) という方式が使われています。この記事では、REST API の仕様ドキュメントを記述する手段として OpenAPI (Swagger) というものを紹介し、REST Client 機能を備えたインタラクティブな API 仕様ドキュメントを作成・共有する方法についてお伝えしたいと思います。

OpenAPI (Swagger) とは?

OpenAPI Specification (OAS) といい、REST API の仕様を記述するためのフォーマットです。また Swagger とは、Open API を使用するツールのことで、以下のようなものがあります。

  • Swagger Editor
  • Swagger UI
  • Swagger Codegen

OpenAPI は、元々 Swagger Specification として知られています。REST API を定義するフォーマットの標準化を推進する団体 OpenAPI Initiative (OAI) が結成され、OAI の一員であり Swagger の開発元でもある SmartBear Software により Swagger Specification が寄贈(Donation)されたことで、Open API と言うようになりました。現場では Swagger の方が馴染みがあるので、OpenAPI と言うところはまだ少ないかもしれません。OAS 2.0 は Swagger Specification 2.0 に対応しており、現在(2019年7月)最新バージョンは 3.0 です。

OpenAPI を利用するメリット

OpenAPI を利用すると何が良いのか、いくつかピックアップしてみました。

API 定義のバージョン管理が楽になる

基本的に YAML または JSON で記述するため、Git 等を使用してソースコードと同様に管理することができます。つまり、Word, Excel で記述された仕様書に比べて更新履歴を管理していく努力が削減されます。API 定義ファイルと実装を一緒にコミットすることで仕様と実装が乖離しにくくなるため、より正確かつ最新の情報を共有することができます。

仕様が明確になる

OAS のフォーマットに合わせて宣言的に書いていくことで曖昧な記述がなくなります。またデータの仕様を明記するための各種データ型がサポートされているので、仕様が明確になります。Swagger UI を利用する場合、Markdown で記述された項目の表示もサポートされ、細かい仕様や注意点を分かりやすく表現することができます。

WebAPI の仕様管理を仕組み化することができる

Swagger UI から API 定義ファイルを読み込むことでインタラクティブな Web ドキュメントを作成することができます。別途 REST Client を使うことなく Swagger UI 上で動作確認ができてしまいます。また Swagger Codegen を使ってクライアントライブラリ(SDK)を自動生成することもできますので、WebAPI を叩くクライアント側の実装も楽になります。

Amazon API Gateway を利用する場合、API 定義ファイルをインポートすることで API をデプロイすることができます。逆にソースコードから API 定義ファイルを生成する仕組みもあるので、実に色んな使い方ができます。API 定義ファイルの操作を CI に組み込むことで、仕様書の更新・クライアントSDKの生成と配布・WebAPIのデプロイなどをまとめて自動化することが可能になります。

※ OAS 2 と 3 でフォーマットが異なりますので、サービスによってサポートされる OAS バージョンに注意する必要があります。

OpenAPI 導入イメージ(例)

構成の概要としては、

  • API定義ファイルは GitHub で管理
  • Swagger UI を SPA(シングルページアプリケーション)として静的サイトホスティング
  • CircleCI に連携して API 定義ファイルをアップロード

といったところになります。

※ Swagger UI を自前でホスティングしないで SwaggerHub 等のサービスを利用する方法もありますが、この記事では割愛させていただきます。詳細はこちらをご参考ください。

Open API を利用して API 定義を作成する

YAML または JSON で API 定義を作成します。個人的には宣言的でコメントも書ける YAML の方がオススメです。作成にはどのようなエディタを使っても問題ないですが、編集時にリアルタイムで Swagger UI のプレビューを表示してくれる Swagger Editor が便利です。Validation までしてくれるのでとても助かります。フォーマットの仕様については、こちらをご参考ください。

※ OAS 2 と 3 でフォーマットが異なりますので、Web 等に掲載されているスニペットを参考にする場合は注意が必要です。

引き続き、作成した API 定義を Swagger UI で表示するため、メニューの「File」から「Save as YAML」を選択し、サンプルの API 定義を保存しておきます。

Swagger UI を使用して API 定義ファイルを読み込む

Swagger UI を API 仕様ドキュメントとして活用するためには、Swagger UI (SPA) と API 定義ファイルをホスティングする必要があります。例えば、以下のような構成にすることができます。

項目内容
Swagger UIhttps://docs.sample-api.dev/swagger-ui/index.html
API 定義ファイルhttps://docs.sample-api.dev/api-definitions/{Gitブランチ名}/sample.yml

クエリパラメータに API 定義ファイルの URL を指定することで読み込まれます。

1
https://docs.sample-api.dev/swagger-ui/index.html?url={API定義ファイルのURL}

また、API 定義ファイルのパスに Git ブランチ名を指定して CI を回すことで、API 定義ファイルそのもののバージョン管理ができるだけでなく、レビュー中のブランチについても仕様の確認が容易にできるような仕組みづくりが可能になります。

Swagger UI を SPA としてホスティングする

Swagger UI の GitHub リポジトリにて、ソースコードをダウンロードして解凍、 dist というディレクトリをまるごと静的サイトホスティングすれば OK です。

このまま他の API 定義を読み込みたい場合は、下の赤枠に URL を入力して右側「Explore」ボタンを押します。各 API の項目を広げて「Try it out」、パラメータを入力して「Execute」することで、Swagger UI 上で API の動作確認ができます。別途 REST Client を使う必要がなく、とても便利です!

静的サイトホスティングについては色んな方法がありますが、AWS 環境であれば別の記事でやり方を紹介しておりますので是非ご参考ください。Swagger UI を用意して社内向けまたは開発パートナー向けにアクセス制限をかけて共有するなど、色んな利用シーンが考えられるのではないでしょうか。

まとめ


  • OpenAPI をうまく利用することで、API 仕様の明確化・管理の効率化が図れる
  • Swagger UI をインタラクティブな API 仕様ドキュメントとして活用する

いかがだったでしょうか。

OAS で API 定義を書いていくと、かえって記述量が増えて疲れるようになったといった意見もありますので、この記事の内容がすべての現場にフィットするとは限りません。ですが、ある程度規模が大きく、人の入れ替わりも多いような現場であれば、仕様ドキュメントの管理をしっかり行いたいということもあるのではないかと思います。今後も OAS と Swagger の使い方について具体的に紹介していきたいと思いますので、まだ使ったことないよー!という方がいましたら、是非試してみてください。

勤怠を自動化する技術 LT Nightで、Web-NFC の PWA について LT しました

2019年7月19日に開催された「勤怠を自動化する技術 - LT Night」で LT & 新作アプリのデモをしました。発表のサマリーです。

イベントの説明にあります通り、すべてはココから始まりました。

見かけた際に即 Like し、RT。開催されるだろうかと、ワクワクしてました。勤怠時間の管理については言いたいこともあれば、やってみたいこともある!そう思いながら日々過ごしてたら、ほんとに開催されました 「勤怠を自動化する技術」LT Night - connpass

即刻、参加に申し込むも絶望的な順位(皆さん、早!)。どうしても参加したかったので、空いていた LT 枠に切り替えました。もともと勤怠の時間管理のためにアプリを作るつもりでしが、LT 枠のために前倒し。かなり無茶なスケジュールでの参戦となりましたが、結果として発表できてよかったです。素晴らしい機会に感謝です。ありがとうございます!

発表資料

『Web-NFC の PWA で 簡単タイムレコーダー「ツカエタルヒの記録」』の発表資料はこちらになります。

サマリー

以下の内容で構成しました。

  • 私の現在の勤怠管理
  • 「ツカエタルヒの記録」紹介

私の現在の勤怠管理

簡単に言ってしまうと、毎日 Excel に手入力して、翌月初に上司のサインをもらうという仕組みです。ただし途中で「印刷、サイン、PDF化」が繰り返されるのでかなり大変。もちろん、人手によっているのでトラブルが多発します。

これは、話しててヤバいなと思いつつ、参加者さんからもヤバい旨のツイートがありました💦

「ツカエタルヒの記録」紹介

流石に Excel 管理の仕組み自体は変えられないので、毎日の手入力を支援するツールを自作しました。(本 LT に向けて、3日間の夜なべ仕事だったので、公開に向けてはリファクタリングしないとなので、公開は今しばらくお待ちください。)

Web NFC API を使った PWA です。PWA なので、ブラウザで動作し、またアプリとしてインストールすることもできます。

市販の NFC Tag へアプリで使うデータを書き込むことで、スマホをかざした際に出退勤の時刻を記録します。(Suica などの FeliCa 系は読み書きできません)

せっかくなので「ログインボーナス」「月曜日ボーナス」機能も導入しました。今回のデモ用には るるてあ (@k_r_r_l_l_) さんの「肯定ペンギン」を使わせていただきました。(アプリ公開に当たっては何か別のにしないとですかね。”イラストのアイコン・ヘッダー使用はご自由にどうぞ。画像の商用利用はお控えください。 - るるてあ (@k_r_r_l_l_) / Twitter“ なので大丈夫な気もしますが使わせていただくとなると確認はしないと)

Web NFC は 2019年7月現在、Android の Chrome のみ対応しており iPhone では利用できません。その場合は画面右上の [⏰] アイコンから記録できます(それ以前にアプリを使っていただくことはなさそうですが)

今後としては、まずはリファクタリングして公開を急ぎます。また現在はブラウザのローカルストレージにしかデータを保存していないので、Google スプレッドシートへ保管するようにしたいです。これがないと Excel へ転記するのが大変。また、今回のイベントの会場&懇親会の提供をしてくださった Freee さんの 人事労務API 概要 | freee Developers Community などにも対応してみたいです。

なお「ツカエタルヒ」は 上日(ジョウジツ)とは - コトバンク の “日本古代の律令官人の出勤日数。〈つかえたるひ〉ともよむ。” から付けました。なんと出勤日数の管理および評価は平安時代から変わってなさそうな感じ。(しかも夜の会議と称した酒盛りとか、日勤15の夜勤5で20時間労働のブラック - 平安貴族のお仕事、実はかなりブラックな労働環境だった? - ZAK女 - ZAKZAK とか、1000年以上も同じことを!?ヤバい)

所感

ログインボーナスについて

ログインボーナスについては、ぜひ拡張を続けて何かおもしろいことができたらと思います。

スポンサーセッションの 勤怠打刻の基礎知識 で勉強させて頂いた通り、勤怠管理の仕組み自体を作るのは法律の知識をはじめ、さまざまな勤務形態に対応する必要があります。その部分はやはり専門の SaaS にお任せするのがよいでしょう。

一方でクライアント部分は、もっと自由な発想があってもよいと思います。むしろ、そこが足りてないから入力するのを嫌がられたりするわけです。その嫌われに対処するには、大きく2つあると思っています。

1つは完全に透過してしまい意識させないこと。これは入館ゲート(駅の改札みたいなやつ)を使ったり、GPS や WiFi 使ったりと、まさに自動化する仕組みです。もっとも、今回の会場の Freee さんみたいにオフィスに卓球台があったり、バーのある会社さんもあったりと最近は「会社にいる=仕事している」とは限らない状況もあるので難しいところです。

もう1つは、楽しくすること。使いたくすること。そのためにログインボーナスを作ってみました。効果があるか、まだ何とも言えないですが。また画像が出るだけでは楽しくないので、もっと何か良い仕組みを考えたいと思います。ここはクライアント部分だけで作れるので、アイデアの出しどころですし、作りがいのあるところだと思います。

ハッカソン、ワークショップについて

今回さまざまな発表を聞かせていただく中で、皆さん色々なものを作っているなぁと思いました。

せっかく今回のように色々なものを作る人が集まるのだったらハッカソンとかにしてもおもしろいだろうなぁと。

次回移行も Freee さんが開催してくださるかはわかりませんが、せっかく API を公開されているので、ワークショップにしたり、API 利用を前提としてのハッカソンなどがあると盛り上がりそうです。


いろいろなイベントで発表させていただいてきたのですが、LT は初めてで時間の制約を気にして緊張しました。限られた時間の中で精一杯話すのはとても楽しく、また次の機会に LT できたらと思います。

「勤怠を自動化する技術」ならぬ「勤怠を楽しくする技術」については、あと2つほどネタがあるので、ぜひ第2回、3回と会が連なり、そしてハッカソンなりと盛り上がると嬉しいです。

Git で管理しているファイルの変更追跡を一時的に無視したい

Git を使って開発しているプロジェクトで、トラブル対応や機能のテストのために一時的に変更を加えた状態で作業をしたい、ただし一時的な変更なのでコミットしたくないといったことがあります。このような場合に skip-worktree を使うと、変更の追跡を一時的に無視できます。

特定のオプションを有効にしている場合に発生する問題への対応のために設定ファイルを変更している、しかしオプションはコミットしない。そうそうあることでもないですが、このようなパターンで一部変更しながらもコミットしたくないというケースがあります。そして慎重に作業を進めつつも、うっかりコミットして面倒なことに。。。

最初からコミットするつもりがない変更については明示的に外してしまうのも手です。

環境
本記事の開発環境は以下となります。

  • Windows 10 64bit + WSL Ubuntu 18.04.1 LTS
  • Git 2.17.1 (WSL Ubuntu 18.04.1 LTS)

参考情報

git update-index –skip-worktree で無視

指定するパスを Git の変更追跡から無視する設定が git update-index --skip-worktree <path> です。

このオプションを指定すると変更追跡から無視されるので、ファイルを更新しても Git の変更に乗りません。たとえば変更したファイル config.json があったとします。Git で状態を見ると以下のようになります。

1
2
3
4
5
6
7
8
9
10
11
$ git status
ブランチ master
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)

modified: config.json

no changes added to commit (use "git add" and/or "git commit -a")

そこで変更追跡から無視して再度確認してみます。変更対象に入っていないことがわかります。

1
2
3
4
5
6
$ git update-index --skip-worktree config.json
$ git status
ブランチ master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

また skip-worktree 設定しているファイルは以下のコマンドから確認できます。

1
2
$ git ls-files -v | grep ^S
S config.json

これにより誤りコミットを避けることができます。

変更管理対象に戻す

戻すためのオプションは --no-skip-worktree です。最初に no が入っています。

1
2
3
4
5
6
7
8
9
10
11
12
$ git update-index --no-skip-worktree config.json
$ git status
ブランチ master
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)

modified: config.json

no changes added to commit (use "git add" and/or "git commit -a")

リモートで更新された場合

変更追跡から無視している状態で、そのファイルがリモートで更新されたらどうなるでしょうか。

もし、まだ変更していない場合(無視する設定だけした)は、リモートの更新をマージできます。これは通常の Git 管理と変わらず特別なことは何もありません。

変更してた場合、残念ながらマージできません。いったん --no-skip-worktree して、変更を stash するか、何らかの対応をします。


ちょっと変更をキープしながら、作業をしなければならない時などに便利です。

ただしリモートで変更されてしまうと結構手間なので、長期にわたって使うものではないかもしれません。なにしろローカルの変更があるのでマージできないというエラーが出るのに git statusnothing to commit, working tree clean って、無視設定したことを忘れてると混乱しますから。

AWS WAF を使用して IP ホワイトリストによるアクセス制限を行う方法

前回の記事では AWS 上に静的サイトをホスティングする構成について紹介しました。この記事では、CloudFront のディストリビューションに AWS WAF で作成した Web ACL を関連付け、IP ホワイトリストによるアクセス制限を行う方法についてお伝えしたいと思います。

例えば以下のようなコンテンツで、サイトを外部に公開したくない場合において有効です。

  • WebAPIの仕様、開発ドキュメント ※ Swagger UI など
  • 社内向けサイト
  • 開発中のウェブアプリ

この記事で紹介する構成



  • CloudFront のディストリビューションに AWS WAF を使用してアクセス制限をかけます。
  • クライアントによる S3 バケットへの直アクセスはできません。
  • AWS WAF は Origin の種類に関係なく関連付けることができます。

設定の手順

以下の一連の作業を行う必要があります。
まず、AWS WAF のコンソールを開き、「Go to AWS WAF」 を選択します。

Create web ACL を選択すると以下の画面が表示されます。

  • Web ACL name を入力します。
  • Region については、「Global(CloudFront)」を指定します。

※ AWS resources to associate で関連付ける AWS リソースを指定することができます。ここですでに作成済みの CloudFront ディストリビューションを指定しても OK ですが、この記事では別途 CloudFront のコンソールから指定することにします。

「Next」をクリックして次の設定に移ります。

ここでは「IP match conditions」を選択します。

ここで許可したい IP アドレスを登録します。名前・IP Version・Address を入力して、「Add IP address or range」をクリックします。複数のIPアドレスを登録することもできますので、許可したい IP アドレスがたくさんある場合はどんどん入れていきましょう。

登録が終わったら、画面下の「Next」をクリックします。

ルールの名前、Rule type、条件(Condition)を指定します。

先程作成した IP アドレスのリストが反映されていることを確認し、「Create」をクリックします。

作成したルールの Action は「Allow」を選択、Default action は「Block all requests that don’t match any rules」を選択します。これでこのルールにマッチしなかった IP アドレスはブロックする挙動になります。

準備ができたら「Review and create」をクリック、問題なければ「Confirm and create」します!

先程 AWS resources to associate を設定しておいた場合、このまましばらくすると反映されるようになります。AWS WAF のコンソールではなく CloudFront のコンソールで設定する場合は、ディストリビューションの設定にて「General」タブを選択、以下の場所から設定することができます。

修正してしばらくすると適用されます。WAFによってアクセスがブロックされた場合、以下のようなエラー画面が表示されます。

Web ACL のコンソールを見ると、どのようなリクエストがあったか確認することができます。便利ですね!

アクセスログを取得したい場合は Web ACL のコンソールから Logging タブを選択して有効化することもできますが、この記事では割愛させていただきます。

AWS WAF で作成する項目として 許可する IP アドレスのリスト・ルール・Web ACL の3点を押さえておくと分かりやすいと思います。Web ACL を削除する時、この順番で消していかないとエラーになりますのでご参考ください。

いかがだったでしょうか。

AWS WAF は、ALB(アプリケーションロードバランサー)と API Gateway にも関連付けることができます。ただし、その場合は Web ACL のリージョンを指定する必要があります。

IP アドレス制限のみならず、色んなルールを設定することができますので、是非試してみてください。