本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # Amazon Personalize 中的实时物品推荐 如果您的应用场景或配方生成了物品推荐，那么在[创建推荐器](creating-recommenders.md)或[创建市场活动](campaigns.md)之后，即可为用户获取实时的个性化或相关物品推荐。 如果您的域应用场景或配方提供[实时个性化](use-case-recipe-features.md#about-real-time-personalization)（例如*热门精选*应用场景或 *User-Personalization-v2* 配方），则当您记录用户与目录的交互时，Amazon Personalize 会根据用户的最新活动更新推荐。有关记录实时事件和个性化设置的更多信息，请参阅[记录实时事件以影响推荐](recording-events.md)。 获得实时物品推荐后，您可以执行以下操作： + 如果您将市场活动配置为返回推荐物品的元数据，则可以指定要包括在 [GetRecommendations](API_RS_GetRecommendations.md) API 操作中的列。或者，您可以在使用 Amazon Personalize 控制台测试市场活动时指定列。有关代码示例，请参阅[获取实时推荐的物品元数据](getting-recommendations-with-metadata.md)。有关为市场活动启用元数据的信息，请参阅[推荐中的物品元数据](campaigns.md#create-campaign-return-metadata)。有关为推荐器启用元数据的信息，请参阅[在推荐中为 Amazon Personalize 中的域推荐器启用元数据](create-recommender-return-metadata.md)。 + 对于某些应用场景和配方，您可以在推荐请求中指定推广。*推广* 定义了其他业务规则，这些规则适用于可配置的建议物品子集。有关更多信息，请参阅 [通过实时推荐推广物品](promoting-items.md)。 + 您可以根据自定义条件筛选结果。例如，您可能不想推荐用户已经购买的产品，或者只推荐针对特定年龄段的物品。有关更多信息，请参阅 [筛选建议和用户细分](filter.md)。 **注意** 如果您使用了 PERSONALIZED\$1RANKING 自定义食谱，请参阅[获取个性化排名（自定义资源）](rankings.md)。 **Topics** + [推荐评分的工作原理（自定义资源）](#how-recommendation-scoring-works) + [User-Personalization-v2 的推荐理由](#recommendation-reasons) + [获取实时物品推荐](getting-real-time-item-recommendations.md) + [获取实时推荐的物品元数据](getting-recommendations-with-metadata.md) + [通过实时推荐推广物品](promoting-items.md) ## 推荐评分的工作原理（自定义资源） 借助 User-Personalization-v2 和 User-Personalization 配方，Amazon Personalize 可根据用户的交互数据和元数据为物品生成分数。这些分数表示 Amazon Personalize 对于用户是否与接下来的物品交互的相对确定性。分数越高，意味着确定性越大。 **注意** Amazon Personalize 不会显示域推荐器或者 Similar-Items、SIMS 或 Popularity-Count 食谱的分数。有关 Personalized-Ranking 建议分数的信息，请参阅 [个性化排名评分的工作原理](rankings.md#how-ranking-scoring-works)。 Amazon Personalize 会为每个物品生成一个分数，表示该物品与其他物品之间的相对关系，分数范围从 0 到 1（包括 0 和 1）。借助 User-Personalization-v2，Amazon Personalize 可为部分物品生成分数。借助 User-Personalization，Amazon Personalize 可对目录中的所有物品评分。 如果您使用 User-Personalization-v2 并对推荐应用筛选条件，那么根据筛选条件删除的推荐数量，Amazon Personalize 可能会添加占位符物品。这样做是为了符合推荐请求的 `numResults`。这些物品是基于交互数据量的热门物品，符合您的筛选条件。它们没有针对用户的相关性评分。 对于 User-Personalization-v2 和 User-Personalization，所有分数的总和等于 1。例如，如果您要获取用户的影片推荐，并且物品数据集和交互数据集中显示了三部影片，则其分数可能为 `0.6`、`0.3` 和 `0.1`。同样，如果您的库存中有 1 万部电影，则得分最高的电影的分数可能非常小（平均分数为 `.001`），但由于评分是相对的，推荐仍然有效。 在数学术语中，每个用户-物品对（u,i）的分数是根据以下公式计算的，其中 `exp` 是指数函数，w̅u 和 wi/j 分别是用户和物品嵌入内容，希腊字母西格玛（Σ）表示包含分数的所有物品的总和： ![\[描绘了用于计算推荐中每个物品分数的公式。\]](http://docs.amazonaws.cn/personalize/latest/dg/images/get_recommendations_score.png) ## User-Personalization-v2 的推荐理由 如果您使用 User-Personalization-v2，模型通常不会推荐的物品会包含一个 `reason` 清单。这些理由说明了为什么在推荐中包括该物品。可能的原因包括： + 推广物品 - 表示您在推荐请求中应用的推广活动中包括该物品。 + 浏览 - 表示该物品包括在浏览中。使用浏览时，推荐包括的物品具有更少的交互数据或用户相关性。有关浏览的更多信息，请参阅[浏览](https://docs.amazonaws.cn/personalize/latest/dg/use-case-recipe-features.html#about-exploration)。 + 热门物品 - 表示该物品作为占位符热门物品包括在内。如果您使用筛选条件，那么根据筛选条件删除的推荐数量，Amazon Personalize 可能会添加占位符物品以满足推荐请求的 `numResults`。这些物品是基于交互数据的热门物品，符合您的筛选条件。它们没有针对用户的相关性评分。 # 获取实时物品推荐 您可以通过 Amazon Personalize 控制台、Amazon Command Line Interface (Amazon CLI) 或 Amazon SDK 从 Amazon Personalize 推荐器或自定义市场活动中获取实时物品推荐。 **Topics** + [获取物品建议（控制台）](#get-real-time-recommendations-console) + [获取物品建议 (Amazon CLI)](#get-item-rec-cli) + [获取物品建议 (Amazon SDK)](#get-item-rec-sdk) ## 获取物品建议（控制台） 要通过 Amazon Personalize 控制台获取建议，您需要在推荐器（域数据集组）或自定义市场活动的详情页面上提供请求信息。 **获得建议** 1. 打开 Amazon Personalize 控制台（网址为 [https://console.aws.amazon.com/personalize/home](https://console.amazonaws.cn/personalize/home)），并登录您的账户。 1. 选择包含您要使用的市场活动或推荐器的数据集组。 1. 在导航窗格中，选择**市场活动** 或**推荐器**。 1. 选择目标市场活动或推荐器。 1. 对于活动，在**测试市场活动结果**下，根据您使用的食谱输入建议请求详细信息。对于推荐器，选择**测试推荐器**，然后根据使用案例输入建议请求详细信息。 如果您在用户登录（匿名用户）之前为其记录了事件，则可以通过提供来自这些事件的 `sessionId`（就像是其 `userId`），获取针对此用户的建议。有关为匿名用户记录事件的更多信息，请参阅[为匿名用户记录事件](recording-events.md#recording-anonymous-user-events)。 1. （可选）选择筛选器。有关更多信息，请参阅 [筛选建议和用户细分](filter.md)。 1. 如果您使用上下文元数据，请为每个上下文提供数据。对于每个上下文，为**键** 输入元数据字段。对于**值**，输入上下文数据。有关更多信息，请参阅 [利用上下文元数据提高建议的相关性](contextual-metadata.md)。 1. 如果您在市场活动或推荐器的建议中启用了元数据，请为**物品数据集列**选择要包含在建议结果中的元数据列。有关为市场活动启用元数据的信息，请参阅[推荐中的物品元数据](campaigns.md#create-campaign-return-metadata)。有关为推荐器启用元数据的信息，请参阅[在推荐中为 Amazon Personalize 中的域推荐器启用元数据](create-recommender-return-metadata.md)。 1. 如果您想推广一部分物品，可以选择填写**推广**字段。有关更多信息，请参阅 [通过实时推荐推广物品](promoting-items.md)。 1. 选择**获得建议**。此时，将显示一个包含针对用户推荐的前 25 个物品的表格。如果您使用 User-Personalization-v2，则每个推荐物品都会包含一份理由清单，说明为什么在推荐中包括该物品。有关更多信息，请参阅 [User-Personalization-v2 的推荐理由](recommendations.md#recommendation-reasons)。 ## 获取物品建议 (Amazon CLI) 使用以下代码从市场活动中获得建议。要从推荐器中获得建议，请将 `campaign-arn` 参数替换为 `recommender-arn`。 指定要获取建议的用户的 ID 及市场活动或推荐器的 Amazon 资源名称 (ARN)。这时，将显示为用户推荐的前 10 个物品的列表。如果您使用 User-Personalization-v2，则每个推荐物品都会包含一份理由清单，说明为什么在推荐中包括该物品。有关更多信息，请参阅 [User-Personalization-v2 的推荐理由](recommendations.md#recommendation-reasons)。 要更改推荐物品的数量，请更改 `numResults` 的值。默认值为 25 个物品。最大值为 500 个物品。如果您使用 RELATED\$1ITEMS 食谱来训练支持市场活动的解决方案版本，请将 `user-id` 参数替换为 `item-id` 并指定物品 ID。 如果您在用户登录（匿名用户）之前为其记录了事件，则可以通过提供来自这些事件的 `sessionId`（就像是其 `userId`），获取针对此用户的建议。有关为匿名用户记录事件的更多信息，请参阅[为匿名用户记录事件](recording-events.md#recording-anonymous-user-events)。 ``` aws personalize-runtime get-recommendations \ --campaign-arn campaign arn \ --user-id User ID \ --num-results 10 ``` ## 获取物品建议 (Amazon SDK) 以下代码展示了如何使用 Amazon SDK 从市场活动中为用户获取 Amazon Personalize 推荐。要从推荐器中获得建议，请将 `campaignArn` 参数替换为 `recommenderArn`。 指定要获取建议的用户的 ID 及市场活动或推荐器的 Amazon 资源名称 (ARN)。这时，将显示为用户推荐的前 10 个物品的列表。如果您使用 User-Personalization-v2，则每个推荐物品都会包含一份理由清单，说明为什么在推荐中包括该物品。有关更多信息，请参阅 [User-Personalization-v2 的推荐理由](recommendations.md#recommendation-reasons)。 要更改推荐物品的数量，请更改 `numResults` 的值。默认值为 25 个物品。最大值为 500 个物品。如果您使用 RELATED\$1ITEMS 食谱来训练支持市场活动的解决方案版本，请将 `userId` 参数替换为 `itemId` 并指定物品 ID。 如果您在市场活动或推荐器的建议中启用了元数据，则可以指定要包含在响应中的物品数据集元数据列。有关代码示例，请参阅[在推荐中包括物品元数据（Amazon SDK）](getting-recommendations-with-metadata.md#getting-recommendations-with-metadata-sdk)。有关启用元数据的信息，请参阅[推荐中的物品元数据](campaigns.md#create-campaign-return-metadata)。 如果您在用户登录（匿名用户）之前为其记录了事件，则可以通过提供来自这些事件的 `sessionId`（就像是其 `userId`），获取针对此用户的建议。有关为匿名用户记录事件的更多信息，请参阅[为匿名用户记录事件](recording-events.md#recording-anonymous-user-events)。 ------ #### [ SDK for Python (Boto3) ] ``` import boto3 personalizeRt = boto3.client('personalize-runtime') response = personalizeRt.get_recommendations( campaignArn = 'Campaign ARN', userId = 'User ID', numResults = 10 ) print("Recommended items") for item in response['itemList']: print (item['itemId']) ``` ------ #### [ SDK for Java 2.x ] ``` public static void getRecs(PersonalizeRuntimeClient personalizeRuntimeClient, String campaignArn, String userId) { try { GetRecommendationsRequest recommendationsRequest = GetRecommendationsRequest.builder() .campaignArn(campaignArn) .numResults(20) .userId(userId) .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 (AwsServiceException 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 the recommendation request parameters. export const getRecommendationsParam = { campaignArn: "CAMPAIGN_ARN" /* required */, userId: "USER_ID" /* required */, numResults: 15 /* optional */, }; 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(); ``` ------ # 获取实时推荐的物品元数据 如果您将市场活动或推荐器配置为返回推荐物品的元数据，则可以指定要包括在 [GetRecommendations](API_RS_GetRecommendations.md) API 操作中的列。或者，您可以在使用 Amazon Personalize 控制台测试市场活动时指定列。 有关为市场活动启用元数据的信息，请参阅[推荐中的物品元数据](campaigns.md#create-campaign-return-metadata)。有关为推荐器启用元数据的信息，请参阅[在推荐中为 Amazon Personalize 中的域推荐器启用元数据](create-recommender-return-metadata.md)。 以下代码示例展示了如何使用 Amazon CLI 或 Amazon SDK 指定要包括的元数据列。要使用 Amazon Personalize 控制台完成此操作，请在测试市场活动时指定列。有关更多信息，请参阅 [获取物品建议（控制台）](getting-real-time-item-recommendations.md#get-real-time-recommendations-console)。 **Topics** + [在推荐中包括物品元数据（Amazon CLI）](#getting-recommendations-with-metadata-cli) + [在推荐中包括物品元数据（Amazon SDK）](#getting-recommendations-with-metadata-sdk) ## 在推荐中包括物品元数据（Amazon CLI） 如果您在市场活动或推荐器的建议中启用了元数据，则可以指定要包含在响应中的物品数据集元数据列。以下代码示例显示了如何在请求建议时指定元数据列。 ``` aws personalize-runtime get-recommendations \ --campaign-arn campaign arn \ --user-id User ID \ --num-results 10 \ --metadata-columns "{\"ITEMS\": ["\"columnNameA"\","\"columnNameB"\"]}" ``` ## 在推荐中包括物品元数据（Amazon SDK） 如果您在市场活动或推荐器的建议中启用了元数据，则可以指定要包含在响应中的物品数据集元数据列。以下代码示例显示了如何在请求建议时指定元数据列。 ``` import boto3 personalizeRt = boto3.client('personalize-runtime') response = personalizeRt.get_recommendations( campaignArn = 'Campaign ARN', userId = 'User ID', numResults = 10 metadataColumns = { "ITEMS": ['columnNameA','columnNameB'] } ) print("Recommended items") for item in response['itemList']: print(item['itemId']) print(item['metadata']) ``` # 通过实时推荐推广物品 对于所有域应用场景和一些自定义配方，您可以在获得实时推荐时指定推广。 *推广* 定义了其他业务规则，这些规则适用于可配置的建议物品子集。例如，您可能有一款流应用程序，想要推广自己的节目和电影，但也想推荐相关的内容。您可以使用推广来指定一定比例的推荐物品必须来自*内部* 类别。根据您的食谱和任何请求筛选器，其余的推荐物品将继续是相关建议。 要应用推广，请在建议请求中指定以下内容： + 要应用推广筛选器的推荐物品的百分比。 + 指定推广标准的筛选器。有关更多信息，请参阅 [推广筛选器](#promotion-filters)。 在建议响应中，推广物品相对于其他推荐物品是随机放置的，但相对于其他推广物品按排序顺序列出。根据您的食谱，不属于推广的推荐物品将按与用户的相关性、受欢迎程度或相似度进行排序。如果没有足够的物品符合推广标准，则结果将包含尽可能多的推广物品。 您可以使用 Amazon Personalize 控制台、Amazon Command Line Interface (Amazon CLI) 或 Amazon SDK 将推广应用于建议。 **Topics** + [支持推广的使用案例和食谱](#promotion-use-case-recipes) + [推广筛选器](#promotion-filters) + [推广新物品](#promoting-new-items) + [推广物品（控制台）](#promoting-items-console) + [推广物品 (Amazon CLI)](#promoting-items-cli) + [推广物品 (Amazon 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.amazonaws.cn/personalize/home)），并登录您的账户。 1. 选择包含您要使用的市场活动或推荐器的数据集组。 1. 创建一个筛选器来指定推广条件（如果尚未创建）。为推广创建筛选器的方式与创建请求筛选器的方法相同。有关创建和管理筛选器的信息，请参阅[筛选结果](filter.md)。 1. 在导航窗格中，选择**推荐器** 或**活动**。 1. 选择目标市场活动或推荐器。 1. 对于市场活动，在**测试市场活动结果**下，根据您使用的食谱输入建议请求详细信息。对于推荐器，选择**测试推荐器**，然后输入建议请求详细信息。 1. （可选）为请求选择筛选器。此筛选器仅适用于非推广物品。有关创建和管理筛选器的信息，请参阅[筛选结果](filter.md)。 1. 如果您使用上下文元数据，请为每个上下文提供数据。对于每个上下文，为**键** 输入元数据字段。对于**值**，输入上下文数据。有关更多信息，请参阅 [利用上下文元数据提高建议的相关性](contextual-metadata.md)。 1. 对于**推广**，指定以下内容： + **推广物品百分比**：输入要应用推广的推荐物品所占的百分比。 + **筛选器**：选择用于指定推广标准的筛选器。此筛选器适用于推广物品，而不是您在步骤 7 中可能指定的任何请求筛选器。 + **筛选器参数**：如果您的推广使用的筛选器带有占位符参数，请为每个参数输入值以设置筛选条件。要为一个参数使用多个值，请用英文逗号分隔每个值。 1. 选择**获得建议**。此时，将显示一个包含针对用户推荐的前 25 个物品的表格。**推广物品**列显示该物品是否因为您的推广而被收录。推广物品相对于其他推荐物品是随机放置的，但相对于其他推广物品按排序顺序列出。根据您的使用案例或食谱，不属于推广的推荐物品将按与用户的相关性、受欢迎程度或相似度进行排序。如果没有足够的物品符合推广标准，则结果将包含尽可能多的推广物品。 ## 推广物品 (Amazon CLI) 以下代码展示了如何使用 Amazon CLI 和自定义市场活动在建议中推广物品。要使用推荐器推广物品，请将 `campaign-arn` 参数替换为 `recommender-arn`，并为推荐器指定 Amazon 资源名称 (ARN)。对于推广字段，指定以下内容： + 名称：为推广命名。建议响应使用该名称来标识推广的物品。 + percent-promoted-items：要应用推广的推荐物品所占的百分比。在此示例中，50% 的物品将成为推广物品。 + filterArn：指定用于定义推广条件的筛选器的 Amazon 资源名称 (ARN)。有关更多信息，请参阅 [推广筛选器](#promotion-filters)。 + 参数名称和值：如果您的筛选器表达式有任何参数，请提供参数名称（区分大小写）和值。例如，如果您的筛选器表达式具有 `$GENRE` 参数，请提供 GENRE 作为键，并提供一个或多个类型（例如 *Comedy*）作为值。用英文逗号分隔多个值。使用 Amazon CLI 时，对于每个值，都必须使用 `/` 字符对引号和 `/` 字符进行转义。以下代码示例显示如何设置值的格式。 该代码显示了如何同时使用请求筛选器和推广筛选器。推广筛选器仅适用于推广物品，而请求筛选器仅适用于剩余的推荐物品。有关更多信息，请参阅 [推广筛选器](#promotion-filters)。 有关其他字段的信息，请参阅[获取物品建议 (Amazon 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 }, ..... ] ``` ## 推广物品 (Amazon 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)。 有关其他字段的信息，请参阅[获取物品建议 (Amazon 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 }, ..... ] ```