支援促銷活動的使用案例和配方促銷過濾器推廣新項目推廣項目（控制台）推廣項目（AWS CLI）宣傳項目 (AWS SDK)

推廣建議中的項目

透過所有網域使用案例和一些自訂配方，您可以在取得即時建議時指定促銷活動。

促銷會定義套用至可供配置之建議項目子集的其他企業規則。例如，您可能有一個流媒體應用程序，並希望宣傳自己的節目和電影，但也推薦相關的標題。您可以使用促銷來指定某個百分比的推薦料號必須來自內部類別。根據您的食譜和任何請求過濾器，其餘的推薦項目仍然是相關建議。

若要套用促銷，請在建議請求中指定下列項目：

要套用推進篩選條件的建議項目百分比。
指定推進條件的篩選器。如需詳細資訊，請參閱促銷過濾器。

在建議回應中，推進項目會隨機放置相對於其他建議項目，但會依相對於其他推進項目的排序順序排列。根據您的食譜，不屬於促銷活動一部分的推薦項目會根據與使用者的相關性、受歡迎程度或相似性來排序。如果沒有足夠的物品符合推廣條件，結果將包含盡可能多的推廣物品。

您可以使用 Amazon Personalize 主控台、 AWS Command Line Interface (AWS CLI) 或 AWS 開發套件將促銷套用至建議。

支援促銷活動的使用案例和配方

所有使用案例都支援促銷。以下自定義食譜支持促銷活動：

促銷過濾器

當您將推進套用至建議請求時，您可以選擇用來指定推進條件的篩選器。您可以使用現有篩選器或建立新篩選器。您可以像在 Amazon Personalize 中建立和管理促銷活動的篩選器一樣。如需有關建立和管理篩選器的資訊，請參閱篩選結果。

促銷篩選器和您在促銷之外選擇的篩選器 (請求篩選器) 之間的唯一區別是 Amazon Personalize 套用這些篩選器的方式。推進篩選器僅適用於推進項目，而請求篩選器僅適用於剩餘的建議項目。如果您指定請求篩選器和推進篩選器，並且想要將兩個篩選器套用至推進項目，則推進篩選器的運算式必須包含兩個運算式。結合兩個運算式的方式取決於您使用的資料集。如需篩選器運算式、其規則以及如何建立它們的詳細資訊，請參閱篩選條件表達式。

篩選運算式範例

以下表達式僅包括「內部」類別的項目。如果您想要在建議中宣傳自己的內容，可以使用此運算式。


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

如需篩選範例的更完整清單，請參閱篩選運算式範例。

推廣新項目

如果您使用用戶個性化-v2 配方，Amazon Personalize 會向使用者推薦最相關的項目，並且更頻繁地建議包含互動資料的現有項目。若要確保建議包含一些新項目，您可以將推進套用至包含根據建立時間戳記項目的建議請求。

如果您尚未使用促銷活動，篩選器運算式可以促銷特定日期之後建立的項目：


INCLUDE ItemID WHERE Items.CREATION_TIMESTAMP > $DATE

如果您已使用促銷，您可以建立連結促銷與新料號條件陳述式的運算式：


INCLUDE ItemID WHERE Items.CATEGORY IN ("clothing") OR Items.CREATION_TIMESTAMP > $DATE

推廣項目（控制台）

若要使用 Amazon Personalize 主控台推廣建議中的某些項目，請建立篩選器，然後在建議請求中提供促銷詳細資訊。如需其他欄位的資訊，請參閱取得項目建議 (主控台)。

推廣建議中的項目

在 https://console.aws.amazon.com/personalize/home 打開 Amazon Personalize 化控制台並登錄到您的帳戶。
選擇包含您正在使用的促銷活動或推薦人的資料集群組。
如果您尚未建立，請建立指定推進條件的篩選器。建立促銷活動篩選器的方式與建立請求篩選器的方式相同。如需建立和管理篩選器的資訊，請參閱篩選結果。
在導覽窗格中，選擇 [推薦人] 或 [促銷活動]。
選擇目標廣告系列或推薦人。
對於廣告活動，請在「測試廣告系列結果」下，根據您使用的食譜輸入建議請求詳細資料。對於推薦人，請選擇測試推薦人，然後輸入您的建議請求詳細資料。
選擇性地選擇請求的過濾條件。此篩選條件僅適用於未推廣的項目。如需建立和管理篩選器的資訊，請參閱篩選結果。
如果您使用關聯式詮釋資料，請提供每個上下文的資料。針對每個前後關聯，針對「金鑰」輸入中繼資料欄位。對於「值」，輸入內容資料。如需詳細資訊，請參閱透過上下文中繼資料增加建議。
針對促銷，請指定下列項目：
- 促銷料號百分比：輸入要套用促銷的建議料號百分比。
- 篩選條件：選擇指定促銷條件的篩選條件。此篩選器會套用至推進項目，而不是您在步驟 7 中指定的任何要求篩選器。
- 篩選參數：如果促銷使用具有預留位置參數的篩選條件，請針對每個參數輸入值以設定篩選條件。若要為一個參數使用多個值，請以逗號分隔每個值。
選擇 Get recommendations (取得建議)。此時會顯示一個包含使用者前 25 個建議項目的表格。「推廣物品」欄位會顯示該物品是否因推廣而被納入。推進項目會相對於其他推薦項目隨機放置，但會依相對於其他推進項目的排序順序排列。根據您的使用案例或方案，不屬於促銷活動的推薦項目會依據與使用者的相關性、受歡迎程度或相似性來排序。如果沒有足夠的物品符合推廣條件，結果將包含盡可能多的推廣物品。

推廣項目（AWS CLI）

下列程式碼會示範如何使用 AWS CLI 和自訂廣告活動來宣傳建議中的項目。若要使用推薦人推廣項目，請將campaign-arn參數取代為，recommender-arn並指定推薦人的 Amazon 資源名稱 (ARN)。針對促銷欄位，指定下列項目：

name：為促銷命名。建議回應會使用名稱來識別推進項目。
percent-promoted-items：套用促銷的建議料號百分比。在這個範例中，50% 的物品將會是推廣物品。
篩選器範圍：指定定義促銷條件的篩選器的 Amazon 資源名稱 (ARN)。如需詳細資訊，請參閱促銷過濾器。
參數名稱和值：如果篩選器運算式有任何參數，請提供參數名稱 (區分大小寫) 和值。例如，如果您的篩選器運算式有$GENRE參數，請提供「流派」做為關鍵字，並提供類型或類型 (例如「喜劇」) 做為值。用逗號分隔多個值。當您使用時 AWS CLI，對於每個值，您必須使用/字元來逸出引號和/字元。下列程式碼範例會示範如何格式化值。

該代碼顯示了如何同時使用請求過濾器和促銷過濾器。推進篩選器僅適用於推進項目，而請求篩選器僅適用於剩餘的建議項目。如需詳細資訊，請參閱促銷過濾器。

如需有關其他欄位的資訊，請參閱取得項目建議 (AWS 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
      },
      .....
 ]

宣傳項目 (AWS SDK)

下列程式碼會示範如何使用適用 SDK for Python (Boto3)、Java 2.x 版 SDK 和自訂促銷活動來推廣建議中的項目。若要使用推薦人推廣項目，請使用取代campaignArn參數，recommenderArn並指定推薦人的 Amazon 資源名稱 (ARN)。針對促銷欄位，指定下列項目：

名稱：指定促銷的名稱。建議回應包含用來識別推進項目的名稱。
percentPromotedItems：套用促銷的建議料號百分比。
促銷篩選條件：用於定義促銷條件的篩選器的 Amazon 資源名稱 (ARN)。如需詳細資訊，請參閱促銷過濾器。
任何參數名稱和值：如果篩選器運算式有任何參數，則針對篩選運算式中的每個參數，提供參數名稱 (區分大小寫) 和值。例如，如果您的篩選運算式具有$GENRE參數，請提供"GENRE"為關鍵字，並提供類型或類型 (例如「\" 喜劇 "\」) 做為值。用逗號分隔多個值。例如 "\"comedy\",\"drama\",\"horror"\"。

下面的代碼演示了如何同時使用請求過濾器和促銷過濾器。推進篩選器僅適用於推進項目，而請求篩選器僅適用於剩餘的建議項目。如需詳細資訊，請參閱促銷過濾器。

如需有關其他欄位的資訊，請參閱取得項目建議 (AWS SDK)和使用上下文元數據獲取個性化排名。

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。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

取得項目建議 (AWS SDK)

取得動作建議