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:

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;
  }
}];

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

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

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

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

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

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

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

Swift:

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;
  }
}];

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

Bucket の ACL を取得する

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

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

Swift:

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.
  }
}];

bucketACL() メソッドをコールして KiiACL のインスタンスを生成します。
listACLEntries(_:) メソッドをコールして、登録されている ACL を KiiACLEntry の NSArray として取得します。
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 に対するアクセス権の表をご覧ください。