トピックの 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.
      }
    });

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

  1. URI から目的のグループを取得し、そのグループ内の GroupTopic という名前のトピックを取得します。
  2. 変更対象のトピックの acl() メソッドを実行して ACL ハンドラーを作成します。
  3. KiiACLEntry のコンストラクタを呼び出して、冒頭に示した entry1entry3の ACL エントリーを作成します。
  4. 作成した 3 つの ACL エントリーそれぞれを putACLEntry() メソッドでローカル保存します。
  5. 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 エントリーを削除するには、KiiACLEntrygrant を false にしたエントリーを作成して保存します。サーバー上の ACL から指定した ACL エントリーが削除されます。

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

KiiACLremoveACLEntry() メソッドは、クライアント側で準備中の「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.
      }
    });
  1. acl() メソッドをコールして KiiACL のインスタンスを生成します。
  2. listAclEntries() メソッドをコールして、登録されている ACL を KiiACLEntry の配列として取得します。
  3. 配列の各エントリーを確認することで目的の処理を実行します。

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

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

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

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

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

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

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

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

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