Casos de uso y recetas que admiten promociones Filtros de promoción Promocionar artículos nuevos Promoción de elementos (consola)Promoción de elementos (AWS CLI)Artículos de promoción (AWS SDK)

Promoción de elementos en las recomendaciones

Con todos los casos de uso de dominios y algunas recetas personalizadas, puedes especificar una promoción cuando recibas recomendaciones en tiempo real.

Una promoción define reglas empresariales adicionales que se aplican a un subconjunto configurable de elementos recomendados. Por ejemplo, es posible que tenga una aplicación de streaming y desee promocionar sus propias series y películas, pero también recomendar títulos interesantes. Puede usar una promoción para especificar que un porcentaje determinado de los elementos recomendados deban provenir de la categoría interno. El resto de los elementos recomendados seguirán siendo recomendaciones pertinentes en función de su receta y de cualquier filtro de solicitud.

Para aplicar una promoción, debe especificar lo siguiente en su solicitud de recomendación:

El porcentaje de elementos recomendados a los que se debe aplicar el filtro de promoción.
Un filtro que especifica los criterios de promoción. Para obtener más información, consulte Filtros de promoción.

En la respuesta a la recomendación, los elementos promocionados se colocan aleatoriamente en relación con otros elementos recomendados, pero ordenados en relación con otros elementos promocionados. Según la receta, los elementos recomendados que no forman parte de una promoción se ordenan por relevancia para el usuario, popularidad o similitud. Si no hay suficientes elementos que cumplan los criterios de la promoción, el resultado incluirá tantos elementos promocionados como sea posible.

Puedes aplicar una promoción a las recomendaciones con la consola Amazon Personalize, AWS Command Line Interface (AWS CLI) o AWS los SDK.

Temas

Casos de uso y recetas que admiten promociones
Filtros de promoción
Promocionar artículos nuevos
Promoción de elementos (consola)
Promoción de elementos (AWS CLI)
Artículos de promoción (AWS SDK)

Casos de uso y recetas que admiten promociones

Todos los casos de uso admiten promociones. Las siguientes recetas personalizadas admiten promociones:

Las recetas de USER_PERSONALIZATION.
Las recetas de RELATED_ITEMS.
Las recetas de POPULAR_ITEMS.

Filtros de promoción

Cuando aplica una promoción a una solicitud de recomendación, elige un filtro que especifica los criterios de la promoción. Puede usar un filtro existente o crear uno nuevo. Los filtros de las promociones se crean y administran igual que haría con otros filtros de Amazon Personalize. Para obtener más información acerca de cómo se crean y se administran filtros, consulte Filtrado de resultados.

La única diferencia entre un filtro de promoción y un filtro que elija fuera de la promoción (el filtro de solicitud) es la forma en que Amazon Personalize los aplica. Un filtro de promoción se aplica solo a los elementos en promoción, mientras que un filtro de solicitud se aplica solo al resto de los elementos recomendados. Si especifica un filtro de solicitud y un filtro de promoción y desea aplicar ambos filtros a los elementos en promoción, la expresión del filtro de promoción debe incluir ambas expresiones. La forma de combinar dos expresiones depende de los conjuntos de datos que utilice. Para obtener más información sobre las expresiones de filtro, sus reglas y cómo crearlas, consulte Expresiones de filtro.

Ejemplos de expresiones de filtro

La siguiente expresión incluye solo los elementos de la categoría “internos”. Puede usar esta expresión si desea promocionar su propio contenido en las recomendaciones.


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

La siguiente expresión incluye solo los artículos creados más recientemente que la marca de tiempo que especifique. Puede utilizar esta expresión para promocionar nuevos elementos en las recomendaciones.


INCLUDE ItemID WHERE Items.CREATION_TIMESTAMP > $DATE

La siguiente expresión muestra cómo puede aplicar un filtro de solicitudes a los elementos promocionados. Incluye solo las prendas de vestir disponibles como elementos promocionados. En este escenario, también se usaría Items.AVAILABLE IN ("True") en la expresión del filtro de solicitudes, de modo que todas las recomendaciones se refieran a los elementos que están disponibles.


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

Para obtener una lista más completa de ejemplos de filtro, consulte Ejemplos de expresiones de filtro.

Promocionar artículos nuevos

Si utilizas elReceta V2 de personalización por parte del usuario, Amazon Personalize recomienda los artículos más relevantes a los usuarios y, con mayor frecuencia, recomienda los artículos existentes con datos de interacciones. Para asegurarte de que las recomendaciones incluyen algunos artículos nuevos, puedes aplicar una promoción a las solicitudes de recomendación que incluya artículos en función de la fecha y hora de creación.

Si aún no utilizas una promoción, la expresión de filtro puede promocionar artículos creados después de una fecha determinada:


INCLUDE ItemID WHERE Items.CREATION_TIMESTAMP > $DATE

Si ya utilizas una promoción, debes crear una expresión que vincule tanto la declaración de estado de la promoción como la del nuevo artículo:


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

Promoción de elementos (consola)

Para promocionar determinados elementos de las recomendaciones con la consola Amazon Personalize, cree un filtro y, a continuación, proporcione los detalles de la promoción en la solicitud de recomendación. Para obtener información sobre los demás campos, consulte Obtención de recomendaciones de elementos (consola).

Para promocionar los elementos de las recomendaciones

Abra la consola de Amazon Personalize en https://console.aws.amazon.com/personalize/home e inicie sesión en su cuenta.
Elija el grupo de conjuntos de datos que contenga la campaña o el recomendador que esté utilizando.
Si aún no lo ha hecho, debe crear un filtro que especifique los criterios de promoción. Los filtros para las promociones se crean del mismo modo que los filtros de solicitudes. Para obtener más información acerca de cómo se crean y se administran filtros, consulte Filtrado de resultados.
En el panel de navegación, seleccione Recomendadores o Campañas.
Elija la campaña o el recomendador objetivo.
En el caso de las campañas, en Probar resultado de la campaña, introduzca los detalles de la solicitud de recomendación en función de la receta que haya utilizado. En el caso de los recomendadores, seleccione Probar recomendador e indique detalles de la solicitud de recomendación.
Si lo desea, elija un filtro para la solicitud. Este filtro se aplica únicamente a los elementos no promocionados. Para obtener más información acerca de cómo se crean y se administran filtros, consulte Filtrado de resultados.
Si utiliza metadatos contextuales, proporcione datos para cada contexto. Para cada contexto, introduzca el campo de metadatos para la Clave. Para el Valor, introduzca los datos de contexto. Para obtener más información, consulte Aumento de la relevancia de las recomendaciones con metadatos contextuales.
Para la promoción, especifique lo siguiente:
- Porcentaje de elementos promocionados: indique el porcentaje de elementos recomendados a los que se aplicará la promoción.
- Filtro: elija un filtro que especifique los criterios de promoción. Este filtro se aplica a los elementos promocionados en lugar de a cualquier filtro de solicitud que haya especificado en el paso 7.
- Parámetro de filtro: si la promoción usa un filtro con parámetros de marcador de posición, indique el valor para establecer los criterios del filtro para cada parámetro. Para usar varios valores para un parámetro, separe cada valor con una coma.
Elija Obtener recomendaciones. Aparece una tabla con los 25 elementos más recomendados por el usuario. La columna Artículo promocionado indica si el elemento se incluyó debido a su promoción. Los elementos promocionados se colocan aleatoriamente en relación con otros elementos recomendados, pero ordenados en relación con otros elementos promocionados. Según el caso de uso o la receta, los elementos recomendados que no forman parte de una promoción se ordenan por relevancia para el usuario, popularidad o similitud. Si no hay suficientes elementos que cumplan los criterios de la promoción, el resultado incluirá tantos elementos promocionados como sea posible.

Promoción de elementos (AWS CLI)

En el siguiente código se muestra cómo promocionar artículos en las recomendaciones con la campaña AWS CLI y con una campaña personalizada. Para promocionar elementos con un recomendador, sustituya el parámetro campaign-arn por recommender-arn y especifique el nombre de recurso de Amazon (ARN) del recomendador. Para los campos de promoción, especifique lo siguiente:

name: asigne un nombre a la promoción. La respuesta a la recomendación utiliza el nombre para identificar los elementos promocionados.
percent-promoted-items: el porcentaje de artículos recomendados a los que se aplicará la promoción. En este ejemplo, el 50 % de los elementos serán elementos promocionados.
filterArn: especifique el nombre de recurso de Amazon (ARN) del filtro que define los criterios de promoción. Para obtener más información, consulte Filtros de promoción.
nombres y valores de los parámetros: si la expresión de filtro tiene algún parámetro, proporcione los nombres de los parámetros (teniendo en cuenta que se distingue entre mayúsculas y minúsculas) y los valores. Por ejemplo, si la expresión de filtro tiene un parámetro $GENRE, indique GENRE como la clave y uno o varios géneros, como Comedia, como valor. Separe los valores con comas. Si usas el AWS CLI, para cada valor debes usar el / carácter para evitar tanto las comillas como el / carácter. El siguiente ejemplo de código muestra cómo aplicar formato a los valores.

El código muestra cómo utilizar un filtro de solicitud y un filtro de promoción. Un filtro de promoción se aplica solo a los elementos en promoción, mientras que un filtro de solicitud se aplica solo al resto de los elementos recomendados. Para obtener más información, consulte Filtros de promoción.

Para obtener más información sobre los campos adicionales, consulte Obtener recomendaciones de artículos (SDK)AWS y Obtención de una clasificación personalizada con metadatos contextuales.


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

Aparece una lista de elementos recomendados. Los elementos promocionados se colocan aleatoriamente en relación con otros elementos recomendados, pero ordenados en relación con otros elementos promocionados. Según la receta, los elementos recomendados que no forman parte de una promoción se ordenan por relevancia para el usuario, popularidad o similitud. Si no hay suficientes elementos que cumplan los criterios de la promoción, el resultado incluirá tantos elementos promocionados como sea posible.


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

Artículos de promoción (AWS SDK)

En el siguiente código, se muestra cómo promocionar los elementos de las recomendaciones con el SDK para Python (Boto3) y el SDK para Java 2.x y una campaña personalizada. Para promocionar elementos con un recomendador, sustituya el parámetro campaignArn por recommenderArn y especifique el nombre de recurso de Amazon (ARN) del recomendador. Para los campos de promoción, especifique lo siguiente:

name: especifique el nombre de la promoción. La respuesta a la recomendación incluye el nombre para identificar los elementos promocionados.
percentPromotedItems: el porcentaje de artículos recomendados a los que se aplicará la promoción.
promotionFilterARN: el nombre de recurso de Amazon (ARN) del filtro que define los criterios de promoción. Para obtener más información, consulte Filtros de promoción.
Nombres y valores de los parámetros: si la expresión de filtro tiene algún parámetro, proporcione los nombres de los parámetros (teniendo en cuenta que se distingue entre mayúsculas y minúsculas) y los valores para cada uno de ellos. Por ejemplo, si la expresión de filtro tiene un parámetro $GENRE, indique "GENRE" como la clave y uno o varios géneros, como "\"Comedia"\", como valor. Separe los valores con comas. Por ejemplo, "\"comedy\",\"drama\",\"horror"\".

El código siguiente muestra cómo utilizar un filtro de solicitud y un filtro de promoción. Un filtro de promoción se aplica solo a los elementos en promoción, mientras que un filtro de solicitud se aplica solo al resto de los elementos recomendados. Para obtener más información, consulte Filtros de promoción.

Para obtener más información sobre los campos adicionales, consulte Obtener recomendaciones de artículos (SDK)AWS y Obtención de una clasificación personalizada con metadatos contextuales.

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

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Obtener recomendaciones de artículos (SDK)AWS

Obtención de recomendaciones de acciones