お問い合わせ

お問い合わせ

目次

オブジェクト一覧

BoltzEngine との通信で使用するオブジェクトの一覧です。

Go 言語では提供される型定義ソースコードを参照し、対応するオブジェクトを作成します。HTTP API では 各オブジェクトは JSON オブジェクト(ハッシュ)となります。

基本型一覧

BoltzEngine API インターフェイスで扱うデータ型は以下の通りです。

[] から始まる型名は配列を表します。

通常のデータ型

Go 言語での型 JSON-RPC での型 / 取り扱い
int 数値 (符号つき整数、-2147483648 から 2147483647)
int64 数値 (符号つき整数、-9223372036854775808 から 9223372036854775807)
unit8 数値 (符号なし整数、0 から 255)
unit32 数値 (符号なし整数、0 から 4294967295)
bool 真偽値 (true / false)
string 文字列
[]byte 当該のバイト列を BASE64 エンコーディングした文字列
[](任意の型) 当該のオブジェクトの配列
map[string]string 文字列のキーと文字列の値からなる JSON オブジェクト
map[string]SlaveActivity 文字列のキーと boltz.SlaveActivity からなる JSON オブジェクト
time.Duration 数値 (UNIXタイムスタンプ)
time.Time 文字列 (“yyyy-MM-ddThh:mm:ss.SSSSSSSSSZZZZ” 形式の日時を表す文字列)
Status (APNs) 符号なし整数
Failure (FCM) 文字列

範囲外の整数を渡すなどした場合は、エラーオブジェクトが戻ります(net/rpc ではエラー戻り値が戻され、HTTP ゲートウェイでは error 要素にエラーメッセージがセットされます)。

net/rpc と HTTP ゲートウェイで取り扱いが異なる型

以下の型は RPC と HTTP API ゲートウェイで取り扱いが異なります。

型名 RPC での取り扱い HTTP Gateway での取り扱い
DeviceToken 当該のバイト列を BASE64 エンコーディングした文字列([]byte と同じ) 16進数の文字列
(例. 960d1918d38f9bb8f5f676154ca23da366aed2d1)
PayloadString 当該のバイト列を BASE64 エンコーディングした文字列([]byte と同じ) 文字列

boltz/apns パッケージ

Message

APNs メッセージを表すオブジェクト。

キー 型 概要
ID uint32 送信メッセージID (リクエスト内での連番を付与します)
Expir uint32 メッセージ有効期限のUNIXタイムスタンプ。0以外の値を指定するとその時間まで APNs がリトライします。
Token DeviceToken 送信先端末のデバイストークン
Payload PayloadString 送信する APNs ペイロード JSON
Priority uint8 通知の優先度 (10 または 5 を指定する。10 は即時配信、5 は電源に余裕のあるときに配信)
Topic string アプリのバンドルID (HTTP/2プロトコルのみ)
CollapseID string 複数の通知をまとめるID (HTTP/2プロトコルのみ)

これらのより詳しい情報は LocalおよびPush Notificationプログラミングガイド: APNsとのやりとり を参照してください。

Feedback

APNs フィードバックを表すオブジェクト。

キー 型 概要
Timestamp uint32 端末が無効になった時刻のUNIXタイムスタンプ
Token DeviceToken 無効になったデバイストークン

Credential

APNs への認証情報を表すオブジェクト。HTTP/2またはBinaryプロトコルのうちどちらを使うかによって有効なフィールドが変わる。

Binaryプロトコルの場合は以下が有効です。詳しい情報は LocalおよびPush Notificationプログラミングガイド: バイナリProvider API

キー 型 概要
KeyPEMBlock []byte 秘密鍵
CertPEMBlock []byte 証明書
InsecureSkipVerify bool 接続先サーバの証明書を検査しない (テスト用)

HTTP/2の場合は以下の4つが有効です。詳しい情報は LocalおよびPush Notificationプログラミングガイド: APNsとのやりとり を参照ください。

キー 型 概要
Issuer string issキー
KeyID string kidキー
PrivateKey []byte PEM(PKCS#8)エンコードされたEC P-256秘密鍵
InsecureSkipVerify bool 接続先サーバの証明書を検査しない (テスト用)

FailedMessage

APNs 送信時に、送信に失敗した場合に返されるエラー内容オブジェクト。

キー 型 概要
ErrorString string APNs 以外でエラーが発生した場合にセットされます(例: “no such host”)
Detail ProtocolError エラー詳細 (APNs プロトコルにおけるエラーの場合にセットされます)
Message Message 失敗を引き起こしたメッセージ
  • ErrorString、Detail は、必ずどちらかしか取り得ません
  • Message は上記どの場合であっても必ずセットされます

ProtocolError

APNs プロトコルエラーの詳細情報を表すオブジェクト。Binaryプロトコルの場合は以下の値がセットされます。

キー 型 概要
Cmd uint8 APNs コマンド ID (通常 8 がセットされます)
Status Status エラー種別
ID uint32 送信メッセージ ID (当該の Message オブジェクトに指定されたもの)

HTTP/2の場合は以下の値がセットされます。

キー 型 概要
StatusCode int HTTP ステータスコード
Reason string エラー種別
Time time.Time 無効になった時刻 (トークン無効の場合)

エラー種別やステータスコードの詳細は LocalおよびPush Notificationプログラミングガイド: APNsとのやりとりを参照ください。

Status 列挙体

値 キー
0 Success
1 ProcessingError
2 MissingToken
3 MissingTopic
4 MissingPayload
5 InvalidTokenSize
6 InvalidTopicSize
7 InvalidPayloadSize
8 InvalidToken
10 Shutdown
255 None(Unknown)

Request

APNs 通知送信のリクエストオブジェクト。

HTTP API ゲートウェイでは認証情報は起動時にサーバーに与えられたものが使用されるため、Addr, Credential は指定できない。

キー 型 概要
Addr string APNs 接続先サーバー (gateway.push.apple.com:2195)
Credential Credential 認証情報
Messages []Message 送信メッセージ
BandWidth int32 1秒あたりの通知可能端末数。0の場合は無制限。

Response

APNs 通知送信のレスポンスオブジェクト。

キー 型 概要
FailedMessages []FailedMessage 送信失敗したメッセージと理由。すべて成功した場合は空の配列。

FBRequest

APNs フィードバックサービスのリクエストオブジェクト。

HTTP API ゲートウェイでは認証情報は起動時にサーバーに与えられたものが使用されるため、Addr, Credential は指定できない。

キー 型 概要
Addr string APNs 接続先サーバー (feedback.push.apple.com:2196)
Credential Credential 認証情報

FBResponse

APNs フィードバックサービスのレスポンスオブジェクト。

キー 型 概要
Body []Feedback フィードバックの取得結果

boltz/gcm パッケージ

Message

FCM メッセージを表すオブジェクト。

キー 型 概要
ID string リクエスト内で一意となるメッセージ ID (XMPP の場合は必須)
To string 送信先の端末の FCM レジストレーション ID (XMPP の場合のみ; 必須)
RegIDs []string 送信先の端末の FCM レジストレーション ID (HTTP の場合のみ; 1000 個まで指定可能)
Data map[string]string FCM ペイロードに含めるデータ
CollapseKey string 折りたたみキー (同種のメッセージをキューイングする際に使用されるキー)
DelayWhileIdle bool 現在、廃止されたため未使用
TimeToLive int メッセージの有効期限 (秒数)
Priority string メッセージの優先度 (normal または high)
ContentAvailable bool 送信先の端末のスリープを解除する
MutableContent bool 現在、Androidでは未使用
Notification map[string]string FCM により事前定義された通知用データ
DryRun bool 実際に送信を行わない (テスト用)

それぞれの項目は、以下の公式ドキュメントを参照ください。

Legacy HTTP と XMPP の場合は、Message 型のキーと FCM リクエストのキーが対応していますが、HTTP v1 API の場合は Message 型を使って android と token を使った FCM リクエストへ変換します。

ResponseBody

FCM へ HTTP を使ったメッセージ送信結果を表すオブジェクト。

キー 型 概要
ID int64 マルチキャスト メッセージを識別するユニークな ID
Success int エラーなしで処理されたメッセージの数。
Failure int 処理できなかったメッセージの数。
CanonicalIDs int カノニカル登録 ID を含む結果の数。
Results []Result 処理されたメッセージのステータス
RetryCount int BoltzEngine がリトライ処理を行った回数

Result

FCM へのメッセージ送信に対して、各端末ごとの結果を表すオブジェクト。

キー 型 概要
ID string 送信 ID。送信成功の場合に値が入る。
RegID string 送信成功したが、該当する登録 ID が更新されている場合に新しい登録 ID が入る。
Error Failure エラーメッセージ

Failure が取り得るエラーメッセージの種類

メッセージ 状況の概要
MissingRegistration リクエストにレジストレーション ID が含まれていることの確認が必要
InvalidRegistration FCM サーバに送信したレジストレーション ID フォーマットの確認が必要
MismatchSenderId レジストレーション ID が特定のセンダーのグループに縛られている
NotRegistered レジストレーション ID がなんらかの理由で無効になった
MessageTooBig メッセージに含まれるペイロードデータが大きすぎる
InvalidDataKey Google により予約済みキー名がペイロードのキーとして使われている
InvalidTtl TimeToLive が大きすぎる、または0以下
Unavailable FCM サーバでタイムアウトした (BoltzEngine はリトライするが解決しない場合はこれを返す)
InternalServerError FCM サーバにエラーが発生した (BoltzEngine はリトライするが解決しない場合はこれを返す)
InvalidPackageName 無効なパッケージ名
DeviceMessageRateExceeded 特定デバイスへのメッセージレート超過
TopicMessageRateExceeded 特定トピックへのメッセージレート超過

Signal

FCM へ XMPP を使ったメッセージ送信結果を表すオブジェクト。

キー 型 概要
RegID string 更新された登録 ID
Code string エラーコード。
Description string エラーメッセージ。
Message Message エラーになったメッセージそのものが入る。

Signal は純粋なエラーと更新情報を扱うため、 以下のパターンで分岐する必要があります。

1. 登録 ID が更新された

RegID がセットされている場合は、通知は正しく送信されているが デバイスの登録 ID が更新されたケースです。 この場合は RegID と Message に有効な値が入っています。 次回から新しい登録 ID を使うように対応を行ってください。

2. 送信エラーが発生した

RegID が空文字列の場合はエラーのため通知が届かなかったケースを表します。 この場合は、Code、Description、Message に有効な値が入っています。 Code の内容(詳細は以下)により必要な対応を行ってください。

Code が取り得るエラーコードの種類

エラーコード 状況の概要
BAD_ACK (BoltzEngine が処理するため発生しない)
BAD_REGISTRATION リクエストに指定したセンダー ID と、レジストレーション ID を生成したそれが異なる
CONNECTION_DRAINING (BoltzEngine がリトライするため発生しない)
DEVICE_MESSAGE_RATE_EXCEEDED 特定デバイスへのメッセージレート超過
DEVICE_UNREGISTERED レジストレーション ID がなんらかの理由で無効になった
INTERNAL_SERVER_ERROR FCM サーバにエラーが発生した (BoltzEngine はリトライするが解決しない場合はこれを返す)
INVALID_JSON (BoltzEngine が処理するため発生しない)
SERVICE_UNAVAILABLE FCM サーバでタイムアウトした (BoltzEngine はリトライするが解決しない場合はこれを返す)
TOPICS_MESSAGE_RATE_EXCEEDED 特定トピックへのメッセージレート超過

APIError

FCM へ HTTP v1 API を使ったメッセージ送信結果を表すオブジェクト。

キー 型 概要
Message Message エラーになったメッセージそのものが入る。
Code int HTTP ステータスコード
Status string FCM エラーコード
Description string FCM エラーメッセージ

FCM エラーコードについては ErrorCode を参照ください。

Credential

FCM への認証情報を表すオブジェクト。

Legacy HTTP または XMPP プロトコルの場合は以下のフィールドを使用します。

キー 型 概要
ServerKey string サーバーキー
SenderID string センダーID (XMPP の場合のみ必須)
InsecureSkipVerify bool 接続先サーバの証明書を検査しない (テスト用)

HTTP v1 API プロトコルの場合は以下のフィールドを使用します。

キー 型 概要
ServiceAccount string service-account.json ファイルの内容
InsecureSkipVerify bool 接続先サーバの証明書を検査しない (テスト用)

Request

FCM 通知送信のリクエストオブジェクト。

HTTP API ゲートウェイでは認証情報は起動時にサーバーに与えられたものが使用されるため、Credential は指定できない。

キー 型 概要
URL string FCM 接続先 URL (https://fcm.googleapis.com/fcm/send)
Credential Credential 認証情報
Messages []Message 送信メッセージ
BandWidth int32 1秒あたりの通知可能端末数。0の場合は無制限。

FailedMessage

APNs 送信時に、送信に失敗した場合に返されるエラー内容オブジェクト。

キー 型 概要
ErrorString string FCM 以外でエラーが発生した場合にセットされます(例: “no such host”)
Error APIError エラー詳細 (FCM HTTP v1 API プロトコルにおけるエラーの場合にセットされます)
Detail ResponseBody エラー詳細 (FCM HTTP プロトコルにおけるエラーの場合にセットされます)
Signal Signal エラー詳細 (FCM XMPP プロトコルにおけるエラーの場合にセットされます)
Message Message 失敗を引き起こしたメッセージ
  • ErrorString、Error、Detail、Signal は、必ずどれか1つしか取り得ません
  • Message は上記どの場合であっても必ずセットされます

boltz/webpush パッケージ

Message

WebPush メッセージを表すオブジェクト。

キー 型 概要
Token Token 送信先端末のURI、公開鍵など
TimeToLive int メッセージの有効期限(秒)。0以外の値を指定すると、その時間だけFirebase/Mozillaが保持します
Payload string クライアントへ送信する任意の文字列 (例: JSON, プレーンテキスト, CSV)
Urgency Urgency 通知の優先度
Topic string 同じトピックなら最後のメッセージだけに間引くためのキー文字列(空文字なら間引かない)

Token

WebPush のメッセージ送信に必要な値をまとめたオブジェクト。

キー 型 概要
Version int トークンのバージョン番号(現在は1で固定)
URL string Firebase/Mozilla から取得した通知先 URL
PublicKey string クライアントの秘密鍵を BASE64URL エンコードしたもの
AuthToken string クライアントで生成した Authentication Secret を BASE64URL エンコードしたもの

この値は、net/rpc メソッドを除いて、JSON エンコードした文字列として扱います。 エンコードした後のキー並びは、必ず、以下の順で並ばなければなりません。

  1. v (Version)
  2. endpoint (URL)
  3. p256dh (PublicKey)
  4. auth (AuthToken)

例えば以下のような文字列です。

1{"v":1,"endpoint":"https://example.com/token2","p256dh":"xxxx","auth":"xxxx"}

Urgency 列挙体

値 キー 文字列表現
0 VeryLow very-low
1 Low low
2 Normal normal
3 High high
  • boltz-http-proxy で使う場合、Urgency は文字列表現を使います

Credential

WebPush への認証情報を表すオブジェクト。

キー 型 概要
VAPID VAPID VAPID 生成のための情報
InsecureSkipVerify bool 接続先サーバの証明書を検査しない (テスト用)

VAPID

キー 型 概要
Subject string VAPID 作成者の連絡先 (mailto: または https:// で始まらなければならない)
PublicKey []byte VAPID 生成のための ECDSA 公開鍵
PrivateKey []byte VAPID 生成のための ECDSA 秘密鍵

FailedMessage

WebPush 送信時に、送信に失敗した場合に返されるエラー内容オブジェクト。

キー 型 概要
ErrorString string APNs 以外でエラーが発生した場合にセットされます(例: “no such host”)
Detail ProtocolError エラー詳細 (APNs プロトコルにおけるエラーの場合にセットされます)
Message Message 失敗を引き起こしたメッセージ
  • ErrorString、Detail は、必ずどちらかしか取り得ません
  • Message は上記どの場合であっても必ずセットされます

ProtocolError

WebPush プロトコルエラーの詳細情報を表すオブジェクト。

キー 型 概要
StatusCode int メッセージ送信で受け取った HTTP ステータスコード

boltz パッケージ

MasterActivity

BoltzEngine マスターノードの性能情報を表すオブジェクト。

キー 型 概要
PendingCount int スレーブに対して送信待ちしているリクエスト数
SlaveActivities map[string]SlaveActivity 文字列をキーとしたスレーブノードの性能オブジェクトのオブジェクト

SlaveActivity

BoltzEngine スレーブノードの性能情報を表すオブジェクト。

キー 型 概要
MaxAgents int マスタひとつにつき最大いくつの同時リクエストを許可するか
RequestCount int ノード起動からリクエストされた通知メッセージ数
DeliveringCount int 現在送信処理中の通知数
DeliveredCount int 送信した端末数
TotalExecutionTime time.Duration リクエスト開始から終了までの合計時間
LatestExecutionTime time.Duration 最新のリクエスト処理時間
LastUpdate time.Time マスタひとつにつき最大いくつの同時リクエストを許可するか

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

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

お問い合わせはこちら