はじめに
SendGridの設定変更や確認をコマンドラインから行うツールが欲しかったので作りました。SendGridの公式ライブラリがWeb API v3に対応する方向で刷新されました。このうち、sendgrid-rubyをラップして、Thorでコマンドラインツール化しました。sendgrid-rubyはFluent Interfaceな実装となっており、Web APIのエンドポイントが追加されたり変更されたりしても、柔軟に対応できる作りになっています。今回のツールもその柔軟性を継承しています。curlで直接呼び出すより扱いやすくなっているのではないかと思います。
前提条件
Ruby 2.2 以降
インストール
sgというgemをインストールします。
$ gem install sg
使い方
sg gemをインストールするとsgコマンドが使えるようになります。
sgにはclientというコマンドが一つだけ用意してあり、全ての呼び出しはこのコマンドを利用していきます。
ヘルプの表示
まずは、clientコマンドのヘルプを表示してみます。ツールの使い方はここで確認できます。
$ sg help client
オプション
clientコマンドにはいくつかのオプションがあります。
| オプション | エイリアス | 詳細 |
|---|---|---|
| --apikey | -k | SendGridのAPIキーを指定します。このオプションを省略するとSENDGRID_API_KEYという環境変数からAPIキーをロードして動作します。APIキーを画面上に表示したくない場合などに利用できますが、基本的にこのオプションは省略して環境変数を利用することをお勧めします。 |
| --user | -u | SendGridのユーザ名です。APIキーを使用しない場合に指定します。セキュリティ上の理由から通常はAPIキーの使用を推奨します。 |
| --pass | -p | SendGridのパスワードです。APIキーを使用しない場合に指定します。セキュリティ上の理由から通常はAPIキーの使用を推奨します。 |
| --request-body | -b | APIリクエストのボディ部を指定します。具体的な内容についてはSendGridのAPIリファレンスを参照してください。 |
| --query-params | -q | APIリクエストのクエリストリング部をJSON形式で指定します。具体的な内容についてはSendGridのAPIリファレンスを参照してください。 |
| --response-header | -h | レスポンスヘッダを出力します。 |
| --response-status | -s | レスポンスのHTTPステータスコードを出力します。 |
| --version | -v | sgのバージョンを表示します。 |
引数
clientコマンドの後にはエンドポイントのURLのうち、"v3"よりあとの部分をスペースで区切って、最後にメソッド（HTTP動詞）を指定します。例えば、次のようなエンドポイントを呼び出す場合、
GET https://api.sendgrid.com/v3/api_keys HTTP/1.1
次のように実行します。
$ sg client api_keys get
その他の具体例
例1
エンドポイントのURLに動的な変数を指定する場合も同様にスペースで区切って呼び出します。
GET https://api.sendgrid.com/v3/api_keys/YOUR_API_KEY_ID HTTP/1.1
$ sg client api_keys YOUR_API_KEY_ID get
例2
クエリストリングを指定する場合は、--query-params(または-q）オプションにJSON形式で値を指定します。
GET https://api.sendgrid.com/v3/suppression/unsubscribes?start_time=1367794504&end_time=1467794504 HTTP/1.1
$ sg client suppression unsubscribes get -q='{"start_time":1367794504,"end_time":1467794504}'
例3
ボディ部を指定する場合は、--request-body(または-b)オプションで指定します。
POST https://api.sendgrid.com/v3/api_keys HTTP/1.1
{
"name": "My API Key",
"scopes": [
"mail.send"
]
}
$ sg client api_keys post -b='{"name": "My API Key", "scopes": ["mail.send"]}'
例4
その気になればメール送信もできます。ガチで使おうと思うとボディ部の組み立ては結構大変になりますが。
$ sg client mail send post -b='{"personalizations":[{"to":[{"email":"to@example.com"}],"subject":"Hello, World!"}],"from":{"email":"from@example.com"},"content":[{"type":"text","value":"Hello, World!"}]}'
さいごに
ソースコードはこちら。ヘルプなどがまだ小慣れていないのでPRとかIssueとかいろいろいただけると嬉しいです。