本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在即時建議中提升項目
透過所有網域使用案例和一些自訂配方，您可以在取得即時建議時指定提升。
*提升*定義適用於建議項目可設定子集的其他業務規則。例如，您可能有一個串流應用程式，並想要提升自己的節目和電影，但也建議相關的標題。您可以使用提升來指定建議項目的特定百分比必須來自*內部*類別。剩餘的建議項目會繼續根據您的配方和任何請求篩選條件提供相關建議。
若要套用提升，請在建議請求中指定下列項目：
+ 套用提升篩選條件的建議項目百分比。
+ 指定提升條件的篩選條件。如需詳細資訊，請參閱[提升篩選條件](#promotion-filters)。
在建議回應中，提升的項目會相對於其他建議項目隨機放置，但會依相對於其他提升項目的排序。根據您的配方，不屬於提升一部分的建議項目會依與使用者、熱門度或類似度的相關性排序。如果沒有足夠的項目符合提升條件，結果將包含盡可能多的提升項目。
您可以使用 Amazon Personalize 主控台、 AWS Command Line Interface (AWS CLI) 或 AWS SDKs將提升套用至建議。
**Topics**
+ [支援促銷的使用案例和配方](#promotion-use-case-recipes)
+ [提升篩選條件](#promotion-filters)
+ [提升新項目](#promoting-new-items)
+ [提升項目 （主控台）](#promoting-items-console)
+ [提升項目 (AWS CLI)](#promoting-items-cli)
+ [提升項目AWS SDKs)](#promoting-items-sdk)
## 支援促銷的使用案例和配方
所有使用案例都支援促銷。下列自訂配方支援促銷：
+ [User-Personalization-v2](native-recipe-user-personalization-v2.md) 和 [使用者個人化](native-recipe-new-item-USER_PERSONALIZATION.md)配方
+ [類似項目](native-recipe-similar-items.md) 和 [SIMS](native-recipe-sims.md)配方
+ [Trending-Now](native-recipe-trending-now.md) 和 [熱門計數](native-recipe-popularity.md)配方
## 提升篩選條件
當您將提升套用至建議請求時，您可以選擇指定提升條件的篩選條件。您可以使用現有的篩選條件或建立新的篩選條件。您可以像在 Amazon Personalize 中其他篩選條件一樣，建立和管理促銷的篩選條件。如需建立和管理篩選條件的資訊，請參閱 [篩選結果](filter.md)。
提升篩選條件與您在提升外選擇的篩選條件 (*請求篩選條件*) 之間的唯一差異在於 Amazon Personalize 如何套用它們。提升篩選條件僅適用於提升的項目，而請求篩選條件僅適用於剩餘的建議項目。如果您指定請求篩選條件和提升篩選條件，並想要將兩個篩選條件套用至提升的項目，則提升篩選條件的表達式必須包含兩個表達式。合併兩個表達式的方式取決於您使用的資料集。如需篩選條件表達式、規則以及如何建立它們的詳細資訊，請參閱 [篩選條件表達式](filter-expressions.md)。
**篩選條件表達式範例**
下列表達式僅包含來自「內部」類別的項目。如果您想要在建議中提升自己的內容，則可以使用此表達式。
```
INCLUDE ItemID WHERE Items.OWNER IN ("in-house")
```
下列表達式僅包含比您指定的時間戳記更近期建立的項目。您可以使用此表達式在建議中提升新項目。
```
INCLUDE ItemID WHERE Items.CREATION_TIMESTAMP > $DATE
```
下列表達式顯示如何將請求篩選條件套用至提升的項目。它只包含可用的衣物項目做為提升項目。在此案例中， `Items.AVAILABLE IN ("True")`也會用於請求篩選條件表達式，因此所有建議都適用於可用的項目。
```
INCLUDE ItemID WHERE Items.CATEGORY IN ("clothing") AND Items.AVAILABLE IN ("True")
```
如需篩選範例的更完整清單，請參閱 [篩選條件表達式範例](filter-expression-examples.md)。
## 提升新項目
如果您使用 [User-Personalization-v2 配方](native-recipe-user-personalization-v2.md)，Amazon Personalize 會建議最相關的項目給使用者，並更頻繁地建議具有互動資料的現有項目。為了確保建議包含一些新項目，您可以套用提升到建議請求，其中包含根據建立時間戳記的項目。
如果您尚未使用提升，您的篩選條件表達式可以提升在特定日期之後建立的項目：
```
INCLUDE ItemID WHERE Items.CREATION_TIMESTAMP > $DATE
```
如果您已使用提升，您可以建立同時鏈結提升和新項目條件陳述式的表達式：
```
INCLUDE ItemID WHERE Items.CATEGORY IN ("clothing") OR Items.CREATION_TIMESTAMP > $DATE
```
## 提升項目 （主控台）
若要使用 Amazon Personalize 主控台提升建議中的特定項目，請建立篩選條件，然後在建議請求中提供提升詳細資訊。如需其他欄位的資訊，請參閱 [取得項目建議 （主控台）](getting-real-time-item-recommendations.md#get-real-time-recommendations-console)。
**在建議中提升項目**
1. 在 [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home)：// 開啟 Amazon Personalize 主控台並登入您的帳戶。
1. 選擇包含您正在使用的行銷活動或建議程式的資料集群組。
1. 如果您尚未建立篩選條件，請建立指定提升條件的篩選條件。您建立提升篩選條件的方式與建立請求篩選條件的方式相同。如需建立和管理篩選條件的資訊，請參閱 [篩選結果](filter.md)。
1. 在導覽窗格中，選擇**建議者**或**行銷活動**。
1. 選擇目標行銷活動或推薦者。
1. 對於行銷活動，在**測試行銷活動結果**下，根據您使用的配方輸入您的建議請求詳細資訊。對於建議者，請選擇**測試建議者**，然後輸入您的建議請求詳細資訊。
1. 選擇性地選擇請求的篩選條件。此篩選條件僅適用於非提升的項目。如需建立和管理篩選條件的資訊，請參閱 [篩選結果](filter.md)。
1. 如果您使用內容中繼資料，請提供每個內容的資料。針對每個內容，針對**金鑰**輸入中繼資料欄位。針對**值**，輸入內容資料。如需詳細資訊，請參閱[提高與內容中繼資料的建議相關性](contextual-metadata.md)。
1. 針對**提升**，請指定下列項目：
+ **提升項目百分比**：輸入要套用提升的建議項目百分比。
+ **篩選條件**：選擇指定提升條件的篩選條件。此篩選條件適用於提升的項目，而不是您在步驟 7 中指定的任何請求篩選條件。
+ **篩選條件參數**：如果您的提升使用具有預留位置參數的篩選條件，請針對每個參數輸入值來設定篩選條件。若要對一個參數使用多個值，請以逗號分隔每個值。
1. 選擇 **Get recommendations (取得建議)**。顯示包含使用者前 25 個建議項目的資料表。升級**項目**欄指出該項目是否因為您的提升而包含在內。提升項目會相對於其他建議項目隨機放置，但會相對於其他提升項目按排序排列。根據您的使用案例或配方，不屬於提升一部分的建議項目會依與使用者、熱門度或類似度的相關性排序。如果沒有足夠的項目符合提升條件，結果將包含盡可能多的提升項目。
## 提升項目 (AWS CLI)
下列程式碼說明如何使用 AWS CLI 和自訂行銷活動提升建議中的項目。若要使用建議程式提升項目，請以 取代 `campaign-arn` 參數，`recommender-arn`並指定建議程式的 Amazon Resource Name (ARN)。針對提升欄位，指定下列項目：
+ 名稱：為提升命名。建議回應使用 名稱來識別提升的項目。
+ percent-promoted-items：要套用提升的建議項目百分比。在此範例中，將提升 50% 的項目。
+ filterArn：指定定義提升條件之篩選條件的 Amazon Resource Name (ARN)。如需詳細資訊，請參閱[提升篩選條件](#promotion-filters)。
+ 參數名稱和值：如果您的篩選條件表達式有任何參數，請提供參數名稱 （區分大小寫） 和值。例如，如果您的篩選條件表達式有 `$GENRE` 參數，請提供 GENRE 做為索引鍵，並提供類型或類型，例如 *Comedy* 做為值。使用逗號分隔多個值。當您使用 時 AWS CLI，對於每個值，您必須使用 `/` 字元來逸出引號和`/`字元。下列程式碼範例示範如何格式化值。
此程式碼說明如何同時使用請求篩選條件和提升篩選條件。提升篩選條件僅適用於提升的項目，而請求篩選條件僅適用於剩餘的建議項目。如需詳細資訊，請參閱[提升篩選條件](#promotion-filters)。
如需其他欄位的資訊，請參閱 [取得項目建議AWS SDKs)](getting-real-time-item-recommendations.md#get-item-rec-sdk)和 [使用內容中繼資料取得個人化排名](get-personalized-rankings-sdk.md#personalized-ranking-contextual-metadata-example)。
```
aws personalize-runtime get-recommendations \
--campaign-arn {{CampaignArn}} \
--user-id {{1}} \
--num-results {{10}} \
--filter-arn {{RequestFilterArn}} \
--filter-values '{
"{{RequestFilterParameterName}}": "\"{{value}}\"",
"{{RequestFilterParameterName}}": "\"{{value1}}\",\"{{value2}}\",\"{{value3}}\""
}' \
--promotions "[{
\"name\": \"{{promotionName}}\",
\"percentPromotedItems\": {{50}},
\"filterArn\": \"{{PromotionFilterARN}}\",
\"filterValues\": {\"{{PromotionParameterName}}\":\"\\\"{{value1}}, {{value2}}\\\"\"}
}]"
```
建議項目清單隨即顯示。提升項目會相對於其他建議項目隨機放置，但會相對於其他提升項目按排序排列。根據您的配方，不屬於提升一部分的建議項目會依與使用者、熱門度或類似度的相關性排序。如果沒有足夠的項目符合提升條件，結果將包含盡可能多的提升項目。
```
{
"itemList": [
{
"itemId1": "123",
"score": .0117211,
"promotionName": "promotionName"
},
{
"itemId2": "456",
"score": .0077976
},
{
"itemId3": "789",
"score": .0067171
},
.....
]
```
## 提升項目AWS SDKs)
下列程式碼說明如何使用適用於 Python 的 SDK (Boto3) 和適用於 Java 的 SDK 2.x 和自訂行銷活動提升建議中的項目。若要使用建議程式提升項目，請將 `campaignArn` 參數取代為 ，`recommenderArn`並指定建議程式的 Amazon Resource Name (ARN)。針對提升欄位，指定下列項目：
+ name：指定提升的名稱。建議回應包含識別提升項目的名稱。
+ percentPromotedItems：要套用提升的建議項目百分比。
+ promotionFilterARN：定義提升條件之篩選條件的 Amazon Resource Name (ARN)。如需詳細資訊，請參閱[提升篩選條件](#promotion-filters)。
+ 任何參數名稱和值：如果您的篩選條件表達式有任何參數，請為篩選條件表達式中的每個參數提供參數名稱 （區分大小寫） 和值。例如，如果您的篩選條件表達式有 `$GENRE` 參數，請提供 `"GENRE"`做為索引鍵，以及類型或類型，例如 "\\"Comedy"\\" 做為值。使用逗號分隔多個值。例如 `"\"comedy\",\"drama\",\"horror"\"`。
下列程式碼示範如何使用請求篩選條件和提升篩選條件。提升篩選條件僅適用於提升的項目，而請求篩選條件僅適用於剩餘的建議項目。如需詳細資訊，請參閱[提升篩選條件](#promotion-filters)。
如需其他欄位的資訊，請參閱 [取得項目建議AWS SDKs)](getting-real-time-item-recommendations.md#get-item-rec-sdk)和 [使用內容中繼資料取得個人化排名](get-personalized-rankings-sdk.md#personalized-ranking-contextual-metadata-example)。
------
#### [ SDK for Python (Boto3) ]
```
import boto3
personalizeRt = boto3.client('personalize-runtime')
response = personalizeRt.get_recommendations(
campaignArn = "{{CampaignARN}}",
userId = '{{1}}',
numResults = {{10}},
filterArn = '{{RequestFilterARN}}',
filterValues = {
"{{RequestFilterParameterName}}": "\"value1\"",
"{{RequestFilterParameterName}}": "\"value1\",\"value2\",\"value3\""
....
},
promotions = [{
"name" : "{{promotionName}}",
"percentPromotedItems" : {{50}},
"filterArn": "{{promotionFilterARN}}",
"filterValues": {
"{{PromotionParameterName}}": "\"{{Value1}}\",\"{{Value2}}\""
...
}
}]
)
print("Recommended items")
for item in response['itemList']:
print (item['itemId'])
if ("promotionName" in item):
print(item['promotionName'])
```
------
#### [ SDK for Java 2.x ]
```
public static void getRecommendationsWithPromotedItems(PersonalizeRuntimeClient personalizeRuntimeClient,
String campaignArn,
String userId,
String requestFilterArn,
String requestParameterName,
String requestParameterValue1,
String requestParameterValue2,
String promotionName,
int percentPromotedItems,
String promotionFilterArn,
String promotionParameterName,
String promotionParameterValue1,
String promotionParameterValue2) {
try {
Map promotionFilterValues = new HashMap<>();
promotionFilterValues.put(promotionParameterName, String.format("\"%1$s\",\"%2$s\"",
promotionParameterValue1, promotionParameterValue2));
Promotion newPromotion = Promotion.builder()
.name(promotionName)
.percentPromotedItems(percentPromotedItems)
.filterArn(promotionFilterArn)
.filterValues(promotionFilterValues)
.build();
List promotionList = new List<>();
promotionList.add(newPromotion);
Map requestfilterValues = new HashMap<>();
requestfilterValues.put(requestParameterName, String.format("\"%1$s\",\"%2$s\"",
requestParameterValue1, requestParameterValue2));
GetRecommendationsRequest recommendationsRequest = GetRecommendationsRequest.builder()
.campaignArn(campaignArn)
.numResults(20)
.userId(userId)
.filterArn(requestFilterArn)
.fitlerValues(requestFilterValues)
.promotions(promotionList)
.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());
System.out.println("Promotion name is : "+item.promotionName());
}
} catch (PersonalizeRuntimeException e) {
System.err.println(e.awsErrorDetails().errorMessage());
System.exit(1);
}
}
```
------
#### [ SDK for JavaScript v3 ]
```
// Get service clients and commands using ES6 syntax.
import { GetRecommendationsCommand, PersonalizeRuntimeClient } from
"@aws-sdk/client-personalize-runtime";
// create personalizeRuntimeClient.
const personalizeRuntimeClient = new PersonalizeRuntimeClient({
region: "REGION",
});
// set recommendation request param
export const getRecommendationsParam = {
campaignArn: "CAMPAIGN_ARN", /* required */
userId: "USER_ID", /* required */
numResults: 25, /* optional */
filterArn: "FILTER_ARN", /* provide if you are applying a custom filter */
filterValues: {
"PARAM_NAME": "\"PARAM_VALUE\"" /* provide if your filter has a placeholder parameter */
},
promotions: [
{
name: "PROMOTION_NAME", /* specify the name of the promotion. The recommendation response includes the name to identify promoted items. */
percentPromotedItems: 50, /* the percentage of recommended items to apply the promotion to. */
filterArn:
"PROMOTION_FILTER_ARN", /* the Amazon Resource Name (ARN) of the filter that defines the promotion criteria. */
filterValues: {
"PARAM_NAME": "\"PARAM_VALUE\"" /* provide if your promotion filter has a placeholder parameter */
},
},
],
};
export const run = async () => {
try {
const response = await personalizeRuntimeClient.send(new GetRecommendationsCommand(getRecommendationsParam));
console.log("Success!", "\nItems are: ");
response.itemList.forEach(element => console.log(element.itemId))
return response; // For unit tests.
} catch (err) {
console.log("Error", err);
}
};
run();
```
------
此時會顯示建議項目清單。提升項目會相對於其他建議項目隨機放置，但會相對於其他提升項目依排序排列。根據您的配方，不屬於提升一部分的建議項目會依與使用者、熱門度或類似度的相關性排序。如果沒有足夠的項目符合提升條件，結果將包含盡可能多的提升項目。
```
{
"itemList": [
{
"itemId1": "123",
"score": .0117211,
"promotionName": "promotionName"
},
{
"itemId2": "456",
"score": .0077976
},
{
"itemId3": "789",
"score": .0067171
},
.....
]
```