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

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

トピックの ACL エントリー

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

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

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

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

※ これらのシンボルは、列挙型 KiiACLAction で定義されています。KiiACLAction.KiiACLSubscribeToTopic のように指定できます。

サブジェクト（対象）

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

サブジェクト	誰が実行可能か
KiiUser インスタンス	指定されたユーザー。
KiiGroup インスタンス	指定されたグループのメンバー。
KiiThing インスタンス	指定された Thing。
KiiAnyAuthenticatedUser	ログイン済みの全ユーザー。
KiiAnonymousUser	匿名ユーザー。

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

トピックの ACL の管理

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

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

以下にグループスコープのトピックとユーザースコープのトピックに ACL エントリーを追加するサンプルコードを示します。

グループスコープのトピック

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

entry1：「認証済みユーザー全員」に「トピックの購読」アクションを許可。
entry2：_I_am_a_supervisor_ という名前のユーザーに「トピックの購読」アクションを許可。
entry3：_I_am_a_supervisor_ という名前のユーザーに「トピックへのプッシュメッセージ送信」アクションを許可。

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

// Instantiate a group.
var group = KiiGroup.groupWithURI(groupUri);

// Refresh the group.
group.refresh().then(
  function(theGroup) {
    // Find a user.
    return KiiUser.findUserByUsername("_I_am_a_supervisor_");
  }
).then(
  function(foundUser) {
    // Instantiate a topic in the group scope.
    var topicName = "GroupTopic";
    var topic = group.topicWithName(topicName);

    // Get the ACL handler.
    var acl = topic.acl();

    // Allow the authenticated users to subscribe to the topic.
    var entry1 = KiiACLEntry.entryWithSubject(new KiiAnyAuthenticatedUser(), KiiACLAction.KiiACLSubscribeToTopic);
    acl.putACLEntry(entry1);

    // Allow the user to subscribe to the topic.
    var entry2 = KiiACLEntry.entryWithSubject(foundUser, KiiACLAction.KiiACLSubscribeToTopic);
    acl.putACLEntry(entry2);

    // Allow the user to send push messages to the topic.
    var entry3 = KiiACLEntry.entryWithSubject(foundUser, KiiACLAction.KiiACLSendMessageToTopic);
    acl.putACLEntry(entry3);

    // Save all the ACL entries.
    return acl.save();
  }
).then(
  function(theACL) {
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.

    // Get the group for the failed refresh() method.
    var theGroup = error.target;
    // Get the ACL for the failed save() method.
    var theACL = error.target;
    // Get the error message.
    var errorString = error.message;
  }
);

// Instantiate a group.
var group = KiiGroup.groupWithURI(groupUri);

// Refresh the group.
group.refresh({
  success: function(theGroup) {
    // Find a user.
    KiiUser.findUserByUsername("_I_am_a_supervisor_",{
      success: function(foundUser) {
        // Instantiate a topic in the group scope.
        var topicName = "GroupTopic";
        var topic = group.topicWithName(topicName);

        // Get the ACL handler.
        var acl = topic.acl();

        // Allow the authenticated users to subscribe to the topic.
        var entry1 = KiiACLEntry.entryWithSubject(new KiiAnyAuthenticatedUser(), KiiACLAction.KiiACLSubscribeToTopic);
        acl.putACLEntry(entry1);

        // Allow the user to subscribe to the topic.
        var entry2 = KiiACLEntry.entryWithSubject(foundUser, KiiACLAction.KiiACLSubscribeToTopic);
        acl.putACLEntry(entry2);

        // Allow the user to send push messages to the topic.
        var entry3 = KiiACLEntry.entryWithSubject(foundUser, KiiACLAction.KiiACLSendMessageToTopic);
        acl.putACLEntry(entry3);

        // Save all the ACL entries.
        acl.save({
          success: function(theACL) {
            // Do something.
          },
          failure: function(theACL, errorString) {
            // Handle the error.
          }
        });
      },
      failure: function(errorString) {
        // Handle the error.
      }
    });
  },
  failure: function(theGroup, errorString) {
    // Handle the error.
  }
});

ここでは以下の処理が行われています。

URI から目的のグループを取得し、そのグループ内の GroupTopic という名前のトピックを取得します。
変更対象のトピックの acl() メソッドを実行して ACL ハンドラーを作成します。
KiiACLEntry のコンストラクタを呼び出して、冒頭に示した entry1 ～ entry3の ACL エントリーを作成します。
作成した 3 つの ACL エントリーそれぞれを putACLEntry() メソッドでローカル保存します。
save() メソッドを実行し、ローカルの ACL エントリーを Kii Cloud に保存します。

ユーザースコープのトピック

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

URI で指定されたグループに、「トピックの購読」アクションを許可。

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

// Instantiate an existing topic in the user scope.
var topicName = "MyTODO";
var topic = KiiUser.getCurrentUser().topicWithName(topicName);

// Get the ACL handler.
var acl = topic.acl();

// Instantiate a group.
var group = KiiGroup.groupWithURI(groupUri);

// Refresh the group.
group.refresh().then(
  function(theGroup) {
    // Allow the group members to subscribe to the topic.
    var entry = KiiACLEntry.entryWithSubject(theGroup, KiiACLAction.KiiACLSubscribeToTopic);
    acl.putACLEntry(entry);

    // Save all the ACL entries.
    return acl.save();
  }
).then(
  function(theACL) {
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.

    // Get the group for the failed refresh() method.
    var theGroup = error.target;
    // Get the ACL for the failed save() method.
    var theACL = error.target;
    // Get the error message.
    var errorString = error.message;
  }
);

// Instantiate an existing topic in the user scope.
var topicName = "MyTODO";
var topic = KiiUser.getCurrentUser().topicWithName(topicName);

// Get the ACL handler.
var acl = topic.acl();

// Instantiate a group.
var group = KiiGroup.groupWithURI(groupUri);

// Refresh the group.
group.refresh({
  success: function(theGroup) {
    // Allow the group members to subscribe to the topic.
    var entry = KiiACLEntry.entryWithSubject(theGroup, KiiACLAction.KiiACLSubscribeToTopic);
    acl.putACLEntry(entry);

    // Save all the ACL entries.
    acl.save({
      success: function(theACL) {
        // Do something.
      },
      failure: function(theACL, errorString) {
        // Handle the error.
      }
    });
  },
  failure: function(theGroup, errorString) {
    // Handle the error.
  }
});

基本的な処理は、先ほどのサンプルコードと同様です。こちらの例では、ACL エントリーのサブジェクトとしてユーザーグループを指定しています。これにより、指定したアクション（トピックの購読）が、このユーザーグループのメンバー全員に許可されます。

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

設定されている ACL エントリーを削除するには、KiiACLEntry の grant を false にしたエントリーを作成して保存します。サーバー上の ACL から指定した ACL エントリーが削除されます。

サンプルコードはグループスコープのトピック、ユーザースコープのトピックとも、上記の ACL エントリーの追加の場合と同様で、KiiACLEntry のインスタンスを作成後、entry.setGrant(false) を実行する点だけが異なります。

KiiACL の removeACLEntry() メソッドは、クライアント側で準備中の「ACL の変更リスト」のエントリーを削除するもので、サーバー上の ACL エントリーを削除するものではない点にご注意ください。ACL 設定のコードでは、クライアント上の acl に対して KiiACLSubscribeToTopic を伴う ACL エントリーの削除要求を登録してから、save() メソッドでサーバーに反映しています。removeACLEntry は、この ACL エントリーを変更リストから削除するためのもので、サーバー上の ACL を直接操作するためのものではありません。

トピックの ACL を取得する

トピックに設定されている ACL を取得できます。ACL エントリーを明示的に設定していない場合でも、デフォルトの ACL を取得することができます。

以下のように、ACL は ACL エントリーの配列として取得できます。

// Instantiate an existing topic in the user scope.
var topicName = "MyTODO";
var topic = KiiUser.getCurrentUser().topicWithName(topicName);

// Get the ACL handler.
var acl = topic.acl();

// Get the ACL.
acl.listACLEntries().then(
  function(params) {
    var theACL = params[0];
    var theEntries = params[1];
    for(var i = 0; i < theEntries.length; i++) {
      var action = theEntries[i].getAction();
      var subject = theEntries[i].getSubject();
      // Check the ACL entry.
    }
  }
).catch(
  function(error) {
    // Handle the error.
  }
);

// Instantiate an existing topic in the user scope.
var topicName = "MyTODO";
var topic = KiiUser.getCurrentUser().topicWithName(topicName);

// Get the ACL handler.
var acl = topic.acl();

// Get the ACL.
acl.listACLEntries({
  success: function(theACL, theEntries) {
    for(var i = 0; i < theEntries.length; i++) {
      var action = theEntries[i].getAction();
      var subject = theEntries[i].getSubject();
      // Check the ACL entry.
    }
  },
  failure: function(theACL, errorString) {
    // Handle the error.
  }
});

acl() メソッドをコールして KiiACL のインスタンスを生成します。
listAclEntries() メソッドをコールして、登録されている ACL を KiiACLEntry の配列として取得します。
配列の各エントリーを確認することで目的の処理を実行します。

action には KiiACLAction のいずれかが、subject にはサブジェクトが入ります。いずれも ACL エントリーの一覧をご覧ください。

ACL 設定の際、設定済みの ACL エントリーをさらに追加しようとするとエラーとなります。ここに示す方法で ACL を事前にチェックすることによって、必要な ACL エントリーの変更差分を作成できます。

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

複数回実行するとエラーになる

ACL エントリーは初期化処理等で 1 回だけ書き換え、次回の実行時には再設定しないような実装が必要です。

保存しようとしている ACL エントリーがすでに設定されていた場合、エラーになります。特に、同じ登録処理を複数回実行すると、登録しようとしている ACL エントリーがすでに存在することになるため、エラーになる点に注意が必要です。

なお、複数の ACL エントリーは 1 件ずつサーバーに反映するため、途中でエラーが発生すると不完全な形で ACL エントリーが保存されます。このような状況から回復するには、既存の ACL をサーバーから一旦取得し、重複している ACL エントリーを削除してから登録するような処理が必要です。取得方法の詳細はトピックの ACL を取得するをご覧ください。
ACL エントリーを削除できない

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