トピックの ACL のカスタマイズ

トピックの ACL を変更して、トピックの購読やメッセージの送信を実行できるユーザーをカスタマイズすることができます。ここでは、アクセス権を変更するための実装方法を説明します。

トピックの作成許可をカスタマイズするには、トピックの作成先になるスコープの ACL を変更します。

トピックの ACL を設定する

トピックの ACL エントリーに指定可能な項目は以下のとおりです。

アクション（アクセス制御）

対象のユーザーやグループが「何をできるか」を指定します。

アクション	対象ユーザー/グループ/Thing ができること
SUBSCRIBE_TO_TOPIC	トピックの講読。
SEND_MESSAGE_TO_TOPIC	トピックに対するプッシュメッセージの送信。

サブジェクト（対象）

「誰が」実行できるようになるかを指定します。

サブジェクト	誰が実行可能か
UserID:{USER_ID}	指定されたユーザー。
GroupID:{GROUP_ID}	指定されたグループのメンバー。
ThingID:{THING_ID}	指定された Thing。
UserID:ANY_AUTHENTICATED_USER	ログイン済みの全ユーザー。
UserID:ANONYMOUS_USER	匿名ユーザー。

ログイン済みの全ユーザーと匿名ユーザーの定義については、サブジェクトをご覧ください。

これらのアクションとサブジェクトを使って、「どのトピックの」アクセス許可を変更するかを以下の URL で指定します。

アプリケーションスコープ：

https://api-jp.kii.com/api/apps/{APP_ID}/topics/{TOPIC_ID}/acl/{ACTION}/{SUBJECT}
トピック作成者のアクセストークンが必要
グループスコープ：

https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}/topics/{TOPIC_ID}/acl/ {ACTION}/{SUBJECT}
トピック作成者、または、グループオーナーのアクセストークンが必要
ユーザースコープ：

https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/topics/{TOPIC_ID}/acl/ {ACTION}/{SUBJECT}
https://api-jp.kii.com/api/apps/{APP_ID}/users/me/topics/{TOPIC_ID}/acl/{ACTION}/{SUBJECT}
トピック作成者、または、スコープオーナーのアクセストークンが必要
Thing スコープ：

https://api-jp.kii.com/api/apps/{APP_ID}/things/VENDOR_THING_ID:{VENDOR_THING_ID}/ topics/{TOPIC_ID}/acl/{ACTION}/{SUBJECT}
https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}/topics/{TOPIC_ID}/acl/ {ACTION}/{SUBJECT}
トピック作成者、Thing、または、Thing オーナーのアクセストークンが必要

トピックの ACL の管理

トピックの ACL にエントリーを追加または削除できます。ACL エントリーの一覧を取得することもできます。

トピックに ACL エントリーを追加する

以下のリクエストは、グループスコープのトピック GroupTopic に対して、次の ACL エントリーを追加する例です。

「認証済みユーザー全員」に「トピックの購読」アクションを許可。

なお、これはアクセス権の変更例で示したシナリオの 1 つ目の例に対応します。

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}/topics/GroupTopic/acl/SUBSCRIBE_TO_TOPIC/UserID:ANY_AUTHENTICATED_USER" \
  -d ""

以下のリクエストは、グループスコープのトピック GroupTopic に対して、次の ACL エントリーを追加する例です。

{USER_ID} に「トピックの購読」アクションを許可。
{USER_ID} に「トピックへのプッシュメッセージ送信」アクションを許可。

なお、これはアクセス権の変更例で示したシナリオの 2 つ目の例に対応します。

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}/topics/GroupTopic/acl/SUBSCRIBE_TO_TOPIC/UserID:{USER_ID}" \
  -d ""

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}/topics/GroupTopic/acl/SEND_MESSAGE_TO_TOPIC/UserID:{USER_ID}" \
  -d ""

以下のリクエストは、ユーザースコープのトピック MyTODO に対して、次の ACL エントリーを追加する例です。

{GROUP_ID} に「トピックの購読」アクションを許可。

なお、これはアクセス権の変更例で示したシナリオの 3 つ目の例に対応します。

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/topics/MyTODO/acl/SUBSCRIBE_TO_TOPIC/GroupID:{GROUP_ID}" \
  -d ""

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

ACL エントリーを正常に受け付けた場合は、204 応答を返します。
指定したトピックが存在しない場合は、エラーコード TOPIC_NOT_FOUND を 404 応答で返します。
同じ ACL エントリーが登録済みの場合は、エラーコード ACL_ALREADY_EXISTS を 409 応答で返します。

トピックの ACL エントリーを削除する

一旦許可したアクションを取り消すには、対応する ACL エントリーの DELETE リクエストを送信します。

この例では、ANY_AUTHENTICATED_USER に許可した SUBSCRIBE_TO_TOPIC アクションの ACL エントリーを削除しています。

curl -v -X DELETE \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}/topics/GroupTopic/acl/SUBSCRIBE_TO_TOPIC/UserID:ANY_AUTHENTICATED_USER"

この例ではグループスコープのトピックを指定していますが、初めに示した URL によって、その他のスコープも操作できます。

トピックの ACL を取得する

トピックに設定されている ACL を取得するには、対応する URL からアクションやサブジェクトを省略した形で GET リクエストを送信します。

たとえば、SUBSCRIBE_TO_TOPIC アクションを許可されているサブジェクトの一覧は以下のようにして取得できます。

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}/topics/GroupTopic/acl/SUBSCRIBE_TO_TOPIC"

また、該当トピックの ACL 全体は、以下のように取得できます。

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}/topics/GroupTopic/acl"

いずれの例もグループスコープのトピックを指定していますが、初めに示した URL によって、その他のスコープも操作できます。

期待どおりに動作しない場合

ACL エントリーを削除できない

トピック作成者やスコープオーナーにデフォルトで許可されるアクションの ACL エントリーは削除できません。詳細はスコープオーナーや作成者の ACL エントリーは削除できませんをご覧ください。