Bucket の ACL のカスタマイズ

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

KiiObject にアクセスする場合は、KiiObject の ACL も確認されます。

Bucket の ACL エントリー

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

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

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

    アクション コードでの指定 ※ 対象ユーザー/グループ/Thing ができること
    CREATE_OBJECTS_IN_BUCKET bucketActionCreateObjects Bucket 内に新たな KiiObject を追加。
    QUERY_OBJECTS_IN_BUCKET bucketActionQueryObjects Bucket 内の KiiObject を検索。
    READ_OBJECTS_IN_BUCKET bucketActionReadObjects Bucket 内の KiiObject を読み取り。
    DROP_BUCKET_WITH_ALL_CONTENT bucketActionDropBucket 中の KiiObject とともに Bucket を削除。

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

    注意:bucketActionReadObjects アクションを許可すると、Bucket 内の全ての KiiObject を無条件で読み取れるようになります。詳細は ACL の変更の例 を参照してください。

  • サブジェクト(対象)

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

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

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

Bucket の ACL の管理

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

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

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

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

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

Swift 3:

  • let bucket = KiiUser.current()!.bucket(withName: "my_private")
    
    var succeeded: NSArray?
    var failed: NSArray?
    
    // Create ACL entries.
    let entry = KiiACLEntry(subject: KiiAnyAuthenticatedUser.aclSubject(), andAction: KiiACLAction.bucketActionQueryObjects)!
    let entry2 = KiiACLEntry(subject: KiiAnyAuthenticatedUser.aclSubject(), andAction: KiiACLAction.bucketActionCreateObjects)!
    
    let acl = bucket.bucketACL
    
    // Set the ACL entries to the bucket ACL.
    acl.put(entry)
    acl.put(entry2)
    
    do{
      // Save the ACL to the server.
      try acl.saveSynchronous(&succeeded, didFail: &failed)
    } catch let error as NSError {
      // Handle the error.
      // Failed to update one ACL entry at least.
      // Check the error description and succeeded/failed arrays.
      return
    }
  • let bucket = KiiUser.current()!.bucket(withName: "my_private")
    
    // Create ACL entries.
    let entry = KiiACLEntry(subject: KiiAnyAuthenticatedUser.aclSubject(), andAction: KiiACLAction.bucketActionQueryObjects)!
    let entry2 = KiiACLEntry(subject: KiiAnyAuthenticatedUser.aclSubject(), andAction: KiiACLAction.bucketActionCreateObjects)!
    
    let acl = bucket.bucketACL
    
    // Set the ACL entries to the bucket ACL.
    acl.put(entry)
    acl.put(entry2)
    
    // Save the ACL to the server.
    acl.save { (acl : KiiACL , succeeded : [Any]?, failed : [Any]?, error : Error?) -> Void in
      if (error != nil) {
        // Handle the error.
        // Failed to update one ACL entry at least.
        // Check the error description and succeeded/failed arrays.
        return
      }
    }

Objective-C:

  • KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"my_private"];
    NSError *error;
    NSArray *succeeded, *failed;
    
    // Create ACL entries.
    KiiACLEntry *entry = [KiiACLEntry entryWithSubject:[KiiAnyAuthenticatedUser aclSubject] andAction:KiiACLBucketActionQueryObjects];
    KiiACLEntry *entry2 = [KiiACLEntry entryWithSubject:[KiiAnyAuthenticatedUser aclSubject] andAction:KiiACLBucketActionCreateObjects];
    
    KiiACL *acl = [bucket bucketACL];
    
    // Set the ACL entries to the bucket ACL.
    [acl putACLEntry:entry];
    [acl putACLEntry:entry2];
    
    // Save the ACL to the server.
    [acl saveSynchronous:&error
              didSucceed:&succeeded
                 didFail:&failed];
    
    if (error != nil) {
      // Handle the error.
      // Failed to update one ACL entry at least.
      // Check the error description and succeeded/failed arrays.
      return;
    }
  • KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"my_private"];
    
    // Create ACL entries.
    KiiACLEntry *entry = [KiiACLEntry entryWithSubject:[KiiAnyAuthenticatedUser aclSubject] andAction:KiiACLBucketActionQueryObjects];
    KiiACLEntry *entry2 = [KiiACLEntry entryWithSubject:[KiiAnyAuthenticatedUser aclSubject] andAction:KiiACLBucketActionCreateObjects];
    
    KiiACL *acl = [bucket bucketACL];
    
    // Set the ACL entries to the bucket ACL.
    [acl putACLEntry:entry];
    [acl putACLEntry:entry2];
    
    // Save the ACL to the server.
    [acl saveWithBlock:^(KiiACL *acl, NSArray *succeeded, NSArray *failed, NSError *error) {
      if (error != nil) {
        // Handle the error.
        // Failed to update one ACL entry at least.
        // Check the error description and succeeded/failed arrays.
        return;
      }
    }];

これらは以下の処理を行っています。

  1. bucketACL() メソッドをコールして KiiACL のインスタンスを生成します。
  2. KiiACLEntry を生成して、 put(_:) メソッドの引数として渡します。この例では KiiAnyAuthenticatedUser インスタンスをサブジェクトとして設定し、ログイン済みの全ユーザーにアクセス権限を与えています。同様に KiiAnonymousUser を指定すれば匿名ユーザーに、特定の KiiUser を指定すれば、そのユーザーにアクセス権限を付与できます。
  3. save(_:) メソッドをコールして ACL の変更要求を Kii Cloud に送信します。

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

複数の ACL エントリーを追加する場合、SDK はそれらを 1 件ずつ処理するため、一部の ACL エントリーの処理が失敗する可能性があります。ACL の設定に失敗したときは、サンプルコード上の succeededfailed によって、成功した ACL エントリーの一覧と失敗した ACL エントリーの一覧を取得できます。

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

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

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

Swift 3:

  • let bucket = KiiUser.current()!.bucket(withName: "my_private")
    
    var succeeded: NSArray?
    var failed: NSArray?
    
    // Create ACL entries.
    let entry = KiiACLEntry(subject: KiiAnyAuthenticatedUser.aclSubject(), andAction: KiiACLAction.bucketActionQueryObjects)!
    entry.grant = false
    let entry2 = KiiACLEntry(subject: KiiAnyAuthenticatedUser.aclSubject(), andAction: KiiACLAction.bucketActionCreateObjects)!
    entry2.grant = false
    
    let acl = bucket.bucketACL
    
    // Delete the ACL entries from the bucket ACL.
    acl.put(entry)
    acl.put(entry2)
    
    do{
      // Save the ACL to the server.
      try acl.saveSynchronous(&succeeded, didFail: &failed)
    } catch let error as NSError {
      // Handle the error.
      // Failed to update one ACL entry at least.
      // Check the error description and succeeded/failed arrays.
      return
    }
  • let bucket = KiiUser.current()!.bucket(withName: "my_private")
    
    // Create ACL entries.
    let entry = KiiACLEntry(subject: KiiAnyAuthenticatedUser.aclSubject(), andAction: KiiACLAction.bucketActionQueryObjects)!
    entry.grant = false
    let entry2 = KiiACLEntry(subject: KiiAnyAuthenticatedUser.aclSubject(), andAction: KiiACLAction.bucketActionCreateObjects)!
    entry2.grant = false
    
    let acl = bucket.bucketACL
    
    // Delete the ACL entries from the bucket ACL.
    acl.put(entry)
    acl.put(entry2)
    
    // Save the ACL to the server.
    acl.save { (acl : KiiACL , succeeded : [Any]?, failed : [Any]?, error : Error?) -> Void in
      if (error != nil) {
        // Handle the error.
        // Failed to update one ACL entry at least.
        // Check the error description and succeeded/failed arrays.
        return
      }
    }

Objective-C:

  • KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"my_private"];
    NSError *error;
    NSArray *succeeded, *failed;
    
    // Create ACL entries.
    KiiACLEntry *entry = [KiiACLEntry entryWithSubject:[KiiAnyAuthenticatedUser aclSubject] andAction:KiiACLBucketActionQueryObjects];
    entry.grant = NO;
    KiiACLEntry *entry2 = [KiiACLEntry entryWithSubject:[KiiAnyAuthenticatedUser aclSubject] andAction:KiiACLBucketActionCreateObjects];
    entry2.grant = NO;
    
    KiiACL *acl = [bucket bucketACL];
    
    // Delete the ACL entries from the bucket ACL.
    [acl putACLEntry:entry];
    [acl putACLEntry:entry2];
    
    // Save the ACL to the server.
    [acl saveSynchronous:&error
              didSucceed:&succeeded
                 didFail:&failed];
    
    if (error != nil) {
      // Handle the error.
      // Failed to update one ACL entry at least.
      // Check the error description and succeeded/failed arrays.
      return;
    }
  • KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"my_private"];
    
    // Create ACL entries.
    KiiACLEntry *entry = [KiiACLEntry entryWithSubject:[KiiAnyAuthenticatedUser aclSubject] andAction:KiiACLBucketActionQueryObjects];
    entry.grant = NO;
    KiiACLEntry *entry2 = [KiiACLEntry entryWithSubject:[KiiAnyAuthenticatedUser aclSubject] andAction:KiiACLBucketActionCreateObjects];
    entry2.grant = NO;
    
    KiiACL *acl = [bucket bucketACL];
    
    // Delete the ACL entries from the bucket ACL.
    [acl putACLEntry:entry];
    [acl putACLEntry:entry2];
    
    // Save the ACL to the server.
    [acl saveWithBlock:^(KiiACL *acl, NSArray *succeeded, NSArray *failed, NSError *error) {
      if (error != nil) {
        // Handle the error.
        // Failed to update one ACL entry at least.
        // Check the error description and succeeded/failed arrays.
        return;
      }
    }];

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

Bucket の ACL を取得する

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

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

Swift 3:

  • let bucket = KiiUser.current()!.bucket(withName: "my_private")
    let acl = bucket.bucketACL
    
    do{
      // Get the ACL entries from the server.
      let aclList = try acl.listACLEntriesSynchronous() as! [KiiACLEntry]
      for entry in aclList{
        let action = entry.action
        let subject = entry.subject
        // Check the ACL entry.
      }
    }catch(let error as NSError){
      // Handle the error.
      return
    }
  • let bucket = KiiUser.current()!.bucket(withName: "my_private")
    let acl = bucket.bucketACL
    
    // Get the ACL entries from the server.
    acl.listACLEntries { (retAcl : KiiACL, aclList : [Any]?, error : Error?) -> Void in
      if (error != nil) {
        // Handle the error.
        return
      }
      for entry in aclList as! [KiiACLEntry]{
        let action = entry.action
        let subject = entry.subject
        // Check the ACL entry.
      }
    }

Objective-C:

  • KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"my_private"];
    
    KiiACL *acl = [bucket bucketACL];
    NSError *error = nil;
    
    // Get the ACL entries from the server.
    NSArray *aclList = [acl listACLEntriesSynchronous:&error];
    if (error != nil) {
      // Handle the error.
      return;
    }
    for (KiiACLEntry *entry in aclList) {
      KiiACLAction action = entry.action;
      id subject = entry.subject;
      // Check the ACL entry.
    }
  • KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"my_private"];
    
    KiiACL *acl = [bucket bucketACL];
    
    // Get the ACL entries from the server.
    [acl listACLEntriesWithBlock:^(KiiACL *acl, NSArray *aclList, NSError *error) {
      if (error != nil) {
        // Handle the error.
        return;
      }
      for (KiiACLEntry *entry in aclList) {
        KiiACLAction action = entry.action;
        id subject = entry.subject;
        // Check the ACL entry.
      }
    }];
  1. bucketACL() メソッドをコールして KiiACL のインスタンスを生成します。
  2. listACLEntries(_:) メソッドをコールして、登録されている ACL を KiiACLEntry の NSArray として取得します。
  3. NSArray の各エントリーを確認することで目的の処理を実行します。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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