REST API Push API
last update 2015-9-17

Push Delivery (Reserved)

Specific Data&Time Reservation API

日時を指定してプッシュ配信を予約します。
配信対象となるデバイスは、すでに登録されているデバイスの抽出条件を指定するか、リストとして直接指定することができます。

Notes

As long as you set your Push Notification deliveries via Appiaries Control Panel,
you have no limitations as to the number of target devices you wish to deliver the messages to,
(there are certainly delivery limitations per contract)
If you are setting Push Notification deliveries via REST APIs,
you may deliver messages up to 1,000 target devices.

基本仕様

API 仕様

項目 説明
エンドポイント https://api-datastore.appiaries.com/v1/push/manage/{contractId}/{applicationId}
エンドポイントのパラメータ {contractId}:契約者ID
{applicationId}:アプリケーションID
メソッド POST
リクエストコンテントタイプ application/json
レスポンスコンテントタイプ application/json
制約事項 ・1回の予約登録で配信可能なデバイス数は1千個です。
・「devices:レジストレーションIDリスト」は、1回の予約登録内に於いて、ユニークである必要があります。

ヘッダーパラメータ

パラメータ名 項目名 タイプ 必須 説明
X-Appiaries-Token Appiariesトークン 文字列 アプリトークン

クエリーパラメータ

パラメータ名 項目名 必須 説明
proc count デバイス数返却 プッシュ配信は行わず、検索デバイス数のみを返却する
proc payload ペイロードサイズ返却 プッシュ配信は行わず、ペイロードサイズのみを返却する

ボディパラメータ

ボディパラメータ: GCM
パラメータ名 パラメータ名(子) パラメータ名(子2) 項目名 タイプ 必須 説明
reserve_datetime 送信予約日時 文字列 ・送信日時を下記の形式で指定します。
yyyy-MM-ddTHH:mm+0900(ISO8601)
・指定がない場合、即時配信となります。
・未来日時は1ヶ月先まで指定できます。
・過去日時は指定できません。
gcm gcm オブジェクト GCMパラメータ定義開始ポイント
data 通知データ オブジェクト ・アプリケーションが利用するパラメータを設定します。
・基本書式は「{“aa”:”bb”}」となり、「””」による文字列指定となります。
・「{}」内は1階層のみ許可されます。
・文字列以外が指定された場合、予期せぬ変換が行われるため、必ず「””」で囲って下さい。
collapse_key グループ折畳メッセージ 文字列 ・パラメータ「time_to_live」指定時は必須となります。
・折畳メッセージ文字列を指定します。
delay_while_idle アイドル時送信の有効/無効 Boolean ・アイドル送信の有効/無効を設定します。
・true:有効
・false:無効
time_to_live メッセージ保存時間 Int ・パラメータ「collapse_key」指定時は必須となります。
・メッセージの保存時間を指定します。
api_key GCM API KEY 文字列 ※説明参照 ・GCMのAPIキーを設定します。
※ユーザ管理画面のマーケット設定に、「API Key」が登録されている場合、本パラメータを省略することができます。
device_search_conditions デバイス検索条件 文字列 ※説明参照 ・条件で検索して結果がない場合は 404 が返却されます。
・全件指定の場合は “all” または “ALL” を指定して下さい。
・複数条件でなくても最後の「;」は必須となります。
※devices と device_search_conditions のいずれかを指定する必要があります。
devices と同時に指定することはできません。
devices レジストレーションIDリスト 文字列
リスト
※説明参照 ・Push通知先のレジストレーションIDをリスト形式で指定します。
※devices と device_search_conditions のいずれかを指定する必要があります。
device_search_conditions と同時に指定することはできません。
ボディパラメータ: APNs
パラメータ名 パラメータ名(子) パラメータ名(子2) 項目名 タイプ 必須 説明
reserve_datetime 送信予約日時 文字列 ・送信日時を下記の形式で指定します。
yyyy-MM-ddTHH:mm+0900(ISO8601)
・指定がない場合、即時配信となります。
・未来日時は1ヶ月先まで指定できます。
・過去日時は指定できません。
apns APNs オブジェクト APNsパラメータ定義開始ポイント
alert 通知 オブジェクト 通知メッセージ定義開始ポイント
body 通知メッセージ 文字列 ・通知センターの表示メッセージを設定します。
badge バッヂ Int ・ホーム画面上のアイコンの右上に表示される数値を設定します。
・0以下の値が設定されると数値表示がクリアされます。
sound 通知音声 文字列 ・通知センターがプッシュ通知を受取った際に鳴らすサウンドを設定します。
・アプリケーションバンドルに含まれるサウンドを設定します。
・アプリケーションがフォアグラウンドで動作している状態で直接プッシュ通知を受取った場合、サウンドは鳴りません。
content_available バックグラウンド起動フラグ Int ・iOS7以降、バックグラウンド通知を受取るか指定します。
・アプリケーションがフォアグラウンドで起動していない場合、直接アプリケーションが受け取ります。
・0=フロント起動
・1=バックグラウンド起動

(Apple 提供ガイドラインからの抜粋)

content-availableプロパティの値が1であれば、リモート通知は「無言の」通知として振る舞います。無言の通知が届くと、iOSはアプリケーションをバックグラウンドで「起こし」て、サーバから新規データを取得したり、バックグラウンドで情報を処理したりできるようにします。ユーザは、この時点では新しい情報や変化した情報を何も知らされませんが、次にアプリケーションを開いた時点で知ることができます。

custom_data カスタムデータ オブジェクト ・アプリケーションが利用するパラメータを設定します。
・プッシュメッセージ全体のペイロードサイズは下記に制限されます。
iOS7以前:最大256バイト
iOS8以降:最大2048バイト
・基本書式は「{“aa”:”bb”}」となり、「””」による文字列指定となります。
・「{}」内は1階層のみ許可されます。
・文字列以外が指定された場合、予期せぬ変換が行われるため、必ず「””」で囲って下さい。
p12cert APNs証明書
(p12証明書)
文字列 ※説明参照 ・APNs証明書をBASE64(パディングなし)形式へ変換した文字列を設定します。
・APNs証明書のBASE64の変換手順は「9.APNsのp12証明書をBase64へ変換する手順」を参照して下さい。
※ユーザ管理画面のマーケット設定に、「証明書」が登録されている場合、本パラメータを省略することができます。
・ユーザ管理画面へ設定するAPNs証明書はBASE64へ変換する必要はありません。
password APNs証明書のパスワード 文字列 ※説明参照 ・APNs証明書のパスワードを設定します。
※ユーザ管理画面のマーケット設定に、「パスワード」が登録されている場合、本パラメータを省略することができます。
production プッシュ送信先環境 Boolean ※説明参照 ・プッシュ送信先の環境を設定します。
・true:本番環境
・false:サンドボックス環境
※ユーザ管理画面のマーケット設定に、「パスワード」が登録されている場合、本パラメータを省略することができます。
device_search_conditions デバイス検索条件 文字列 ※説明参照 ・条件で検索して結果がない場合は 404 が返却されます。
・全件指定の場合は “all” または “ALL” を指定して下さい。
・複数条件でなくても最後の「;」は必須となります。
※devices と device_search_conditions のいずれかを指定する必要があります。
devices と同時に指定することはできません。
devices デバイストークンリスト 文字列
リスト
※説明参照 ・Push送信先端末のデバイストークンをリスト形式で指定します。
※devices と device_search_conditions のいずれかを指定する必要があります。
device_search_conditions と同時に指定することはできません。

返却値

返却値: コンテントボディ

正常に予約登録が完了した場合の返却値を下記に説明します。

パラメータ名 項目名 タイプ 説明
_id 送信予約ID 文字列 ・予約IDを返却します。
payload_length 送信ペイロード長 Int ・送信メッセージのペイロード長を返却します。
duplicate_devices 重複したデバイスIDと個数 オブジェクト ・オプション「devices」のリスト内に重複デバイスが存在した場合、デバイスID、個数を返却します。
“duplicate_devices” : { “A” : 3 , “B” : 2}
返却値: レスポンスステータス

REST APIのレスポンスステータスを下記に説明します。

ステータスコード 説明
201 正常に処理が終了しました。(重複するデバイスIDなし)
202 正常に処理が終了しました。(重複するデバイスIDあり、自動重複排除処理済み)
400 不正なリクエスト内容が送信されました。
401 アプリトークンが未指定、又は、認証に失敗しました。
403 指定されたIDにアセス権限がありません。
412 マーケット設定が行われていません。
422 以下の何れかの誤りがあります。
・契約に対して送信できる上限数の超過、又は、パラメータが不適切です。
・オプション「apns」「gcm」の両方が指定されています。
・オプション「reserve_datetime」に過去日時が指定されています。
・オプション「reserve_datetime」に1ヶ月以上先の日時が指定されています。
500 アピアリーズサーバに於いて、エラーが発生しました。

REST API のリクエスト例

REST API リクエスト例: GCM

項目
リクエスト先のエンドポイント https://api-datastore.appiaries.com/v1/push/manage/{contractId}/{applicationId}
メソッド POST
コンテントタイプ application/json
ヘッダーパラメータ X-Appiaries-Token: {アプリトークン}

ボディパラメータ

devices 指定の場合

device_search_conditions 指定の場合

REST API リクエスト例: APNs

項目
リクエスト先のエンドポイント https://api-datastore.appiaries.com/v1/push/manage/{contractId}/{applicationId}
メソッド POST
コンテントタイプ application/json
ヘッダーパラメータ X-Appiaries-Token: {アプリトークン}

ボディパラメータ

devices 指定の場合

device_search_conditions 指定の場合

curl のリクエスト例

curl コマンド例: GCM

リクエストコマンドの例

devices 指定の場合

device_search_conditions 指定の場合

返却値の例

返却値の例:異常(1):パラメータエラー発生

※エラー番号一覧は「エラーコード一覧」を参照して下さい。

返却値の例:異常(2):パラメータエラー発生

※エラー番号一覧は「エラーコード一覧」を参照して下さい。

curl コマンド例: APNs

リクエストコマンドの例

devices 指定の場合

device_search_conditions 指定の場合

返却値の例

返却値の例:異常(1):パラメータエラー発生

※エラー番号一覧は「エラーコード一覧」を参照して下さい。

返却値の例:異常(2):パラメータエラー発生

※エラー番号一覧は「エラーコード一覧」を参照して下さい。