プロモーションをサポートするユースケースとレシピプロモーションフィルターアイテムの宣伝 (コンソール)プロモーションアイテム (AWS CLI)プロモーションアイテム (AWSSDK)

おすすめ商品のプロモーション

すべてのドメインのユースケースと一部のカスタムレシピでは、おすすめを受け取ったときにプロモーションを指定できます。プロモーションでは、設定可能なおすすめアイテムのサブセットに適用される追加のビジネスルールを定義します。たとえば、ストリーミングアプリを使用していて、自分の番組や映画を宣伝しながら、関連性の高いタイトルを推薦したい場合があります。プロモーションを利用して、おすすめ商品の一定割合を社内のカテゴリーから購入するように指定できます。残りのおすすめ商品は、引き続きレシピやリクエストフィルターに基づいた関連性の高いおすすめ商品となります。

プロモーションを適用するには、レコメンデーションリクエストで以下を指定します。

プロモーションフィルターを適用するおすすめ商品の割合。
プロモーション基準を指定するフィルター。詳細については、「プロモーションフィルター」を参照してください。

レコメンデーションレスポンスでは、プロモートされたアイテムは、他のおすすめアイテムに対してはランダムに配置されますが、他のプロモートされたアイテムとの相対的な順序はソートされています。レシピに応じて、プロモーションに含まれていないおすすめアイテムは、ユーザーとの関連性、人気度、類似度でソートされます。プロモーション条件を満たすアイテムが十分でない場合、結果にはプロモーションされたアイテムができるだけ多く含まれます。

Amazon Personalize コンソール AWS Command Line Interface (AWS CLI)、または AWS SDK を使用してレコメンデーションにプロモーションを適用できます。

プロモーションをサポートするユースケースとレシピ

すべてのユースケースがプロモーションをサポートします。以下のカスタムレシピはプロモーションをサポートしています。

プロモーションフィルター

レコメンデーションリクエストにプロモーションを適用するときは、プロモーション条件を指定するフィルターを選択します。既存のフィルターを使用することも、新しいフィルターを作成することもできます。Amazon Personalize の他のフィルターと同様に、プロモーション用のフィルターを作成および管理します。フィルターの作成と管理については、を参照してください結果のフィルタ処理。

プロモーションフィルターとプロモーション外で選択したフィルター (リクエストフィルター) の唯一の違いは、Amazon Personalize がそれらをどのように適用するかです。プロモーションフィルターはプロモートされたアイテムにのみ適用され、リクエストフィルターは残りの推奨アイテムにのみ適用されます。リクエストフィルターとプロモーションフィルターを指定し、両方のフィルターをプロモートアイテムに適用する場合は、プロモーションフィルターの式に両方の式を含める必要があります。2 つの式を組み合わせる方法は、使用するデータセットによって異なります。フィルター式、その規則、および作成方法の詳細については、を参照してくださいフィルタ式。

フィルター表現の例

次の表現には、「社内」カテゴリのアイテムのみが含まれます。自分のコンテンツをレコメンデーションで宣伝したい場合は、この表現を使うとよいでしょう。


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")

フィルター例の詳細なリストについては、を参照してくださいフィルター式の例。

アイテムの宣伝 (コンソール)

Amazon Personalize コンソールでレコメンデーション内の特定の商品をプロモーションするには、フィルターを作成してから、レコメンデーションリクエストでプロモーションの詳細を指定します。他のフィールドについては、を参照してくださいレコメンデーションの取得 (コンソール)。

プロモーションアイテム (AWS CLI)

次のコードは、AWS CLIおよびカスタムキャンペーンを使用してレコメンデーション内のアイテムを宣伝する方法を示しています。レコメンダーで商品を宣伝するには、campaign-arnrecommender-arnパラメータをaに置き換え、レコメンダーの Amazon リソースネーム (ARN) を指定します。プロモーションフィールドには、以下を指定します。

名前:プロモーションに名前を付けてください。レコメンデーションレスポンスでは、その名前を使用してプロモートされたアイテムを識別します。
percent-promoted-items: プロモーションを適用するおすすめ商品の割合。この例では、アイテムの 50% がプロモーションアイテムになります。
FilterArn: プロモーション条件を定義するフィルターの Amazon リソースネーム (ARN) を指定します。詳細については、「プロモーションフィルター」を参照してください。
パラメータ名と値:フィルタ式にパラメータがある場合は、パラメータ名 (大文字と小文字を区別) と値を指定します。たとえば、$GENREフィルター条件式にパラメーターがある場合は、キーとして GENRE を指定し、値として 1 つまたは複数のジャンル (コメディーなど) を指定します。複数の値はコンマで区切ります。を使用する場合AWS CLI、//値ごとに引用符と文字の両方をエスケープする文字を使用する必要があります。次のコード例は、値をフォーマットする方法を示しています。

このコードは、リクエストフィルターとプロモーションフィルターの両方を使用する方法を示しています。プロモーションフィルターはプロモートされたアイテムにのみ適用され、リクエストフィルターは残りの推奨アイテムにのみ適用されます。詳細については、「プロモーションフィルター」を参照してください。

その他のフィールドについては、レコメンデーションの取得 (AWS SDK)およびを参照してくださいコンテキストメタデータを使用した、パーソナライズされたランキングの取得 (AWS Python SDK)。


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
      },
      .....
 ]

プロモーションアイテム (AWSSDK)

次のコードは、Python 用 SDK (Boto3) と SDK for Java 2.x、およびカスタムキャンペーンを使用して、レコメンデーション内のアイテムをプロモートする方法を示しています。レコメンダーで商品を宣伝するには、campaignArnパラメータをレコメンダーの Amazon リソースネーム (ARN) に置き換えて指定します。recommenderArnプロモーションフィールドには、以下を指定します。

名前:プロモーションの名前を指定します。レコメンデーションレスポンスには、プロモートされたアイテムを識別するための名前が含まれます。
percentPromotedItems: プロモーションを適用するおすすめ商品の割合。
PromotionFilterArn: プロモーション条件を定義するフィルターの Amazon リソースネーム (ARN)。詳細については、「プロモーションフィルター」を参照してください。
任意のパラメータ名と値:フィルタ式にパラメータがある場合は、フィルタ式の各パラメータについて、パラメータ名 (大文字と小文字を区別) と値を指定します。たとえば、$GENREフィルター条件式にパラメーターがある場合、"GENRE"キーとして指定し、値として「\" コメディ "\」などのジャンルを指定します。複数の値はコンマで区切ります。例えば、"\"comedy\",\"drama\",\"horror"\"。

次のコードは、リクエストフィルターとプロモーションフィルターの両方を使用する方法を示しています。プロモーションフィルターはプロモートされたアイテムにのみ適用され、リクエストフィルターは残りの推奨アイテムにのみ適用されます。詳細については、「プロモーションフィルター」を参照してください。

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<String, String> 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<Promotion> promotionList = new List<>();
      
      promotionsList.add(newPromotion);
      
      Map<String, String> 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<PredictedItem> 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
      },
      .....
 ]

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

レコメンデーションの取得

パーソナライズされたランキングの取得 (カスタムリソース)