As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Como promover itens nas recomendações

Com todos os casos de uso do domínio e algumas receitas personalizadas, você pode especificar uma promoção ao receber recomendações em tempo real.

Uma promoção define regras de negócios adicionais que se aplicam a um subconjunto configurável de itens recomendados. Exemplo: você tem um aplicativo de streaming e quer promover seus próprios programas e filmes, mas também recomendar títulos importantes. Você pode usar uma promoção para especificar que uma certa porcentagem dos itens recomendados deve ser da categoria interna. Os demais itens recomendados continuariam sendo recomendações relevantes baseadas na fórmula e nos filtros de solicitações.

Para aplicar uma promoção, você especifica o seguinte na solicitação de recomendação:

Na resposta à recomendação, os itens promovidos são posicionados aleatoriamente em relação a outros itens recomendados, mas em ordem ordenada em relação aos outros itens promovidos. Dependendo da sua fórmula, os itens recomendados que não forem parte de uma promoção serão classificados por relevância para o usuário, popularidade ou semelhança. Se não houver itens suficientes que atendam aos critérios da promoção, o resultado trará o maior número possível de itens promovidos.

Você pode aplicar uma promoção às recomendações com o console Amazon Personalize, AWS Command Line Interface (AWS CLI) ou AWS SDKs.

Casos de uso e fórmulas para promoções

Todos os casos de uso trabalham com promoções. As seguintes fórmulas personalizadas são compatíveis com promoções:

Filtros de promoção

Quando aplica uma promoção a uma solicitação de recomendação, você escolhe um filtro que especifica os critérios da promoção. Você pode criar um filtro ou usar um que já existe. Você cria e gerencia filtros para promoções da mesma forma que faria com outros filtros no Amazon Personalize. Para mais informações sobre como criar e gerenciar filtros, consulte Filtrar resultados.

A única diferença entre um filtro de promoção e um filtro que você escolhe fora da promoção (o filtro de solicitação) está na maneira como o Amazon Personalize os aplica. Um filtro de promoção se aplica somente aos itens promovidos, já o de solicitação vale apenas para os demais itens recomendados. Se você especificar um filtro de solicitação e outro de promoção e quiser aplicar ambos aos itens promovidos, a expressão do filtro de promoção deverá incluir ambas as expressões. A forma como você combina duas expressões depende dos conjuntos de dados que você usa. Para mais informações sobre expressões de filtro, suas regras e como criá-los, consulte Expressões de filtro.

Exemplos de expressões de filtro

A expressão a seguir inclui somente itens da categoria “interno”. Você pode usar essa expressão se quiser promover seu próprio conteúdo nas suas recomendações.

INCLUDE ItemID WHERE Items.OWNER IN ("in-house")

A expressão a seguir inclui somente itens criados mais recentemente do que um carimbo de data/hora especificado por você. Você pode usar essa expressão para promover novos itens nas recomendações.

INCLUDE ItemID WHERE Items.CREATION_TIMESTAMP > $DATE

A expressão a seguir mostra como aplicar um filtro de solicitação aos itens promovidos. incluindo apenas itens de vestuário disponíveis como itens promovidos. Nesse cenário, o Items.AVAILABLE IN ("True") também seria usado na expressão do filtro de solicitação, de forma que todas as recomendações sejam feitas para itens que estão disponíveis.

INCLUDE ItemID WHERE Items.CATEGORY IN ("clothing") AND Items.AVAILABLE IN ("True")

Para uma lista mais completa de exemplos de filtro, consulte Exemplos de expressões de filtro.

Promovendo novos itens

Se você usa oReceita de personalização do usuário v2, o Amazon Personalize recomenda os itens mais relevantes para os usuários e recomenda com mais frequência os itens existentes com dados de interações. Para garantir que as recomendações incluam alguns itens novos, você pode aplicar uma promoção às solicitações de recomendação que inclua itens com base na data e hora da criação.

Se você ainda não usa uma promoção, sua expressão de filtro pode promover itens criados após uma determinada data:

INCLUDE ItemID WHERE Items.CREATION_TIMESTAMP > $DATE

Se você já usa uma promoção, cria uma expressão que encadeia as declarações de condição da promoção e do novo item:

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

Como promover itens (console)

Para promover determinados itens nas recomendações com o console do Amazon Personalize, crie um filtro e forneça os detalhes da promoção na solicitação de recomendação. Para informações sobre outros campos, consulte Obter recomendações de itens (console).

Como promover itens (AWS CLI)

O código a seguir mostra como promover itens nas recomendações com a AWS CLI e uma campanha personalizada. Para promover itens com um recomendador, substitua o parâmetro campaign-arn por um recommender-arn e especifique o nome do recurso da Amazon (ARN) para o recomendador. Para os campos de promoção, especifique o seguinte:

O código mostra como usar os filtros de solicitação e de promoção. Um filtro de promoção se aplica somente aos itens promovidos, já o de solicitação vale apenas para os demais itens recomendados. Para ter mais informações, consulte Filtros de promoção.

Para informações sobre os campos adicionais, consulte Obter recomendações de itens (AWS SDKs) e Obter uma classificação personalizada usando metadados contextuais.

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\\\"\"}
}]"

Uma lista de itens recomendados vai aparecer. Os itens promovidos são posicionados aleatoriamente em relação a outros itens recomendados, mas em ordem ordenada em relação aos outros itens promovidos. Dependendo da sua fórmula, os itens recomendados que não forem parte de uma promoção serão classificados por relevância para o usuário, popularidade ou semelhança. Se não houver itens suficientes que atendam aos critérios da promoção, o resultado trará o maior número possível de itens promovidos.

{
  "itemList": [
      { 
          "itemId1": "123",
          "score": .0117211,
          "promotionName": "promotionName"
      },
      { 
         "itemId2": "456",
         "score": .0077976
      },
      { 
         "itemId3": "789",
         "score": .0067171
      },
      .....
 ]

Promovendo itens (AWS SDKs)

O código a seguir mostra como promover itens nas recomendações com o SDK para Python (Boto3), o SDK para Java 2.x e uma campanha personalizada. Para promover itens com um recomendador, substitua o parâmetro campaignArn por recommenderArn e especifique o nome do recurso da Amazon (ARN) para o recomendador. Para os campos de promoção, especifique o seguinte:

O código a seguir mostra como usar os filtros de solicitação e de promoção. Um filtro de promoção se aplica somente aos itens promovidos, já o de solicitação vale apenas para os demais itens recomendados. Para ter mais informações, consulte Filtros de promoção.

Para informações sobre os campos adicionais, consulte Obter recomendações de itens (AWS SDKs) e Obter uma classificação personalizada usando metadados contextuais.

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();
            
          

Uma lista de itens recomendados vai aparecer. Os itens promovidos são posicionados aleatoriamente em relação a outros itens recomendados, mas em ordem ordenada em relação aos outros itens promovidos. Dependendo da sua fórmula, os itens recomendados que não forem parte de uma promoção serão classificados por relevância para o usuário, popularidade ou semelhança. Se não houver itens suficientes que atendam aos critérios da promoção, o resultado trará o maior número possível de itens promovidos.

{
  "itemList": [
      { 
          "itemId1": "123",
          "score": .0117211,
          "promotionName": "promotionName"
      },
      { 
         "itemId2": "456",
         "score": .0077976
      },
      { 
         "itemId3": "789",
         "score": .0067171
      },
      .....
 ]