本页面介绍如何使用访问控制列表 (ACL) 控制存储分区和对象的访问权限。ACL 是一种机制,可用于定义谁有权访问您的存储分区和对象,以及他们具有何种级别的访问权限。如需详细了解 ACL,请参阅 ACL 概览。
如需了解如何以其他方式控制存储分区和对象的访问权限,请参阅访问权限控制概览。
准备工作
您应当使用 ACL 吗?
大多数情况下,我们建议您使用 Cloud Identity and Access Management (Cloud IAM) 来控制资源访问权限,因为它针对 Google Cloud Platform 的各个方面提供了企业级访问控制,并允许子资源(比如存储分区和对象)继承授予父资源(比如项目)的权限。如需阅读有关在 Cloud Storage 中使用 Cloud IAM 的指南,请参阅使用 Cloud IAM 权限。
如果您需要自定义对存储分区中单个对象的访问权限,则最适合使用 ACL,因为 Cloud IAM 权限适用于存储分区中的所有对象。但对适用于存储分区中所有对象的任何访问权限,您仍应使用 IAM,因为这可为您减轻需要完成的精细管理工作量。
您需要设置 ACL 吗?
根据您希望存储分区或对象具有的权限,您可能不一定需要设置 ACL。创建的存储分区和对象具有默认 ACL,而默认 ACL 可能已包含您希望这些存储分区或对象具有的权限。
使用以下准则决定是否应当设置 ACL。
对于存储分区:
控制台
新创建的存储分区具有预定义的 project-private
ACL。如果您的存储分区需要其他权限,请设置 ACL。
gsutil
新存储分区将作为 project-private
添加。如果您的存储分区需要其他权限,请设置 ACL。
JSON API
默认情况下,新存储分区将作为 project-private
添加。如果您的存储分区需要其他权限,请设置 ACL。
XML API
新存储分区将作为 project-private
添加。如果您的存储分区需要其他权限,请设置 ACL。
如上所述,每个存储分区都有一个默认对象 ACL,该 ACL 将应用于上传到该存储分区中且没有预定义 ACL 的所有对象,或者未在请求中指定 ACL 的所有对象(如果使用 JSON API)。如需了解详情,请参阅默认对象 ACL。
对于对象:
控制台
上传的对象获得与存储分区对象相同的 ACL,系统会将上传者作为所有者添加到 ACL 中。如果您的对象需要其他权限,请设置 ACL。
gsutil
添加新对象后,新对象将具有存储分区的默认对象 ACL。复制已存储在云中的对象时,您可以使用 -p
选项替换此行为。
JSON API
默认情况下,添加新对象后,新对象将具有存储分区的默认对象 ACL。
XML API
添加新对象后,新对象将具有存储分区的默认对象 ACL。
您应该使用哪个界面?
以下示例显示了如何使用 Google Cloud Platform Console、gsutil 命令行工具、Cloud Storage 客户端库以及 XML 和 JSON API 来配置访问控制。通过以下准则来选择要使用的方法:
如果您刚开始了解访问控制,并且只希望修改单个对象的 ACL,请使用 GCP Console。
如果您刚开始了解访问控制,并且希望修改存储分区和对象的 ACL,请使用 gsutil。
如果您有某个 Cloud Storage 客户端库的使用经验,请使用此库来管理 ACL。
如果您使用 API 来指定 ACL,则应该有发出 HTTP 请求的经验。您可以使用自己喜欢的工具或应用发送 HTTP 请求。在示例中,我们使用 cURL 工具。您可以从 OAuth 2.0 Playground 获取要在 cURL 示例中使用的授权令牌。
设置 ACL
您用于设置和获取 ACL 的工具或 API 决定了您使用的 ACL 语法。 虽然各种 ACL 语法看起来有所不同,但它们包含相同的 ACL 信息:向范围授予权限的条目。
控制台
转到 GCP Console 中的 Cloud Storage 浏览器。
转到 Cloud Storage 浏览器导航到需要修改其 ACL 的对象。
从对象的下拉菜单中选择修改权限。
您应看到一个类似于如下所示的权限对话框:
此屏幕截图显示了包含四个条目的 ACL:
点击添加一项。
选择要向其授予权限的实体类型。
实体指定了获得权限的对象的类型(例如,用户或群组)。如需查看受支持的实体值列表,请参阅访问控制范围。
在名称中输入值。
名称标识了特定的用户、群组或其他实体类型。如需查看受支持的名称值列表,请参阅访问控制范围。
实体和名称共同定义了权限适用的对象。
在访问权限中选择一个值。
访问权限定义了您要在对象上设置的权限。 如需查看受支持的访问权限值列表,请参阅访问控制权限。
点击保存。
gsutil
使用 gsutil acl
指定 ACL:
如需指定单个授权,请运行以下命令:
gsutil acl ch -u [USER_EMAIL]:[PERMISSION] gs://[BUCKET_NAME]
如需指定预设的 ACL,请运行以下命令:
gsutil acl set [CANNED_ACL_NAME] gs://[BUCKET_NAME]
如需以 JSON 格式指定 ACL,请运行以下命令:
gsutil acl set [JSON_FILE] gs://[bucket-name]
其中,
[JSON_FILE]
包含以 JSON 格式指定的 ACL。
代码示例
C++
如需了解详情,请参阅 Cloud Storage C++ API 参考文档。
以下示例将 ACL 添加到存储分区中:
以下示例将 ACL 添加到对象中:
C#
如需了解详情,请参阅 Cloud Storage C# API 参考文档。
以下示例将 ACL 添加到存储分区中:
以下示例将 ACL 添加到对象中:
Go
如需了解详情,请参阅 Cloud Storage Go API 参考文档。
以下示例将 ACL 添加到存储分区中:
以下示例将 ACL 添加到对象中:
Java
如需了解详情,请参阅 Cloud Storage Java API 参考文档。
以下示例将 ACL 添加到存储分区中:
以下示例将 ACL 添加到对象中:
Node.js
如需了解详情,请参阅 Cloud Storage Node.js API 参考文档。
以下示例将 ACL 添加到存储分区中:
以下示例将 ACL 添加到对象中:
PHP
如需了解详情,请参阅 Cloud Storage PHP API 参考文档。
以下示例将 ACL 添加到存储分区中:
以下示例将 ACL 添加到对象中:
Python
如需了解详情,请参阅 Cloud Storage Python API 参考文档。
以下示例将 ACL 添加到存储分区中:
以下示例将 ACL 添加到对象中:
Ruby
如需了解详情,请参阅 Cloud Storage Ruby API 参考文档。
以下示例将 ACL 添加到存储分区中:
以下示例将 ACL 添加到对象中:
JSON API
创建存储分区时,您可以在 insert 请求中指定 acl[]
属性。如果是现有存储分区,请在 patch 或 update 请求中指定 acl[]
属性。
创建对象时,您可以在请求正文中指定 acl[]
属性,或在 insert 请求中指定 predefinedAcl
查询参数。如果是现有对象,请在 patch 或 update 请求中指定 acl[]
属性或 predefinedAcl
查询参数。
如需查看存储分区和对象 ACL 属性的定义,请分别参阅 BucketAccessControls
和 ObjectAccessControls
资源。
以下示例显示了不同的存储分区 ACL 条目。
"acl": [ { "kind": "storage#bucketAccessControl", "id": "example-bucket/project-owners-123412341234", "selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/acl/project-owners-123412341234", "bucket": "example-bucket", "entity": "project-owners-123412341234", "role": "OWNER", "projectTeam": { "projectNumber": "123412341234", "team": "owners" }, "etag": "CDk=" }, { "kind": "storage#bucketAccessControl", "id": "example-bucket/project-editors-123412341234", "selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/acl/project-editors-123412341234", "bucket": "example-bucket", "entity": "project-editors-123412341234", "role": "OWNER", "projectTeam": { "projectNumber": "123412341234", "team": "editors" }, "etag": "CDk=" }, { "kind": "storage#bucketAccessControl", "id": "example-bucket/project-viewers-123412341234", "selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/acl/project-viewers-123412341234", "bucket": "example-bucket", "entity": "project-viewers-123412341234", "role": "READER", "projectTeam": { "projectNumber": "123412341234", "team": "viewers" }, "etag": "CDk=" }, { "kind": "storage#bucketAccessControl", "id": "example-bucket/group-gs-announce@googlegroups.com", "selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/acl/group-gs-announce@googlegroups.com", "bucket": "example-bucket", "entity": "group-gs-announce@googlegroups.com", "role": "READER", "email": "gs-announce@googlegroups.com", "etag": "CDk=" }, { "kind": "storage#bucketAccessControl", "id": "example-bucket/user-jane@gmail.com", "selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/acl/user-jane@gmail.com", "bucket": "example-bucket", "entity": "user-jane@gmail.com", "role": "READER", "email": "jane@gmail.com", "etag": "CDk=" }, { "kind": "storage#bucketAccessControl", "id": "example-bucket/allUsers", "selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/acl/allUsers", "bucket": "example-bucket", "entity": "allUsers", "role": "READER", "etag": "CDk=" }, { "kind": "storage#bucketAccessControl", "id": "example-bucket/allAuthenticatedUsers", "selfLink": "https://www.googleapis.com/storage/v1/b/example-bucket/acl/allAuthenticatedUsers", "bucket": "example-bucket", "entity": "allAuthenticatedUsers", "role": "READER", "etag": "CDk=" } ]
XML API
在 XML API 中,您使用 XML 格式的 ACL。您必须将一个 XML 文档附加到用于更改存储分区和对象 ACL 的请求的正文中。 当您获取存储分区和对象 ACL 时,系统会返回一个 XML 文档。该 XML 文档包含各个存储分区或对象 ACL 条目。
使用
PUT
Bucket 请求创建存储分区后,使用包含?acl
参数的另一个 PUT Bucket 请求来更改存储分区 ACL。使用
PUT
Object 请求上传对象后,使用包含?acl
参数或x-googl-acl
请求标头的另一个 PUT 请求来更改 ACL。
为 XML API 使用以下 ACL 语法。
元素 | 说明 |
---|---|
AccessControlList |
Entries 和 Owner 元素的容器。 |
Owner |
DisplayName 和 ID 元素的容器。此元素对于对象而言并不是必需的,因为对象的 Owner 始终是上传该对象的用户。在迁移情景中使用 Amazon S3 ACL 语法时,您将使用此元素。Amazon Simple Storage Service 和 Amazon S3 是 Amazon.com, Inc. 或其关联公司在美国和/或其他国家/地区的商标。 |
ID |
存储分区所有者的 Google Cloud Storage ID。 |
DisplayName |
目前尚未实现。该值始终为空字符串。 |
Entries |
零个或零个以上 Entry 元素的容器。 |
Entry |
Scope 和 Permission 元素的容器。Entry 只能包含一个 Scope 和一个 Permission 元素。 |
Scope |
ID 、EmailAddress 或 Domain 元素的容器,用于定义 ACL 范围。此元素必须具有一个 type 特性 (Attribute),包含下列中的一个值:UserByID 、UserByEmail 、GroupByID 、GroupByEmail 、GroupByDomain 、AllUsers 或 AllAuthenticatedUsers 。 |
ID |
被授予方的标识符(当权限条目由 ID 指定时)。 |
EmailAddress |
被授予方的电子邮件标识符(当权限条目由电子邮件指定时)。 |
Domain |
被授予方的网域标识符(当权限条目由网域指定时)。 |
Name |
可选元素(您可以指定此元素,或者,如果范围是 UserByEmail 或 GroupByEmail ,则可以自动添加此元素)。 |
Permission |
用于授予 READ 、WRITE 或 FULL_CONTROL 访问权限的权限。 |
使用 XML API 设置 ACL 时:
- 您只能使用上述 XML 格式。
您不能设置重复的范围。
您可以在 ACL XML 中包含许多条目,但不能包含具有重复范围的条目。例如,您不能拥有两个具有相同范围元素
jane@example.com
的条目。
以下示例显示了不同的存储分区 ACL 条目:
<?xml version="1.0" encoding="UTF-8"?> <AccessControlList> <Owner> <ID>00b4903a9721...</ID> </Owner> <Entries> <Entry> <Scope type="GroupById"> <ID>00b4903a9722...</ID> </Scope> <Permission>FULL_CONTROL</Permission> </Entry> <Entry> <Scope type="GroupById"> <ID>00b4903a9723...</ID> </Scope> <Permission>FULL_CONTROL</Permission> </Entry> <Entry> <Scope type="GroupById"> <ID>00b4903a9724...</ID> </Scope> <Permission>READ</Permission> </Entry> <Entry> <Scope type="GroupByDomain"> <Domain>example.com</Domain> </Scope> <Permission>READ</Permission> </Entry> <Entry> <Scope type="GroupByEmail"> <EmailAddress>gs-announce@googlegroups.com</EmailAddress> </Scope> <Permission>READ</Permission> </Entry> <Entry> <Scope type="UserByEmail"> <EmailAddress>jane@gmail.com</EmailAddress> <Name>jane</Name> </Scope> <Permission>READ</Permission> </Entry> <Entry> <Scope type="AllUsers"/> <Permission>READ</Permission> </Entry> <Entry> <Scope type="AllAuthenticatedUsers"/> <Permission>READ</Permission> </Entry> </Entries> </AccessControlList>
设置 ACL XML 中的 Name 元素
从存储分区或对象检索 ACL 时,您可能会注意到,某些条目附加了一个额外的 <Name>
元素。例如,您可能会看到如下所示的条目:
<Entry> <Scope type="UserByEmail"> <EmailAddress>jane@gmail.com</EmailAddress> <Name>Jane</Name> </Scope> <Permission>FULL_CONTROL</Permission> </Entry>
在以下两种情况下,系统会填充这些可选的 <Name>
元素:
当存储分区或对象的 ACL 包含
<Name>
元素时。设置 ACL 时,您可以选择在 ACL 条目中包含
<Name>
元素。您可以在<Name>
元素中提供任何值,在移除或覆盖 ACL 之前,Cloud Storage 会一直记住这些值。如果您使用不易识别的标识符(比如 Google Cloud Storage ID),则此方法十分实用。当
UserByEmail
或GroupByEmail
范围包含公开的 Google 个人资料时。如果您使用这些范围中的任何一个,但未提供
<Name>
元素,则 Cloud Storage 会检查与该电子邮件地址关联的用户或 Google 群组是否拥有公开的 Google 个人资料(包含公开名称)。如果存在这种情况,Cloud Storage 会自动使用公开名称填充<Name>
元素。
应用预定义的 ACL
您可以使用预定义的 ACL(自动应用多个针对特定情景进行自定义的条目),而不是如上所示逐个条目地指定整个 ACL。您可以使用 gsutil、JSON API 或 XML API 将预定义的 ACL 应用到存储分区或对象上。
对于新的对象
如需在对象上传期间将预定义 ACL 应用于对象,请执行以下操作:
控制台
您无法使用 GCP Console 应用预定义的 ACL。请改为使用 gsutil。
gsutil
搭配 -a
选项使用 gsutil cp
命令来应用预定义的 ACL:
gsutil cp -a [PREDEFINED_ACL] [OBJECT] gs://[BUCKET_NAME]
例如,如需在将对象 paris.jpg
上传到存储分区 example-travel-maps
时应用预定义的 ACL bucket-owner-read
,请运行以下命令:
gsutil cp -a bucket-owner-read paris.jpg gs://example-travel-maps
JSON API
在 insert 请求中使用 predefinedAcl
查询字符串参数来应用预定义的 ACL。
例如,如需在将对象 paris.jpg
上传到存储分区 example-travel-maps
时应用预定义的 ACL bucketOwnerRead
,请运行以下命令:
curl -X POST --data-binary @paris.jpg -H "Content-Type: image/jpeg"
-H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg"
"https://www.googleapis.com/upload/storage/v1/b/example-travel-maps/o?name=paris.jpg&predefinedAcl=bucketOwnerRead"
请求类似于如下示例:
POST /upload/storage/v1/b/example-travel-maps/o?name=paris.jpg&predefinedAcl=bucketOwnerRead HTTP/1.1 Host: www.googleapis.com Content-Type: image/jpeg Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg Content-Length: 12345 Date: Fri, 10 Oct 2014 00:02:38 GMT
XML API
在 Put Object 请求中使用 x-goog-acl
标头来应用预定义的 ACL。
例如,如需在将对象 paris.jpg
上传到存储分区 example-travel-maps
时应用预定义的 ACL bucket-owner-read
,请运行以下命令:
curl -X PUT --upload-file paris.jpg -H "x-goog-acl: bucket-owner-read"
-H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg"
https://storage.googleapis.com/example-travel-maps/paris.jpg
请求类似于如下示例:
PUT /paris.jpg HTTP/1.1 Host: example-travel-maps.storage.googleapis.com Date: Thu, 09 Oct 2014 23:06:08 GMT Content-Length: 12345 Content-Type: image/jpg x-goog-acl: bucket-owner-read Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg 12345 bytes in entity body
对于现有存储分区或对象
您还可以将预定义的 ACL 应用到现有存储分区或对象上,如果要将预定义的 ACL 更改为另一个预定义 ACL,或者要将自定义 ACL 更新为预定义 ACL,此方法非常有用。
控制台
您无法使用 GCP Console 应用预定义的 ACL。请改为使用 gsutil。
gsutil
使用 gsutil acl set
命令来应用预定义的 ACL:
gsutil acl set [PREDEFINED_ACL] gs://[BUCKET_NAME]/[OBJECT_NAME]
例如,如需将预定义的 ACL private
应用于存储分区 example-travel-maps
中的对象 paris.jpg
,请运行以下命令:
gsutil acl set private gs://example-travel-maps/paris.jpg
JSON API
在 patch 请求中使用 predefinedAcl
查询字符串参数并指定空的 acl
属性,以应用预定义的 ACL。
例如,如需将预定义的 ACL private
应用于存储分区 example-travel-maps
中的对象 paris.jpg
,请运行以下命令:
curl -X PATCH --data '{"acl": []}' -H "Content-Type: application/json"
-H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg"
https://www.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg?predefinedAcl=private
请求类似于如下示例:
PATCH /storage/v1/b/example-travel-maps/o/paris.jpg?predefinedAcl=private HTTP/1.1 Host: www.googleapis.com Content-Type: application/json Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg Content-Length: 11 Date: Fri, 10 Oct 2014 18:57:59 GMT
XML API
在 Put Object 请求中使用 x-goog-acl
标头和 acl
查询字符串参数,但不要在请求中添加 XML 文档。
例如,如需将预定义的 ACL private
应用于存储分区 example-travel-maps
中的对象 paris.jpg
,请运行以下命令:
curl -X PUT -H "Content-Length: 0"
-H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg"
-H "x-goog-acl: private" https://storage.googleapis.com/example-travel-maps/paris.jpg?acl
请求类似于如下示例:
PUT /paris.jpg?acl HTTP/1.1 Host: example-travel-maps.storage.googleapis.com Date: Thu, 09 Oct 2014 23:14:59 GMT Content-Length: 0 x-goog-acl: private Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg empty entity body
设置默认对象 ACL
为避免每次创建新对象时都要设置 ACL,您可以在存储分区上设置默认对象 ACL。执行此操作后,添加到该存储分区但未明确应用 ACL 的每个新对象都将应用默认 ACL。例如,您可能只想允许特定用户组访问特定存储分区中的大多数对象。您可以更改默认对象 ACL,然后将对象添加到该存储分区中。这些添加的对象会自动应用您指定的默认对象 ACL;但是,您可以为特定对象指定不同的 ACL,在这种情况下,这些对象不会应用默认 ACL。
如需查看和更改存储分区的默认对象 ACL,请执行以下操作:
控制台
您无法使用 GCP Console 设置默认对象 ACL。请改为使用 gsutil。
gsutil
使用
gsutil defacl
检索默认对象 ACL:gsutil defacl get gs://[BUCKET_NAME]
使用
gsutil defacl ch
或gsutil defacl set
修改默认对象 ACL。例如,以下命令可将
jane@gmail.com
添加到存储分区example-travel-maps
的默认对象 ACL 中:gsutil defacl ch -u jane@gmail.com:READER gs://example-travel-maps
您还可以从某个文件指定默认对象 ACL。如需了解详情,请参阅
gsutil defacl
帮助。
代码示例
C++
如需了解详情,请参阅 Cloud Storage C++ API 参考文档。
以下示例将默认对象 ACL 添加到存储分区中:
以下示例从存储分区中删除默认对象 ACL:
C#
如需了解详情,请参阅 Cloud Storage C# API 参考文档。
以下示例将默认对象 ACL 添加到存储分区中:
以下示例从存储分区中删除默认对象 ACL:
Go
如需了解详情,请参阅 Cloud Storage Go API 参考文档。
以下示例将默认对象 ACL 添加到存储分区中:
以下示例从存储分区中删除默认对象 ACL:
Java
如需了解详情,请参阅 Cloud Storage Java API 参考文档。
以下示例将默认对象 ACL 添加到存储分区中:
以下示例从存储分区中删除默认对象 ACL:
Node.js
如需了解详情,请参阅 Cloud Storage Node.js API 参考文档。
以下示例将默认对象 ACL 添加到存储分区中:
以下示例从存储分区中删除默认对象 ACL:
PHP
如需了解详情,请参阅 Cloud Storage PHP API 参考文档。
以下示例将默认对象 ACL 添加到存储分区中:
以下示例从存储分区中删除默认对象 ACL:
Python
如需了解详情,请参阅 Cloud Storage Python API 参考文档。
以下示例将默认对象 ACL 添加到存储分区中:
以下示例从存储分区中删除默认对象 ACL:
Ruby
如需了解详情,请参阅 Cloud Storage Ruby API 参考文档。
以下示例将默认对象 ACL 添加到存储分区中:
以下示例从存储分区中删除默认对象 ACL:
JSON API
使用 GET 请求检索默认对象 ACL。例如:
curl -X GET -H "Authorization: Bearer [OAUTH2_TOKEN]"
https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]?projection=full使用 patch 请求替换默认对象 ACL。例如,以下请求将存储分区
example-travel-maps
的默认对象 ACL 替换为defacls.json
中指定的 ACL:curl -X PATCH --data @defacls.json -H "Content-Type: application/json" -H "Authorization: Bearer [OAUTH2_TOKEN]"
https://www.googleapis.com/storage/v1/b/example-travel-mapsdefacls.json
的示例:{ "defaultObjectAcl": [ { "email": "jane@gmail.com", "entity": "user-jane@gmail.com", "role": "READER" } ] }
XML API
使用
GET
请求(范围限定为您的存储分区)和?defaultObjectAcl
参数检索默认对象 ACL。例如:curl -X GET -H "Authorization: Bearer [OAUTH2_TOKEN]"
https://storage.googleapis.com/[BUCKET_NAME]?defaultObjectAcl使用
PUT
请求(范围限定为您的存储分区)和?defaultObjectAcl
参数,将默认对象 ACL 替换为acls.xml
中指定的 ACL。例如:curl -X PUT --data-binary @acls.xml -H "Authorization: Bearer [OAUTH2_TOKEN]"
http://storage.googleapis.com/[BUCKET_NAME]?defaultObjectAclacls.xml
的示例:<AccessControlList> <Entries> <Entry> <Permission>
FULL_CONTROL
</Permission> <Scope type="GroupByEmail"> <EmailAddress>travel-companions@googlegroups.com</EmailAddress> </Scope> </Entry> </Entries> </AccessControlList>
设置 ACL 中讨论了 ACL 的语法。 您还可以将预定义的 ACL 指定为默认对象 ACL。
如需将存储分区的默认对象 ACL 设为预定义的 ACL,请执行以下操作:
控制台
您无法使用 GCP Console 设置默认对象 ACL。请改为使用 gsutil。
gsutil
使用 gsutil defacl
命令并搭配预定义 ACL 的名称。
例如,如需将存储分区 example-travel-maps
的默认对象 ACL 设为 project-private
,请运行以下命令:
gsutil defacl set project-private gs://example-travel-maps
JSON API
使用 PUT 请求和 predefinedAcl
参数。
例如:
curl -X PUT -H "Content-Length: 0" -H "Authorization: Bearer [OAUTH2_TOKEN]"
https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]?predefinedAcl=private
XML API
使用 PUT
请求(范围限定为您的存储分区),并在请求中包含 ?defaultObjectAcl
参数和 x-goog-acl
标头。
例如:
curl -X PUT -H "x-goog-acl: project-private" -H "Content-Length: 0" -H "Authorization: Bearer [OAUTH2_TOKEN]"
http://storage.googleapis.com/[BUCKET_NAME]?defaultObjectAcl
新创建的存储分区的默认对象 ACL:
新创建的存储分区的默认对象 ACL 如下所示。将这些 ACL 与您的存储分区的默认对象 ACL 进行比较,以了解您的存储分区的默认对象 ACL 是否已被修改。
控制台
您无法使用 GCP Console 处理默认对象 ACL。 请改为使用 gsutil。
gsutil
在下面的示例中,项目 ID 为“123412341234”;您的项目 ID 将有所不同。
[ { "entity": "project-owners-123412341234", "projectTeam": { "projectNumber": "123412341234", "team": "owners" }, "role": "OWNER" }, { "entity": "project-editors-123412341234", "projectTeam": { "projectNumber": "123412341234", "team": "editors" }, "role": "OWNER" }, { "entity": "project-viewers-123412341234", "projectTeam": { "projectNumber": "123412341234", "team": "viewers" }, "role": "READER" } ]
JSON API
在下面的示例中,项目 ID 为“123412341234”;您的项目 ID 将有所不同。
defaultObjectAcl": [ { "kind": "storage#objectAccessControl", "entity": "project-owners-123412341234", "role": "OWNER", "projectTeam": { "projectNumber": "123412341234", "team": "owners" } }, { "kind": "storage#objectAccessControl", "entity": "project-editors-123412341234", "role": "OWNER", "projectTeam": { "projectNumber": "123412341234", "team": "editors" } }, { "kind": "storage#objectAccessControl", "entity": "project-viewers-123412341234", "role": "READER", "projectTeam": { "projectNumber": "123412341234", "team": "viewers" } } ]
XML API
在下面的示例中,项目角色 ID 以“00b4903a97...”开头;您的项目 ID 将有所不同。
<?xml version='1.0' encoding='UTF-8'?> <AccessControlList> <Entries> <Entry> <Scope type='GroupById'> <ID>00b4903a9721...</ID> </Scope> <Permission>FULL_CONTROL</Permission> </Entry> <Entry> <Scope type='GroupById'> <ID>00b4903a9722...</ID> </Scope> <Permission>FULL_CONTROL</Permission> </Entry> <Entry> <Scope type='GroupById'> <ID>00b4903a9723...</ID> </Scope> <Permission>READ</Permission> </Entry> </Entries> </AccessControlList>
请注意,新创建的存储分区的默认对象 ACL 等同于预定义的 projectPrivate
ACL。
检索 ACL
如需获取现有存储分区或对象的 ACL,请执行以下操作:
控制台
转到 GCP Console 中的 Cloud Storage 浏览器。
转到 Cloud Storage 浏览器导航到需要查看其 ACL 的对象。
从对象的下拉菜单中选择修改权限。
您会看到包含对象权限的权限对话框。
gsutil
使用 gsutil acl get
返回对象的 ACL。
例如,如需返回存储分区 example-travel-maps
中的对象 paris.jpg
的 ACL,请运行以下命令:
gsutil acl get gs://example-travel-maps/paris.jpg
示例响应:
[ { "entity": "project-owners-123412341234", "projectTeam": { "projectNumber": "123412341234", "team": "owners" }, "role": "OWNER" }, { "entity": "project-editors-123412341234", "projectTeam": { "projectNumber": "123412341234", "team": "editors" }, "role": "OWNER" }, { "entity": "project-viewers-123412341234", "projectTeam": { "projectNumber": "123412341234", "team": "viewers" }, "role": "READER" }, { "email": "gs-announce@googlegroups.com", "entity": "group-gs-announce@googlegroups.com", "role": "READER" }, { "email": "jane@gmail.com", "entity": "user-jane@gmail.com", "role": "READER" }, { "entity": "allUsers", "role": "READER" }, { "entity": "allAuthenticatedUsers", "role": "READER" } ]
如需返回存储分区的 ACL,请运行以下命令:
gsutil acl get gs://[BUCKET_NAME]
当 gsutil 通过 gsutil acl get
返回存储分区和对象的 ACL 时,这两种 ACL 采用相同的 JSON 格式(您可以使用此格式设置 ACL)。JSON 格式的 ACL 使用 JSON API 属性名称,例如 entity
和 role
。
如需详细了解如何解读输出结果或运行 gsutil help acls
,请参阅 JSON API 语法。
代码示例
C++
如需了解详情,请参阅 Cloud Storage C++ API 参考文档。
以下示例获取了一个存储分区 ACL:
以下示例获取了一个对象 ACL:
C#
如需了解详情,请参阅 Cloud Storage C# API 参考文档。
以下示例获取了一个存储分区 ACL:
以下示例获取了一个对象 ACL:
Go
如需了解详情,请参阅 Cloud Storage Go API 参考文档。
以下示例获取了一个存储分区 ACL:
以下示例获取了一个对象 ACL:
Java
如需了解详情,请参阅 Cloud Storage Java API 参考文档。
以下示例获取了一个存储分区 ACL:
以下示例获取了一个对象 ACL:
Node.js
如需了解详情,请参阅 Cloud Storage Node.js API 参考文档。
以下示例获取了一个存储分区 ACL:
以下示例获取了一个对象 ACL:
PHP
如需了解详情,请参阅 Cloud Storage PHP API 参考文档。
以下示例获取了一个存储分区 ACL:
以下示例获取了一个对象 ACL:
Python
如需了解详情,请参阅 Cloud Storage Python API 参考文档。
以下示例获取了一个存储分区 ACL:
以下示例获取了一个对象 ACL:
Ruby
如需了解详情,请参阅 Cloud Storage Ruby API 参考文档。
以下示例获取了一个存储分区 ACL:
以下示例获取了一个对象 ACL:
JSON API
确保您在存储分区或对象上具有
OWNER
权限。使用
GET
请求检索存储分区或对象的 ACL。对象 ACL 以 JSON 格式返回,并将附加到响应正文中。
例如,如需返回存储分区 example-travel-maps
中的对象 paris.jpg
的 ACL,请运行以下命令:
curl -X GET -H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg"
https://www.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg?projection=full
您应看到类似于如下所示的响应:
{ "kind": "storage#object", "id": "example-travel-maps/paris.jpg/1412805837131000", "selfLink": "https://www.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg", "name": "paris.jpg", "bucket": "example-travel-maps", ... "acl": [ { ... "entity": "project-owners-867489160491", "role": "OWNER", "projectTeam": { "projectNumber": "867489160491", "team": "owners" }, ... }, { ... "entity": "user-jane@gmail.com", "role": "OWNER", "email": "jane@gmail.com", ... }, { ... "entity": "group-gs-announce@googlegroups.com", "role": "READER", "email": "gs-announce@googlegroups.com", ... } ], "owner": { "entity": "user-jane@gmail.com" }, ... }
您还可以使用 objectAccessControls
资源 GET
方法返回对象 ACL 中的各个条目。
XML API
确保您在存储分区或对象上具有
FULL_CONTROL
权限。在 GET Object 请求中使用
acl
查询字符串参数,以检索存储分区或对象的 ACL。
ACL 以 XML 格式描述,随附在响应正文中。
例如,如需返回存储分区 example-travel-maps
中的对象 paris.jpg
的 ACL,请运行以下命令:
curl -X GET -H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg"
https://storage.googleapis.com/example-travel-maps/paris.jpg?acl
您应看到类似于如下所示的响应:
<?xml version="1.0" encoding="UTF-8"?> <AccessControlList> <Owner> <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID> <Name>Owner Name</Name> </Owner> <Entries> <Entry> <Scope type="UserById"> <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID> <Name>Name</Name> </Scope> <Permission>FULL_CONTROL</Permission> </Entry> <Entry> <Scope type="UserByEmail"> <EmailAddress>jane@gmail.com</EmailAddress> <Name>Jane</Name> </Scope> <Permission>FULL_CONTROL</Permission> </Entry> <Entry> <Scope type="GroupByEmail"> <EmailAddress>gs-announce@googlegroups.com</EmailAddress> </Scope> <Permission>READ</Permission> </Entry> </Entries> </AccessControlList>
您还可以使用 ObjectAccessControls
资源的 JSON GET
方法返回特定的 ACL 条目。
更改 ACL
如需更改现有对象或存储分区的 ACL,请执行以下操作:
控制台
转到 GCP Console 中的 Cloud Storage 浏览器。
转到 Cloud Storage 浏览器导航到需要更改其 ACL 的对象。
从对象的下拉菜单中选择修改权限。
您会看到包含对象权限的权限对话框。
以下示例显示了如何向 jane@gmail.com
用户授予对象 paris.jpg
的 OWNER
权限以及向 gs-announce
群组成员授予该对象的 READER
权限:
gsutil
在文件中定义 ACL。
将 ACL 文件传递给
gsutil acl set
,并指定要设置该 ACL 的对象。
例如,如需将 acls.txt
文件中的 ACL 应用到存储分区 example-travel-maps
中名为 paris.jpg
的对象上,请运行以下命令:
gsutil acl set acl.txt gs://example-travel-maps/paris.jpg
acl.txt
的内容如下所示。这些 ACL 向项目 867489160491
的所有者以及用户 jane@gmail.com
授予对象 paris.jpg
的 OWNER
权限,以及向 gs-announce
群组成员授予此对象的 READER
权限:
[ { "entity": "project-owners-867489160491", "role": "OWNER", "projectTeam": { "projectNumber": "867489160491", "team": "owners" }, }, { "entity": "user-jane@gmail.com", "email": "jane@gmail.com", "role": "OWNER" }, { "entity": "group-gs-announce@googlegroups.com", "email": "gs-announce@googlegroups.com", "role": "READER" } ]
您还可以使用单个授权操作为此对象设置相同的 ACL。
例如,如需向 jane@gmail.com
用户授予 READER
访问权限,请使用以下命令:
gsutil acl ch -u jane@gmail.com:READ gs://example-travel-maps/paris.jpg.
代码示例
C++
如需了解详情,请参阅 Cloud Storage C++ API 参考文档。
以下示例从存储分区中移除 ACL:
以下示例从对象中移除 ACL:
C#
如需了解详情,请参阅 Cloud Storage C# API 参考文档。
以下示例从存储分区中移除 ACL:
以下示例从对象中移除 ACL:
Go
如需了解详情,请参阅 Cloud Storage Go API 参考文档。
以下示例从存储分区中移除 ACL:
以下示例从对象中移除 ACL:
Java
如需了解详情,请参阅 Cloud Storage Java API 参考文档。
以下示例从存储分区中移除 ACL:
以下示例从对象中移除 ACL:
Node.js
如需了解详情,请参阅 Cloud Storage Node.js API 参考文档。
以下示例从存储分区中移除 ACL:
以下示例从对象中移除 ACL:
PHP
如需了解详情,请参阅 Cloud Storage PHP API 参考文档。
以下示例从存储分区中移除 ACL:
以下示例从对象中移除 ACL:
Python
如需了解详情,请参阅 Cloud Storage Python API 参考文档。
以下示例从存储分区中移除 ACL:
以下示例从对象中移除 ACL:
Ruby
如需了解详情,请参阅 Cloud Storage Ruby API 参考文档。
以下示例从存储分区中移除 ACL:
以下示例从对象中移除 ACL:
JSON API
在 JSON 文件中定义 ACL。
发送包含 JSON 文件的 patch 请求,并指定要设置该 ACL 的对象。
例如,以下 cURL 命令将文档 acls.json
中的 JSON 载荷应用到存储分区 example-travel-maps
中名为 paris.jpg
的对象上:
curl -X PATCH --data @acls.json -H "Content-Type: application/json"
-H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg"
https://www.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg
如果 ACL 向项目 867489160491
的所有者以及用户 jane@gmail.com
授予 OWNER
权限,以及向 gs-announce
群组成员授予 READER
权限,则请求如下所示:
PATCH /storage/v1/b/example-travel-maps/o/paris.jpg HTTP/1.1 Host: www.googleapis.com Content-Type: application/json Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg Content-Length: 597 Date: Wed, 08 Oct 2014 22:37:58 GMT { "acl": [ { "entity": "project-owners-867489160491", "role": "OWNER", "projectTeam": { "projectNumber": "867489160491", "team": "owners" }, { "entity": "user-jane@gmail.com", "role": "OWNER", "email": "jane@gmail.com" }, { "entity": "group-gs-announce@googlegroups.com", "role": "READER", "email": "gs-announce@googlegroups.com" } ] }
XML API
在 XML 文档中定义 ACL。
使用
acl
查询字符串参数和相应的 XML 文档发送PUT Object
请求。
以下 cURL 命令将文档 acls.xml
中的 XML 载荷应用到存储分区 example-travel-maps
中名为 paris.jpg
的对象:
curl -X PUT --data-binary @acls.xml
-H "Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg"
https://storage.googleapis.com/example-travel-maps/paris.jpg?acl
如果 ACL 向 jane@gmail.com
用户授予 FULL_CONTROL
权限,以及向 gs-announce
群组成员授予 READ
权限,则请求如下所示:
PUT /paris.jpg?acl HTTP/1.1 Host: example-travel-maps.storage.googleapis.com Date: Sat, 20 Feb 2010 08:31:08 GMT Content-Length: 589 Content-Type=application/xml Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg <?xml version='1.0' encoding='utf-8'?> <AccessControlList> <Owner> <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID> </Owner> <Entries> <Entry> <Permission>FULL_CONTROL
</Permission> <Scope type="UserById"> <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID> </Scope> </Entry> <Entry> <Scope type="UserByEmail"> <EmailAddress>jane@gmail.com</EmailAddress> <Name>Jane</Name> </Scope> <Permission>FULL_CONTROL
</Permission> </Entry> <Entry> <Scope type="GroupByEmail"> <EmailAddress>gs-announce@googlegroups.com</EmailAddress> </Scope> <Permission>READ
</Permission> </Entry> </Entries> </AccessControlList>