# IAM JSON 策略语言的语法
<a name="reference_policies_grammar"></a>

该页提供了用于在 IAM 中创建 JSON 策略的语言的正式语法。提供此语法的目的是为了便于您理解如何构造和验证策略。

有关策略示例，请参阅以下主题：
+ [Amazon Identity and Access Management 中的策略和权限](access_policies.md)
+ [IAM 基于身份的策略示例](access_policies_examples.md)
+ 《*Amazon EC2 用户指南*》中的[用于 Amazon EC2 控制台的策略示例](https://docs.amazonaws.cn/AWSEC2/latest/UserGuide/iam-policies-ec2-console.html)和[使用 Amazon CLI、Amazon EC2 CLI 或 Amazon SDK 的策略示例](https://docs.amazonaws.cn/AWSEC2/latest/UserGuide/ExamplePolicies_EC2.html)。
+  *Amazon Simple Storage Service User Guide*（亚马逊云科技 Simple Storage Service 用户指南）中的[存储桶策略示例](https://docs.amazonaws.cn/AmazonS3/latest/userguide/example-bucket-policies.html)和[用户策略示例](https://docs.amazonaws.cn/AmazonS3/latest/userguide/example-policies-s3.html)。

有关其他 Amazon 产品中使用的策略的示例，请参阅相应服务的文档。

**Topics**
+ [策略语言和 JSON](#policies-grammar-json)
+ [此语法采用的约定](#policies-grammar-conventions)
+ [语法](#policies-grammar-bnf)
+ [策略语法说明](#policies-grammar-notes)

## 策略语言和 JSON
<a name="policies-grammar-json"></a>

策略是以 JSON 格式表示的。当您创建或编辑 JSON 策略时，IAM 可以执行策略验证以帮助您创建有效的策略。IAM 可识别 JSON 语法错误，而 IAM Access Analyzer 将提供额外的策略检查和建议，以帮助您进一步优化策略。要了解策略验证的更多信息，请参阅 [IAM 策略验证](access_policies_policy-validator.md)。要了解有关 IAM Access Analyzer 策略检查和可执行建议的更多信息，请参阅 [IAM Access Analyzer 策略验证](https://docs.amazonaws.cn/IAM/latest/UserGuide/access-analyzer-policy-validation.html)。

在此文档中，我们不提供有效 JSON 组成部分的完整说明。而是提供一些基本的 JSON 规则：
+ 各实体间允许使用空格。
+ 值用引号括起来。对于数字值和布尔值，引号是可选的。
+ 很多元素 (例如 `action_string_list` 和 `resource_string_list`) 都可以采用 JSON 数组作为值。数组可以采用一个或多个值。如果包含多个值，则数组用方括号 (`[` 和 `]`) 括起来并用逗号分隔，如以下示例中所示：

  `"Action" : ["ec2:Describe*","ec2:List*"]`
+ 基本 JSON 数据类型 (布尔型、数字和字符串) 在 [RFC 7159](https://datatracker.ietf.org/doc/html/rfc7159) 中定义。

## 此语法采用的约定
<a name="policies-grammar-conventions"></a>

此语法采用以下约定：
+ 以下字符是 JSON 令牌，*包含* 在策略中：

  `{ } [ ] " , :`
+ 以下字符是语法中的特殊字符，*不包含* 在策略中：

  `= < > ( ) |`
+ 当一个元素允很多个值时，使用重复值、逗号分隔符和省略号 (`...`) 进行表示。示例：

  `[<action_string>, <action_string>, ...]`

  `<principal_map> = { <principal_map_entry>, <principal_map_entry>, ... }`

  允许多个值时，只包含一个值也是有效的。只有一个值时，必须省略尾部的逗号。如果元素采用数组 (使用 [ 和 ] 标记) 但只包含一个值，则括号可选。示例：

  `"Action": [<action_string>]`

  `"Action": <action_string>`
+ 元素后的问号 (`?`) 表示该元素是可选的。示例：

  <`version_block?>`

  不过，请务必参考语法列表后的说明了解有关可选元素的详细信息。
+ 元素之间的竖线 (`|`) 表示备选项。在语法中，圆括号定义备选项的范围。示例：

  `("Principal" | "NotPrincipal")` 
+ 必须为文字字符串的元素括在双引号 (`"`) 中。示例：

  `<version_block> = "Version" : ("2008-10-17" | "2012-10-17" )`

有关更多说明，请参阅语法列表后面的[策略语法说明](#policies-grammar-notes)。

## 语法
<a name="policies-grammar-bnf"></a>

下面的列表描述了策略语言语法。有关此列表中采用的约定，请参阅前面的部分。有关更多信息，请参阅后面的说明。

**注意**  
此语法描述了使用版本号 `2008-10-17 ` 和 `2012-10-17 ` 标记的策略。`Version` 策略元素与策略版本不同。`Version` 策略元素用在策略之中，用于定义策略语言的版本。另一方面，当您对 IAM 中的客户托管策略进行更改时，将创建一个策略版本。已更改的策略不会覆盖现有策略。而是由 IAM 创建新的托管策略版本。要了解 `Version` 策略元素的更多信息，请参阅[IAM JSON 策略元素：Version](reference_policies_elements_version.md)。要了解策略版本的更多信息，请参阅[IAM policy 版本控制](access_policies_managed-versioning.md)。

```
policy  = {
     <version_block?>,
     <id_block?>,
     <statement_block>
}

<version_block> = "Version" : ("2008-10-17"		 	 	  | "2012-10-17"		 	 	 )

<id_block> = "Id" : <policy_id_string>

<statement_block> = "Statement" : [ <statement>, <statement>, ... ]

<statement> = { 
    <sid_block?>,
    <principal_block?>,
    <effect_block>,
    <action_block>,
    <resource_block>,
    <condition_block?>
}

<sid_block> = "Sid" : <sid_string>

<effect_block> = "Effect" : ("Allow" | "Deny")  

<principal_block> = ("Principal" | "NotPrincipal") : ("*" | <principal_map>)

<principal_map> = { <principal_map_entry>, <principal_map_entry>, ... }

<principal_map_entry> = ("AWS" | "Federated" | "Service" | "CanonicalUser") :   
    [<principal_id_string>, <principal_id_string>, ...]

<action_block> = ("Action" | "NotAction") : 
    ("*" | <action_string> | [<action_string>, <action_string>, ...])

<resource_block> = ("Resource" | "NotResource") : 
    : ("*" | <resource_string> | [<resource_string>, <resource_string>, ...])

<condition_block> = "Condition" : { <condition_map> }
<condition_map> = { 
  <condition_type_string> : { <condition_key_string> : <condition_value_list> },
  <condition_type_string> : { <condition_key_string> : <condition_value_list> }, ...
}  
<condition_value_list> = [<condition_value>, <condition_value>, ...]
<condition_value> = (<condition_value_string> | <condition_value_string> | <condition_value_string>)
```

## 策略语法说明
<a name="policies-grammar-notes"></a>
+ 一个策略可以包含一组语句。
+ 策略的最大大小介于 2048 个字符和 10,240 个字符之间，具体取决于策略所附加到的实体。有关更多信息，请参阅 [IAM 和 Amazon STS 配额](reference_iam-quotas.md)。策略大小计算不包括空格字符。
+ 单个元素不能包含同一个键的多个实例。例如，不能在同一语句中包含两次 `Effect` 块。
+ 各个块的显示顺序无限制。例如，在策略中，`version_block` 可以跟在 `id_block` 后面。同样地，`effect_block`、`principal_block`、`action_block` 在语句中也可以按任何顺序显示。
+ `id_block` 在基于资源的策略中是可选的。它一定*不能* 包含在基于身份的策略中。
+ `principal_block` 元素在基于资源的策略中（例如，在 Amazon S3 存储桶策略中）和 IAM 角色的信任策略中是必需的。它一定*不能* 包含在基于身份的策略中。
+ Amazon S3 存储桶策略中的 `principal_map` 元素可能包含 `CanonicalUser` ID。大多数基于资源的策略不支持该映射。要了解有关在存储桶策略中使用规范用户 ID 的更多信息，请参阅 *Amazon Simple Storage Service 用户指南*中的[在策略中指定主体](https://docs.amazonaws.cn/AmazonS3/latest/userguide/s3-bucket-user-policy-specifying-principal-intro.html)。
+ 每个字符串值 (`policy_id_string`、`sid_string`、`principal_id_string`、`action_string`、`resource_string`、`condition_type_string`、`condition_key_string` 以及 `condition_value` 的字符串版本) 都可以有其自己的最小和最大长度限制、具体的允许值或必需的内部格式。

### 有关字符串值的说明
<a name="policies-grammar-notes-strings"></a>

这一部分提供了有关在策略的不同元素中使用的字符串值的更多信息。

**`action_string`**  
由服务命名空间、冒号和操作名称组成。操作名称可以包含通配符。示例：  

```
"Action":"ec2:StartInstances"

"Action":[
  "ec2:StartInstances",
  "ec2:StopInstances"
]

"Action":"cloudformation:*"

"Action":"*"

"Action":[
  "s3:Get*",
  "s3:List*"
]
```

**`policy_id_string`**  
提供一种方法将关于策略的信息作为整体包含在其中。某些服务 (如 Amazon SQS 和 Amazon SNS) 以预留方式使用 `Id` 元素。除非另受某个服务限制，否则 policy\$1id\$1string 可以包含空格。有些服务要求此值在 Amazon 账户内唯一。  
`id_block` 可在基于资源的策略中使用，但不能在基于身份的策略中使用。
长度没有限制，但此字符串计入策略总长度，而策略总长度是有限制的。  

```
"Id":"Admin_Policy"

"Id":"cd3ad3d9-2776-4ef1-a904-4c229d1642ee"
```

**`sid_string`**  
提供一种方法来包含有关单个语句的信息。对于 IAM policy，`Sid` 值中仅允许使用基本的字母数字（A-Z、a-z、0-9）字符。支持资源策略的其他 Amazon 服务对于 `Sid` 值可能有其他要求。例如，一些服务要求此值在 Amazon Web Services 账户 内唯一，而一些服务允许在 `Sid` 值中使用其他字符，如空格。  

```
"Sid":"1" 

"Sid": "ThisStatementProvidesPermissionsForConsoleAccess"
```

**`principal_id_string`**  
提供使用 Amazon Web Services 账户、IAM 用户、IAM 角色、联合用户或代入角色的用户的 [*Amazon 资源名称*（ARN）](reference_identifiers.md#identifiers-arns) 指定主体的方式。对于 Amazon Web Services 账户，您还可以使用简单形式 `AWS:accountnumber` 而不是完整的 ARN。有关所有选项（包括 Amazon 服务、担任的角色等），请参阅[如何指定主体](reference_policies_elements_principal.md#Principal_specifying)。  
请注意，您只能使用 \$1 指定“everyone/anonymous”。您不能使用它指定一部分名称或 ARN。

**`resource_string`**  
在大多数情况下，由一个 [Amazon Resource Name](reference_identifiers.md#identifiers-arns) (ARN) 组成。您可以在 ARN 的资源部分使用通配符（\$1 和 ?）。有关在 ARN 中使用通配符的更多信息，请参阅 [在路径中使用通配符](reference-arns.md#arns-paths-wildcards)。  
当您在基于身份的策略中指定不完整的 ARN（少于标准的六个字段）时，Amazon 会通过在所有缺失字段中添加通配符 (\$1) 来自动完成 ARN。例如，指定 `arn:aws:sqs` 相当于 `arn:aws:sqs:*:*:*`，它让您有可以访问所有区域和账户中的所有 Amazon SQS 资源。

```
"Resource":"arn:aws:iam::123456789012:user/Bob"

"Resource":"arn:aws:s3:::amzn-s3-demo-bucket/*"
```

**`condition_type_string`**  
标识所测试条件的类型，例如 `StringEquals`、`StringLike`、`NumericLessThan`、`DateGreaterThanEquals`、`Bool`、`BinaryEquals`、`IpAddress`、`ArnEquals` 等。有关条件类型的完整列表，请参阅[IAM JSON 策略元素：条件运算符](reference_policies_elements_condition_operators.md)。  

```
"Condition": {
  "NumericLessThanEquals": {
    "s3:max-keys": "10"
  }
}

"Condition": {
  "Bool": {
    "aws:SecureTransport": "true"
  }
}

"Condition": {
  "StringEquals": {
      "s3:x-amz-server-side-encryption": "AES256"
   }
}
```

**`condition_key_string`**  
标识将对其值进行测试以便确定条件是否满足的条件键。Amazon 定义了一组在所有 Amazon 服务（包括 `aws:PrincipalType`、`aws:SecureTransport` 和 `aws:userid`）中可用的条件键。  
有关 Amazon 条件键的列表，请参阅 [Amazon 全局条件上下文密钥](reference_policies_condition-keys.md)。有关服务特定的条件键，请参阅相应服务的文档，例如：  
+ *Amazon Simple Storage Service 用户指南*中的[在策略中指定条件](https://docs.amazonaws.cn/AmazonS3/latest/userguide/amazon-s3-policy-keys.html)
+ 《*Amazon EC2 用户指南*》中的 [Amazon EC2 的 IAM 策略](https://docs.amazonaws.cn/AWSEC2/latest/UserGuide/iam-policies-for-amazon-ec2.html)。

```
"Condition":{
  "Bool": {
      "aws:SecureTransport": "true"
   }
}

"Condition": {
  "StringNotEquals": {
      "s3:x-amz-server-side-encryption": "AES256"
   }
}

"Condition": {
  "StringEquals": {
    "aws:ResourceTag/purpose": "test"
  }
}
```

**`condition_value_string`**  
标识 condition\$1key\$1string 的值，该值决定了是否满足条件。有关条件类型的有效值的完整列表，请参阅 [IAM JSON 策略元素：条件运算符](reference_policies_elements_condition_operators.md)。  

```
"Condition":{
  "ForAnyValue:StringEquals": {
		"dynamodb:Attributes": [
			"ID",
			"PostDateTime"
  	      ]
  }
}
```