Bucket の ACL 設定

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

Bucket の作成許可をカスタマイズするには、Bucket の作成先になるスコープの ACL を変更します。スコープの ACL 設定について詳しくは、スコープの ACL 設定 を参照してください。

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

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

Bucket の ACL エントリー

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

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 を無条件で読み取れるようになります。

  • サブジェクト(対象)

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

    サブジェクト 誰が実行可能か
    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 内への Object 作成を許可する)。アプリケーションスコープの 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 内の 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 のアクセス権を変更できない

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

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