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.urlhttps://から指定されるURLが指定された場合はHTTP/2で送信するモードになります。両方指定された場合は後に指定されているパラメーターが有効となります。

FCM各モードで必要なパラメータは以下の通りです。

オプション Legacy HTTP Legacy XMPP HTTP v1 API
-fcm.key サーバキー サーバキー (不要)
-fcm.sender (不要) 送信者ID (不要)
-fcm.account (不要) (不要) アカウントJSONファイルのパス

-fcm.urlhttps:// かつ /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.urlhttps://から指定される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 で共通したフォーマットとなります。

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

トークン は有効なデバイストークンを16進文字列で記述します。 有効期限 は、端末がオフラインの場合などに、該当時間だけメッセージを保持し、期限が過ぎれば未達のままメッセージは破棄されます。 メッセージ はそのまま端末へ通知するメッセージです。 メッセージ中に,を含めたい場合は”“で囲んでください。 また、FCM の場合、 メッセージ はインテントで alert キーとして取得できます。

4 カラム以降は追加パラメータです。 任意の個数パラメータを追加でき、不要なら省略可能ですが、必ず、最初の行から最後までは、同じカラム数にしなければなりません。 これらのパラメータを設定した場合、通知を受信するアプリからは、4カラム目は attr1 というキーで取得することが可能です。 以後 attr2, attr3 と続きます。

-apns.badge オプションを使う場合、追加パラメータのうち指定されたフィールドはバッジの数として扱われます。 この場合、attr1 というキー名は詰めて扱われます。 例えば -apns.badge=2 とした場合、attr2 は3番目の追加パラメータを参照します。

送信結果

CSV ファイルを使って送信した結果、トークンが無効になっていたり、 更新されていたりする場合があります。 boltz-csv-queue コマンドは、標準出力に、CSV として対応が必要なトークンを出力します。

それぞれのフィールドは以下の意味となります。

  1. 発生時刻
  2. 送信に使ったトークン
  3. 更新後のトークン(空なら無効になったと扱う)

発生時刻 には、APNs/FCM によって 送信に使ったトークン が不要と扱われた時刻が入ります(RFC3339)。 この時刻よりも新しいトークンを所有しているなら、新しい方を優先してください。 以下は管理しているトークンの更新日が、 発生時刻 より古い場合の取り扱いルールです。

更新後のトークン が空なら、そのトークンは(アンインストール等で)無効になっています。 次回以降の通知メッセージに含めないような処理をしたほうが良いとされます。 また、 更新後のトークン に1文字以上の文字列があれば、次回以降は新しいトークンを使うべきです。 更新された場合であっても端末には届いているため、メッセージの再送は不要です。

上記以外でメッセージの通知に失敗したトークンがあれば、標準エラー出力に書き出します。

制限事項

  • BoltzEngine 3.1 現在、boltz-csv-queue は ADM に対応しておりません。

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

機能の詳細、導入のご検討、お見積もり依頼などは、お気軽にお問い合わせください。
担当者から追ってご連絡いたします。

お問い合わせはこちら

記事へ戻る