本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 透過 S3 Access Grants 請求存取 Amazon S3 資料
使用 S3 存取授權[建立存取授權](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-grants-grant.html)後，承授者可以請求憑證，以存取他們獲授存取權的 S3 資料。承授者可以是 AWS Identity and Access Management (IAM) 主體、您的公司目錄身分或授權的應用程式。
應用程式或 AWS 服務 可以使用 S3 Access Grants `GetDataAccess` API 操作，要求 S3 Access Grants 代表承授者存取您的 S3 資料。 `GetDataAccess` 首先， 會驗證您已授予此身分對資料的存取權。然後，S3 存取授權會使用 [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) API 操作來取得臨時憑證權杖，並將其提供給請求者。這個臨時憑證權杖是 AWS Security Token Service (AWS 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/` 字首。
| 授權範圍 | 請求範圍 | 權限 | 傳回範圍 | Effect |
| --- | --- | --- | --- | --- |
| S3://{{amzn-s3-demo-bucket1}}/bob/\* | {{amzn-s3-demo-bucket1}}/bob/\* | Default | {{amzn-s3-demo-bucket1}}/bob/\* | 請求者可以存取 `{{amzn-s3-demo-bucket1}}` 儲存貯體中，具有以字首 `bob/` 開頭的索引鍵名稱的所有物件。 |
| S3://{{amzn-s3-demo-bucket1}}/bob/\* | {{amzn-s3-demo-bucket1}}/bob/ | Minimal | {{amzn-s3-demo-bucket1}}/bob/ | 若字首名稱 `bob/` 後沒有萬用字元 \*，則請求者只能存取 `{{amzn-s3-demo-bucket1}}` 儲存貯體中名為 `bob/` 的物件。這類物件並不常見。請求者無法存取任何其他物件，包括具有以 `bob/` 字首開頭的索引鍵名稱的物件。 |
| S3://{{amzn-s3-demo-bucket1}}/bob/\* | {{amzn-s3-demo-bucket1}}/bob/images/\* | Minimal | {{amzn-s3-demo-bucket1}}/bob/images/\* | 請求者可以存取 `{{amzn-s3-demo-bucket1}}` 儲存貯體中，具有以字首 `bob/images/*` 開頭的索引鍵名稱的所有物件。 |
| S3://{{amzn-s3-demo-bucket1}}/bob/reports/\* | {{amzn-s3-demo-bucket1}}/bob/reports/file.txt | Default | {{amzn-s3-demo-bucket1}}/bob/reports/\* | 請求者可以存取 `{{amzn-s3-demo-bucket1}}` 儲存貯體中，具有以 `bob/reports` 字首開頭的索引鍵名稱的所有物件，這是相符授權的範圍。 |
| S3://{{amzn-s3-demo-bucket1}}/bob/reports/\* | {{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 身分授權。如需身分感知工作階段的詳細資訊，請參閱**《AWS Identity and Access Management 使用者指南》中的[授予許可以使用身分感知主控台工作階段](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_control-access_sts-setcontext.html)。`GetDataAccess` 會產生憑證，將範圍限制為最嚴格的授權，如下表所示：
| IAM 身分的授權範圍 | 目錄身分的授權範圍 | 請求範圍 | 傳回範圍 | 權限 | Effect |
| --- | --- | --- | --- | --- | --- |
| S3://{{amzn-s3-demo-bucket1}}/bob/\* | {{amzn-s3-demo-bucket1}}/bob/images/\* | S3://{{amzn-s3-demo-bucket1}}/bob/images/image1.jpeg | S3://{{amzn-s3-demo-bucket1}}/bob/images/\* | Default | 請求者可以存取索引鍵名稱開頭為字首 *bob/* 的所有物件，做為 IAM 角色授予的一部分，但僅限於字首 *bob/images/* 做為目錄身分授權的一部分。IAM 角色和目錄身分都可以存取請求的範圍，亦即 `bob/images/image1.jpeg`，但目錄身分的授權更為嚴格。因此，傳回的範圍僅限於更嚴格的目錄身分授權。 |
| S3://{{amzn-s3-demo-bucket1}}/bob/\* | {{amzn-s3-demo-bucket1}}/bob/images/\* | 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/\* | {{amzn-s3-demo-bucket1}}/bob/\* | S3://{{amzn-s3-demo-bucket1}}/bob/images/image1.jpeg | S3://{{amzn-s3-demo-bucket1}}/bob/images/\* | Default | 請求者可以存取索引鍵名稱開頭為字首 *bob/* 的所有物件，做為目錄身分的一部分，但僅限於字首 *bob/images/* 做為 IAM 角色授權的一部分。IAM 角色和目錄身分都可以存取請求的範圍，亦即 `bob/images/image1.jpeg`，但 IAM 角色的授權更為嚴格。因此，傳回的範圍僅限於更嚴格的 IAM 角色授權。 |
| S3://{{amzn-s3-demo-bucket1}}/bob/images/\* | {{amzn-s3-demo-bucket1}}/bob/\* | S3://{{amzn-s3-demo-bucket1}}/bob/images/image1.jpeg | S3://{{amzn-s3-demo-bucket1}}/bob/images/image1.jpeg | Minimal | 由於權限設定為 `Minimal`，即使身分可存取更大的範圍，只有請求的範圍會傳回 `bob/images/image1.jpeg`。 |
**持續時間**
`durationSeconds` 參數會設定臨時憑證的持續時間 (以秒為單位)。預設值為 `3600` 秒 (1 小時)，但請求者 (承授者) 可以指定從 `900` 秒 (15 分鐘) 到最長 `43200` 秒 (12 小時) 的範圍。若承授者請求的值高於此上限，則請求會失敗。
**注意**
在您的臨時權杖請求中，如果位置是物件，請將您請求中的 `targetType` 參數值設定為 `Object`。只有在位置是物件且權限層級為 `Minimal` 時，才需要此參數。若位置是儲存貯體或字首，則不需要指定此參數。
**範例**
您可以使用 AWS Command Line Interface (AWS CLI)、Amazon S3 REST API 和 AWS SDKs 來請求臨時憑證。請參閱這些範例。
如需額外資訊，請參閱《Amazon Simple Storage Service API 參考》**中的 [GetDataAccess](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetDataAccess.html)。
## 使用 AWS CLI
若要安裝 AWS CLI，請參閱*AWS Command Line Interface 《 使用者指南*[》中的安裝 AWS CLI](https://docs.aws.amazon.com/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.aws.amazon.com/AmazonS3/latest/API/API_control_GetDataAccess.html)。
## 使用 AWS SDKs
本節提供承授者如何使用 AWS SDKs 從 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}}
))
```
------