Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Personalizzazione dei segmenti con AWS Lambda

È possibile utilizzare AWS Lambda per personalizzare il modo in cui una campagna Amazon Pinpoint coinvolge i destinatari. Con AWS Lambda, è possibile modificare il segmento della campagna nel momento in cui Amazon Pinpoint invia il messaggio.

AWS Lambda è un servizio di calcolo che consente di eseguire il codice senza gestire i server o effettuarne il provisioning. È possibile creare pacchetti di codice e quindi caricarli in Lambda come funzioni Lambda. Lambda esegue una funzione quando la funzione viene richiesta, manualmente o in modo automatico, in risposta a eventi. Per ulteriori informazioni, consulta la Guida per gli sviluppatori di AWS Lambda.

Per assegnare una funzione Lambda a una campagna, definisci le impostazioni CampaignHook della campagna utilizzando la risorsa Campagna nell'API Amazon Pinpoint. Tali impostazioni includono il nome della funzione Lambda e la modalità CampaignHook, che specifica se Amazon Pinpoint riceve un valore restituito dalla funzione.

Una funzione Lambda assegnata a una campagna viene definita estensione di Amazon Pinpoint.

Dopo aver definito le impostazioni CampaignHook, Amazon Pinpoint richiama automaticamente la funzione Lambda quando esegue la campagna, prima di inviare il messaggio della campagna. Quando Amazon Pinpoint richiama la funzione, fornisce dati di evento che si riferiscono al recapito del messaggio. Questi dati includono il segmento della campagna, ovvero l'elenco degli endpoint a cui Amazon Pinpoint invia il messaggio.

Se la modalità CampaignHook è impostata su FILTER, Amazon Pinpoint consente alla funzione di modificare e restituire il segmento prima di inviare il messaggio. Ad esempio, è possibile che la funzione aggiorni le definizioni di endpoint con attributi contenenti i dati provenienti da un'origine esterna ad Amazon Pinpoint. Oppure potrebbe filtrare il segmento rimuovendo determinati endpoint, in base alle condizioni indicate nel tuo codice di funzione. Dopo che ha ricevuto il segmento modificato dalla funzione, Amazon Pinpoint invia il messaggio a ciascun endpoint del segmento utilizzando il canale di distribuzione della campagna.

Elaborando i segmenti con AWS Lambda, si dispone di maggiore controllo sugli utenti a cui inviare messaggi e sul contenuto dei messaggi stessi. È possibile personalizzare le campagne in tempo reale, nel momento in cui vengono inviati i messaggi. L'applicazione di filtri ai segmenti consente di coinvolgere sottoinsiemi di segmenti definiti in modo più specifico. L'aggiunta o l'aggiornamento di attributi di endpoint permette anche di rendere disponibili nuovi dati per le variabili dei messaggi.

Per modificare i segmenti di una campagna con AWS Lambda, è prima necessario creare una funzione che elabori i dati relativi agli eventi inviati da Amazon Pinpoint e restituisca un segmento modificato. Quindi, autorizza Amazon Pinpoint a richiamare la funzione assegnando una policy di funzione Lambda. Infine, bisogna assegnare la funzione a una o più campagne definendo le impostazioni CampaignHook.

Dati eventi

Quando richiama la funzione Lambda, Amazon Pinpoint fornisce il payload seguente come dati degli eventi:

{
  "MessageConfiguration": {Message configuration}
  "ApplicationId": ApplicationId,
  "CampaignId": CampaignId,
  "TreatmentId": TreatmentId,
  "ActivityId": ActivityId,
  "ScheduledTime": Scheduled Time,
  "Endpoints": {
    EndpointId: {Endpoint definition}
    . . .
  }
}

AWS Lambda trasferisce i dati di evento al codice di funzione. I dati sugli eventi forniscono gli attributi seguenti:

Creazione di una funzione Lambda

Per informazioni su come creare una funzione Lambda, consulta Guida introduttiva nella Guida per gli sviluppatori di AWS Lambda. Quando crei una funzione, tieni presente che la consegna del messaggio non riesce quando si verificano le seguenti condizioni:

Amazon Pinpoint accetta solo definizioni di endpoint nel valore restituito della funzione. La funzione non può modificare altri elementi nei dati di evento.

Funzione Lambda di esempio

La funzione Lambda elabora i dati degli eventi inviati da Amazon Pinpoint e restituisce l'endpoint modificato, come illustrato dal seguente gestore di esempio, scritto in Node.js:

'use strict';
 
exports.handler = (event, context, callback) => {
    for (var key in event.Endpoints) {
        if (event.Endpoints.hasOwnProperty(key)) {
            var endpoint = event.Endpoints[key];
            var attr = endpoint.Attributes;
            if (!attr) {
                attr = {};
                endpoint.Attributes = attr;
            }
            attr["CreditScore"] = [ Math.floor(Math.random() * 200) + 650];
        }
    }
    console.log("Received event:", JSON.stringify(event, null, 2));
    callback(null, event.Endpoints);
};

Lambda trasferisce i dati degli eventi al gestore come parametro event.

In questo esempio il gestore scorre tutti gli endpoint nell'oggetto event.Endpoints e aggiunge un nuovo attributo, CreditScore, all'endpoint. Il valore dell'attributo CreditScore è semplicemente un numero casuale.

L'istruzione console.log() registra l'evento nei file di log CloudWatch.

L'istruzione callback() restituisce gli endpoint modificati ad Amazon Pinpoint. Di solito, il parametro callback è facoltativo nelle funzioni Lambda Node.js, ma in questo contesto è obbligatorio perché la funzione deve restituire ad Amazon Pinpoint gli endpoint aggiornati.

La funzione deve restituire gli endpoint nello stesso formato dei dati di evento, che fornisce una mappa di associazioni di ID e definizioni degli endpoint, come nell'esempio seguente:

{
    "eqmj8wpxszeqy/b3vch04sn41yw": {
        "ChannelType": "GCM",
        "Address": "4d5e6f1a2b3c4d5e6f7g8h9i0j1a2b3c",
        "EndpointStatus": "ACTIVE",
        "OptOut": "NONE",
        "Demographic": {
            "Make": "android"
        },
        "EffectiveDate": "2017-11-02T21:26:48.598Z",
        "User": {}
    },
    "idrexqqtn8sbwfex0ouscod0yto": {
        "ChannelType": "APNS",
        "Address": "1a2b3c4d5e6f7g8h9i0j1a2b3c4d5e6f",
        "EndpointStatus": "ACTIVE",
        "OptOut": "NONE",
        "Demographic": {
            "Make": "apple"
        },
        "EffectiveDate": "2017-11-02T21:26:48.598Z",
        "User": {}
    }
}

La funzione di esempio modifica e restituisce l'oggetto event.Endpoints ricevuto nei dati di evento.

Facoltativamente, è possibile includere gli attributi TitleOverride e BodyOverride nelle definizioni degli endpoint che vengono restituite.

Assegnazione di una policy di funzione Lambda

Prima di utilizzare la funzione Lambda per elaborare gli endpoint, è necessario autorizzare Amazon Pinpoint a richiamare la funzione Lambda. Per concedere l'autorizzazione per l'invocazione, assegna una policy di funzione Lambda alla funzione. Una policy di funzione Lambda è una policy di autorizzazione basata su risorse che designa le entità che possono utilizzare la funzione e le azioni che tali entità possono eseguire.

Per ulteriori informazioni, consulta Uso delle policy basate sulle risorse per AWS Lambda nella Guida per gli sviluppatori di AWS Lambda.

Policy di funzione di esempio

La policy seguente autorizza l'entità principale del servizio Amazon Pinpoint a utilizzare l'azione lambda:InvokeFunction per una campagna specifica (campaign-id):

{
  "Sid": "sid",
  "Effect": "Allow",
  "Principal": {
    "Service": "pinpoint.us-east-1.amazonaws.com"
  },
  "Action": "lambda:InvokeFunction",
  "Resource": "{arn:aws:lambda:us-east-1:account-id:function:function-name}",
  "Condition": {
    "StringEquals": {
      "AWS:SourceAccount": "111122223333"
    },
    "ArnLike": {
      "AWS:SourceArn": "arn:aws:mobiletargeting:us-east-1:account-id:apps/application-id/campaigns/campaign-id"
    }
  }
}

La policy di funzione richiede un blocco Condition che includa una chiave AWS:SourceArn. Questo codice indica la campagna Amazon Pinpoint a cui è consentito richiamare la funzione. In questo esempio, la policy concede l'autorizzazione per una sola campagna. Il blocco Condition deve includere anche una chiave AWS:SourceAccount, che controlla quale account AWS può richiamare l'azione.

Per scrivere una policy più generica, utilizza un caratteri jolly di corrispondenza con più caratteri (*). Ad esempio, puoi usare il seguente blocco Condition per consentire a qualsiasi campagna in un progetto Amazon Pinpoint specifico (application-id) di richiamare la funzione:

...
"Condition": {
  "StringEquals": {
    "AWS:SourceAccount": "111122223333"
  },
  "ArnLike": {
    "AWS:SourceArn": "arn:aws:mobiletargeting:us-east-1:account-id:apps/application-id/campaigns/*"
  }
}
...

Se vuoi che la funzione Lambda sia la funzione predefinita utilizzata da tutte le campagne per un progetto, è consigliabile configurare il blocco Condition per la policy nel modo precedente. Per informazioni sull'impostazione di una funzione Lambda come predefinita per tutte le campagne in un progetto, consulta Assegnazione di una funzione Lambda a una campagna.

Concessione dell'autorizzazione di invocazione di Amazon Pinpoint

È possibile usare l'AWS Command Line Interface (AWS CLI) per aggiungere autorizzazioni alla policy di funzione Lambda assegnata alla funzione Lambda stessa. Per consentire ad Amazon Pinpoint di richiamare una funzione per una determinata campagna, usa il comando Lambda add-permission, come mostrato nell'esempio seguente:

$ aws lambda add-permission \
> --function-name function-name \
> --statement-id sid \
> --action lambda:InvokeFunction \
> --principal pinpoint.us-east-1.amazonaws.com \
> --source-account 111122223333
> --source-arn arn:aws:mobiletargeting:us-east-1:account-id:apps/application-id/campaigns/campaign-id

Puoi cercare gli ID delle campagne utilizzando il comando get-campaigns in AWS CLI. Puoi anche cercare l'ID dell'applicazione utilizzando il comando get-apps.

Quando esegui il comando Lambda add-permission, viene restituito l'output seguente:

{
  "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:apps/application-id/campaigns/campaign-id\"}}
      {\"StringEquals\": 
        {\"AWS:SourceAccount\": 
          \"111122223333\"}}}
}

Il valore di Statement è una versione in formato stringa JSON dell'istruzione aggiunta alla policy della funzione Lambda.

Assegnazione di una funzione Lambda a una campagna

È possibile assegnare una funzione Lambda a una campagna Amazon Pinpoint specifica. In alternativa, puoi impostare la funzione Lambda come predefinita per tutte le campagne in un progetto, tranne le campagne a cui assegni una funzione individualmente.

Per assegnare una funzione Lambda a una campagna specifica, utilizza l'API Amazon Pinpoint per creare o aggiornare un oggetto Campaign e definire il relativo attributo CampaignHook. Per impostare una funzione Lambda come predefinita per tutte le campagne in un progetto, crea o aggiorna la risorsa Settings per il progetto in questione e definisci il relativo oggetto CampaignHook.

In entrambi i casi, imposta gli attributi CampaignHook seguenti:

Con le impostazioni CampaignHook definite per una campagna, Amazon Pinpoint richiama la funzione Lambda specificata prima di inviare i messaggi della campagna. Amazon Pinpoint attende di ricevere gli endpoint modificati dalla funzione. Se riceve gli endpoint aggiornati, Amazon Pinpoint procede con il recapito dei messaggi utilizzando i dati aggiornati.