Bucket の ACL のカスタマイズ

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

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

Bucket の ACL エントリー

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

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

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

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

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

注意：KiiACLBucketActionReadObjects アクションを許可すると、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 エントリーを追加する例を挙げます。この例では KiiACLBucketActionQueryObjects アクションと BucketActionCreateObjects アクションを KiiAnyAuthenticatedUser に許可しています。

var user = KiiUser.getCurrentUser();
var bucket = user.bucketWithName("my_private");

// Create ACL entries.
var entry1 = KiiACLEntry.entryWithSubject(new KiiAnyAuthenticatedUser(), KiiACLAction.KiiACLBucketActionQueryObjects);
var entry2 = KiiACLEntry.entryWithSubject(new KiiAnyAuthenticatedUser(), KiiACLAction.KiiACLBucketActionCreateObjects);

var acl = bucket.acl();

// Set the ACL entries to the bucket ACL.
acl.putACLEntry(entry1);
acl.putACLEntry(entry2);

// Save the ACL to the server.
acl.save().then(
  function(theACL) {
    // Do something.
  }
).catch(
  function(error) {
    var theACL = error.target;
    var errorString = error.message;
    // Handle the error.
  }
);

var user = KiiUser.getCurrentUser();
var bucket = user.bucketWithName("my_private");

// Create ACL entries.
var entry1 = KiiACLEntry.entryWithSubject(new KiiAnyAuthenticatedUser(), KiiACLAction.KiiACLBucketActionQueryObjects);
var entry2 = KiiACLEntry.entryWithSubject(new KiiAnyAuthenticatedUser(), KiiACLAction.KiiACLBucketActionCreateObjects);

var acl = bucket.acl();

// Set the ACL entries to the bucket ACL.
acl.putACLEntry(entry1);
acl.putACLEntry(entry2);

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

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

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

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

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

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

var user = KiiUser.getCurrentUser();
var bucket = user.bucketWithName("my_private");

// Create ACL entries.
var entry1 = KiiACLEntry.entryWithSubject(new KiiAnyAuthenticatedUser(), KiiACLAction.KiiACLBucketActionQueryObjects);
entry1.setGrant(false);
var entry2 = KiiACLEntry.entryWithSubject(new KiiAnyAuthenticatedUser(), KiiACLAction.KiiACLBucketActionCreateObjects);
entry2.setGrant(false);

var acl = bucket.acl();

// Delete the ACL entries from the bucket ACL.
acl.putACLEntry(entry1);
acl.putACLEntry(entry2);

// Save the ACL to the server.
acl.save().then(
  function(theACL) {
    // Do something.
  }
).catch(
  function(error) {
    var theACL = error.target;
    var errorString = error.message;
    // Handle the error.
  }
);

var user = KiiUser.getCurrentUser();
var bucket = user.bucketWithName("my_private");

// Create ACL entries.
var entry1 = KiiACLEntry.entryWithSubject(new KiiAnyAuthenticatedUser(), KiiACLAction.KiiACLBucketActionQueryObjects);
entry1.setGrant(false);
var entry2 = KiiACLEntry.entryWithSubject(new KiiAnyAuthenticatedUser(), KiiACLAction.KiiACLBucketActionCreateObjects);
entry2.setGrant(false);

var acl = bucket.acl();

// Delete the ACL entries from the bucket ACL.
acl.putACLEntry(entry1);
acl.putACLEntry(entry2);

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

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

Bucket の ACL を取得する

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

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

var user = KiiUser.getCurrentUser();
var bucket = user.bucketWithName("my_private");

var acl = bucket.acl();

// Get the ACL entries from the server.
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) {
    var theACL = error.target;
    var errorString = error.message;
    // Handle the error.
  }
);

var user = KiiUser.getCurrentUser();
var bucket = user.bucketWithName("my_private");

var acl = bucket.acl();

// Get the ACL entries from the server.
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 エントリーを削除してから登録するような処理が必要です。取得方法の詳細は Bucket の ACL を取得するをご覧ください。
"KiiACLBucketActionQueryObjects" を許可しても Bucket 内の KiiObject を検索できない

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

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

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

また ACL の変更の例に詳しい説明がありますので、あわせてご覧ください。
ACL エントリーを削除できない

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

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

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

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