本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 为匿名用户嵌入控制面板时，使用采用基于标签的规则的行级别安全性来限制对数据集的访问
<a name="quicksight-dev-rls-tags"></a>


|  | 
| --- |
|  适用于：企业版  | 


|  | 
| --- |
|    目标受众：Amazon Quick 管理员和 Amazon Quick 开发者  | 

当您在应用程序中为未在 Quick 中配置（注册）的用户嵌入 Amazon Quick 控制面板时，您可以使用行级安全 (RLS) 来 filter/restrict 保护带有标签的数据。标签是用户指定的字符串，用于标识应用程序中的会话。您可以使用标签为数据集实现 RLS 控制。通过在数据集中配置基于 RLS 的限制，Quick 根据与用户身份/会话关联的会话标签筛选数据。

例如，假设您的物流公司会为各种零售商提供面向客户的应用程序。来自这些零售商的成千上万名用户会访问您的应用程序，查看与他们的订单如何从您的仓库发货相关的指标。

您不想在 Quick 中管理成千上万的用户，因此您可以使用匿名嵌入将选定的仪表板嵌入到您的应用程序中，经过身份验证和授权的用户可以看到这些仪表板。不过，您要确保零售商只能看到与其业务相关的数据，而不会看到其他业务数据。您可以使用带标签的 RLS 来确保客户只能看到与他们相关的数据。

为此，请完成以下步骤：

1. 向数据集添加 RLS 标签。

1. 在运行时系统中使用 `GenerateEmbedUrlForAnonymousUser` API 操作为这些标签分配值。

   有关使用 `GenerateEmbedUrlForAnonymousUser` API 操作为匿名用户嵌入控制面板的更多信息，请参阅[为匿名（未注册）用户嵌入 Amazon Quick Sight 控制面板](embedded-analytics-dashboards-for-everyone.md)。

使用带标签的 RLS 之前，请记住以下几点：
+ 目前仅匿名嵌入尤其是使用 `GenerateEmbedUrlForAnonymousUser` API 操作的嵌入式控制面板，才支持使用带标签的 RLS。
+ 使用 `GenerateEmbedURLForRegisteredUser` API 操作或旧 `GetDashboardEmbedUrl` API 操作的嵌入式控制面板不支持使用带标签的 RLS。
+  AWS Identity and Access Management (IAM) 或快速身份类型不支持 RLS 标签。
+ 将 SPICE 数据集应用于行级别安全性时，数据集中的每个字段最多可以包含 2,047 个 Unicode 字符。如果字段包含的内容超过该限额，则会在摄取过程中被截断。要了解有关 SPICE 数据限额的更多信息，请参阅[导入数据的 SPICE 限额](data-source-limits.md#spice-limits)。

## 步骤 1：向数据集添加 RLS 标签
<a name="quicksight-dev-rls-tags-add"></a>

您可以在 Amazon Quick 中向数据集添加基于标签的规则。您也可以调用 `CreateDataSet` 或 `UpdateDataSet` API 操作来添加基于标签的规则。有关更多信息，请参阅 [使用 API 向数据集添加 RLS 标签](#quicksight-dev-rls-tags-add-api)。

使用以下步骤在 Quick 中向数据集添加 RLS 标签。

**向数据集添加 RLS 标签**

1. 在快速入门页面中，选择左侧**的数据**。

1. 选择要向其添加 RLS 的数据集。

1. 在打开的数据集详细信息页面上，为**行级别安全性**选择**设置**。

1. 在打开的**设置行级别安全性**页面上，选择**基于标签的规则**。

1. 对于**列**，选择要添加标签规则的列。

   例如，若为物流公司，则使用 `retailer_id` 列。

   仅列出数据类型为字符串的列。

1. 对于**标签**，输入标签键。您可以输入所需的任何标签名称。

   例如，若为物流公司，则使用 `tag_retailer_id` 标签键。这样做可以根据访问应用程序的零售商来设置行级别安全性。

1. （可选）对于**分隔符**，从列表中选择一个分隔符，或输入自己的分隔符。

   为标签分配多个值时，可以使用分隔符来分隔文本字符串。分隔符的值最长可达 10 个字符。

1. （可选）对于**全部匹配**，选择 **\$1**，或输入自己的一个或多个字符。

   在要按数据集中该列的所有值进行筛选时，此选项可以是您希望使用的任何字符。您可以使用字符，而不是逐一列出值。如果指定了此值，则其长度可以至少为一个字符，或最多 256 个字符。

1. 选择**添加**。

   标签规则已添加到数据集并在底部列出，但尚未应用。要向数据集添加其他标签规则，请重复步骤 5 到 9。要编辑标签规则，请选择规则后面的铅笔图标。要删除标签规则，请选择规则后面的删除图标。您最多可以向数据集添加 50 个标签。

1. 准备好将标签规则应用于数据集时，选择**应用规则**。

1. 在打开的**是否启用基于标签的安全性？**页面中，选择**应用并激活**。

   基于标签的规则现已激活。**设置行级别安全性**页面将显示一个切换开关，供您开启和关闭数据集的标签规则。

   要关闭数据集的所有基于标签的规则，请关闭**基于标签的规则**开关，然后在出现的文本框中输入“确认”。

   在**数据**页面上，数据集行中会出现一个锁形图标，表示标签规则已启用。

   您现在可以在运行时系统中使用标签规则来设置标签值，如 [步骤 2：在运行时系统中为 RLS 标签分配值](#quicksight-dev-rls-tags-assign-values) 中所述。这些规则仅在处于活动状态时影响快速阅读器。
**重要**  
在数据集上分配并启用标签后，请确保授予 Quick authors 权限，以便在创作仪表板时查看数据集中的任何数据。  
要授予 Quick 作者查看数据集中数据的权限，请创建权限文件或查询以用作数据集规则。有关更多信息，请参阅 [为行级别安全性创建数据集规则](restrict-access-to-a-data-set-using-row-level-security.md#create-data-set-rules-for-row-level-security)。

创建基于标签的规则后，将出现一个新的**管理规则**表，其中会显示基于标签的规则之间的关系。要更改**管理规则**表中列出的规则，请选择规则后面的铅笔图标。然后添加或移除标签，并选择**更新**。要将更新后的规则应用于数据集，请选择**应用**。

### （可选）将 OR 条件添加到 RLS 标签
<a name="quicksight-dev-rls-tags-or"></a>

您还可以在基于标签的规则中添加 OR 条件，以进一步自定义向 Quick 账户用户显示数据的方式。当您在基于标签的规则中使用 OR 条件时，如果规则中定义的至少一个标签有效，则会显示 Quick 中的视觉效果。

**将 OR 条件添加到基于标签的规则**

1. 在**管理规则**表中，选择**添加 OR 条件**。

1. 在出现的**选择标签**下拉列表中，选择要创建 OR 条件的标签。您最多可以向**管理规则**表添加 50 个 OR 条件。您可以向数据集中的单列添加多个标签，但规则中至少需要包含一个列标签。

1. 选择**更新**将条件添加到规则，然后选择**应用**将更新后的规则应用于数据集。

### 使用 API 向数据集添加 RLS 标签
<a name="quicksight-dev-rls-tags-add-api"></a>

您也可以通过调用 `CreateDataSet` 或 `UpdateDataSet` API 操作，在数据集中配置并启用基于标签的行级别安全性。通过以下示例了解如何操作。

**重要**  
在 API 调用中配置会话标签时，  
将会话标签视为安全证书。不要向最终用户或客户端代码公开会话标签。
实现服务器端控制。确保会话标签完全由您可信的后端服务设置，而不是由最终用户可以修改的参数设置。
保护会话标签不被枚举。确保一个租户中的用户无法发现或猜测属于其他租户的 SessionTag 值。
查看您的架构。如果允许下游客户或合作伙伴直接调用 API，请评估这些用户是否可以为他们不应访问的租户指定 SessionTag 值。

------
#### [ CreateDataSet ]

以下示例展示了如何创建带 RLS 标签的数据集。该示例采用了前述的物流公司场景。标签在 `row-level-permission-tag-configuration` 元素中定义。标签在数据要受到保护的列上定义。有关此可选元素的更多信息，请参阅 *Amazon Quick API 参考[RowLevelPermissionTagConfiguration](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_RowLevelPermissionTagConfiguration.html)*中的。

```
create-data-set
		--aws-account-id <value>
		--data-set-id <value>
		--name <value>
		--physical-table-map <value>
		[--logical-table-map <value>]
		--import-mode <value>
		[--column-groups <value>]
		[--field-folders <value>]
		[--permissions <value>]
		[--row-level-permission-data-set <value>]
		[--column-level-permission-rules <value>]
		[--tags <value>]
		[--cli-input-json <value>]
		[--generate-cli-skeleton <value>]
		[--row-level-permission-tag-configuration 
	'{
		"Status": "ENABLED",
		"TagRules": 
			[
				{
					"TagKey": "tag_retailer_id",
					"ColumnName": "retailer_id",
					"TagMultiValueDelimiter": ",",
					"MatchAllValue": "*"
				},
				{
					"TagKey": "tag_role",
					"ColumnName": "role"
				}
			],
		"TagRuleConfigurations":
			[
				tag_retailer_id
			],
			[
				tag_role
			]
	}'
]
```

本示例中的标签是在元素的 `TagRules` 部分中定义的。在本示例中，根据两列定义了两个标签：
+ `tag_retailer_id` 标签键是为 `retailer_id` 列定义的。对本示例中的物流公司而言，这将根据访问应用程序的零售商来设置行级别安全性。
+ `tag_role` 标签键是为 `role` 列定义的。对本示例中的物流公司而言，这将根据从特定零售商访问应用程序的用户的角色来设置额外的行级别安全性层。例如 `store_supervisor` 或 `manager`。

对于每个标签，您都可以定义 `TagMultiValueDelimiter` 和 `MatchAllValue`。这二者都是可选项。
+ `TagMultiValueDelimiter` – 此选项可以是任意字符串，用于在运行时系统中传递值时分隔值。此值最长可达 10 个字符。本示例使用逗号作为分隔符值。
+ `MatchAllValue` – 在要按数据集中该列的所有值进行筛选时，此选项可以是您希望使用的任何字符。您可以使用字符，而不是逐一列出值。如果指定了此值，其长度至少为一个字符，最多为 256 个字符。本示例使用星号作为通配值。

在为数据集列配置标签时，请使用强制属性 `Status` 开启或关闭标签。要启用标签规则，请为该属性使用值 `ENABLED`。启用标签规则后，就可以在运行时系统中使用这些规则来设置标签值，如 [步骤 2：在运行时系统中为 RLS 标签分配值](#quicksight-dev-rls-tags-assign-values) 中所述。

以下为响应定义的示例。

```
{
			"Status": 201,
			"Arn": "arn:aws:quicksight:us-west-2:11112222333:dataset/RLS-Dataset",
			"DataSetId": "RLS-Dataset",
			"RequestId": "aa4f3c00-b937-4175-859a-543f250f8bb2"
		}
```

------
#### [ UpdateDataSet ]

**UpdateDataSet**

您可以使用 `UpdateDataSet` API 操作为现有数据集添加或更新 RLS 标签。

以下为使用 RLS 标签更新数据集的示例。该示例采用了前述的物流公司场景。

```
update-data-set
		--aws-account-id <value>
		--data-set-id <value>
		--name <value>
		--physical-table-map <value>
		[--logical-table-map <value>]
		--import-mode <value>
		[--column-groups <value>
		[--field-folders <value>]
		[--row-level-permission-data-set <value>]
		[--column-level-permission-rules <value>]
		[--cli-input-json <value>]
		[--generate-cli-skeleton <value>]
				[--row-level-permission-tag-configuration 
	'{
		"Status": "ENABLED",
		"TagRules": 
			[
				{
					"TagKey": "tag_retailer_id",
					"ColumnName": "retailer_id",
					"TagMultiValueDelimiter": ",",
					"MatchAllValue": "*"
				},
				{
					"TagKey": "tag_role",
					"ColumnName": "role"
				}
			],
		"TagRuleConfigurations":
			[
				tag_retailer_id
			],
			[
				tag_role
			]
	}'
]
```

以下为响应定义的示例。

```
{
			"Status": 201,
			"Arn": "arn:aws:quicksight:us-west-2:11112222333:dataset/RLS-Dataset",
			"DataSetId": "RLS-Dataset",
			"RequestId": "aa4f3c00-b937-4175-859a-543f250f8bb2"
		}
```

------

**重要**  
在数据集上分配并启用标签后，请确保授予 Quick authors 权限，以便在创作仪表板时查看数据集中的任何数据。  
要授予 Quick 作者查看数据集中数据的权限，请创建权限文件或查询以用作数据集规则。有关更多信息，请参阅 [为行级别安全性创建数据集规则](restrict-access-to-a-data-set-using-row-level-security.md#create-data-set-rules-for-row-level-security)。

有关该`RowLevelPermissionTagConfiguration`元素的更多信息，请参阅 *Amazon Quick API 参考[RowLevelPermissionTagConfiguration](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_RowLevelPermissionTagConfiguration.html)*中的。

## 步骤 2：在运行时系统中为 RLS 标签分配值
<a name="quicksight-dev-rls-tags-assign-values"></a>

您只能将 RLS 标签用于匿名嵌入。您可以使用 `GenerateEmbedUrlForAnonymousUser` API 操作为标签设置值。

**重要**  
在 API 调用中配置会话标签时，  
将会话标签视为安全证书。不要向最终用户或客户端代码公开会话标签。
实现服务器端控制。确保会话标签完全由您可信的后端服务设置，而不是由最终用户可以修改的参数设置。
保护会话标签不被枚举。确保一个租户中的用户无法发现或猜测属于其他租户的 SessionTag 值。
查看您的架构。如果允许下游客户或合作伙伴直接调用 API，请评估这些用户是否可以为他们不应访问的租户指定 SessionTag 值。

以下示例演示了如何为上一步数据集中定义的 RLS 标签分配值。

```
POST /accounts/AwsAccountId/embed-url/anonymous-user
	HTTP/1.1
	Content-type: application/json
	{
		“AwsAccountId”: “string”,
		“SessionLifetimeInMinutes”: integer,
		“Namespace”: “string”, // The namespace to which the anonymous end user virtually belongs
		“SessionTags”:  // Optional: Can be used for row-level security
			[
				{
					“Key”: “tag_retailer_id”,
					“Value”: “West,Central,South”
				}
				{
					“Key”: “tag_role”,
					“Value”: “shift_manager”
				}
			],
		“AuthorizedResourceArns”:
			[
				“string”
			],
		“ExperienceConfiguration”:
			{
				“Dashboard”:
					{
						“InitialDashboardId”: “string”
						// This is the initial dashboard ID the customer wants the user to land on. This ID goes in the output URL.
					}
			}
	}
```

以下为响应定义的示例。

```
HTTP/1.1 Status
	Content-type: application/json

	{
	"EmbedUrl": "string",
	"RequestId": "string"
	}
```

只有 `GenerateEmbedUrlForAnonymousUser` API 操作才支持无需在 Quick 中注册用户的 RLS。在此操作中，您可以在 `SessionTags` 下定义与数据集列关联的标签的值。

本示例定义了以下分配：
+ 值 `West`、`Central` 和 `South` 在运行时系统中分配给 `tag_retailer_id` 标签。数据集中的 `TagMultipleValueDelimiter` 中定义的分隔符使用一个逗号。要在列中使用调用值，可以将值设置为 *\$1*，该值在创建标签时定义为 `MatchAllValue`。
+ 值 `shift_manager` 被分配给 `tag_role` 标签。

使用生成的 URL 的用户只能查看 `role` 列中包含 `shift_manager` 值的行。该用户只能查看 `retailer_id` 列中的值 `West`、`Central` 或 `South`。

有关使用 `GenerateEmbedUrlForAnonymousUser` API 操作为匿名用户嵌入控制面板的更多信息[为匿名（未注册）用户嵌入 Amazon Quick Sight 控制面板](embedded-analytics-dashboards-for-everyone.md)，请参阅或[GenerateEmbedUrlForAnonymousUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForAnonymousUser.html)在 *Amazon Quick API 参考*中