はじめに
スマレジという非常に多機能なPOS・勤怠管理システム・オーダーシステムを低価格で提供しているタブレットPOSサービスがあるのですが、2020年8月1より、アプリマーケット上の『アプリ』という形で開発者が独自に機能を追加し、スマレジユーザーに売ることが出来るサービスが開始しました。
スマレジ本体のデータのほぼ全てがAPIで公開されているため、店舗の売上や勤怠のリアルタイムのデータを取得できるなど、非常に面白いサービスなのですが、アプリマーケットが賑わわないと、そもそもアプリが使われません（MacのApp Storeがいい例ですね）。アプリ開発にはSaaSサービスとの連携アプリともあって、OpenID Connectなど最低限の実装が少し高いハードルになっています。
そのため、これらの最初に躓く部分を出来る限り取り払い、簡単にアプリを作れるテンプレートとして「スマレジアプリ・スターターパック」を作りました。このパックを使うと、アカウント取得などの事前準備が終わっていれば、約５分でアプリを作成し、スマレジのプラットフォームとつなぐことができます。
OpenID Connectでのログイン機能もスターターパックで提供されるので、アプリの機能に集中することができます。スターターパックという名前の通り、実装したい機能を簡単に追加できるようにしているため、このパックを元に本番アプリの作成・公開も可能です。
本記事では、スターターパックの概要と使用方法を書いています。スターターパックの詳細なしくみやアーキテクチャについては後日別の記事で書きますが、仕組みを理解していなくても問題なくアプリを動かせるようになっています。
特徴
こちらのスターターパックを使うだけで、スマレジのOpenIDでログイン機能を持ち、契約期間内の契約者にはHello Worldを表示するアプリをGoogle Cloud上でデプロイすることができます。アプリの部分を最低限にしていますので、まずHello Worldアプリを実装できたら、簡単にアプリで実装したい機能を追加していくことができます。
以下のような特徴を持っています。
- ユーザー数が100人程度で、月あたりのログイン数が1000アクセス程度の想定で、月額約3円のクラウドコストで収まる設計
- ユーザー数が10万人となっても落ちないスケールアウト設計
- IaCに沿ったパッケージのため、インスタンスの設定やデプロイもすべてコード化されています。ローカルで起動して簡単にテストができ、デプロイもスクリプトを走らせるだけです
- 障害時・エラー時にすぐにアラートが来るようにデフォルトで設定済みです（解除も可能）
構成
全体がサーバーレス構成となっております。Google CloudのFaaSであるCloud Functionを使う構成です。サーバー等のミドルウェアはGoogle Cloudで管理されるため、開発者はそのミドルウェア上で動くコードだけを開発・デプロイすればよい形です。
データベースにはFirestoreというNoSQLを使っておりますが、アプリからの使い勝手もよく、データの確認もGUIで簡単にできます。
- Python3.8ベース
- メインコンポーネント：Cloud Function＋Firestore
- サブコンポーネント：Cloud Storage（実行バイナリの保存先）、Error Reporting（アラート用）
必要要件
- MacOSでの開発を想定（スクリプト構成のため）
- Google Cloud環境
- Docker環境
パッケージのダウンロード
GitHubでホストしていますので、こちらからgit cloneしていただくか、ZIPでダウンロードして下さい。
スマレジ・スターターパックのGitHubレポはこちら
使い方
手順の概要
- Google Cloudで新しいプロジェクトを作成：30秒程度
- Google Cloudのウェブ画面からFirestore（データベース）を作成：30秒程度
- スターターパックの初期化スクリプトを実行：1分程度
- （並行して）スマレジのアプリを作成し、IDやキーをスターターパックの設定ファイルにコピー：30秒程度
- メイン画面のコードをデプロイし、URLを設定ファイルにコピー：1分半程度
- 残りの２つのコンポーネントをデプロイ：1分程度
1・２・４のステップ以外はすべてスクリプトで自動化されているので、デプロイのやり方などを知らなくても全く問題ありません。合計で時間は５分ほどかかりますが、ほとんどが待ち時間となります。これらの手順の前に、事前準備で必要なものを揃えておいて下さい。
事前準備
必要な事前準備は以下の通りです。すでにインストール済みであれば、各項目はスキップしていただいて構いません。
1. スマレジの開発アカウントの取得
2. Google Cloudのアカウント取得、CLIツールのインストール
3. Dockerのインストール
スマレジのシステムとの連携の関係で、ローカルサーバーだけではアプリを動かせません。パブリックにアクセス可能なサーバーが必要な関係上、スターターパックではGoogle Cloudでのデプロイを前提にしてます。今後、AWSやAzure等で提供できるように機能追加予定です。（もしくは有志の方、ぜひPRお待ちしています！）
1. スマレジ開発アカウントの取得
こちらにスマレジ公式のチュートリアルがあありますので、こちらの通りにセットアップして下さい。
2. Google Cloudの準備
Google Cloudは約３万円ほどの無料枠があるので、スターターパックを走らせても課金されることはありません。また、１ヶ月スタータパックを走らせても、100ユーザー程度では月10円もかからず運用できますので、ご安心下さい。必要無くなれば、プロジェクトを消すことで、全てのリソースを削除できるため、追加で課金が発生することもありません。
こちらの公式ページから始められます。Googleアカウントとクレジットカードの登録が必須となりますが、課金はデフォルトでオフになっており、課金されることはありません。また、CLIツール（Google Cloud SDK）が必須となるため、こちらの公式ガイドにしたがってGoogle Cloud SDKをインストールして下さい。
3. Dockerのインストール
ローカル環境で開発ができるように、Dockerベースのスクリプトを用意しています。こちらの公式ガイドにしたがってDocker Desktop for Macをインストールして下さい。インストール後、以下を実行してみて動けば問題ありません。
docker run --rm helloworld
これですべての事前準備が完了です！
詳細な手順
1. Google Cloudで新しいプロジェクトを作成
Google Cloudのアカウントを作成したら、まずは新しいプロジェクトを作って下さい。今後はこのプロジェクト配下に全てのリソースが配置されます。また、削除も用意になるので、他のプロジェクトがあっても、別で作られることをおすすめします。
2. Google CloudのGUIでFirestore（データベース）を作成
次に、FirestoreというデータベースをGUIで作成します。残念ながら、現在（2021-03)ではCLIが提供されていないため、GUI上でセットアップをする必要があります。
3. スターターパックの初期化スクリプトを実行
gitからソースコードをcloneして、初期セットアップ用のシェルスクリプトを実行しましょう。このときに作成したGoogle CloudのプロジェクトIDが聞かれるので、入力して下さい。また、Google Cloudへログインするようリクエストされるので、立ち上がったブラウザからログインして下さい。
git clone https://github.com/senbishi21/smaregi-app-starter.git （もしくはzipダウンロードでも可能）
smaregi-app-starter/_init/init.sh
Google CloudのFirestoreのページで以下のように表示されたら成功です。
4. スマレジアプリを作成し、認証情報を設定ファイルにコピー
（こちらの手順は３番と並行して行うこともできます。）
アプリを動かすには、まずアプリの認証情報が最初に必要です。認証情報を生成するため、アプリを初期登録する必要があります。以下のステップの通り勧めていけば大丈夫です。
アプリを作成したら、コピーした認証情報を_init/credentials/secrets.txtに入力して下さい。ダブルクオート等は不要です。QA_MAIN_URL以外を埋めて下さい。例：
QA_APP_CLIENT_ID=xxxx
QA_APP_CLIENT_SECRET=xxxxx
PROD_APP_CLIENT_ID=xxxxx
PROD_APP_CLIENT_SECRET=xxxxx
LOCAL_CONTRACT_ID=xxxx
QA_MAIN_URL=変更して下さい
PROJECT_ID=xxx
5. cf-mainのコードをデプロイし、URLを設定ファイルにコピー
cf-main/のフォルダで./run.shを実行すると、ローカルでスタンドアローンで起動するウェブサーバーが動きます。自動でブラウザも開くので、こちらで以下のような画面がでたら成功です。
問題なければ、./deploy.sh qaを実行して、デプロイして下さい。こちらでGoogle CloudのCloud FunctionというFaaSサービスにコードをデプロイしています。デプロイには約1~2分ほどかかります。終了したら、Google CloudでCloud Functionのページを見てみて下さい。以下のように、緑のアイコンとなっていれば成功です。
qa-mainと表示されている部分をクリックすると、トリガーURLという項目があるので、それを_init/credentials/secrets.txtのQA_MAIN_URLにコピーして下さい。
6. 残りの２つのコンポーネントをデプロイ
のこりのcf-redirect-OIDC, cf-contract-webhookで./deploy.sh qaを実行して下さい。同じように約２分ほどかかりますので、終了したら、Cloud Functionのページで緑のアイコンとなっていることを確認して下さい。
cf-contract-webhookはアプリの使用を始める時・終了する際に、スマレジ側から呼ばれるWebhook型のサーバー（コンテナ）です。スマレジのアプリ画面で、以下のように設定して下さい。設定のあと、「テスト通知を送信」というボタンを押すと・・・
以下のように契約者情報がFirestoreデータベースに入ったことを確認出来ると思います。これで、アプリの契約が開始・終了した時にデータベースに保存されるようになりました。
完了！
これですべて完了です！cf-mainのURLにアクセスしてみて下さい。以下のようにスマレジのOpenIDのページにリダイレクトされ、ログイン（認証）してアプリを認可すると、以下のように自分のアプリが表示され、契約者IDも反映されるはずです。QA環境では10分でクッキーの有効期限が切れるようになっているので、手早くリダイレクトの動作をテストできます。
あとは、実装したい機能やウェブページをcf-mainにて実装すればOKです！PythonのFlaskをベースにしているので、かなり簡単に機能やロジックの実装ができると思います。
また、QAとPROD環境をデプロイスクリプトの変数でスイッチ出来るようにしていますので、開発のCI/CDを行いやすいコードになっております。
補足
OSSについて
当コードはGitHub上にホストしていますので、PR大歓迎です。ただし、以下のルールを守って頂けると幸いです。
- セキュリティ情報（CloudのTokenやCredential情報等）はDockerfileに入れ込まず、_init/credentialsのフォルダでのみ保持する。こちらのフォルダは.gitignoreで無視されるため、空のテンプレートファイルを_init/credentials-templateに入れ込んで下さい。
- ディレクトリ内でrun.shでローカルに走らせる、deploy.shでクラウド環境にデプロイする、という構成をお願いします。ローカルで走らせることがない場合、run.shをなくすか、echoでその旨を伝えるだけのスクリプトにして下さい。
料金について
料金のシミュレーションはGoogle Cloud price estimateで。
- 100人のユーザーが1000アクセス/月で、５分ごとにスマレジのデータを同期する場合の料金シミュレーションでは月のコストが2.44円です：料金詳細参考ページ
- 10万人のユーザーが全員毎日5アクセスする大規模システムで、５分ごとにスマレジのデータを同期する場合の料金シミュレーションでは月のコストが19万円/月となります：料金詳細参考ページ
スマレジアプリマーケットについて
スマレジアプリマーケットに登録された開発者には、スマレジの担当者からアプリの作り方等について、かなり手厚いサポートが受けられますので、ぜひ活用してみて下さい！私自身もかなりお世話になっています。
また、テクニカルサポートはスマレジ Developers Communityで受け付けているそうで、レスポンスが早い上、機能改善のケースでも実装が早いです。
どちらも、Appl○のiOSアプリや○ndroidアプリストアの対応より相当に早く、サポートも手厚いですので、どんどん使っていくのが早道です。
その他参考資料
- 【スマレジアプリを作ってみた#3】認証機能の実装：こちらの方がOpenIDでのログインの仕組みなど紹介してくださっています。
- 【スマレジアプリを作ってみた#5】Sandboxでの動作確認（テスト）：同じ作者の方で、本番環境でのテスト手法を共有してくださってます。