# 通过 S3 Access Grants 请求访问 Amazon S3 数据
使用 S3 访问权限管控[创建访问权限管控](https://docs.amazonaws.cn/AmazonS3/latest/userguide/access-grants-grant.html)后，被授权者可以申请凭证，以访问他们已获得访问权限的 S3 数据。被授权者可以是 Amazon Identity and Access Management（IAM）主体、您的公司目录身份或获得授权的应用程序。
应用程序或 Amazon Web Services 服务可以使用 S3 访问权限管控 `GetDataAccess` API 操作来代表被授权者向 S3 访问权限管控请求对 S3 数据的访问权限。`GetDataAccess` 首先验证您是否已向该身份授予对此数据的访问权限。然后，S3 Access Grants 使用 [https://docs.amazonaws.cn/STS/latest/APIReference/API_AssumeRole.html](https://docs.amazonaws.cn/STS/latest/APIReference/API_AssumeRole.html) API 操作来获取临时凭证令牌并将其出售给请求方。此临时凭证令牌是 Amazon Security Token Service（Amazon STS）令牌。
`GetDataAccess` 请求必须包含 `target` 参数，该参数指定临时凭证适用于的 S3 数据的范围。此 `target` 范围可以与授权的范围相同，也可以是该范围的子集，但 `target` 范围必须在已向被授权者提供的授权范围内。请求还必须指定 `permission` 参数以指示临时凭证的权限级别，即 `READ`、`WRITE` 或 `READWRITE`。
**特权**
请求者可以在其凭证请求中指定临时令牌的权限级别。通过使用 `privilege` 参数，请求者可以在授权范围边界内缩小或增大临时凭证的访问范围。`privilege` 参数的默认值为 `Default`，这意味着返回的凭证的目标范围是原始授权范围。`privilege` 的另一个可能值是 `Minimal`。如果 `target` 范围从最初的授权范围缩小，则只要 `target` 范围在授权范围内，就会解除临时凭证的范围以匹配 `target` 范围。
下表详细说明了 `privilege` 参数对两个授权的影响。一个授权具有范围 `S3://amzn-s3-demo-bucket1/bob/*`，其中包括 `amzn-s3-demo-bucket1` 存储桶中的整个 `bob/` 前缀。另一个授权具有范围 `S3://amzn-s3-demo-bucket1/bob/reports/*`，其中仅包括 `amzn-s3-demo-bucket1` 存储桶中的 `bob/reports/` 前缀。
| 授权范围 | 请求的范围 | 特权 | 返回的范围 | 效果 |
| --- | --- | --- | --- | --- |
| S3://amzn-s3-demo-bucket1/bob/\$1 | amzn-s3-demo-bucket1/bob/\$1 | Default | amzn-s3-demo-bucket1/bob/\$1 | 请求者有权访问 `amzn-s3-demo-bucket1` 存储桶中所有带以前缀 `bob/` 开始的密钥名称的对象。 |
| S3://amzn-s3-demo-bucket1/bob/\$1 | amzn-s3-demo-bucket1/bob/ | Minimal | amzn-s3-demo-bucket1/bob/ | 如果前缀名称 `bob/` 后面没有通配符 \$1，则请求者只能访问 `amzn-s3-demo-bucket1` 存储桶中名为 `bob/` 的对象。此类对象并不常见。请求者无权访问任何其他对象，包括那些带以 `bob/` 前缀开头的密钥名称的对象。 |
| S3://amzn-s3-demo-bucket1/bob/\$1 | amzn-s3-demo-bucket1/bob/images/\$1 | Minimal | amzn-s3-demo-bucket1/bob/images/\$1 | 请求者有权访问 `amzn-s3-demo-bucket1` 存储桶中所有带以前缀 `bob/images/*` 开始的密钥名称的对象。 |
| S3://amzn-s3-demo-bucket1/bob/reports/\$1 | amzn-s3-demo-bucket1/bob/reports/file.txt | Default | amzn-s3-demo-bucket1/bob/reports/\$1 | 请求者有权访问 `amzn-s3-demo-bucket1` 存储桶中所有带以前缀 `bob/reports` 开始的密钥名称的对象，它是匹配授权的范围。 |
| S3://amzn-s3-demo-bucket1/bob/reports/\$1 | amzn-s3-demo-bucket1/bob/reports/file.txt | Minimal | amzn-s3-demo-bucket1/bob/reports/file.txt | 请求者只能访问 `amzn-s3-demo-bucket1` 存储桶中具有密钥名称 `bob/reports/file.txt` 的对象。请求者无权访问任何其他对象。 |
**目录身份**
`GetDataAccess` 在匹配合适的授权时会考虑请求中涉及的所有身份。对于公司目录身份，`GetDataAccess` 还会返回用于身份感知会话的 IAM 身份的授权。有关身份感知会话的更多信息，请参阅《Amazon Identity and Access Management 用户指南》**中的[授予使用身份感知控制台会话的权限](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_credentials_temp_control-access_sts-setcontext.html)。`GetDataAccess` 生成凭证来将范围限制为受限最严的授权，如下表所示：
| IAM 身份的授权范围 | 目录身份的授权范围 | 请求的范围 | 返回的范围 | 特权 | 效果 |
| --- | --- | --- | --- | --- | --- |
| S3://amzn-s3-demo-bucket1/bob/\$1 | amzn-s3-demo-bucket1/bob/images/\$1 | S3://amzn-s3-demo-bucket1/bob/images/image1.jpeg | S3://amzn-s3-demo-bucket1/bob/images/\$1 | Default | 作为 IAM 角色授权的一部分，请求者可以访问键名称以前缀 *bob/* 开头的所有对象，但作为目录身份授权的一部分，则仅限于前缀 *bob/images/*。IAM 角色和目录身份都提供对所请求范围（也即 `bob/images/image1.jpeg`）的访问权限，但目录身份的授权限制性更强。因此，返回的范围限于对目录身份的限制性更强的授权。 |
| S3://amzn-s3-demo-bucket1/bob/\$1 | amzn-s3-demo-bucket1/bob/images/\$1 | S3://amzn-s3-demo-bucket1/bob/images/image1.jpeg | S3://amzn-s3-demo-bucket1/bob/images/image1.jpeg | Minimal | 由于权限设置为 `Minimal`，因此，即使身份可以访问更大的范围，也只返回所请求的范围 `bob/images/image1.jpeg`。 |
| S3://amzn-s3-demo-bucket1/bob/images/\$1 | amzn-s3-demo-bucket1/bob/\$1 | S3://amzn-s3-demo-bucket1/bob/images/image1.jpeg | S3://amzn-s3-demo-bucket1/bob/images/\$1 | Default | 作为目录身份授权的一部分，请求者可以访问键名称以前缀 *bob/* 开头的所有对象，但作为 IAM 角色授权的一部分，则仅限于前缀 *bob/images/*。IAM 角色和目录身份都提供对所请求范围（也即 `bob/images/image1.jpeg`）的访问权限，但 IAM 角色的授权限制性更强。因此，返回的范围限于对 IAM 角色的限制性更强的授权。 |
| S3://amzn-s3-demo-bucket1/bob/images/\$1 | amzn-s3-demo-bucket1/bob/\$1 | S3://amzn-s3-demo-bucket1/bob/images/image1.jpeg | S3://amzn-s3-demo-bucket1/bob/images/image1.jpeg | Minimal | 由于权限设置为 `Minimal`，因此，即使身份可以访问更大的范围，也只返回所请求的范围 `bob/images/image1.jpeg`。 |
**Duration**
`durationSeconds` 参数设置临时凭证的持续时间（以秒为单位）。默认值为 `3600` 秒（1 小时），但请求者（被授权者）可以指定介于 `900` 秒（15 分钟）和 `43200` 秒（12 小时）之间的范围。如果被授权者请求的值高于此最大值，请求将失败。
**注意**
在对临时令牌的请求中，如果位置是对象，请将请求中的 `targetType` 参数值设置为 `Object`。仅当位置为对象且权限级别为 `Minimal` 时需要此参数。如果位置是存储桶或前缀，则无需指定此参数。
**示例**
可以使用 Amazon Command Line Interface（Amazon CLI）、Amazon S3 REST API 和 Amazon SDK 请求临时凭证。请参阅这些示例。
有关其它信息，请参阅《Amazon Simple Storage Service API Reference》**中的 [GetDataAccess](https://docs.amazonaws.cn/AmazonS3/latest/API/API_control_GetDataAccess.html)。
## 使用 Amazon CLI
要安装 Amazon CLI，请参阅 *Amazon Command Line Interface 用户指南*中的[安装 Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/getting-started-install.html)。
要使用以下示例命令，请将 `user input placeholders` 替换为您自己的信息。
**Example 请求临时凭证**
请求:
```
aws s3control get-data-access \
--account-id 111122223333 \
--target s3://amzn-s3-demo-bucket/prefixA* \
--permission READ \
--privilege Default \
--region us-east-2
```
响应:
```
{
"Credentials": {
"AccessKeyId": "Example-key-id",
"SecretAccessKey": "Example-access-key",
"SessionToken": "Example-session-token",
"Expiration": "2023-06-14T18:56:45+00:00"},
"MatchedGrantTarget": "s3://amzn-s3-demo-bucket/prefixA**",
"Grantee": {
"GranteeType": "IAM",
"GranteeIdentifier": "arn:aws:iam::111122223333:role/role-name"
}
}
```
## 使用 REST API
有关用于请求 S3 Access Grants 中的临时凭证的 Amazon S3 REST API 支持的信息，请参阅**《Amazon Simple Storage Service API 参考》中的 [GetDataAccess](https://docs.amazonaws.cn/AmazonS3/latest/API/API_control_GetDataAccess.html)。
## 使用 Amazon SDK
此部分中的示例说明被授权者如何使用 Amazon SDK 从 S3 Access Grants 请求临时凭证。
------
#### [ Java ]
以下代码示例返回被授权者用于访问您的 S3 数据的临时凭证。要使用此代码示例，请将 `user input placeholders` 替换为您自己的信息。
**Example 获取临时凭证**
请求:
```
public void getDataAccess() {
GetDataAccessRequest getDataAccessRequest = GetDataAccessRequest.builder()
.accountId("111122223333")
.permission(Permission.READ)
.privilege(Privilege.MINIMAL)
.target("s3://amzn-s3-demo-bucket/prefixA*")
.build();
GetDataAccessResponse getDataAccessResponse = s3Control.getDataAccess(getDataAccessRequest);
LOGGER.info("GetDataAccessResponse: " + getDataAccessResponse);
}
```
响应:
```
GetDataAccessResponse(
Credentials=Credentials(
AccessKeyId="Example-access-key-id",
SecretAccessKey="Example-secret-access-key",
SessionToken="Example-session-token",
Expiration=2023-06-07T06:55:24Z
))
```
------