Bucket の ACL のカスタマイズ

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

Bucket の作成許可をカスタマイズするには、Bucket の作成先になるスコープの ACL を変更します。

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

Bucket の ACL エントリー

Bucket に対する ACL を設定すると、たとえば、ある Bucket に対して匿名ユーザーが KiiObject を作成できるようにするなどの制御が行えます。

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

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

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

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

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

サブジェクト（対象）

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

サブジェクト	誰が実行可能か
UserID:{USER_ID}	指定されたユーザー。
GroupID:{GROUP_ID}	指定されたグループのメンバー。
ThingID:{THING_ID}	指定された Thing。
UserID:ANY_AUTHENTICATED_USER	ログイン済みの全ユーザー。
UserID:ANONYMOUS_USER	匿名ユーザー。

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

これらのアクションとサブジェクトを使って、「どの Bucket の」アクセス許可を変更するかを以下の URL で指定します。

アプリケーションスコープ：

https://api-jp.kii.com/api/apps/{APP_ID}/buckets/{BUCKET_ID}/acl/{ACTION}/{SUBJECT}
アプリ管理者向け機能で取得した管理者のアクセストークンが必要
グループスコープ：

https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}/buckets/{BUCKET_ID}/acl/ {ACTION}/{SUBJECT}
グループオーナーのアクセストークンが必要
ユーザースコープ：

https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/acl/ {ACTION}/{SUBJECT}
https://api-jp.kii.com/api/apps/{APP_ID}/users/me/buckets/{BUCKET_ID}/acl/{ACTION}/{SUBJECT}
スコープオーナーのアクセストークンが必要
Thing スコープ：

https://api-jp.kii.com/api/apps/{APP_ID}/things/VENDOR_THING_ID:{VENDOR_THING_ID}/ buckets/{BUCKET_ID}/acl/{ACTION}/{SUBJECT}
https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}/buckets/{BUCKET_ID}/acl/ {ACTION}/{SUBJECT}
Thing または Thing オーナーのアクセストークンが必要

Bucket の ACL の管理

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

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

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

ユーザースコープに存在する Bucket に ACL エントリーを追加する例を以下に示します。この例では、ユーザー ID が {USER_ID_2} のユーザーに CREATE_OBJECTS_IN_BUCKET アクションを許可しています。

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/acl/CREATE_OBJECTS_IN_BUCKET/UserID:{USER_ID_2}" \
  -d ""

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

以下、いくつか例を挙げます。

ANONYMOUS_USER に対して CREATE_OBJECTS_IN_BUCKET アクションを許可する例

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/acl/CREATE_OBJECTS_IN_BUCKET/UserID:ANONYMOUS_USER" \
  -d ""

ANY_AUTHENTICATED_USER に対して CREATE_OBJECTS_IN_BUCKET アクションを許可する例

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/acl/CREATE_OBJECTS_IN_BUCKET/UserID:ANY_AUTHENTICATED_USER" \
  -d ""

グループに対して CREATE_OBJECTS_IN_BUCKET アクションを許可する例

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/acl/CREATE_OBJECTS_IN_BUCKET/GroupID:{GROUP_ID}" \
  -d ""

Thing に対して CREATE_OBJECTS_IN_BUCKET アクションを許可する例

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/acl/CREATE_OBJECTS_IN_BUCKET/ThingID:{THING_ID}" \
  -d ""

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

一旦許可したアクションを取り消すには、対応する ACL エントリーの DELETE リクエストを送信します。

この例では、ユーザー ID が {USER_ID_2} のユーザーに許可した CREATE_OBJECTS_IN_BUCKET アクションの ACL エントリーを削除しています。

curl -v -X DELETE \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/acl/CREATE_OBJECTS_IN_BUCKET/UserID:{USER_ID_2}"

初めに示した URL によって、その他のスコープも操作できます。

Bucket の ACL を取得する

Bucket に設定されている ACL を取得するには、対応する URL からアクションやサブジェクトを省略した形で GET リクエストを送信します。

たとえば、CREATE_OBJECTS_IN_BUCKET アクションが許可されているサブジェクトの一覧は以下のようにして取得できます。

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/acl/CREATE_OBJECTS_IN_BUCKET"

また、該当 Bucket の ACL 全体は、以下のように取得できます。

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/acl"

いずれの例もユーザースコープの Bucket を指定していますが、初めに示した URL によって、その他のスコープも操作できます。

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

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

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

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

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

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

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

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

アプリケーションスコープの Bucket のアクセス権を変更するにはアプリ管理者の権限が必要です。アプリ管理者向け機能の方法によってアプリ管理者のアクセストークンを取得し、そのアクセストークンをリクエストで使用します。

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