本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在 中使用參數化受管許可 AWS RAM
參數化受管許可是一種受管許可，其預留位置位於您以自己的值填入的政策條件中。這些預留位置是範本參數。他們不會建立新的受管許可。它們將變異性新增至現有政策範本。
您不是為每個唯一條件值建立單獨的客戶受管許可，而是使用參數建立一個客戶受管許可。當您將其與資源共用建立關聯時，您會為每個參數提供一個值。 會將您的值 AWS RAM 取代為政策範本，並將產生的資源型政策連接至共用資源。
例如，中央平台團隊會為 AWS Systems Manager 參數存放區參數 （資源類型 ) 建立一個客戶受管許可`ssm:Parameter`。它將僅供讀取存取權授予具有核准`team`標籤的主體。平台團隊與其組織中的帳戶共用該客戶受管許可。然後，每個帳戶會在自己的資源共享中使用它，其中包含一或多個參數存放區參數。在每個資源共用中，帳戶會提供可讀取共用參數存放區參數之主體的`team`標籤值。
**Topics**
+ [範本參數類型](#template-parameter-types)
+ [政策範本語法規則](#template-syntax-rules)
+ [建立參數化受管許可](#create-parameterized-permission)
+ [版本化參數化受管許可](#parameterized-permission-versioning)
+ [預覽轉譯的政策範本](#preview-rendered-policy)
+ [將參數化受管許可與資源共享建立關聯](#associate-parameterized-permission)
+ [檢視範本參數和值](#view-template-parameters)
+ [跨帳戶共用參數化受管許可](#sharing-parameterized-permissions)
+ [使用 IAM 政策控制範本參數值](#template-iam-condition-keys)
+ [`STRING_LIST` 參數範例](#template-stringlist-examples)
## 範本參數類型
AWS RAM 支援兩種參數類型。類型決定 如何將值 AWS RAM 取代為轉譯政策。在 AWS RAM API 和 中 AWS CLI，類型為 `STRING`和 `STRING_LIST`。 AWS RAM 主控台會將它們顯示為**字串**和**StringList**。
**`STRING`**
只接受一個字串值。
+ 您可以在條件索引鍵或條件值中使用`STRING`參數。
+ 您可以在其他文字中嵌入`STRING`參數。例如 `"arn:aws:iam::@{accountId}:role/Auditor"`。
+ 轉譯值一律為字串。由於 IAM 條件運算子會將字串轉換為比較的類型，因此`STRING`參數可以提供數值、布林值、日期、IP 地址或 ARN 值。
**`STRING_LIST`**
接受 1 到 100 個字串值。
+ 您只能在條件值中使用`STRING_LIST`參數，不能在條件索引鍵中使用。
+ 如果條件值是只包含 參數的單一字串，例如 `"@{teams}"`， 會 AWS RAM 轉譯您提供的值陣列。如果您提供單一值， 會 AWS RAM 轉譯單一字串。
+ 如果條件值在參數之前或之後有文字，例如 `"arn:aws:iam::@{accountIds}:role/ParameterReader"`， 會將每個值與該文字 AWS RAM 結合。
+ 若要結合每個值與多個字串，請列出條件值陣列中的字串。 AWS RAM 會轉譯每個值的每個陣列項目，並移除重複的結果。結果一律為陣列。
+ AWS RAM 和 IAM 不會在逗號上分割字串。逗號分隔字串會比較為一個值。
如需範例，請參閱 [`STRING_LIST` 參數範例](#template-stringlist-examples)。
## 政策範本語法規則
當您將參數新增至受管許可的政策範本時，適用下列規則。如果請求中斷其中一個規則， 會以 `InvalidParameterException`或 `InvalidPolicyException`錯誤 AWS RAM 拒絕該請求。
+ 參數預留位置使用語法 `@{parameterName}`。
+ 參數名稱可包含字母 (a-z、A-Z)、數字 (0-9)、冒號 (：)、連字號 (-) 和底線 (\_)。在受管許可版本中，名稱必須是唯一的，而且比較會忽略案例。
+ 您必須在建立 許可或 許可版本時宣告每個參數。每個宣告都需要名稱、類型和描述。描述最多可達 255 個字元。
+ 每個宣告的參數都必須出現在政策範本中。
+ 預留位置完全符合宣告的名稱，包括案例。不符合宣告名稱的`@{...}`格式文字會以文字文字的形式保留在政策中。例如，如果您宣告 `teams`但寫入 `@{Teams}`， 會 AWS RAM 視為`@{Teams}`文字並拒絕請求，因為 `teams` 未使用。
+ 參數只能以條件索引鍵或條件值的形式出現在 `Condition`元素中。 AWS RAM 拒絕 `Effect`、 `Action`或任何其他元素中的參數。
+ 條件索引鍵最多可包含一個參數，而且必須是`STRING`參數。條件值可以包含多個參數，例如 `"@{project}-@{stage}"`。當條件值結合`STRING_LIST`參數時， 會 AWS RAM 轉譯其值的每個組合，每個條件值最多 100 個字串。
+ 您可以為每個受管許可版本宣告最多 100 個參數。
+ 參數沒有預設值。當您將許可與資源共享建立關聯時，您必須為每個宣告的參數提供非空白值，而且您無法提供未宣告的名稱或提供相同名稱兩次。
## 建立參數化受管許可
您建立參數化受管許可的方式與建立任何其他客戶受管許可的方式相同。差別在於您宣告參數，並在政策範本的條件中使用`@{parameterName}`預留位置。
------
#### [ Console ]
**建立參數化受管許可**
1. 開啟**[受管許可程式庫](https://console.aws.amazon.com/ram/home#Permissions:)**，然後選擇**建立客戶受管許可**。
1. 在**客戶受管許可詳細資訊**下，輸入名稱並選擇資源類型。
1. 在**政策範本**下，輸入政策。在您希望每個資源共享提供自己的值的條件中使用`@{parameterName}`預留位置。
1. 在**範本參數**下，選擇**從政策新增參數**以新增政策中每個預留位置的資料列，或選擇**新增參數**以一次新增一列。對於每個參數，輸入**參數名稱**，選擇**類型** **（字串**或**StringList**)，然後輸入**描述**。描述會向為 參數提供值的任何人顯示。
1. (選用) 新增標籤。
1. 選擇**建立客戶受管許可**。
------
#### [ AWS CLI ]
**建立參數化受管許可**
+ 使用 `--policy-template`和 `--permission-template-parameters` 參數執行 [create-permission](https://docs.aws.amazon.com/cli/latest/reference/ram/create-permission.html) 命令。
下列範例會建立 `ssm:Parameter` 資源類型的客戶受管許可。在此政策中，只有當委託人具有值在`teams`清單中的`team`標籤時，委託人才能讀取參數。
```
$ aws ram create-permission \
--name ParameterReadByTeam \
--resource-type ssm:Parameter \
--permission-template-parameters '[{"name":"teams","type":"STRING_LIST","description":"Values of the team principal tag that can read the shared parameters"}]' \
--policy-template '{"Effect":"Allow","Action":["ssm:GetParameter","ssm:GetParameters"],"Condition":{"StringEquals":{"aws:PrincipalTag/team":"@{teams}"}}}'
{
"permission": {
"arn": "arn:aws:ram:us-east-1:123456789012:permission/ParameterReadByTeam",
"version": "1",
"defaultVersion": true,
"name": "ParameterReadByTeam",
"resourceType": "ssm:Parameter",
"status": "ATTACHABLE",
"creationTime": 1763300000.000,
"lastUpdatedTime": 1763300000.000,
"permissionTemplateParameters": [
{
"name": "teams",
"type": "STRING_LIST",
"description": "Values of the team principal tag that can read the shared parameters"
}
]
}
}
```
------
## 版本化參數化受管許可
參數化受管許可的版本控制方式與任何其他客戶受管許可相同。每個版本都會獨立宣告其參數，因此新版本可以宣告與之前版本不同的參數集。
若要建立新的版本，請使用 `--policy-template`和 `--permission-template-parameters` 參數執行 [create-permission-version](https://docs.aws.amazon.com/cli/latest/reference/ram/create-permission-version.html) 命令。下列範例使用名為 的`STRING`參數新增第二個條件`environment`。
```
$ aws ram create-permission-version \
--permission-arn arn:aws:ram:us-east-1:123456789012:permission/ParameterReadByTeam \
--permission-template-parameters '[{"name":"teams","type":"STRING_LIST","description":"Values of the team principal tag that can read the shared parameters"},{"name":"environment","type":"STRING","description":"Value of the environment principal tag that can read the shared parameters"}]' \
--policy-template '{"Effect":"Allow","Action":["ssm:GetParameter","ssm:GetParameters"],"Condition":{"StringEquals":{"aws:PrincipalTag/team":"@{teams}","aws:PrincipalTag/environment":"@{environment}"}}}'
```
新版本會在您建立時立即成為預設版本。現有的資源共用會保留其使用的版本。當資源共用的擁有者將其更新為新版本時，擁有者必須為新版本宣告的參數提供值。如需詳細資訊，請參閱[將 AWS 受管許可更新至較新版本](working-with-sharing-update-permissions.md)。
如需客戶受管許可版本和預設版本運作方式的詳細資訊，請參閱 [在 中建立和使用客戶受管許可 AWS RAM](create-customer-managed-permissions.md)。
## 預覽轉譯的政策範本
將參數化受管許可與資源共享建立關聯之前，您可以預覽從特定參數值轉譯的政策 AWS RAM 。
在 AWS RAM 主控台中，當您建立或更新資源共享時，請在**範本參數值下輸入值**，然後選擇**預覽轉譯政策**。
在 中 AWS CLI，使用 `--permission-template-parameters` 參數執行 [get-permission](https://docs.aws.amazon.com/cli/latest/reference/ram/get-permission.html) 命令。回應的 `permission` 欄位包含具有值的政策，以取代預留位置。
```
$ aws ram get-permission \
--permission-arn arn:aws:ram:us-east-1:123456789012:permission/ParameterReadByTeam \
--permission-template-parameters '[{"name":"teams","values":["payments","analytics"]},{"name":"environment","values":["prod"]}]'
{
"permission": {
"arn": "arn:aws:ram:us-east-1:123456789012:permission/ParameterReadByTeam",
"version": "2",
"defaultVersion": true,
"name": "ParameterReadByTeam",
"resourceType": "ssm:Parameter",
"permission": "{\"Effect\":\"Allow\",\"Action\":[\"ssm:GetParameter\",\"ssm:GetParameters\"],\"Condition\":{\"StringEquals\":{\"aws:PrincipalTag/team\":[\"payments\",\"analytics\"],\"aws:PrincipalTag/environment\":\"prod\"}}}",
"creationTime": 1763400000.000,
"lastUpdatedTime": 1763400000.000,
"isResourceTypeDefault": false,
"permissionType": "CUSTOMER_MANAGED",
"featureSet": "STANDARD",
"status": "ATTACHABLE",
"permissionTemplateParameters": [
{
"name": "teams",
"type": "STRING_LIST",
"description": "Values of the team principal tag that can read the shared parameters"
},
{
"name": "environment",
"type": "STRING",
"description": "Value of the environment principal tag that can read the shared parameters"
}
]
}
}
```
如果沒有 `--permission-template-parameters` 參數，`get-permission`命令會傳回具有`@{parameterName}`預留位置的政策範本。`permissionTemplateParameters` 欄位列出每個宣告參數的名稱、類型和描述。
## 將參數化受管許可與資源共享建立關聯
當您將參數化受管許可與資源共享建立關聯時，必須為版本 declares. AWS RAM renders 政策範本與您的值提供所有參數的值，並將產生的資源型政策連接到該類型的共用資源。
------
#### [ Console ]
**將參數化受管許可與資源共享建立關聯**
1. 當您建立或更新資源共享時，請在**關聯受管許可**頁面上，選擇資源類型的參數化受管許可。
1. 在**範本參數值**下，輸入每個參數的值。對於 **StringList** 參數，在每個值後按 Enter，或貼上以換行分隔的值。
1. （選用） 選擇**預覽轉譯政策**以檢查 AWS RAM 要連接的政策。
1. 完成精靈的其餘部分。檢閱頁面列出**範本參數值下的值**。
------
#### [ AWS CLI ]
**將參數化受管許可與資源共享建立關聯**
1. 使用 `--permission-template-parameters` 參數執行 [create-resource-share](https://docs.aws.amazon.com/cli/latest/reference/ram/create-resource-share.html) 或 [associate-resource-share-permission](https://docs.aws.amazon.com/cli/latest/reference/ram/associate-resource-share-permission.html)。
對於 `create-resource-share`， 參數是清單。每個項目都包含 `permissionArn`和該許可`permissionTemplateParameters`的值。下列範例會建立與另一個 共用參數存放區參數的資源共用 AWS 帳戶。具有 `team` 標籤`payments`或 `analytics`和 `environment`標籤的主體`prod`可以讀取它。
```
$ aws ram create-resource-share \
--name PaymentsConfig \
--resource-arns arn:aws:ssm:us-east-1:123456789012:parameter/payments/endpoint \
--principals 111122223333 \
--permission-arns arn:aws:ram:us-east-1:123456789012:permission/ParameterReadByTeam \
--permission-template-parameters '[{"permissionArn":"arn:aws:ram:us-east-1:123456789012:permission/ParameterReadByTeam","permissionTemplateParameters":[{"name":"teams","values":["payments","analytics"]},{"name":"environment","values":["prod"]}]}]'
{
"resourceShare": {
"resourceShareArn": "arn:aws:ram:us-east-1:123456789012:resource-share/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"name": "PaymentsConfig",
"owningAccountId": "123456789012",
"allowExternalPrincipals": true,
"status": "ACTIVE",
"creationTime": 1763300000.000,
"lastUpdatedTime": 1763300000.000,
"featureSet": "STANDARD"
}
}
```
`create-resource-share` 一律使用每個受管許可的預設版本。您只能將受管許可的預設版本與資源共用建立關聯。
1. 若要變更現有資源共享的參數值，或將其移至許可的預設版本，請使用 `--replace` 參數執行 [associate-resource-share-permission](https://docs.aws.amazon.com/cli/latest/reference/ram/associate-resource-share-permission.html)。對於此命令， 會直接`--permission-template-parameters`取得參數值。
```
$ aws ram associate-resource-share-permission \
--resource-share-arn arn:aws:ram:us-east-1:123456789012:resource-share/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
--permission-arn arn:aws:ram:us-east-1:123456789012:permission/ParameterReadByTeam \
--permission-template-parameters '[{"name":"teams","values":["payments"]},{"name":"environment","values":["prod"]}]' \
--replace
{
"returnValue": true
}
```
------
若要將許多資源共用從一個版本或許可移至另一個版本，請執行 [replace-permission-associations](https://docs.aws.amazon.com/cli/latest/reference/ram/replace-permission-associations.html)。如果目標版本宣告參數，則 `--permission-template-parameters`.Applicing 會將相同的值 AWS RAM 套用至命令更新的每個資源共用。
## 檢視範本參數和值
您可以檢視受管許可宣告的參數，以及資源共用提供的值。
**檢視受管許可宣告的參數**
執行 [get-permission](https://docs.aws.amazon.com/cli/latest/reference/ram/get-permission.html) 命令。`permissionTemplateParameters` 欄位列出每個參數的名稱、類型和描述。在 主控台中，許可詳細資訊頁面會顯示相同的資訊。
**檢視資源共用提供的值**
執行 [list-resource-share-permissions](https://docs.aws.amazon.com/cli/latest/reference/ram/list-resource-share-permissions.html) 命令。對於每個相關聯的參數化受管許可， `permissionTemplateParameters` 欄位包含資源共用提供的值。
```
$ aws ram list-resource-share-permissions \
--resource-share-arn arn:aws:ram:us-east-1:123456789012:resource-share/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
{
"permissions": [
{
"arn": "arn:aws:ram:us-east-1:123456789012:permission/ParameterReadByTeam",
"version": "2",
"defaultVersion": true,
"name": "ParameterReadByTeam",
"resourceType": "ssm:Parameter",
"status": "ATTACHABLE",
"creationTime": 1763400000.000,
"lastUpdatedTime": 1763400000.000,
"isResourceTypeDefault": false,
"permissionType": "CUSTOMER_MANAGED",
"featureSet": "STANDARD",
"permissionTemplateParameters": [
{
"name": "teams",
"values": ["payments"]
},
{
"name": "environment",
"values": ["prod"]
}
]
}
]
}
```
[list-permission-associations](https://docs.aws.amazon.com/cli/latest/reference/ram/list-permission-associations.html) 命令也會傳回您擁有之資源共用的值。當您列出使用您共用之客戶受管許可 AWS 帳戶 的其他 中的資源共用時，回應不會包含其值。
## 跨帳戶共用參數化受管許可
您可以與其他 共用參數化受管許可， AWS 帳戶 就像任何其他客戶受管許可一樣。接收帳戶可以查看每個參數的名稱、類型和描述，因此請撰寫描述，告訴他們要提供什麼值。每個接收帳戶在將共用的受管許可與自己的資源共用建立關聯時，都會提供自己的值。
如需共用客戶受管許可的說明，請參閱 [在 中跨帳戶共用和使用客戶受管許可 AWS RAM](sharing-customer-managed-permissions.md)。
## 使用 IAM 政策控制範本參數值
您可以在 IAM 政策中使用 `ram:PermissionTemplateParameter/{{parameter-name}}`條件索引鍵，以控制委託人可以為參數提供哪些值。金鑰為多值，且包含具名參數請求中的值。它可在 `ram:CreateResourceShare`、 `ram:AssociateResourceSharePermission`和 `ram:ReplacePermissionAssociations`動作的許可資源上使用。
在下列範例政策中，第一個陳述式會授予`ParameterReadByTeam`客戶受管許可的動作。如果為 提供的任何值`teams`不是 `payments`或 ，則第二個陳述式會拒絕它們`analytics`。由於金鑰是多值的，因此政策會使用 `ForAnyValue` set operator. AWS RAM requis 值來宣告每個參數，因此使用此客戶受管許可的請求一律會包含金鑰。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ram:CreateResourceShare",
"ram:AssociateResourceSharePermission",
"ram:ReplacePermissionAssociations"
],
"Resource": "arn:aws:ram:us-east-1:123456789012:permission/ParameterReadByTeam"
},
{
"Effect": "Deny",
"Action": [
"ram:CreateResourceShare",
"ram:AssociateResourceSharePermission",
"ram:ReplacePermissionAssociations"
],
"Resource": "arn:aws:ram:us-east-1:123456789012:permission/ParameterReadByTeam",
"Condition": {
"ForAnyValue:StringNotEquals": {
"ram:PermissionTemplateParameter/teams": [
"payments",
"analytics"
]
}
}
}
]
}
```
這些陳述式只會控制許可資源。委託人還需要請求中其他資源的許可，例如資源共用及其共用的資源。如需更多範例，請參閱[的 IAM 政策範例 AWS RAM](security-iam-policies-examples.md)。
## `STRING_LIST` 參數範例
下列範例顯示 如何 AWS RAM 轉譯`STRING_LIST`參數。
**Example 單在條件值中的`STRING_LIST`參數**
範本：
```
"Condition": {
"StringEquals": {
"aws:PrincipalTag/team": "@{teams}"
}
}
```
數值: `["payments", "analytics"]`
轉譯的政策：
```
"Condition": {
"StringEquals": {
"aws:PrincipalTag/team": ["payments", "analytics"]
}
}
```
使用單一值 時`["payments"]`，轉譯值為字串 `"payments"`。
**Example 具有周圍文字的`STRING_LIST`參數**
AWS RAM 會將每個值與參數前後的文字合併。
範本：
```
"Condition": {
"ArnLike": {
"aws:PrincipalArn": "arn:aws:iam::@{accountIds}:role/ParameterReader"
}
}
```
數值: `["111122223333", "444455556666"]`
轉譯的政策：
```
"Condition": {
"ArnLike": {
"aws:PrincipalArn": [
"arn:aws:iam::111122223333:role/ParameterReader",
"arn:aws:iam::444455556666:role/ParameterReader"
]
}
}
```
**Example 條件值陣列中的`STRING_LIST`參數**
AWS RAM 會針對每個值轉譯陣列中的每個項目，並移除重複的結果。
範本：
```
"Condition": {
"ArnLike": {
"aws:PrincipalArn": [
"arn:aws:iam::@{accountIds}:role/Auditor",
"arn:aws:iam::@{accountIds}:role/Reader"
]
}
}
```
數值: `["111122223333", "444455556666"]`
轉譯的政策：
```
"Condition": {
"ArnLike": {
"aws:PrincipalArn": [
"arn:aws:iam::111122223333:role/Auditor",
"arn:aws:iam::444455556666:role/Auditor",
"arn:aws:iam::111122223333:role/Reader",
"arn:aws:iam::444455556666:role/Reader"
]
}
}
```