本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 通过实时推荐推广物品 对于所有域应用场景和一些自定义配方，您可以在获得实时推荐时指定推广。 *推广* 定义了其他业务规则，这些规则适用于可配置的建议物品子集。例如，您可能有一款流应用程序，想要推广自己的节目和电影，但也想推荐相关的内容。您可以使用推广来指定一定比例的推荐物品必须来自*内部* 类别。根据您的食谱和任何请求筛选器，其余的推荐物品将继续是相关建议。 要应用推广，请在建议请求中指定以下内容： + 要应用推广筛选器的推荐物品的百分比。 + 指定推广标准的筛选器。有关更多信息，请参阅 [推广筛选器](#promotion-filters)。 在建议响应中，推广物品相对于其他推荐物品是随机放置的，但相对于其他推广物品按排序顺序列出。根据您的食谱，不属于推广的推荐物品将按与用户的相关性、受欢迎程度或相似度进行排序。如果没有足够的物品符合推广标准，则结果将包含尽可能多的推广物品。 您可以使用 Amazon Personalize 控制台、AWS Command Line Interface (AWS CLI) 或 AWS SDK 将推广应用于建议。 **Topics** + [支持推广的使用案例和食谱](#promotion-use-case-recipes) + [推广筛选器](#promotion-filters) + [推广新物品](#promoting-new-items) + [推广物品（控制台）](#promoting-items-console) + [推广物品 (AWS CLI)](#promoting-items-cli) + [推广物品 (AWS SDK)](#promoting-items-sdk) ## 支持推广的使用案例和食谱 所有使用案例都支持推广。以下自定义食谱支持推广： + [User-Personalization-v2](native-recipe-user-personalization-v2.md) 和 [User-Personalization](native-recipe-new-item-USER_PERSONALIZATION.md) 配方 + [Similar-Items](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. 打开 Amazon Personalize 控制台（网址为 [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home)），并登录您的账户。 1. 选择包含您要使用的市场活动或推荐器的数据集组。 1. 创建一个筛选器来指定推广条件（如果尚未创建）。为推广创建筛选器的方式与创建请求筛选器的方法相同。有关创建和管理筛选器的信息，请参阅[筛选结果](filter.md)。 1. 在导航窗格中，选择**推荐器** 或**活动**。 1. 选择目标市场活动或推荐器。 1. 对于市场活动，在**测试市场活动结果**下，根据您使用的食谱输入建议请求详细信息。对于推荐器，选择**测试推荐器**，然后输入建议请求详细信息。 1. （可选）为请求选择筛选器。此筛选器仅适用于非推广物品。有关创建和管理筛选器的信息，请参阅[筛选结果](filter.md)。 1. 如果您使用上下文元数据，请为每个上下文提供数据。对于每个上下文，为**键** 输入元数据字段。对于**值**，输入上下文数据。有关更多信息，请参阅 [利用上下文元数据提高建议的相关性](contextual-metadata.md)。 1. 对于**推广**，指定以下内容： + **推广物品百分比**：输入要应用推广的推荐物品所占的百分比。 + **筛选器**：选择用于指定推广标准的筛选器。此筛选器适用于推广物品，而不是您在步骤 7 中可能指定的任何请求筛选器。 + **筛选器参数**：如果您的推广使用的筛选器带有占位符参数，请为每个参数输入值以设置筛选条件。要为一个参数使用多个值，请用英文逗号分隔每个值。 1. 选择**获得建议**。此时，将显示一个包含针对用户推荐的前 25 个物品的表格。**推广物品**列显示该物品是否因为您的推广而被收录。推广物品相对于其他推荐物品是随机放置的，但相对于其他推广物品按排序顺序列出。根据您的使用案例或食谱，不属于推广的推荐物品将按与用户的相关性、受欢迎程度或相似度进行排序。如果没有足够的物品符合推广标准，则结果将包含尽可能多的推广物品。 ## 推广物品 (AWS CLI) 以下代码展示了如何使用 AWS CLI 和自定义市场活动在建议中推广物品。要使用推荐器推广物品，请将 `campaign-arn` 参数替换为 `recommender-arn`，并为推荐器指定 Amazon 资源名称 (ARN)。对于推广字段，指定以下内容： + 名称：为推广命名。建议响应使用该名称来标识推广的物品。 + percent-promoted-items：要应用推广的推荐物品所占的百分比。在此示例中，50% 的物品将成为推广物品。 + filterArn：指定用于定义推广条件的筛选器的 Amazon 资源名称 (ARN)。有关更多信息，请参阅 [推广筛选器](#promotion-filters)。 + 参数名称和值：如果您的筛选器表达式有任何参数，请提供参数名称（区分大小写）和值。例如，如果您的筛选器表达式具有 `$GENRE` 参数，请提供 GENRE 作为键，并提供一个或多个类型（例如 *Comedy*）作为值。用英文逗号分隔多个值。使用 AWS CLI 时，对于每个值，都必须使用 `/` 字符对引号和 `/` 字符进行转义。以下代码示例显示如何设置值的格式。 该代码显示了如何同时使用请求筛选器和推广筛选器。推广筛选器仅适用于推广物品，而请求筛选器仅适用于剩余的推荐物品。有关更多信息，请参阅 [推广筛选器](#promotion-filters)。 有关其他字段的信息，请参阅[获取物品建议 (AWS SDK)](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 SDK) 以下代码展示了如何使用 SDK for Python (Boto3)、SDK for Java 2.x 和自定义市场活动在建议中推广物品。要使用推荐器推广物品，请将 `campaignArn` 参数替换为 `recommenderArn`，并为推荐器指定 Amazon 资源名称 (ARN)。对于推广字段，指定以下内容： + 名称：指定推广的名称。建议响应包含该名称来标识推广的物品。 + percentPromotedItems：要应用推广的推荐物品所占的百分比。 + promotionFilterARN：指定用于定义推广条件的筛选器的 Amazon 资源名称 (ARN)。有关更多信息，请参阅 [推广筛选器](#promotion-filters)。 + 任何参数名称和值：如果您的筛选器表达式包含任何参数，请为筛选器表达式中的每个参数提供参数名称（区分大小写）和值。例如，如果您的筛选器表达式具有 `$GENRE` 参数，请提供 `"GENRE"` 作为键，并提供一个或多个类型（例如 "\$1"Comedy"\$1"）作为值。用英文逗号分隔多个值。例如 `"\"comedy\",\"drama\",\"horror"\"`。 以下代码显示了如何同时使用请求筛选器和推广筛选器。推广筛选器仅适用于推广物品，而请求筛选器仅适用于剩余的推荐物品。有关更多信息，请参阅 [推广筛选器](#promotion-filters)。 有关其他字段的信息，请参阅[获取物品建议 (AWS SDK)](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 }, ..... ] ```