Bucket の購読

ある Bucket の更新に興味のあるユーザーは、この Bucket を講読することで、Bucket に何らかの更新があった際にプッシュ通知を受信できるようになります。

アプリケーションスコープの Bucket を購読する例を以下に挙げます。

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/buckets/{BUCKET_ID}/filters/all/push/subscriptions/users/{TARGET_USER_ID}" \
  -d ""

グループスコープの Bucket を購読する例を以下に挙げます。

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}/buckets/{BUCKET_ID}/filters/all/push/subscriptions/users/{TARGET_USER_ID}" \
  -d ""

ユーザースコープの Bucket を購読する例を以下に挙げます。

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/filters/all/push/subscriptions/users/{TARGET_USER_ID}" \
  -d ""

いずれの場合についても {APP_ID} をアプリの値に、{TARGET_USER_ID} を購読するユーザーの ID にそれぞれ置き換えてください。また {ACCESS_TOKEN} は、このユーザーのアクセストークンかアプリ管理者トークンである必要があります。

Bucket 購読者と ACCESS_TOKEN 所有者が同一の場合は、以下の例のように TARGET_USER_ID の指定を省略できます。

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/buckets/{BUCKET_ID}/filters/all/push/subscriptions/users" \
  -d ""

Kii Cloud は以下の応答を返します。

Bucket の購読に成功した場合は、204 応答を返します。
指定した Bucket が存在しない場合は、エラーコード FILTER_NOT_FOUND を 404 応答で返します。
指定した Bucket を購読済みの場合は、エラーコード PUSH_SUBSCRIPTION_ALREADY_EXISTS を 404 応答で返します。

多数の KiiObject を持つ Bucket の購読

Bucket への更新が 1 件あるごとに、プッシュ通知は 1 回行われるため、Bucket によってはプッシュ通知の回数が非常に多くなります。

たとえば、3 台のデバイスを持っているユーザーが、ある Bucket を購読しているとします。その Bucket に 100 件のオブジェクトがあり、それらすべてが更新されたとすると、プッシュ通知の回数は各デバイスごとに 100 回、合計 300 回のプッシュ通知となります。

あらかじめ、このように大量のプッシュ通知が発生することが予想できる場合は、サーバー上変更のプッシュ通知（Push to App）ではなく、ユーザープッシュ通知 (Push to User) を利用することができます。Bucket を更新した後、プログラムからトピックへのメッセージ送信の要求を出すことで、プッシュ通知の回数をデバイスごとに 1 回とすることができます。ただし、この場合はトランザクションに示すように、更新とトピックへのプッシュ要求の間に処理の中断要素があるため、プッシュが届かない可能性も考慮する必要があります。