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 が登録されます。

コマンドの書式とオプション

1

boltz-http-proxy [options]

オプション	使用例	説明
-a address	-a :14001	HTTP Proxy が待ち受けるアドレス
-x address	-a localhost:13070	BoltzEngine Master のアドレス
-log file	-log file:///var/log/boltz-http-proxy.log	BoltzEngine HTTP API Gateway のログ出力先
-apns.url	-apns.url https://api.push.apple.com/	APNs 送信インターフェイスのアドレス
-apns.cert file	-apns.cert cert.pem	HTTP/2 + cert-based: p12 ファイルから生成した APNs 証明書のファイルパス
-apns.key file	-apns.key key.pem	HTTP/2 + cert-based: p12 ファイルから生成した APNs 秘密鍵のファイルパス HTTP/2 + token-based: APNs 接続用の秘密鍵ファイルパス (p8 ファイル)
-apns.iss	-apns.iss xxxx	HTTP/2 + token-based: APNs JWTのIssuer(Develper ProgramのTeam ID)
-apns.kid	-apns.kid xxxx	HTTP/2 + token-based: APNs JWTのキーID
-apns.topic	-apns.topic xxxx	HTTP/2 共通: APNs 送信先トピック(アプリのBundle Identifier)
-fcm.url url	-fcm.url https://fcm.googleapis.com/v1/	FCM リクエスト URL
-fcm.key key	-fcm.key xxxx	FCM-XMPP or FCM HTTP: FCM サーバキー
-fcm.sender senderID	-fcm.sender xxxx	FCM-XMPP: FCM 送信者ID (XMPP時必須)
-fcm.account file	-fcm.serviceAccount service-account.json	FCM HTTP v1: 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 各プロトコルで必要なパラメーター

この方式は現在非推奨です。
Apple より APNs の legacy I/F ( binary I/F ) が 2020 年 11 月以降に廃止されることが告知されております。
Apple Push Notification Serviceのアップデート

追記
Apple より廃止期限が 2021 年 3 月 31 日に延長される旨が告知されています。
APNs Provider APIの期限の変更

プロトコル	apns.gateway	apns.feedback	apns.url	apns.key	apns.cert	apns.issuer	apns.keyId	apns.topic
APNs HTTP/2 + token-based auth			◯	◯		◯	◯	◯
APNs HTTP/2 + cert-based auth			◯	◯	◯			◯
APNs binary interface	◯	◯		◯	◯

-apns.url に https:// から指定される URL が指定された場合は HTTP/2 で送信するモードになります。

FCM 各プロトコルで必要なパラメータ

オプション	Legacy HTTP	Legacy XMPP	HTTP v1 API
-fcm.url	https://fcm.googleapis.com/fcm/send	fcm-xmpp.googleapis.com:5235 (本番) fcm-xmpp.googleapis.com:5236 (本番前)	https://fcm.googleapis.com/v1/
-fcm.key	サーバキー	サーバキー	(不要)
-fcm.sender	(不要)	送信者ID	(不要)
-fcm.account	(不要)	(不要)	アカウントJSONファイルのパス

-fcm.url が https:// かつ /v1/ を含む場合は HTTP v1 APIとして、https:// の場合は Legacy HTTP、host:port 形式なら Legacy XMPP として動作します。

WebPush のパラメータ

-webpush.で始まるオプションが全て空文字列(未設定)の場合、WebPushの機能は無効になります。

Windows版の設定方法

BoltzEngine インストーラを使ってインストールすると、サービスが作成され、インストール時に入力した値がそのまま設定として使われます。値の変更を行う場合は、再インストールを行うか、sc コマンドを使ってサービス情報を変更してください。

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


@echo off
set service=BoltzEngineHttpProxy
set name=Boltz Engine HTTP Proxy
set app=C:\Program Files\BoltzEngine
set addr=:14001
set 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\"

sc query "%service%"
if not %errorlevel% == 1060 (
	sc delete "%service%"
)

sc create "%service%" binPath= "\"%app%\runsvc.exe\" -svc %service% %cmd%" start= auto displayName= "%name%"
sc 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 サービスを開始します。

1
2
3


$ # el7 の場合
$ sudo systemctl enable boltz-http-proxy.service
$ sudo systemctl start boltz-http-proxy.service

1
2


$ # el6 の場合
$ sudo initctl start boltz-http-proxy

停止方法

停止するには、boltz-http-proxy サービスを停止します。

1
2


$ # el7 の場合
$ sudo systemctl stop boltz-http-proxy.service

1
2


$ # el6 の場合
$ sudo initctl stop boltz-http-proxy

状態確認方法

状態を確認するには、status コマンドで確認できます

1
2


$ # el7 の場合
$ sudo systemctl status boltz-http-proxy.service

1
2


$ # el6 の場合
$ sudo 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 パッケージをインストールすると利用可能です。

コマンドの書式とオプション

1

boltz-csv-queue [options] [file ...]

オプション	使用例	説明
-a address	-a localhost:13070	BoltzEngine Master のアドレス
-t target	-t apns	対象プラットフォーム名(apns or fcm or webpush)
-apns.url	-apns.url https://api.push.apple.com/	APNs 送信インターフェイスのアドレス
-apns.cert file	-apns.cert cert.pem	HTTP/2 + cert-based: p12 ファイルから生成した APNs 証明書のファイルパス
-apns.key file	-apns.key key.pem	HTTP/2 + cert-based: p12 ファイルから生成した APNs 秘密鍵のファイルパス HTTP/2 + token-based: APNs 接続用の秘密鍵ファイルパス (p8 ファイル)
-apns.iss	-apns.iss xxxx	HTTP/2 + token-based: APNs JWTのIssuer(Develper ProgramのTeam ID)
-apns.kid	-apns.kid xxxx	HTTP/2 + token-based: APNs JWTのキーID
-apns.topic	-apns.topic xxxx	HTTP/2 共通: APNs 送信先トピック(アプリのBundle Identifier)
-apns.badge field	-apns.badge 1	追加パラメータの field 番目(1から開始)フィールドをバッジと扱う
-fcm.url url	-fcm.url https://fcm.googleapis.com/v1/	FCM リクエスト URL
-fcm.key key	-fcm.key xxxx	FCM-XMPP or FCM HTTP: FCM サーバキー
-fcm.sender senderID	-fcm.sender xxxx	FCM-XMPP: FCM 送信者ID (XMPP時必須)
-fcm.account file	-fcm.serviceAccount service-account.json	FCM HTTP v1: 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を使います。

引数で与えられたファイル単位でリクエストをまとめて BoltzEngine へ送信します。
引数のファイルが省略された場合、または-が与えられた場合、boltz-csv-queue は標準入力から CSV を読み込みます。

APNs 各プロトコルで必要なパラメーター

プロトコル	apns.gateway	apns.feedback	apns.url	apns.key	apns.cert	apns.issuer	apns.keyId	apns.topic
APNs HTTP/2 + token-based auth			◯	◯		◯	◯	◯
APNs HTTP/2 + cert-based auth			◯	◯	◯			◯
APNs binary interface	◯	◯		◯	◯

-apns.url に https:// から指定される URL が指定された場合は HTTP/2 で送信するモードになります。

FCM 各プロトコルで必要なパラメータ

オプション	Legacy HTTP	Legacy XMPP	HTTP v1 API
-fcm.url	https://fcm.googleapis.com/fcm/send	fcm-xmpp.googleapis.com:5235 (本番) fcm-xmpp.googleapis.com:5236 (本番前)	https://fcm.googleapis.com/v1/
-fcm.key	サーバキー	サーバキー	(不要)
-fcm.sender	(不要)	送信者ID	(不要)
-fcm.account	(不要)	(不要)	アカウントJSONファイルのパス

-fcm.url が https:// かつ /v1/ を含む場合は HTTP v1 APIとして、https:// の場合は Legacy HTTP、host:port 形式なら Legacy XMPP として動作します。

CSV ファイルフォーマット

APNs/FCM で共通したフォーマットとなります。

トークン
有効期限(秒)
通知するメッセージ
追加パラメータ

1
2
3


39053fd0ea90634699568ef0d9d2983a20b45dc4a4dee8dc8b648caa5a3aa558,1500,メッセージ1
9ed6251c87b1e4f8d0a05b2aab6b850cf4034d24a82d7f555917d229f86a7b38,1500,メッセージ2
7a7e3f3ee9cbd74d194267980e18755ac579d1ea4ee1b206ac7c8533518e902f,300,メッセージ3

トークン は有効なデバイストークンを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 に対応しておりません。

目次

BoltzEngine Tools

BoltzEngine HTTP API Gateway サービス

コマンドの書式とオプション

APNs 各プロトコルで必要なパラメーター

FCM 各プロトコルで必要なパラメータ

WebPush のパラメータ

Windows版の設定方法

Linux 版の設定方法

起動方法

停止方法

状態確認方法

制限事項

BoltzEngine CSV

コマンドの書式とオプション

APNs 各プロトコルで必要なパラメーター

FCM 各プロトコルで必要なパラメータ

CSV ファイルフォーマット

送信結果

制限事項

ご不明な点はありませんか？