DockerとSripe CLIを使ってダッシュボードなしでオンライン決済を操作・管理する


2022/06/25

できるだけ自前でECサイトを構築する話を以前、以下のブログで紹介してきました。

ウェブページのほうは頑張ればかなりの割合で自作できることが可能なのですが、ECサイトにおいてもっともファンダメンタルな機能である
決済機能は、適切な有料サービスを利用せざるをえないのが現状です。

ということで、そんな高機能の決済機能を提供しているサービスの一つである
『Stripe』が公開しているコマンドライン開発ツール・Stripe CLIをDockerから使ってみることを試します。


Makefileでdocker-composeコマンドのショートカットコマンドセットの作り方

いきなり話題が脇道に逸れますが、DockerコマンドとStripeコマンドを組み合わせると、手動ではとても打ち込んで要られない状況になることがあります。

転ばぬ先の杖ということで、先に
Makeコマンドの利用方法を紹介します。

npmやyarnがインストールされている環境であれば、
package.jsonのスクリプトから自作のショートカットコマンドを使うことができますが、だいたいどのLinuxOSでも組み込まれているmakeコマンドでも同じようなことが実現できます。

Makefileというファイルを
docker-compose.ymlと同じ階層のフォルダに新規作成しておけば、make [サブコマンド]でカスタマイズしたコマンドが呼び出せるようにできます。

例えば、

            
            echo:
	echo 'HELLO, HOGE'
        
としておき、その作業ディレクトリ内で、

            
            $ make echo
echo 'HELLO, HOGE'
HELLO, HOGE
        
とすれば登録していたスクリプトが実行されます。

makeコマンド実行後直後の一行目に、スクリプトの中身が表示してほしくない場合には、

            
            echo:
	@echo 'HELLO, HOGE'
        
というようにコマンド冒頭に@を付けてあげることで、

            
            $ make echo
HELLO, HOGE
        
スクリプトの実行結果だけを標準出力することができます。

このMakefileを利用して、冗長なコマンドになりがちなdockerコマンド、docker-composeコマンド、およびstripe-cliコマンドなどを含むスクリプトをあらかじめ登録しておくと便利です。

例えば、

            
            #dockerコマンド(例)
run-mysql:
	docker run -d --name my_mysql -e MYSQL_ROOT_PASSWORD=root mysql:latest
run-php:
	docker run --rm -it --link my_mysql:db php:latest cat /etc/hosts

#docker-composeコマンド(例)
start:
	docker-compose up -d
	docker-compose exec app yarn serve
up:
	docker-compose up -d
	docker-compose exec app bash
down:
	docker-compose down
        
などなど、手ではとても打ち込むのが大変な長いオプションだったり、多数の引数だったり、面倒なコマンド打ち込みを全てパッケージすることができます。

なおMakefileを作成する際の注意点として、
タブ文字でインデントする必要があります。

VS CodeでMakefileを編集しておくと良く発生するエラーで
Makefile:*: *** 分離記号を欠いています. 中止.のようなものが吐かれたら、タブ文字で正しく書かれているかを確認しましょう。

なお、プロジェクトのリソースよってインデントに利用できる文字が異なる場合、
.editorconfigファイルで仕分けることができます。

            
            [*]
charset = utf-8
indent_style = space
indent_size = 4
insert_final_newline = true
trim_trailing_whitespace = true

[*.md]
max_line_length = off
trim_trailing_whitespace = false

[*.yml]
indent_size = 2

[Makefile]
indent_style = tab
        
よく使うファイルの設定を使い分けながら.editorconfigファイルに記述していくと便利です。


Docker-composeを使ったStripe CLIの導入

Stripe CLI(以下stripeコマンド)をインストールする方法は、公式のドキュメントに記載されている手順通りです。

WindowsやmacOSはもちろんのこと、LinuxOSの各ディストーションへもバイナリ版などがインストール可能です。

各自に適した環境へ、都合の良い方法を選択すると良いのですが、Dockerが使える環境ならば、
alpineベースの軽量なコンテナとしてstripeコマンドが利用できるようになっています。

例えば以下のようにこのコンテナをインタラクティブモードで使う場合、

            
            $ docker run --rm -it stripe/stripe-cli:latest
        
で簡単に利用できます。

ただしインストール版(※)と違って、Dockerコンテナ版のstripeコマンドを使うに当たり、オンライン上のstripeリモートサーバーへログインセッションを保持させるのが面倒です。

※バイナリ版のstripeコマンドを使う場合、stripeのウェブページへログイン認証後、90日間セッションが維持されます。

そこで、Docker版stripeコマンドでは、
「APIシークレットキー」をローカル変数として控えておき、docker-composeコマンドからログイン認証なしで使えるようにしてみましょう。

なお、docker-composeコマンドが既にお手元の環境に導入済みなものとして以降で説明を続けます。

Docker-composeにstripeコマンドを埋め込む

まずは適当なフォルダに以下のようなdocker-compose.ymlを作成します。

            
            version: '3'

services:
  cli:
    image: stripe/stripe-cli:latest
    container_name: stripe_worker
    environment:
      STRIPE_API_KEY: ${STRIPE_API_KEY}
      STRIPE_DEVICE_NAME: ${STRIPE_DEVICE_NAME}
    command: --device-name=${STRIPE_DEVICE_NAME} --api-key=${STRIPE_API_KEY}
        
また、docker-composeが実行時にローカルシェル変数として使えるように以下のように.envファイルを作成しておきます。

            
            STRIPE_API_KEY=sk_test_**********************
STRIPE_DEVICE_NAME=stripe-docker
        
ここで、変数STRIPE_API_KEYには開発者用のテストページからAPIシークレットキーをstripeダッシュボードから取得したものを利用します。

合同会社タコスキングダム|蛸壺の技術ブログ

なお、デバイス名・
STRIPE_DEVICE_NAMEの設置は任意ですが、チームで管理する場合にはアクセスする環境の識別が出来る方が好ましいでしょう。

これで、ログイン無しでstripeコマンドを使う準備は整いました。

試しに、Stripeアカウントの状態を
stripe statusから取得してみます。

            
            $ docker-compose run --rm cli status --verbose
✔ All services are online.
✔ API
✔ Dashboard
✔ Stripe.js
✔ Checkout.js
As of: June 25, 2022 @ 05:14AM +00:00
        
リモートアカウントからきちんと状態が取得されていたらOKです。

ダッシュボードの各遷移先URL一覧を表示する

知っておくと便利なコマンドで、ダッシュボードの各ページのURLを教えてくれるコマンドが

            
            $ docker-compose run --rm cli open --list
open quickly opens Stripe pages. To use, run 'stripe open <shortcut>'.
open supports the following shortcuts:

shortcut                              url
--------                              ---------
api                                => https://stripe.com/docs/api
apiref                             => https://stripe.com/docs/api
cliref                             => https://stripe.com/docs/cli
dashboard                          => https://dashboard.stripe.com/test
#....中略
docs                               => https://stripe.com/docs
        

stripeのサブコマンド一覧を表示する

基本的にStripe CLIはhelpを確認しながら、ダッシュボードで出来る操作を思い浮かべるような感じに操作していきます。

ということで、それぞれのダッシュボードからできる操作をサブコマンドが担当しているようなイメージになります。

各サブコマンドの確認は、

            
            $ docker-compose run --rm cli resources
Available commands:
  3d_secure                     
  account_links                 
  accounts                      
  #...中略
  usage_records                 
  webhook_endpoints             

Use "stripe [command] --help" for more information about a command.
        
で知ることができます。


Stripeコマンドで操作するはじめての操作〜新規顧客を作成する

stripeコマンド出来ることは多岐に渡り、どこから手を付けたものか目移りしてしまいます。

まずは最初の練習として、顧客を新規作成するコマンドを知るところから始めてみましょう。

お目当てのstripeサブコマンドを探す

stripeダッシュボードが出来ることは、stripeコマンドでも出来るようにツール設計されています。

stripeコマンドを使う上で知っておくべきことは、
「ダッシュボードの各ページのルート名がstripeのサブコマンド名に対応している」ということです。

例えば、ダッシュボード上の顧客の設定ページであれば、

            
            ライブ(本番)モード:
    https://dashboard.stripe.com/customers
テストモード:
    https://dashboard.stripe.com/test/customers
        
になっていますので、顧客を操作するstripeサブコマンドはstripe customersとなります。

サブコマンドの種類は多く、全てを覚えるのが困難であるので、前節でも紹介した
stripe resourcesから目的のサブコマンドを探します。

その際には、grepコマンドでキーワードを添えると探しやすくなります。

            
            $ docker-compose run --rm cli resources | grep customer
  customer_balance_transactions
  customers
        
ここからstripe customersというコマンドで顧客情報を管理することが分かります。

さらにこのサブコマンドの使い方を調べるために、
--helpを掛けます。

            
            $ docker-compose run --rm cli customers --help
Usage:
  stripe customers <operation> [parameters...]

Available Operations:
  balance_transactions        
  create                      
  create_funding_instructions 
  delete                      
  delete_discount             
  list                        
  list_payment_methods        
  retrieve                    
  retrieve_payment_method     
  search                      
  update                      
#...以下略
        
サブコマンドのヘルプでは、操作したいオペレーション名を調べることができます。

新規顧客情報を登録する場合のオペレーションは
createが該当します。

さらにさらに、このオペレーションの引数を調べるために、追い
--helpを掛けます。

            
            $ docker-compose run --rm cli customers create --help
Usage:
  stripe customers create [--param=value] [-d "nested[param]=value"]

Request Parameters:
      --balance
      --coupon
      --description
      --email
      --invoice-prefix
      --name
      --next-invoice-sequence
      --payment-method
      --phone
      --promotion-code
      --source
      --tax-exempt
      --test-clock

Flags:
  -c, --confirm                 Skip the warning prompt and automatically confirm the command being entered
      --dark-style              Use a darker color scheme better suited for lighter command-lines
  -d, --data stringArray        Data for the API request
  -e, --expand stringArray      Response attributes to expand inline
  -h, --help                    help for create
  -i, --idempotency string      Set the idempotency key for the request, prevents replaying the same requests within 24 hours
      --live                    Make a live request (default: test)
  -s, --show-headers            Show response headers
      --stripe-account string   Set a header identifying the connected account
  -v, --stripe-version string   Set the Stripe API version to use for your request

#...以下略
        
これでようやくstripe customers createで欲しかったオプションが得られました。

早速、適当な顧客を新規作成してみましょう。

最低限として、名前とEメールくらいがあれば良いでしょう。(※オプション引数が何も無くても、空の顧客は問題なく作成できるようです。)

            
            $ docker-compose run --rm cli customers create \
    --name 'ピヨだ ぽよオ' \
    --email hogehoge@piyo.com
        
このコマンド実行後に、ダッシュボードで[顧客]のテストページを確認してみましょう。

合同会社タコスキングダム|蛸壺の技術ブログ

確かに、ダッシュボードにはコマンドラインから入力されたイベントが反映されています。

顧客リストの取得

わざわざダッシュボードに追加された顧客を確認しに行かずとも、
stripe customers listを使えばコマンドラインから顧客を取得できます。

            
            $ docker-compose run --rm cli customers list
{
  "object": "list",
  "data": [
    {
      "id": "cus_Lw0eNIRpVSayMX",
  #...中略
  "url": "/v1/customers"
}
        
ただし、コマンドレスポンスとして長々と「生JSON」が返ってくるので、いささか読みづらいのが難点です。

以下のようにStripe公式のリファレンスビデオにもあるように、
「jqコマンド」を利用することが推奨されます。

例えば、先程の顧客データを簡潔に欲しいフィールドだけ表示したい場合、

            
            $ docker-compose run --rm cli customers list --color off | jq '.data[] | {email:.email,name:.name}'
{
  "email": "hogehoge@piyo.com",
  "name": "ピヨだ ぽよオ"
}
        
というように整理された形式で無駄なく表示することができます。

jqコマンドを使う上での注意点としては、
--color offのオプションを付けて、stripeコマンドが綺麗にデータを色付けして標準出力してくれる機能をオフにしておかないと、jqコマンドが正しく読み込んでくれるフォーマットにすることができないのでご留意ください。


まとめ

今回は、Stripe CLIの導入から、最初のコマンド利用例を説明していきました。

もちろん、Stripeのダッシュボードから行える操作は全てStripe CLIコマンドから操作が代替できるので、非常に効率的にオンライン決済に関連した業務をコンソール端末から完結して行えることが大きなメリットの一つです。

また、サーバーサイドのStripeの機能を組み込んでいくアプリ開発にもこのStripe CLIは無くてはならないツールです。

そのへんはまた後日、機会があれば別の記事で解説するかも知れません。