本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 篩選即時建議
您可以使用 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/home](https://console.aws.amazon.com/personalize/home)：// 開啟 Amazon Personalize 主控台並登入您的帳戶。
1. 選擇資料集群組，其中包含您想要用來取得篩選建議的行銷活動或建議者。
1. 在導覽窗格中，選擇**篩選條件**，然後選擇**建立新篩選條件**。隨即顯示**建立篩選條件**頁面。
![\[顯示具有篩選條件名稱和表達式欄位的建立篩選條件頁面。\]](http://docs.aws.amazon.com/zh_tw/personalize/latest/dg/images/create-filter-page.png)
1. 針對**篩選條件名稱**，輸入篩選條件的名稱。將篩選條件套用至建議請求時，您將依此名稱選擇篩選條件。
1. 針對**表達式**，選擇**建置表達式**或**手動新增表達式**，然後建置或插入您的表達式：
+ 若要使用表達式建置器，請選擇**建置表達**式。表達式建置器提供結構、欄位和準則，用於建置正確格式的篩選條件表達式。如需詳細資訊，請參閱[使用篩選條件表達式建置器](#using-filter-expression-builder)。
+ 若要輸入您自己的表達式，請選擇**手動新增表達式**。如需詳細資訊，請參閱[篩選條件表達式元素](creating-filter-expressions.md#filter-expression-elements)。
1. 選擇**完成**。篩選條件的概觀頁面會顯示篩選條件的 Amazon Resource Name (ARN)、狀態和完整篩選條件表達式。若要刪除篩選條件，請選擇**刪除**。如需有關在離開概觀頁面後尋找和刪除篩選條件的資訊，請參閱 [刪除篩選條件 （主控台）](#delete-filter-console)。
![\[使用篩選條件的 ARN 和表達式來描述篩選條件詳細資訊頁面。\]](http://docs.aws.amazon.com/zh_tw/personalize/latest/dg/images/filter-details-page.png)
### 套用篩選條件 （主控台）
若要套用篩選條件，請在**測試推薦者** （適用於推薦者） 或**測試行銷活動結果** （適用於自訂行銷活動） 中選擇篩選條件，然後輸入任何篩選條件參數值。然後取得使用者的建議。
**重要**
對於使用 `INCLUDE`元素的篩選條件表達式，您必須為表達式中定義的所有參數提供值。對於具有使用 `EXCLUDE`元素之表達式的篩選條件，您可以省略 `filter-values`。在此情況下，Amazon Personalize 不會使用表達式的該部分來篩選建議。
**套用篩選條件 （主控台）**
1. 在 [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home)：// 開啟 Amazon Personalize 主控台並登入您的帳戶。
1. 選擇資料集群組，其中包含您想要用來取得篩選建議的行銷活動或建議者。
1. 根據您的資料集群組類型或資源類型，執行下列其中一項操作：
1. 對於網域資料集群組，在導覽窗格中選擇**建議者**。
1. 對於自訂資料集群組或自訂資源，在導覽窗格中選擇**自訂資源**，然後選擇**行銷活動**。
1. 在**建議者**或**行銷活動**頁面上，選擇目標建議者或行銷活動。
1. 為了進行比較，請先取得建議，而不套用篩選條件。在**測試建議者**/**測試行銷活動結果**下，輸入您要取得建議的使用者 ID，或相關項目的項目 ID，然後選擇**取得建議**。包含最佳建議的資料表隨即出現。
![\[描述不套用篩選條件的建議結果。\]](http://docs.aws.amazon.com/zh_tw/personalize/latest/dg/images/Recommendations_no-filter.PNG)
1. 從**篩選條件名稱**功能表中，選擇您建立的篩選條件。如果您的篩選條件有任何預留位置參數，則會顯示每個參數的關聯欄位。
1. 如果您使用具有預留位置參數的篩選條件，請針對每個參數輸入值來設定篩選條件。若要對一個參數使用多個值，請以逗號分隔每個值。
1. 使用`Item ID`與先前步驟相同的 `User ID`或 ，選擇**取得建議**。系統會顯示建議表格。
![\[顯示套用篩選條件的建議結果。\]](http://docs.aws.amazon.com/zh_tw/personalize/latest/dg/images/Recommendations_filter.png)
例如，如果使用者已購買建議項目，篩選條件會從建議清單中將其移除。在此範例中，項目 2657、2985 已由使用者未購買的最合適項目取代 （項目 2641 和 1573)。
### 使用篩選條件表達式建置器
**建立篩選條件**頁面上的**表達式建置器**提供結構、欄位和準則，用於建置正確格式的篩選條件。
![\[顯示建立篩選條件頁面上表達式建置器的欄位。\]](http://docs.aws.amazon.com/zh_tw/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`條件。
+ 您只能將`IF`條件用於依 篩選的表達式`CurrentUser`。
+ 選擇**新增表達**式按鈕，以新增額外的篩選條件表達式，進行更精確的篩選。每個表達式都會先獨立評估，結果是兩個結果的聯集。
**注意**
若要建立同時使用項目和項目互動資料集或動作和動作互動資料集的篩選條件，*您必須*使用多個表達式。
#### 表達式建置器範例
下列範例示範如何建置篩選條件，以排除您在取得建議時指定的類型項目 （請注意 \$1GENRES 預留位置參數）。篩選條件也會排除 `DOWNLOAD_COUNT`大於 的項目`200`，但僅限於目前使用者的存留期大於 時`17`。
![\[示範如何使用表達式建置器來建置範例篩選條件表達式。\]](http://docs.aws.amazon.com/zh_tw/personalize/latest/dg/images/create-filter-expression-builder.png)
### 刪除篩選條件 （主控台）
刪除篩選條件會從資料集群組的篩選條件清單中移除篩選條件。
**重要**
當批次推論任務正在進行時，您無法刪除篩選條件。
**刪除篩選條件 （主控台）**
1. 在 [https://console.aws.amazon.com/personalize/home](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 來套用該篩選條件。
**重要**
若要使用篩選條件搭配參數和您在 2020 年 11 月 10 日之前部署的行銷活動來篩選建議，您必須使用 [UpdateCampaign](API_UpdateCampaign.md)呼叫重新部署行銷活動，或建立新的行銷活動。
### 建立篩選條件 (AWS CLI)
使用下列`create-filter`操作來建立篩選條件並指定篩選條件表達式。
`Filter name` 將 取代為篩選條件的名稱，將 `Dataset group ARN`取代為資料集群組的 Amazon Resource Name (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。記錄以供日後使用。若要驗證篩選條件是否作用中，請在使用篩選條件之前使用 [DescribeFilter](API_DescribeFilter.md)操作。
如需 API (匯入 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 Resource Name (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 來套用該篩選條件。
**重要**
若要使用篩選條件搭配參數和您在 2020 年 11 月 10 日之前部署的行銷活動來篩選建議，您必須使用 [UpdateCampaign](API_UpdateCampaign.md)呼叫重新部署行銷活動，或建立新的行銷活動。
### 建立篩選條件AWS SDKs)
使用 [CreateFilter](API_CreateFilter.md)操作建立新的篩選條件。下列程式碼說明如何建立篩選條件。指定資料集群組的篩選名稱、Amazon Resource Name (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 (匯入 API) 的詳細資訊，請參閱「[CreateFilter](API_CreateFilter.md)」。如需篩選條件表達式的詳細資訊，包括範例，請參閱 [篩選表達式結構和元素](creating-filter-expressions.md)。
### 套用篩選條件 (AWS SDKs)
當您使用 GetRecommendations、GetActionRecommendations 或 GetPersonalizedRanking 操作時，請傳遞 `filterArn`和任何篩選條件值做為參數來套用篩選條件。
下列程式碼說明如何取得使用者的篩選 Amazon Personalize 項目建議。指定您要取得建議的使用者 ID、行銷活動的 Amazon Resource Name (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 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 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 SDK)
使用下列`delete_filter`方法刪除篩選條件。將 `filter ARN`取代為篩選條件的 ARN。
```
import boto3
personalize = boto3.client("personalize")
response = personalize.delete_filter(
filterArn = "filter ARN"
)
```