翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# リアルタイムレコメンデーション内のアイテムのプロモーション
すべてのドメインユースケースと一部のカスタムレシピでは、リアルタイムレコメンデーションを受け取ったときにプロモーションを指定できます。
*プロモーション*では、設定可能な推奨アイテムのサブセットに適用される追加のビジネスルールを定義します。例えば、ストリーミングアプリがあり、自身の番組や映画を宣伝したいだけでなく、関連するタイトルもレコメンドしたい場合があるかもしれません。プロモーションを利用して、推奨アイテムの一定割合を*社内*のカテゴリからとするように指定できます。残りの推奨アイテムは、レシピやリクエストフィルターに基づいて、引き続き関連性あるレコメンデーションになります。
プロモーションを適用するには、レコメンデーションリクエストで以下を指定します。
+ プロモーションフィルターを適用する推奨アイテムの割合。
+ プロモーション条件を指定するフィルター。詳細については、「[プロモーションフィルター](#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) レシピ
+ [トレンド-ナウ](native-recipe-trending-now.md) および [Popularity-Count](native-recipe-popularity.md) レシピ
## プロモーションフィルター
レコメンデーションリクエストにプロモーションを適用するときは、プロモーション条件を指定するフィルターを選択します。既存のフィルターを使用するか、新しいフィルターを作成できます。Amazon Personalize の他のフィルターと同様に、プロモーション用のフィルターを作成および管理します。フィルターの作成および管理の詳細については、「[結果のフィルタリング](filter.md)」を参照してください。
プロモーションフィルターとプロモーション外で選択するフィルター (*リクエストフィルター*) との唯一の違いは、Amazon Personalize がそれらをどのように適用するかです。プロモーションフィルターはプロモーション対象アイテムのみに適用され、リクエストフィルターはその他の推奨アイテムにのみ適用されます。リクエストフィルターとプロモーションフィルターを指定し、両方のフィルターをプロモーション対象アイテムに適用する場合は、プロモーションフィルターの式に両方の式を含める必要があります。2 つの式を組み合わせる方法は、使用するデータセットによって異なります。フィルター式、ルール、およびフィルター式の作成方法の詳細については、「[フィルタ式](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 つのパラメータに複数の値を使用するには、各値をコンマで区切ります。
1. **[レコメンデーションの取得]** を選択します。ユーザーの上位 25 個の推奨アイテムを含むテーブルが表示されます。**プロモート対象アイテム**列には、そのアイテムがプロモーションのために含まれていたかどうかが示されます。プロモーション対象アイテムは、他の推奨アイテムとの相対位置はランダムですが、他のプロモーション対象アイテムとの相対的な順序で並んでいます。ユースケースやレシピに応じて、プロモーションに含まれていない推奨アイテムは、ユーザーとの関連性、人気、類似度でソートされます。プロモーション条件を満たすアイテムが十分でない場合、結果にはできるだけ多くのプロモーション対象アイテムが含まれます。
## アイテムのプロモーション (AWS CLI)
次のコードは、レコメンデーション内の商品を AWS CLI とカスタムキャンペーンでプロモーションする方法を示しています。レコメンダーを使って商品をプロモーションするには、`campaign-arn` パラメーターを `recommender-arn` に置き換え、レコメンダーの Amazon リソースネーム (ARN) を指定します。プロモーションフィールドには、以下を指定します。
+ 名前: プロモーションに名前を付けます。レコメンデーションレスポンスでは、その名前を使用してプロモートされたアイテムを識別します。
+ プロモーション商品の割合:プロモーションを適用する推奨アイテムの割合。この例では、50% の商品がプロモーション対象商品になります。
+ filterArn: プロモーション条件を定義するフィルターの Amazon リソースネーム (ARN) を指定します。詳細については、「[プロモーションフィルター](#promotion-filters)」を参照してください。
+ パラメータの名前と値:フィルター式にパラメータがある場合は、パラメータ名 (大文字と小文字が区別されます) と値を指定します。例えば、フィルター式に `$GENRE` パラメータがある場合は、キーとして「GENRE」を指定し、値として 1 つまたは複数のジャンル (*コメディ* など) を指定します。複数の値はコンマで区切ります。AWS CLI を使用するときは、値ごとに引用符と `/` 文字の両方をエスケープする `/` 文字を使用する必要があります。次のコード例は、値をフォーマットする方法を示しています。
このコードは、リクエストフィルターとプロモーションフィルターの両方を使用する方法を示しています。プロモーションフィルターはプロモーション対象アイテムのみに適用され、リクエストフィルターは残りの推奨アイテムにのみ適用されます。詳細については、「[プロモーションフィルター](#promotion-filters)」を参照してください。
追加フィールドについては、「[アイテムレコメンデーションの取得 (AWS)](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"\\" など) を指定します。複数の値はコンマで区切ります。例えば、`"\"comedy\",\"drama\",\"horror"\"`。
次のコードは、リクエストフィルターとプロモーションフィルターの両方を使用する方法を示しています。プロモーションフィルターはプロモーション対象アイテムのみに適用され、リクエストフィルターは残りの推奨アイテムにのみ適用されます。詳細については、「[プロモーションフィルター](#promotion-filters)」を参照してください。
追加フィールドについては、「[アイテムレコメンデーションの取得 (AWS)](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
},
.....
]
```