BoltzEngine Tools
BoltzMessenger 以外にも HTTP API と CSV を使って送信するコマンドが付属しています。
これらのパッケージは、Linux RPM 版では boltz-tools パッケージ、Windows 版はインストーラーで選択すると同時にインストールされます。
BoltzEngine HTTP API Gateway サービス
boltz-http-proxy は HTTP リクエストを通して BoltzEngine へリクエストを送信します。このコマンドは、起動すると HTTP サーバとして動作します。
実際に提供される API の仕様は、BoltzEngine API インターフェイス仕様書をご参照ください。
Linux RPM 版は、boltz-tools パッケージをインストールすると boltz-http-proxy サービスが利用可能になります。 Windows 版では、BoltzEngine HTTP Proxy をインストールすると、Windows サービスに BoltzEngine HTTP Proxy が登録されます。
コマンドの書式とオプション
1boltz-http-proxy [options]
| オプション | 使用例 | 説明 |
|---|---|---|
| -a address | -a :14001 | HTTP Proxy が待ち受けるアドレス |
| -x address | -a localhost:13070 | BoltzEngine Master のアドレス |
| -apns.cert file | -apns.cert cert.pem | APNs 証明書のファイルパス |
| -apns.key file | -apns.key key.pem | APNs 秘密鍵のファイルパス(バイナリインターフェイスの場合pem、HTTP/2の場合p8ファイル) |
| -apns.gateway address | -apns.gateway gateway.push.apple.com:2195 | APNs 送信インターフェイスのアドレス |
| -apns.feedback address | -apns.feedback feedback.push.apple.com:2196 | APNs バイナリインターフェイス フィードバックサービスのアドレス |
| -apns.url | -apns.url https://api.development.push.apple.com/ | APNs 送信インターフェイスのアドレス(-apns.gatewayのエイリアス) |
| -apns.iss | -apns.iss xxxx | APNs JWTのIssuer(Develper ProgramのTeam ID) |
| -apns.kid | -apns.kid xxxx | APNs JWTのキーID |
| -apns.topic | -apns.topic xxxx | APNs 送信先トピック(アプリのBundle Identifier) |
| -fcm.key key | -fcm.key xxxx | FCM サーバキー |
| -fcm.url url | -fcm.url https://fcm.googleapis.com/fcm/send | FCM リクエスト URL |
| -fcm.sender senderID | -fcm.sender xxxx | FCM 送信者ID (XMPP時必須) |
| -fcm.account file | -fcm.serviceAccount service-account.json | FCM HTTP v1サービスアカウント |
| -webpush.subject subj | -webpush.subject mailto:info@example.com | VAPID 生成者の連絡先情報 |
| -webpush.key file | -webpush.key private.key | VAPID 生成のための ECDSA 秘密鍵(BASE64URLエンコード) |
| -webpush.pub file | -webpush.key public.key | VAPID 生成のための ECDSA 公開鍵(BASE64URLエンコード) |
| -skipverify | -skipverify | APNs/FCM ホストの証明書を検証しない |
送信サーバーへの接続時、通常 BoltzEngine はサーバ証明書を検証しますが、-skipverify オプションを与えると、検証を抑制して接続済みとなります。
このオプションは、本番環境で使うべきではありません。
APNs各モードで必要なパラメーターは以下の通りです。
| オプション | HTTP/2 | バイナリインターフェイス |
|---|---|---|
| -apns.gateway または -apns.url | HTTP/2 の送信URL (https://api.development.push.apple.com/) | 送信用サーバーのエンドポイント (gateway.push.apple.com:2195) |
| -apns.feedback | (不要) | フィードバックサービスのエンドポイント (feedback.push.apple.com:2196) |
| -apns.key | p8ファイルのパス | 秘密鍵ファイルのパス |
| -apns.cert | (不要) | 証明書ファイルのパス |
| -apns.iss | Issuer (Developer ProgramのTeam ID) | (不要) |
| -apns.kid | キーID (p8ファイル発行時に表示されます) | (不要) |
| -apns.topic | 送信先トピック (通常アプリのBundle Identifierになります) | (不要) |
-apns.gateawyもしくは-apns.urlに https://から指定されるURLが指定された場合はHTTP/2で送信するモードになります。両方指定された場合は後に指定されているパラメーターが有効となります。
FCM各モードで必要なパラメータは以下の通りです。
| オプション | Legacy HTTP | Legacy XMPP | HTTP v1 API |
|---|---|---|---|
| -fcm.key | サーバキー | サーバキー | (不要) |
| -fcm.sender | (不要) | 送信者ID | (不要) |
| -fcm.account | (不要) | (不要) | アカウントJSONファイルのパス |
-fcm.url が https:// かつ /v1/ を含む場合は HTTP v1 APIとして、https:// の場合は Legacy HTTP、host:port 形式なら Legacy XMPP として動作します。
-webpush.で始まるオプションが全て空文字列(未設定)の場合、WebPushの機能は無効になります。
Windows版の設定方法
BoltzEngine インストーラを使ってインストールすると、サービスが作成され、インストール時に入力した値がそのまま設定として使われます。
値の変更を行う場合は、再インストールを行うか、sc コマンドを使ってサービス情報を変更してください。
1@echo off
2set service=BoltzEngineHttpProxy
3set name=Boltz Engine HTTP Proxy
4set app=C:\Program Files\BoltzEngine
5set addr=:14001
6set cmd=\"%app%\boltz-http-proxy.exe\" -a %addr% -apns.cert \"C:\ProgramData\boltz-messenger\cert.pem\" -apns.key \"C:\ProgramData\boltz-messenger\key.pem\" -fcm.key \"xxxx\"
7
8sc query "%service%"
9if not %errorlevel% == 1060 (
10 sc delete "%service%"
11)
12
13sc create "%service%" binPath= "\"%app%\runsvc.exe\" -svc %service% %cmd%" start= auto displayName= "%name%"
14sc start "%service%"
上記スクリプトの %service% と %name% を変更すれば複数のサービスを起動できます。
Linux 版の設定方法
RPM パッケージで導入した BoltzEngine HTTP API Gateway の初回実行前には、設定ファイルの編集が必要です。
- el7 系の場合
- /etc/sysconfig/boltz/http-proxy ファイルを編集
- el6 系の場合
- /etc/init/boltz-http-proxy.override ファイルを作成
- 下記の設定値を1行毎に
env [設定名]=[設定値]として記載してください。
それぞれの値は、コマンドラインオプションの各項目に該当します。
| 設定名 | オプション |
|---|---|
| listen_addr | -a |
| engine_addr | -x |
| apns_key | -apns.key |
| apns_cert | -apns.cert |
| apns_gateway_addr | -apns.gateway |
| apns_feedback_addr | -apns.feedback |
| fcm_key | -fcm.key |
| fcm_url | -fcm.url |
| fcm_account | -fcm.account |
| webpush_subject | -webpush.subject |
| webpush_key | -webpush.key |
| webpush_pub | -webpush.pub |
起動方法
起動するには、boltz-http-proxy サービスを開始します。
1el7 の場合
2
3# systemctl enable boltz-http-proxy.service
4# systemctl start boltz-http-proxy.service
5
6el6 の場合
7
8# initctl start boltz-http-proxy
停止方法
停止するには、boltz-http-proxy サービスを停止します。
1el7 の場合
2
3# systemctl stop boltz-http-proxy.service
4
5el6 の場合
6
7# initctl stop boltz-http-proxy
状態確認方法
状態を確認するには、status コマンドで確認できます
1el7 の場合
2
3# systemctl status boltz-http-proxy.service
4
5el6 の場合
6
7# initctl status boltz-http-proxy
制限事項
- BoltzEngine 3.1 現在、
boltz-http-proxyは ADM に対応しておりません。
BoltzEngine CSV
boltz-csv-queue はCSVファイルを使って BoltzEngine へリクエストを送信します。
このコマンドは、簡単なテキストメッセージを通知するためだけに使われます。
BoltzMessenger Gateway や HTTP Proxy と異なり、メッセージ以外の情報を含めることはできません。
Windows 版では常に、インストール先フォルダへコピーされます。 Linux RPM 版は、boltz-tools パッケージをインストールすると利用可能です。
コマンドの書式とオプション
1boltz-csv-queue [options] [file ...]
| オプション | 使用例 | 説明 |
|---|---|---|
| -a address | -a localhost:13070 | BoltzEngine Master のアドレス |
| -t target | -t apns | 対象プラットフォーム名(apns or fcm or webpush) |
| -apns.cert file | -apns.cert cert.pem | APNs 証明書のファイルパス |
| -apns.key file | -apns.key key.pem | APNs 秘密鍵のファイルパス(バイナリインターフェイスの場合pem、HTTP/2の場合p8ファイル) |
| -apns.gateway address | -apns.gateway gateway.push.apple.com:2195 | APNs 送信インターフェイスのアドレス |
| -apns.feedback address | -apns.feedback feedback.push.apple.com:2196 | APNs バイナリインターフェイス フィードバックサービスのアドレス |
| -apns.url | -apns.url https://api.development.push.apple.com/ | APNs 送信インターフェイスのアドレス(-apns.gatewayのエイリアス) |
| -apns.iss | -apns.iss xxxx | APNs JWTのIssuer(Develper ProgramのTeam ID) |
| -apns.kid | -apns.kid xxxx | APNs JWTのキーID |
| -apns.topic | -apns.topic xxxx | APNs 送信先トピック(アプリのBundle Identifier) |
| -apns.badge field | -apns.badge 1 | 追加パラメータの field 番目(1から開始)フィールドをバッジと扱う |
| -fcm.key file | -fcm.key key.txt | FCM サーバキーを保存したファイルパス |
| -fcm.url url | -fcm.url https://fcm.googleapis.com/fcm/send | FCM リクエストURL |
| -fcm.sender senderID | -fcm.sender xxxx | FCM 送信者ID (XMPP時必須) |
| -fcm.account file | -fcm.account service-account.json | FCM HTTP v1サービスアカウント |
| -webpush.subject subj | -webpush.subject mailto:info@example.com | VAPID 生成者の連絡先情報 |
| -webpush.key file | -webpush.key private.key | VAPID 生成のための ECDSA 秘密鍵(BASE64URLエンコード) |
| -webpush.pub file | -webpush.key public.key | VAPID 生成のための ECDSA 公開鍵(BASE64URLエンコード) |
APNs へのリクエストを送信したい場合は、-t apnsオプションを使います。その場合、-fcm.から始まるオプションは使われません。同様に、FCM へのリクエストは、-t fcmを使います。
APNs各モードで必要なパラメーターは以下の通りです。
| HTTP/2 | バイナリインターフェイス | |
|---|---|---|
| -apns.gateway または -apns.url | HTTP/2 の送信URL (https://api.development.push.apple.com/) | 送信用サーバーのエンドポイント (gateway.push.apple.com:2195) |
| -apns.feedback | (不要) | フィードバックサービスのエンドポイント (feedback.push.apple.com:2196) |
| -apns.key | p8ファイルのパス | 秘密鍵ファイルのパス |
| -apns.cert | (不要) | 証明書ファイルのパス |
| -apns.iss | Issuer (Developer ProgramのTeam ID) | (不要) |
| -apns.kid | キーID (p8ファイル発行時に表示されます) | (不要) |
| -apns.topic | 送信先トピック (通常アプリのBundle Identifierになります) | (不要) |
-apns.gateawyもしくは-apns.urlに https://から指定されるURLが指定された場合はHTTP/2で送信するモードになります。両方指定された場合は後に指定されているパラメーターが有効となります。
FCM各モードで必要なパラメータは以下の通りです。
| オプション | Legacy HTTP | Legacy XMPP | HTTP v1 API |
|---|---|---|---|
| -fcm.key | サーバキー | サーバキー | (不要) |
| -fcm.sender | (不要) | 送信者ID | (不要) |
| -fcm.account | (不要) | (不要) | アカウントJSONファイルのパス |
引数で与えられたファイル単位でリクエストをまとめて BoltzEngine へ送信します。
引数のファイルが省略された場合、または-が与えられた場合、boltz-csv-queue は標準入力から CSV を読み込みます。
CSV ファイルフォーマット
APNs/FCM で共通したフォーマットとなります。
- トークン
- 有効期限(秒)
- 通知するメッセージ
- 追加パラメータ
トークン は有効なデバイストークンを16進文字列で記述します。 有効期限 は、端末がオフラインの場合などに、該当時間だけメッセージを保持し、期限が過ぎれば未達のままメッセージは破棄されます。 メッセージ はそのまま端末へ通知するメッセージです。 メッセージ中に,を含めたい場合は"“で囲んでください。 また、FCM の場合、 メッセージ はインテントで alert キーとして取得できます。
4 カラム以降は追加パラメータです。 任意の個数パラメータを追加でき、不要なら省略可能ですが、必ず、最初の行から最後までは、同じカラム数にしなければなりません。 これらのパラメータを設定した場合、通知を受信するアプリからは、4カラム目は attr1 というキーで取得することが可能です。 以後 attr2, attr3 と続きます。
-apns.badge オプションを使う場合、追加パラメータのうち指定されたフィールドはバッジの数として扱われます。
この場合、attr1 というキー名は詰めて扱われます。
例えば -apns.badge=2 とした場合、attr2 は3番目の追加パラメータを参照します。
送信結果
CSV ファイルを使って送信した結果、トークンが無効になっていたり、
更新されていたりする場合があります。
boltz-csv-queue コマンドは、標準出力に、CSV として対応が必要なトークンを出力します。
それぞれのフィールドは以下の意味となります。
- 発生時刻
- 送信に使ったトークン
- 更新後のトークン(空なら無効になったと扱う)
発生時刻 には、APNs/FCM によって 送信に使ったトークン が不要と扱われた時刻が入ります(RFC3339)。 この時刻よりも新しいトークンを所有しているなら、新しい方を優先してください。 以下は管理しているトークンの更新日が、 発生時刻 より古い場合の取り扱いルールです。
更新後のトークン が空なら、そのトークンは(アンインストール等で)無効になっています。 次回以降の通知メッセージに含めないような処理をしたほうが良いとされます。 また、 更新後のトークン に1文字以上の文字列があれば、次回以降は新しいトークンを使うべきです。 更新された場合であっても端末には届いているため、メッセージの再送は不要です。
上記以外でメッセージの通知に失敗したトークンがあれば、標準エラー出力に書き出します。
制限事項
- BoltzEngine 3.1 現在、
boltz-csv-queueは ADM に対応しておりません。