Bucket の ACL 設定

Bucket の ACL を設定することにより、Bucket そのものに対するアクセス権を変更できます。

Object にアクセスする場合は、Object の ACL も確認されます。Object の ACL 設定に関する詳細は Object の ACL 設定 を参照してください。

アクセス権についての機能概要は アクセス制御 以下の情報をご覧ください。特に、Bucket のデフォルト ACL については Bucket に対するアクセス権 に記載があります。このページでは、機能概要の知識があることを前提に実装方法を説明しています。

Bucket の ACL エントリー

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

  • アクション(アクセス制御)

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

    アクション 対象ユーザー/グループ/Thing ができること
    CREATE_OBJECTS_IN_BUCKET Bucket 内に新たな Object を追加。
    QUERY_OBJECTS_IN_BUCKET Bucket 内の Object を検索。
    READ_OBJECTS_IN_BUCKET Bucket 内の Object を読み取り。
    DROP_BUCKET_WITH_ALL_CONTENT 中の Object とともに Bucket をドロップ。

    注意:READ_OBJECTS_IN_BUCKET アクションを許可すると、Bucket 内の全ての Object を無条件で読み取れるようになります。

  • サブジェクト(対象)

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

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

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

Bucket の ACL の管理

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

Bucket に ACL エントリーを追加する

アプリケーションスコープ以外のスコープの Bucket については、ACL を設定して新たなアクセス許可を追加できます(例:匿名ユーザーに対して Bucket 内への Object 作成を許可する)。アプリケーションスコープの Bucket の ACL は、管理者のみが変更できます。下記のヒント をご覧ください。

まだ存在しない Bucket に対して ACL エントリーを追加することもできます。この場合、Bucket を自動生成した後に ACL エントリーが追加されます。

一例として、ユーザースコープの Bucket に 2 つの新しい ACL エントリーを追加する例を挙げます。この例では QUERY_OBJECTS_IN_BUCKET アクションと CREATE_OBJECTS_IN_BUCKET アクションを KiiAnyAuthenticatedUser に許可しています。

  • KiiBucket userBucket = Kii.user().bucket("my_private");
    KiiACL bucketACL = userBucket.acl();
    
    // Set ACL entries to the bucket ACL.
    bucketACL.putACLEntry(new KiiACLEntry(KiiAnyAuthenticatedUser.create(),
                KiiACL.BucketAction.QUERY_OBJECTS_IN_BUCKET, true));
    bucketACL.putACLEntry(new KiiACLEntry(KiiAnyAuthenticatedUser.create(),
                KiiACL.BucketAction.CREATE_OBJECTS_IN_BUCKET, true));
    
    try {
      // Save the ACL to the server.
      bucketACL.save();
    } catch (ACLOperationException e) {
      // Handle the error.
      List<KiiACLEntry> failed = e.getFailedACLEntries();
    }
  • KiiBucket userBucket = Kii.user().bucket("my_private");
    KiiACL bucketACL = userBucket.acl();
    
    // Set ACL entries to the bucket ACL.
    bucketACL.putACLEntry(new KiiACLEntry(KiiAnyAuthenticatedUser.create(),
                KiiACL.BucketAction.QUERY_OBJECTS_IN_BUCKET, true));
    bucketACL.putACLEntry(new KiiACLEntry(KiiAnyAuthenticatedUser.create(),
                KiiACL.BucketAction.CREATE_OBJECTS_IN_BUCKET, true));
    
    // Save the ACL to the server.
    bucketACL.save(new KiiACLCallBack() {
      @Override
      public void onSaveCompleted(int token, KiiACL acl, Exception exception) {
        if (exception != null) {
          // Handle the error.
          return;
        }
      }
    });
  1. acl メソッドをコールして KiiACL のインスタンスを生成します。
  2. KiiACLEntry を生成して、 putACLEntry メソッドの引数として渡します。この例では KiiAnyAuthenticatedUser インスタンスをサブジェクトとして設定し、ログイン済みの全ユーザーにアクセス権限を与えています。同様に KiiAnonymousUser を指定すれば匿名ユーザーに、特定の KiiUser を指定すれば、そのユーザーにアクセス権限を付与できます。
  3. save メソッドをコールして ACL の変更要求を Kii Cloud に送信します。

ACL エントリーにユーザーやグループなど、他のサブジェクトを指定する方法の詳細は KiiACLEntry を参照してください。

複数の ACL エントリーを追加する場合、SDK はそれらを 1 件ずつ処理するため、一部の ACL エントリーの処理が失敗する可能性があります。ACL の設定に失敗したときは、ACLOperationExceptiongetFailedACLEntries メソッドを使うと、追加されなかった ACL エントリーの一覧を取得できます。

Bucket の ACL エントリーを削除する

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

以下は、上のサンプルコードによって作成された ACL エントリーを削除する例です。

  • KiiBucket userBucket = Kii.user().bucket("my_private");
    KiiACL bucketACL = userBucket.acl();
    
    // Delete the ACL entries from the bucket ACL.
    bucketACL.putACLEntry(new KiiACLEntry(KiiAnyAuthenticatedUser.create(),
                KiiACL.BucketAction.QUERY_OBJECTS_IN_BUCKET, false));
    bucketACL.putACLEntry(new KiiACLEntry(KiiAnyAuthenticatedUser.create(),
                KiiACL.BucketAction.CREATE_OBJECTS_IN_BUCKET, false));
    
    try {
      // Save the ACL to the server.
      bucketACL.save();
    } catch (ACLOperationException e) {
      // Handle the error.
    }
  • KiiBucket userBucket = Kii.user().bucket("my_private");
    KiiACL bucketACL = userBucket.acl();
    
    // Delete the ACL entries from the bucket ACL.
    bucketACL.putACLEntry(new KiiACLEntry(KiiAnyAuthenticatedUser.create(),
                KiiACL.BucketAction.QUERY_OBJECTS_IN_BUCKET, false));
    bucketACL.putACLEntry(new KiiACLEntry(KiiAnyAuthenticatedUser.create(),
                KiiACL.BucketAction.CREATE_OBJECTS_IN_BUCKET, false));
    
    // Save the ACL to the server.
    bucketACL.save(new KiiACLCallBack() {
      @Override
      public void onSaveCompleted(int token, KiiACL acl, Exception exception) {
        if (exception != null) {
          // Handle the error.
          return;
        }
      }
    });

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

Bucket の ACL を取得する

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

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

  • KiiBucket userBucket = KiiUser.getCurrentUser().bucket("my_private");
    KiiACL bucketACL = userBucket.acl();
    try {
      // Get the ACL entries from the server.
      Set<KiiACLEntry> list = bucketACL.listACLEntries();
      for (KiiACLEntry entry : list) {
        KiiACL.Action action = entry.getAction();
        KiiSubject subject = entry.getSubject();
        // Check the ACL entry.
      }
    } catch (ACLOperationException e) {
      // Handle the error.
    }
  • KiiBucket userBucket = KiiUser.getCurrentUser().bucket("my_private");
    KiiACL bucketACL = userBucket.acl();
    
    // Get the ACL entries from the server.
    bucketACL.listACLEntries(new KiiACLCallBack() {
      public void onListACLEntriesCompleted(int token, Set<KiiACLEntry> list, KiiACL acl, Exception exception) {
        if (exception != null) {
          // Handle the error.
          return;
        }
        for (KiiACLEntry entry : list) {
          KiiACL.Action action = entry.getAction();
          KiiSubject subject = entry.getSubject();
          // Check the ACL entry.
        }
      }
    });
  1. acl メソッドをコールして KiiACL のインスタンスを生成します。
  2. listAclEntries メソッドをコールして、登録されている ACL を KiiACLEntry の Set として取得します。
  3. Set の各エントリーを確認することで目的の処理を実行します。

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

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

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

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

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

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

  • "QUERY_OBJECTS_IN_BUCKET" を許可しても Bucket 内の Object を検索できない

    QUERY_OBJECTS_IN_BUCKET アクションは、Bucket 内の検索のみを許可します。検索結果を取得するには、検索対象である Object に対する読み取り権限が必要です。

    Object に対する読み取り権限を与える最も簡単な方法は、サブジェクトに QUERY_OBJECTS_IN_BUCKET アクションとともに READ_OBJECTS_IN_BUCKET アクションを許可することです。これにより、サブジェクトは Bucket 内の全ての Object に対する読み取り権限を持つことになるため、検索結果を読み取れるようになります。

    別の方法として Bucket 内の Object に対する READ_EXISTING_OBJECT アクションをサブジェクトに許可する方法もあります。Object ACL について詳しくは Object の ACL 設定 をご覧ください。

    また ACL の変更の例 に詳しい説明がありますので、あわせてご覧ください。

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

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

  • アプリケーションスコープの Bucket の ACL を変更できない

    アプリケーションスコープの Bucket の ACL を変更するにはアプリ管理者の権限が必要です。操作は、REST API を使って実行できます。アプリ管理者向け機能 の方法によってアプリ管理者のアクセストークンを取得し、Bucket の ACL 設定 の方法によってアクセス権を変更します。

    なお、アクセス権の操作が可能なユーザーについては、Bucket に対するアクセス権 の表をご覧ください。