10.6. Push送信¶

POST /1/(tenantId)/push/notifications¶

Push通知を送信する。

Request Headers:
	X-Application-Id -- アプリケーションID(必須) X-Application-Key -- アプリケーションキー(必須) X-Session-Token -- セッショントークン(オプション) Content-Type -- "application/json"
Request JSON Object:
	query (object) -- クエリ条件 message (string) -- Pushメッセージ本文 badge (int) -- バッジカウント (APNsのみ) sound (string) -- Application Bundle 内のサウンドファイル名 (APNsのみ) content-available (int) -- 1 にセットするとバックグランドPushを有効 (APNsのみ) category (string) -- Notificationカテゴリ(APNsのみ) subtitle (string) -- 通知センターに表示するサブタイトル (APNsのみ) apsCustom (object) -- カスタムペイロード (APNsのみ) mutable-content (int) -- 可変コンテンツ (APNsのみ) uri (string) -- 通知を開いたときに起動するURI (FCMのみ) title (string) -- 通知ドロワー、通知センターに表示するタイトル (FCM・APNs共通) allowedReceives (array) -- 通知を受信可能なユーザID・グループ名の配列 sseEventId (string) -- イベントID (SSEのみ) sseEventType (string) -- イベントタイプ (SSEのみ)
Status Codes:	200 OK -- 正常送信 400 Bad Request -- パラメータ・リクエストボディ不正 401 Unauthorized -- 認証エラー 403 Forbidden -- 認可エラー 415 Unsupported Media Type -- Content-Type 不正
Response JSON Object:
	result (string) -- 実行結果(成功時は"ok") installations (int) -- 該当したインスタレーション数 error (string) -- エラーメッセージ

リクエストボディ

PUSHメッセージは JSON で以下のように指定する。

{
    "query": { /* 送信先指定 */ },
    "message": "Test message",
    "badge": 5,
    "sound": "xxx",
    "content-available": 1,
    "category": "xxx",
    "uri": "xxx",
    "title": "test",
    "sseEventId" : "xxx",
    "sseEventType" : "xxx",
    "allowedReceivers": [ "g:admin" ],
    "subtitle": "sub-title",
    "mutable-content": 0,
    "apsCustom": { /* 自由指定 */ }
}

以下のプロパティは、OS非依存かつ必須である。

query : 送信先インスタレーションを指定するためのクエリ (後述)
message : Pushメッセージ本文

以下のプロパティは、OS非依存かつオプションである。

allowedReceivers : 通知を受信可能なユーザ・グループの一覧(後述)

以下のプロパティは，iOSおよびAndroidにて指定可能であり、オプションである。

title : 通知のタイトル

以下のプロパティは APNs(iOS) 固有であり、すべてオプションである。

badge : バッジカウント
sound : Application Bundle 内のサウンドファイル名
content-available : 1にセットすると、バックグランド Push を有効にする
category : Notification カテゴリ
subtitle : サブタイトル
mutable-content : 1にセットすると，通知の加工を有効にする
apsCustom : カスタムペイロード。apsCustom以下のキーは、APNsサーバ送信用JSONにおいてcustom keyとして扱われる。"aps"というキーを含んではならない。

以下のプロパティは FCM(Android) 固有であり、すべてオプションである。

uri : 通知を開いたときに起動する URI

以下のプロパティはSSE固有であり，全てオプションである．

sseEventId : イベントID
sseEventType: イベントタイプ

query には、インスタレーションを指定するための MongoDB クエリ式を指定する。これらのクエリは、インスタレーションオブジェクトに対するクエリとして動作する。以下に例を示す。

例1) チャネル "chan1" を含むインスタレーションを指定する。

{ "_channels": "chan1" }

例2) インスタレーションID を１つ指定する。

{ "_id": "541bc0a0e4b03de4b0287b2e" }

例3) インスタレーションIDを複数指定する。

{
    "_id": {
        "$in": ["541bc0a0e4b03de4b0287b2e", "541bc0a0e4b03de4b0287b2f"]
    }
}

例4) E-mail アドレスを指定する (インスタレーション登録時に E-mail が指定されている前提)

{ "email": "foo@example.com" }

allowedReceivers を使用して、この通知を受信可能なユーザ・グループを制限することができる。

このオプションを指定した場合、適合する owner (allowedReceivers に含まれるユーザIDの１つに一致する、もしくは allowedReceivers に指定されたグループのいずれかに所属する)がセットされているインスタレーションに対してのみ Push が配信される。 allowedReceivers に適合しないか、または owner が設定されていないインスタレーションには配信されない。

グループを指定する場合はグループ名の先頭に "g:" を付けて指定する。

例5) allowedReceivers を指定する。（１つのユーザID とグループ "group1" を指定する場合）

{ "allowedReceivers": ["55ed50600c69293704e34f9d", "g:group1" ] }

allowedReceiversのグループには、"g:anonymous", "g:authenticated" は指定できない。

allowedReceivers を指定しなかった場合は、配信の制限は実施されず、query で指定された全インスタレーションに Push 配信される。

レスポンスボディ

リクエストが成功すると、200 OK が返る。レスポンスには以下のように該当したインスタレーション数が返る。

{
    "result": "ok",
    "installations": 17
}

該当するインスタレーションが無い場合は、エラーではなく "installations":0 の結果が返る

エラー時には、"error" にエラーメッセージが返却される。

{
    "error": "error messages..."
}

注意事項

デベロッパコンソールでクライアント Push が禁止されている場合、マスターキーを指定しなければならない。アプリケーションキーを指定した場合は 403 Forbidden エラーとなる。