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

# 筛选实时建议


您可以使用 Amazon Personalize 控制台、 AWS Command Line Interface (AWS CLI) 或 AWS SDKs。

 当您获取个性化物品建议或类似物品时，可以在请求中指定促销活动。*推广* 使用筛选器来定义其他业务规则，这些规则适用于可配置的建议物品子集。有关更多信息，请参阅 [通过实时推荐推广物品](promoting-items.md)。

**Topics**
+ [

## 筛选实时建议（控制台）
](#filter-rt-console)
+ [

## 筛选实时建议 (AWS CLI)
](#filter-rt-cli)
+ [

## 筛选实时建议 (AWS SDKs)
](#filter-rt-sdk)

## 筛选实时建议（控制台）


要使用控制台筛选实时建议，请创建筛选器，然后将其应用于建议请求。

**注意**  
要使用带有参数的筛选器和您在 2020 年 11 月 10 日之前部署的市场活动来筛选建议，您必须使用 [UpdateCampaign](API_UpdateCampaign.md) 操作重新部署市场活动或创建新市场活动。

### 创建筛选器（控制台）


 要在控制台中创建筛选器，请选择包含要用于获取筛选建议的市场活动或推荐器的数据集组。然后，提供筛选器名称和筛选器表达式。

**创建筛选器（控制台）**

1. 在[https://console.aws.amazon.com/personalize/家](https://console.aws.amazon.com/personalize/home)中打开 Amazon Personalize 控制台并登录您的账户。

1. 选择包含要用于获取筛选建议的市场活动或推荐器的数据集组。

1. 在导航窗格中，选择**筛选条件**，然后选择**创建新筛选条件**。这时，将显示**创建筛选器**页面。  
![\[描绘了带有筛选条件名称和表达式字段的创建筛选条件页面。\]](http://docs.aws.amazon.com/zh_cn/personalize/latest/dg/images/create-filter-page.png)

1. 对于**筛选器名称**，输入筛选器的名称。当您将筛选器应用于建议请求时，您将按此名称选择筛选器。

1. 对于**表达式**，选择**构建表达式**或**手动添加表达式**，然后构建或插入表达式：
   + 要使用表达式生成器，请选择**构建表达式**。表达式生成器提供结构、字段和指南，用于构建格式正确的筛选器表达式。有关更多信息，请参阅 [使用筛选器表达式生成器](#using-filter-expression-builder)。
   +  要输入您自己的表达式，请选择**手动添加表达式**。有关更多信息，请参阅 [筛选器表达式元素](creating-filter-expressions.md#filter-expression-elements)。

1. 选择**结束**。筛选器的概述页面显示筛选器的 Amazon 资源名称 (ARN)、状态和完整的筛选器表达式。要删除筛选器，请选择**删除**。有关在离开概述页面后查找和删除筛选器的信息，请参阅[删除筛选器（控制台）](#delete-filter-console)。  
![\[描绘了带有筛选条件的 ARN 和表达式的筛选条件详细信息页面。\]](http://docs.aws.amazon.com/zh_cn/personalize/latest/dg/images/filter-details-page.png)

### 应用筛选器（控制台）


 要应用筛选条件，请在**测试推荐器**（针对推荐器）或**测试市场活动结果**（针对自定义市场活动）中，选择筛选条件并输入任何筛选条件参数值。然后，获取针对用户的建议。

**重要**  
对于使用 `INCLUDE` 元素的筛选条件表达式，您必须为表达式中定义的所有参数提供值。对于带有使用 `EXCLUDE` 元素的表达式的筛选条件，您可以省略 `filter-values`。在本例中，Amazon Personalize 未使用表达式的这一部分来筛选建议。

**应用筛选器（控制台）**

1. 在[https://console.aws.amazon.com/personalize/家](https://console.aws.amazon.com/personalize/home)中打开 Amazon Personalize 控制台并登录您的账户。

1. 选择包含要用于获取筛选建议的市场活动或推荐器的数据集组。

1. 根据数据集组类型或资源类型，执行以下任一操作：

   1. 对于域数据集组，在导航窗格中选择**推荐器**。

   1. 对于自定义数据集组或自定义资源，在导航窗格中选择**自定义资源**，然后选择**市场活动**。

1. 在**推荐器或市场活动******页面上，选择目标推荐器或市场活动。

1. 为了进行比较，请先在不应用筛选条件的情况下获取建议。在**测试推荐器**/**测试市场活动结果**下，输入您要获取其建议的用户的 ID 或相关物品的物品 ID，然后选择**获取建议**。此时将显示一个包含前几项建议的表。  
![\[描绘了未应用筛选条件的推荐结果。\]](http://docs.aws.amazon.com/zh_cn/personalize/latest/dg/images/Recommendations_no-filter.PNG)

1. 从**筛选器名称**菜单中，选择您创建的筛选器。如果您的筛选器有任何占位符参数，则会显示每个参数的关联字段。

1. 如果您使用的筛选器带有占位符参数，请为每个参数输入值以设置筛选条件。要为一个参数使用多个值，请用英文逗号分隔每个值。

1. 使用与上一步相同的 `User ID` 或 `Item ID`，选择**获取建议**。此时将显示建议表。  
![\[描绘了已应用筛选条件的推荐结果。\]](http://docs.aws.amazon.com/zh_cn/personalize/latest/dg/images/Recommendations_filter.png)

   例如，如果用户已经购买了建议的物品，筛选条件会将其从建议列表中删除。在本示例中，物品 2657、2985 被用户未购买的最合适的物品（物品 2641 和 1573）所取代。

### 使用筛选器表达式生成器


**创建筛选条件**页面上的**表达式生成器**提供结构、字段和指南，用于构建格式正确的筛选条件。

![\[描绘了创建筛选条件页面上表达式生成器的字段。\]](http://docs.aws.amazon.com/zh_cn/personalize/latest/dg/images/expression-builder-empty.png)


构建筛选器表达式：
+ 使用**类型**、**操作**、**属性**、**运算符**和**值**字段创建表达式。

  对于**值**，输入固定值，或者要在获得建议时设置筛选条件，请输入 *\$1* \$1 参数名称。例如 `$GENRES`。获得建议时，您将提供一个或多个要筛选的值。在此示例中，将在获取建议时提供一个类型或类型列表。

  用英文逗号分隔多个非参数值。不能向筛选器中添加以逗号分隔的参数。
**注意**  
选择**属性**（`dataset.field` 格式）后，由 `AND` 或 `OR` 条件链接的任何后续行的**属性**值都必须使用相同的 `dataset`。
+  使用 **\$1** 和 **X** 按钮，在表达式中添加或删除一行。您无法删除第一行。
+  对于新行，使用 **AND** 菜单上的 `AND`、`IF` 或 `OR` 运算符来创建条件链。

  对于 `IF` 条件：
  + 每个表达式只能包含一个 `IF` 项。如果删除 IF 条件，则表达式生成器会删除其后的所有 `AND` 条件。
  + 只能对按 `CurrentUser` 筛选的表达式使用 `IF` 条件。
+  选择**添加表达式**按钮，以添加其它筛选条件表达式来进行更精确的筛选。首先对每个表达式进行独立评估，产生的结果是两个结果的并集。
**注意**  
要创建同时使用物品数据集和交互数据集（或操作数据集和操作交互数据集）的筛选条件，*必须*使用多个表达式。

#### 表达式生成器示例


以下示例说明如何构建筛选器，以排除含有在获得建议时指定的类型的物品（注意 \$1GENRES 占位符参数）。该筛选器还会排除 `DOWNLOAD_COUNT` 超过 `200` 的物品，但前提是当前用户的年龄超过 `17`。

![\[演示如何使用表达式生成器来生成示例筛选条件表达式。\]](http://docs.aws.amazon.com/zh_cn/personalize/latest/dg/images/create-filter-expression-builder.png)


### 删除筛选器（控制台）


删除筛选器会将筛选器从数据集组的筛选器列表中移除。

**重要**  
批量推理作业正在进行时，您无法删除筛选器。

**删除筛选器（控制台）**

1. 在[https://console.aws.amazon.com/personalize/家](https://console.aws.amazon.com/personalize/home)中打开 Amazon Personalize 控制台并登录您的账户。

1. 从**数据集组**列表中，选择包含要删除的筛选器的数据集组。

1. 在导航窗格中，选择**筛选器**。

1. 从筛选器列表中，选择要删除的筛选器，然后选择**查看详细信息**。此时会显示筛选器详细信息页面。

1. 选择**删除**，并在确认对话框中确认删除。

## 筛选实时建议 (AWS CLI)


要使用筛选推荐 AWS CLI，您可以创建一个筛选条件，然后通过在[GetRecommendations](API_RS_GetRecommendations.md)或[GetPersonalizedRanking](API_RS_GetPersonalizedRanking.md)请求中指定筛选条件 ARN 来应用该过滤器 ARN。

**重要**  
要使用带有参数的筛选器和您在 2020 年 11 月 10 日之前部署的市场活动来筛选建议，您必须使用 [UpdateCampaign](API_UpdateCampaign.md) 调用重新部署市场活动或创建新市场活动。

### 创建筛选器 (AWS CLI)


使用以下 `create-filter` 操作创建筛选器并指定筛选器表达式。

将 `Filter name` 替换为筛选器的名称，将 `Dataset group ARN` 替换为数据集组的 Amazon 资源名称 (ARN)。将示例 `filter-expression` 替换为您自己的筛选器表达式。

```
aws personalize create-filter \
  --name Filter name \
  --dataset-group-arn dataset group arn \
  --filter-expression "EXCLUDE ItemID WHERE Items.CATEGORY IN (\"$CATEGORY\")"
```

 如果成功，将显示筛选器 ARN。记下该 ARN 供将来使用。要验证筛选器是否处于活动状态，请在使用筛选器之前使用 [DescribeFilter](API_DescribeFilter.md) 操作。

 有关 API 的更多信息，请参阅 [CreateFilter](API_CreateFilter.md)。有关筛选器表达式的更多信息（包括示例），请参阅[筛选条件表达式结构和元素](creating-filter-expressions.md)。

### 应用筛选器 (AWS CLI)


使用 `get-recommendations`、`get-action-recommendations` 或 `get-personalized-ranking` 操作时，您通过将 `filter-arn` 和任何筛选条件值作为参数传递，应用筛选条件。

以下是 `get-recommendations` 操作的示例。将 `Campaign ARN` 替换为市场活动的 Amazon 资源名称 (ARN)，将 `User ID` 替换为要获得建议的用户的 ID，将 `Filter ARN` 替换为筛选器的 ARN。如果您从推荐器（而不是市场活动）获得建议，请使用 `recommender-arn`（而不是 `--campaign-arn`），并提供推荐器的 ARN。

如果您的表达式含有任何参数，请包含 `filter-values` 对象。对于筛选器表达式中的每个参数，提供参数名称（区分大小写）和值。例如，如果您的筛选器表达式具有 `$GENRE` 参数，请提供 *"GENRE"* 作为键，并提供一个或多个类型（例如 `"Comedy"`）作为值。用英文逗号分隔多个值。例如 `"\"comedy\",\"drama\",\"horror"\"`。

**重要**  
对于使用 `INCLUDE` 元素来包含物品的筛选器表达式，您必须为表达式中定义的所有参数提供值。对于带有使用 `EXCLUDE` 元素排除物品的表达式的筛选器，您可以省略 `filter-values`。在本例中，Amazon Personalize 未使用表达式的这一部分来筛选建议。

```
aws personalize-runtime get-recommendations \
  --campaign-arn Campaign ARN \
  --user-id User ID \
  --filter-arn Filter ARN \
  --filter-values '{
      "Parameter name": "\"value\"",
      "Parameter name": "\"value1\",\"value2\",\"value3\""
    }'
```

### 删除筛选器 (AWS CLI)


 要删除筛选器，请使用以下 `delete-filter` 操作。将 `filter ARN` 替换为筛选器的 ARN。

```
aws personalize delete-filter --filter-arn Filter ARN
```

## 筛选实时建议 (AWS SDKs)


要使用筛选推荐 AWS SDKs，您可以创建一个筛选条件，然后通过在[GetRecommendations](API_RS_GetRecommendations.md)或[GetPersonalizedRanking](API_RS_GetPersonalizedRanking.md)请求中指定筛选条件 ARN 来应用该过滤器 ARN。

**重要**  
要使用带有参数的筛选器和您在 2020 年 11 月 10 日之前部署的市场活动来筛选建议，您必须使用 [UpdateCampaign](API_UpdateCampaign.md) 调用重新部署市场活动或创建新市场活动。

### 创建筛选器 (AWS SDKs)


 使用 [CreateFilter](API_CreateFilter.md) 操作创建新筛选器。以下代码展示了如何创建筛选器。指定筛选器名称、数据集组的 Amazon 资源名称 (ARN)，并提供筛选器表达式。

------
#### [ SDK for Python (Boto3) ]

```
import boto3
 
personalize = boto3.client('personalize')
 
response = personalize.create_filter(
    name = 'Filter Name',
    datasetGroupArn = 'Dataset Group ARN',
    filterExpression = 'EXCLUDE ItemID WHERE Items.CATEGORY IN ($CATEGORY)'
) 
filter_arn = response["filterArn"]
print("Filter ARN: " + filter_arn)
```

------
#### [ SDK for Java 2.x ]

```
public static String createFilter(PersonalizeClient personalizeClient,
                                 String filterName,
                                 String datasetGroupArn,
                                 String filterExpression) {
    try {
        CreateFilterRequest request = CreateFilterRequest.builder()
                .name(filterName)
                .datasetGroupArn(datasetGroupArn)
                .filterExpression(filterExpression)
                .build();

        return personalizeClient.createFilter(request).filterArn();
    }
    catch(PersonalizeException e) {
        System.err.println(e.awsErrorDetails().errorMessage());
        System.exit(1);
    }
    return "";
}
```

------
#### [ SDK for JavaScript v3 ]

```
// Get service clients module and commands using ES6 syntax.
import { CreateFilterCommand } from "@aws-sdk/client-personalize";
import { personalizeClient } from "./libs/personalizeClients.js";
// Or, create the client here.
// const personalizeClient = new PersonalizeClient({ region: "REGION"});

// Set the filter's parameters.
export const createFilterParam = {
  datasetGroupArn: "DATASET_GROUP_ARN" /* required */,
  name: "NAME" /* required */,
  filterExpression: "FILTER_EXPRESSION" /*required */,
};

export const run = async () => {
  try {
    const response = await personalizeClient.send(
      new CreateFilterCommand(createFilterParam),
    );
    console.log("Success", response);
    return response; // For unit tests.
  } catch (err) {
    console.log("Error", err);
  }
};
run();
```

------

记录筛选器 ARN 以备后用。要验证筛选器是否处于活动状态，请在使用筛选器之前使用 [DescribeFilter](API_DescribeFilter.md) 操作。有关 API 的更多信息，请参阅 [CreateFilter](API_CreateFilter.md)。有关筛选器表达式的更多信息（包括示例），请参阅[筛选条件表达式结构和元素](creating-filter-expressions.md)。

### 应用筛选器 (AWS SDKs)


使用 GetRecommendations、或 GetPersonalizedRanking 操作时 GetActionRecommendations，通过传递 a `filterArn` 和任意筛选值作为参数来应用过滤器。

以下代码展示了如何为用户获取经过筛选的 Amazon Personalize 物品建议。指定要获取建议的用户的 ID、市场活动的 Amazon 资源名称 (ARN)，以及筛选器的 ARN。如果您从推荐器（而不是市场活动）获得建议，请使用 `recommenderArn`（而不是 `campaignArn`），并提供推荐器的 ARN。

对于 `filterValues`，对于筛选器表达式中的每个可选参数，提供参数名称（区分大小写）和一个或多个值。例如，如果您的筛选器表达式具有 `$GENRES` 参数，请提供 *"GENRES"* 作为键，并提供一个或多个类型（例如 `"\"Comedy"\"`）作为值。对于多个值，用英文逗号分隔每个值。例如 `"\"comedy\",\"drama\",\"horror\""`。

**重要**  
对于使用 `INCLUDE` 元素来包含物品的筛选器表达式，您必须为表达式中定义的所有参数提供值。对于带有使用 `EXCLUDE` 元素排除物品的表达式的筛选器，您可以省略 `filter-values`。在本例中，Amazon Personalize 未使用表达式的这一部分来筛选建议。

------
#### [ SDK for Python (Boto3) ]

```
import boto3

personalize_runtime = boto3.client("personalize-runtime")

response = personalize_runtime.get_recommendations(
    campaignArn = "Campaign ARN",
    userId = "User ID",
    filterArn = "Filter ARN",
    filterValues = {
      "Parameter name": "\"value1\"",
      "Parameter name": "\"value1\",\"value2\",\"value3\""
      ....
    }
)
```

------
#### [ SDK for Java 2.x ]

以下示例使用两个参数，一个参数具有两个值，另一个参数具有一个值。根据您的筛选器表达式，修改代码以添加或移除 parameterName 和 parameterValue 字段。

```
public static void getFilteredRecs(PersonalizeRuntimeClient personalizeRuntimeClient,
                                   String campaignArn,
                                   String userId,
                                   String filterArn,
                                   String parameter1Name,
                                   String parameter1Value1,
                                   String parameter1Value2,
                                   String parameter2Name,
                                   String parameter2Value){

    try {

        Map<String, String> filterValues = new HashMap<>();

        filterValues.put(parameter1Name, String.format("\"%1$s\",\"%2$s\"",
                parameter1Value1, parameter1Value2));
        filterValues.put(parameter2Name, String.format("\"%1$s\"",
                parameter2Value));

        GetRecommendationsRequest recommendationsRequest = GetRecommendationsRequest.builder()
                .campaignArn(campaignArn)
                .numResults(20)
                .userId(userId)
                .filterArn(filterArn)
                .filterValues(filterValues)
                .build();

        GetRecommendationsResponse recommendationsResponse = personalizeRuntimeClient.getRecommendations(recommendationsRequest);
        List<PredictedItem> items = recommendationsResponse.itemList();

        for (PredictedItem item: items) {
            System.out.println("Item Id is : "+item.itemId());
            System.out.println("Item score is : "+item.score());
        }
    } catch (PersonalizeRuntimeException e) {
        System.err.println(e.awsErrorDetails().errorMessage());
        System.exit(1);
    }
}
```

------
#### [ SDK for JavaScript v3 ]

```
// Get service clients module and commands using ES6 syntax.
import { GetRecommendationsCommand } from "@aws-sdk/client-personalize-runtime";
import { personalizeRuntimeClient } from "./libs/personalizeClients.js";
// Or, create the client here:
// const personalizeRuntimeClient = new PersonalizeRuntimeClient({ region: "REGION"});

// Set recommendation request parameters.
export const getRecommendationsParam = {
  campaignArn: "CAMPAIGN_ARN" /* required */,
  userId: "USER_ID" /* required */,
  numResults: 15 /* optional */,
  filterArn: "FILTER_ARN" /* required to filter recommendations */,
  filterValues: {
    PROPERTY:
      '"VALUE"' /* Only required if your filter has a placeholder parameter */,
  },
};

export const run = async () => {
  try {
    const response = await personalizeRuntimeClient.send(
      new GetRecommendationsCommand(getRecommendationsParam),
    );
    console.log("Success!", response);
    return response; // For unit tests.
  } catch (err) {
    console.log("Error", err);
  }
};
run();
```

------

### 删除过滤器（AWS Python 开发工具包）


 要删除筛选器，请使用以下 `delete_filter` 方法。将 `filter ARN` 替换为筛选器的 ARN。

```
import boto3
personalize = boto3.client("personalize")

response = personalize.delete_filter(
  filterArn = "filter ARN"
)
```