Personalizar recomendações com o AWS Lambda

No Amazon Pinpoint, você pode recuperar recomendações personalizadas de um modelo de recomendação e adicioná-las a mensagens enviadas de campanhas e jornadas. Um modelo de recomendação é um tipo de modelo de machine learning (ML) que encontra padrões em dados e gera previsões e recomendações com base nos padrões encontrados. Ele prevê o que um determinado usuário preferirá de um determinado conjunto de produtos ou itens, e fornece essas informações como um conjunto de recomendações para o usuário.

Usando modelos de recomendação com o Amazon Pinpoint, você pode enviar recomendações personalizadas para destinatários de mensagens com base nos atributos e no comportamento de cada destinatário. Com o AWS Lambda, você também pode personalizar e aprimorar essas recomendações. Por exemplo, você pode transformar dinamicamente uma recomendação de um único valor de texto (como um nome ou ID de produto) para conteúdo mais sofisticado (como nome de produto, descrição e imagem). E você pode fazer isso em tempo real, quando o Amazon Pinpoint envia a mensagem.

Esse atributo está disponível nas seguintes Regiões da AWS: Leste dos EUA (Norte da Virgínia); Oeste dos EUA (Oregon); Ásia-Pacífico (Mumbai); Ásia-Pacífico (Sydney) e Europa (Irlanda).

Usar recomendações em mensagens

Para usar um modelo de recomendação com o Amazon Pinpoint, comece criando uma solução do Amazon Personalize e implantando essa solução como uma campanha do Amazon Personalize. Depois disso, crie uma configuração para o modelo de recomendação no Amazon Pinpoint. Na configuração, você especifica configurações que determinam como recuperar e processar dados de recomendação da campanha do Amazon Personalize. Isso inclui se uma função do AWS Lambda deve ser invocada para executar processamento adicional dos dados recuperados.

O Amazon Personalize é um serviço da AWS projetado para ajudar você a criar modelos de ML que fornecem recomendações personalizadas em tempo real para clientes que usam os aplicativos criados por você. O Amazon Personalize fornece orientação no processo de criação e treinamento de um modelo de ML e, em seguida, na preparação e implantação do modelo como uma campanha do Amazon Personalize. Depois, você pode recuperar recomendações personalizadas em tempo real da campanha. Para saber mais sobre o Amazon Personalize, consulte o Guia do desenvolvedor do Amazon Personalize.

O AWS Lambda é um serviço de computação que pode ser usado para executar código sem provisionamento ou gerenciamento de servidores. Você empacota o código e faz upload dele no AWS Lambda como uma função do Lambda. O AWS Lambda então executa a função quando ela é invocada. Você pode invocar uma função manual e automaticamente em resposta a eventos ou em resposta a solicitações de aplicativos ou serviços, incluindo o Amazon Pinpoint. Para obter mais informações sobre criar e invocar funções do Lambda, consulte o Guia do desenvolvedor do AWS Lambda.

Depois de criar uma configuração do Amazon Pinpoint para um modelo de recomendação, você pode adicionar recomendações do modelo às mensagens enviadas de campanhas e jornadas. Faça isso usando modelos de mensagens que contêm variáveis de mensagem para os atributos recomendados. Um atributo recomendado é um endpoint dinâmico ou um atributo de usuário projetado para armazenar dados de recomendação. Você define esses atributos ao criar a configuração para um modelo de recomendação.

Você pode usar variáveis para atributos recomendados nos seguintes tipos de modelos de mensagens:

• Modelos de e-mail, para mensagens de e-mail que você envia de campanhas ou jornadas.

• Modelos de notificação por push, para as notificações por push enviadas de campanhas.

• Modelos de SMS, para mensagens de texto SMS enviadas de campanhas.

Para obter mais informações sobre como usar modelos de recomendação com o Amazon Pinpoint, consulte Modelos de machine learning no Guia do usuário do Amazon Pinpoint.

Se você configurar o Amazon Pinpoint para invocar uma função do Lambda que processa dados de recomendação, o Amazon Pinpoint executará as seguintes tarefas gerais sempre que enviar recomendações personalizadas em uma mensagem para uma campanha ou jornada:

1. Avalia e processa as definições de configuração e o conteúdo da mensagem e do modelo de mensagem.

2. Determina que o modelo de mensagem está conectado a um modelo de recomendação.

3. Avalia as definições da configuração de conexão e uso do modelo. Essas são definidas pelo recurso Modelo de recomendação do modelo.

4. Detecta uma ou mais variáveis de mensagem para atributos recomendados definidos pelas definições de configuração do modelo.

5. Recupera dados de recomendação da campanha do Amazon Personalize especificada nas configurações do modelo. Ele usa a operação GetRecommendations da API de runtime do Amazon Personalize para executar essa tarefa.

6. Adiciona os dados de recomendação apropriados a um atributo dinâmico recomendado (RecommendationItems) para cada destinatário da mensagem.

7. Invoca sua função do Lambda e envia os dados de recomendação para cada destinatário dessa função para processamento.

   Os dados são enviados como um objeto JSON que contém a definição do endpoint de cada destinatário. Cada definição de endpoint inclui um campo RecommendationItems que contém uma matriz ordenada de valores de 1 a 5. O número de valores na matriz depende das definições de configuração do modelo.

8. Aguarda que sua função do Lambda processe os dados e retorne os resultados.

   Os resultados são um objeto JSON que contém uma definição de endpoint atualizada para cada destinatário. Cada definição de endpoint atualizada contém um novo objeto Recommendations Esse objeto contém de 1 a 10 campos, um para cada atributo personalizado recomendado que você definiu nas configurações do modelo. Cada um desses campos armazena dados de recomendação aprimorados para o endpoint.

9. Usa a definição do endpoint atualizada para cada destinatário para substituir cada variável de mensagem pelo valor apropriado para esse destinatário.

10. Envia uma versão da mensagem que contém as recomendações personalizadas para cada destinatário da mensagem.

Para personalizar e aprimorar as recomendações dessa maneira, comece criando uma função do Lambda que processa as definições de endpoint enviadas pelo Amazon Pinpoint e retorna definições de endpoint atualizadas. Depois disso, atribua uma política de função do Lambda à função e autorize o Amazon Pinpoint a invocar a função. Depois, configure o modelo de recomendação no Amazon Pinpoint. Ao configurar o modelo, especifique a função a ser invocada e defina os atributos recomendados a serem usados.

Criar a função do Lambda

Para saber como criar uma função do Lambda, consulte Conceitos básicos no Guia do desenvolvedor do AWS Lambda. Ao projetar e desenvolver sua função, lembre-se dos seguintes requisitos e diretrizes.

Dados de evento de entrada

Quando o Amazon Pinpoint invoca uma função do Lambda para um modelo de recomendação, ele envia uma carga que contém a configuração e outras definições da campanha ou jornada que está enviando a mensagem. A carga útil inclui um objeto Endpoints, que é um mapa que associa IDs de endpoint a definições de endpoint para os destinatários de mensagem.

As definições de endpoint usam a estrutura definida pelo recurso Endpoint da API do Amazon Pinpoint. No entanto, elas também incluem um campo para um atributo recomendado dinâmico chamado RecommendationItems. O campo RecommendationItems contém um ou mais itens recomendados para o endpoint, conforme retornado pela campanha do Amazon Personalize. O valor desse campo é uma matriz ordenada de 1 a 5 itens recomendados (como cadeias de caracteres). O número de itens na matriz depende do número de itens recomendados que você configurou o Amazon Pinpoint para recuperar para cada endpoint ou usuário.

Por exemplo:

"Endpoints": {
    "endpointIDexample-1":{
        "ChannelType":"EMAIL",
        "Address":"[e-mail]",
        "EndpointStatus":"ACTIVE",
        "OptOut":"NONE",
        "EffectiveDate":"2020-02-26T18:56:24.875Z",
        "Attributes":{
            "AddressType":[
                "primary"
            ]
        },
        "User":{
            "UserId":"SofiaMartínez",
            "UserAttributes":{
                "LastName":[
                    "Martínez"
                ],
                "FirstName":[
                    "Sofia"
                ],
                "Neighborhood":[
                    "East Bay"
                ]
            }
        },
        "RecommendationItems":[
            "1815",
            "2009",
            "1527"
        ],
        "CreationDate":"2020-02-26T18:56:24.875Z"
    },
    "endpointIDexample-2":{
        "ChannelType":"EMAIL",
        "Address":"[e-mail]",
        "EndpointStatus":"ACTIVE",
        "OptOut":"NONE",
        "EffectiveDate":"2020-02-26T18:56:24.897Z",
        "Attributes":{
            "AddressType":[
                "primary"
            ]
        },
        "User":{
            "UserId":"AlejandroRosalez",
            "UserAttributes":{
                "LastName ":[
                    "Rosalez"
                ],
                "FirstName":[
                    "Alejandro"
                ],
                "Neighborhood":[
                    "West Bay"
                ]
            }
        },
        "RecommendationItems":[
            "1210",
            "6542",
            "4582"
        ],
        "CreationDate":"2020-02-26T18:56:24.897Z"
    }
}

No exemplo anterior, as configurações relevantes do Amazon Pinpoint são:

• O modelo de recomendação é configurado para recuperar três itens recomendados para cada endpoint ou usuário. (O valor da propriedade RecommendationsPerMessage é definido como 3.) Com essa configuração, o Amazon Pinpoint recupera e adiciona apenas o primeiro, o segundo e o terceiro item recomendado para cada endpoint ou usuário.

• O projeto está configurado para usar atributos de usuário personalizados que armazenam o nome, o sobrenome e a região em que vivem. (O objeto UserAttributes contém os valores desses atributos.)

• O projeto está configurado para usar um atributo de endpoint personalizado (AddressType) que indica se o endpoint é o endereço preferido do usuário (canal) para receber mensagens do projeto. (O objeto Attributes contém o valor desse atributo.)

Quando o Amazon Pinpoint invoca a função do Lambda e envia essa carga útil como os dados do evento, o AWS Lambda passa os dados para a função do Lambda para processamento.

Cada carga pode conter dados para até 50 endpoints. Se um segmento contiver mais de 50 endpoints, o Amazon Pinpoint invocará a função repetidamente, para até 50 endpoints de cada vez, até que a função processe todos os dados.

Dados e requisitos de resposta

Ao projetar e desenvolver sua função do Lambda, lembre-se das cotas de modelos de machine learning. Se a função não atender às condições definidas por essas cotas, o Amazon Pinpoint não poderá processar e enviar a mensagem.

Lembre-se também dos seguintes requisitos:

• A função deve retornar definições de endpoint atualizadas no mesmo formato fornecido pelos dados do evento de entrada.

• Cada definição de endpoint atualizada pode conter de 1 a 10 atributos personalizados recomendados para o endpoint ou usuário. Os nomes desses atributos devem corresponder aos nomes de atributos especificados ao configurar o modelo de recomendação no Amazon Pinpoint.

• Todos os atributos recomendados personalizados devem ser retornados em um único objeto Recommendations para cada endpoint ou usuário. Esse requisito ajuda a garantir que não ocorram conflitos de nomenclatura. Você pode adicionar o objeto Recommendations a qualquer local em uma definição de endpoint.

• O valor de cada atributo recomendado personalizado precisa ser uma string (valor único) ou uma matriz de strings (vários valores). Se o valor for uma matriz de cadeia de caracteres, recomendamos manter a ordem dos itens recomendados retornados pelo Amazon Personalize, conforme indicado no campo RecommendationItems. Caso contrário, seu conteúdo pode não refletir as previsões do modelo para um endpoint ou usuário.

• A função não deve modificar outros elementos nos dados do evento, incluindo outros valores de atributos para um endpoint ou usuário. Ele só deve adicionar e retornar valores para atributos personalizados recomendados. O Amazon Pinpoint não aceitará atualizações em nenhum outro valor na resposta da função.

• A função deve ser hospedada na mesma Região da AWS que o projeto do Amazon Pinpoint que está invocando a função. Se a função e o projeto não estiverem na mesma Região, o Amazon Pinpoint não poderá enviar dados de evento para a função.

Se qualquer um dos requisitos anteriores não for atendido, o Amazon Pinpoint não poderá processar e enviar a mensagem para um ou mais endpoints. Isso pode fazer com que uma atividade de campanha ou de jornada falhe.

Finalmente, recomendamos reservar 256 execuções simultâneas para a função.

No geral, a função do Lambda deve processar os dados de evento enviados pelo Amazon Pinpoint e retornar definições de endpoint modificadas. Ela pode fazer isso percorrendo cada endpoint no objeto Endpoints e, para cada endpoint, criando e definindo valores para os atributos recomendados personalizados que você deseja usar. O manipulador de exemplo a seguir, escrito em Python e continuando com o exemplo anterior de dados de evento de entrada, mostra o seguinte:

import json
import string
 
def lambda_handler(event, context):
    print("Received event: " + json.dumps(event))
    print("Received context: " +  str(context))
    segment_endpoints = event["Endpoints"]
    new_segment = dict()
    for endpoint_id in segment_endpoints.keys():
        endpoint = segment_endpoints[endpoint_id]
        if supported_endpoint(endpoint):
            new_segment[endpoint_id] = add_recommendation(endpoint)
 
    print("Returning endpoints: " + json.dumps(new_segment))
    return new_segment
 
def supported_endpoint(endpoint):
    return True
 
def add_recommendation(endpoint):
    endpoint["Recommendations"] = dict()
 
    customTitleList = list()
    customGenreList = list()
    for i,item in enumerate(endpoint["RecommendationItems"]):
        item = int(item)
        if item == 1210:
            customTitleList.insert(i, "Hanna")
            customGenreList.insert(i, "Action")
        elif item == 1527:
            customTitleList.insert(i, "Catastrophe")
            customGenreList.insert(i, "Comedy")
        elif item == 1815:
            customTitleList.insert(i, "Fleabag")
            customGenreList.insert(i, "Comedy")
        elif item == 2009:
            customTitleList.insert(i, "Late Night")
            customGenreList.insert(i, "Drama")
        elif item == 4582:
            customTitleList.insert(i, "Agatha Christie\'s The ABC Murders")
            customGenreList.insert(i, "Crime")
        elif item == 6542:
            customTitleList.insert(i, "Hunters")
            customGenreList.insert(i, "Drama")
        
    endpoint["Recommendations"]["Title"] = customTitleList
    endpoint["Recommendations"]["Genre"] = customGenreList
    
    return endpoint

No exemplo anterior, o AWS Lambda passa os dados do evento para o manipulador como o parâmetro event. O manipulador percorre cada endpoint no objeto Endpoints e define valores para os atributos recomendados personalizados nomeados Recommendations.Title e Recommendations.Genre. A instrução return retorna cada definição de endpoint atualizada para o Amazon Pinpoint.

Continuando com o exemplo anterior de dados de evento de entrada, as definições de endpoint atualizadas são:

"Endpoints":{
    "endpointIDexample-1":{
        "ChannelType":"EMAIL",
        "Address":"[e-mail]",
        "EndpointStatus":"ACTIVE",
        "OptOut":"NONE",
        "EffectiveDate":"2020-02-26T18:56:24.875Z",
        "Attributes":{
            "AddressType":[
                "primary"
            ]
        },
        "User":{
            "UserId":"SofiaMartínez",
            "UserAttributes":{
                "LastName":[
                    "Martínez"
                ],
                "FirstName":[
                    "Sofia"
                ],
                "Neighborhood":[
                    "East Bay"
                ]
            }
        },
        "RecommendationItems":[
            "1815",
            "2009",
            "1527"
        ],
        "CreationDate":"2020-02-26T18:56:24.875Z",
        "Recommendations":{
            "Title":[
                "Fleabag",
                "Late Night",
                "Catastrophe"
            ],
            "Genre":[
                "Comedy",
                "Comedy",
                "Comedy"
            ]
        }
    },
    "endpointIDexample-2":{
        "ChannelType":"EMAIL",
        "Address":"[e-mail]",
        "EndpointStatus":"ACTIVE",
        "OptOut":"NONE",
        "EffectiveDate":"2020-02-26T18:56:24.897Z",
        "Attributes":{
            "AddressType":[
                "primary"
            ]
        },
        "User":{
            "UserId":"AlejandroRosalez",
            "UserAttributes":{
                "LastName ":[
                    "Rosalez"
                ],
                "FirstName":[
                    "Alejandro"
                ],
                "Neighborhood":[
                    "West Bay"
                ]
            }
        },
        "RecommendationItems":[
            "1210",
            "6542",
            "4582"
        ],
        "CreationDate":"2020-02-26T18:56:24.897Z",
        "Recommendations":{
            "Title":[
                "Hanna",
                "Hunters",
                "Agatha Christie\'s The ABC Murders"
            ],
            "Genre":[
                "Action",
                "Drama",
                "Crime"
            ]
        }
    }
}

No exemplo anterior, a função modificou o objeto Endpoints que recebeu e retornou os resultados. O objeto Endpoint de cada endpoint agora contém um novo objeto Recommendations que contém os campos Title e Genre. Cada um desses campos armazena uma matriz ordenada de três valores (como strings), onde cada valor fornece conteúdo aprimorado para um item recomendado correspondente no campo RecommendationItems.

Atribuir uma política de função do Lambda

Antes de usar a função do Lambda para processar dados de recomendação, você deve autorizar o Amazon Pinpoint a invocar a função. Para conceder permissão de invocação, atribua uma política de função do Lambda à função. A política de função do Lambda é uma política de permissões baseada em recursos que designa as entidades que podem usar uma função e quais ações essas entidades podem executar. Para mais informações, consulte Uso de políticas com base em recursos para o AWS Lambda no Guia do usuário do AWS Lambda.

A política de exemplo a seguir permite que a entidade principal do serviço do Amazon Pinpoint use a ação lambda:InvokeFunction para uma campanha específica do Amazon Pinpoint (campaignId) em um projeto específico do Amazon Pinpoint (projectId):

{
  "Sid": "sid",
  "Effect": "Allow",
  "Principal": {
    "Service": "pinpoint.us-east-1.amazonaws.com"
  },
  "Action": "lambda:InvokeFunction",
  "Resource": "{arn:aws:lambda:us-east-1:accountId:function:function-name}",
  "Condition": {
    "ArnLike": {
      "AWS:SourceArn": "arn:aws:mobiletargeting:us-east-1:accountId:recommenders/*"
    }
  }
}

A política de função requer um bloco Condition que inclua uma chave AWS:SourceArn. Essa chave especifica qual recurso tem permissão para invocar a função. No exemplo anterior, a política permite que uma campanha específica chame a função.

Você também pode escrever uma política que permita que a entidade principal do serviço do Amazon Pinpoint use a ação lambda:InvokeFunction para todas as campanhas e jornadas em um projeto específico do Amazon Pinpoint (projectId). A política de exemplo a seguir mostra isso:

{
  "Sid": "sid",
  "Effect": "Allow",
  "Principal": {
    "Service": "pinpoint.us-east-1.amazonaws.com"
  },
  "Action": "lambda:InvokeFunction",
  "Resource": "{arn:aws:lambda:us-east-1:accountId:function:function-name}",
  "Condition": {
    "ArnLike": {
      "AWS:SourceArn": "arn:aws:mobiletargeting:us-east-1:accountId:recommenders/*"
    }
  }
}

Ao contrário do primeiro exemplo, a chave AWS:SourceArn no bloco Condition deste exemplo permite que um projeto específico chame a função. Essa permissão aplica-se a todas as campanhas e jornadas do projeto.

Para escrever uma política mais genérica, use um caractere curinga (*) que corresponda a vários caracteres. Por exemplo, você pode usar o seguinte bloco Condition para permitir que qualquer projeto do Amazon Pinpoint invoque a função:

"Condition": {
  "ArnLike": {
    "AWS:SourceArn": "arn:aws:mobiletargeting:us-east-1:accountId:recommenders/*"
  }
}

Para usar a função do Lambda com todos os projetos da sua conta do Amazon Pinpoint, recomendamos configurar o bloco Condition da política da maneira anterior. No entanto, para usar melhores práticas, crie políticas que incluem apenas as permissões necessárias para executar uma ação específica em um recurso específico.

Autorizar o Amazon Pinpoint a invocar a função

Depois de atribuir uma política de função do Lambda à função, você pode adicionar permissões que permitem que o Amazon Pinpoint invoque a função para um projeto, campanha ou jornada específico. Você pode fazer isso usando o AWS Command Line Interface (AWS CLI) e o comando do Lambda add-permission. O exemplo a seguir mostra como fazer isso para um projeto específico (projectId):

$ aws lambda add-permission \
--function-name function-name \
--statement-id sid \
--action lambda:InvokeFunction \
--principal pinpoint.us-east-1.amazonaws.com \
--source-arn arn:aws:mobiletargeting:us-east-1:accountId:recommenders/*

O exemplo anterior está formatado para Unix, Linux e macOS. Para o Microsoft Windows, substitua o caractere de continuação de linha de barra invertida (\) por um circunflexo (^).

Se o comando for executado com êxito, você verá um resultado semelhante a este:

{
  "Statement": "{\"Sid\":\"sid\",
    \"Effect\":\"Allow\",
    \"Principal\":{\"Service\":\"pinpoint.us-east-1.amazonaws.com\"},
    \"Action\":\"lambda:InvokeFunction\",
    \"Resource\":\"arn:aws:lambda:us-east-1:111122223333:function:function-name\",
    \"Condition\":
      {\"ArnLike\":
        {\"AWS:SourceArn\":
         \"arn:aws:mobiletargeting:us-east-1:111122223333:recommenders/*\"}}}"
}

O valor de Statement é uma versão da cadeia de caracteres JSON da instrução adicionada à política da função do Lambda.

Configurar o modelo do recomendação

Para configurar o Amazon Pinpoint para invocar a função do Lambda de um modelo de recomendação, especifique as seguintes definições de configuração específicas ao Lambda para o modelo:

• RecommendationTransformerUri: esta propriedade especifica o nome ou o nome do recurso da Amazon (ARN) da função do Lambda.

• Attributes: este objeto é um mapa que define os atributos recomendados personalizados que a função adiciona a cada definição de endpoint. Cada um desses atributos pode ser usado como uma variável de mensagem em um modelo de mensagem.

É possível especificar essas configurações usando o recurso Modelos de recomendação da API do Amazon Pinpoint (ao criar a configuração de um modelo) ou o recurso Modelo de recomendação da API do Amazon Pinpoint (se você atualizar a configuração de um modelo). Também é possível definir essas configurações usando o console do Amazon Pinpoint.

Para obter mais informações sobre como usar modelos de recomendação com o Amazon Pinpoint, consulte Modelos de machine learning no Guia do usuário do Amazon Pinpoint.