Anpassen von Segmenten mit AWS Lambda

Dies ist die Vorabdokumentation eines Features, das als öffentliche Beta-Version vorliegt. Änderungen sind vorbehalten.

Sie können AWS Lambda damit individuell anpassen, wie eine Amazon Pinpoint Pinpoint-Kampagne Ihre Zielgruppe anspricht. Mit AWS Lambda können Sie das Kampagnensegment in dem Moment ändern, in dem Amazon Pinpoint die Botschaft der Kampagne sendet.

AWS Lambda ist ein Rechenservice, mit dem Sie Code ausführen können, ohne Server bereitstellen oder verwalten zu müssen. Sie packen Ihren Code und laden ihn als Lambda-Funktionen in Lambda hoch. Lambda führt eine Funktion aus, wenn die Funktion ausgerufen wird, was manuell durch Sie oder automatisch als Reaktion auf Ereignisse passieren kann. Weitere Informationen finden Sie im AWS Lambda -Entwicklerhandbuch.

Um einer Kampagne eine Lambda-Funktion zuzuweisen, definieren Sie die CampaignHook-Einstellungen der Kampagne unter Verwendung der Ressource Kampagne in der Amazon-Pinpoint-API. Diese Einstellungen schließen den Namen der Lambda-Funktion ein. Sie schließen auch den CampaignHook-Modus ein, der festlegt, ob Amazon Pinpoint einen Rückgabewert aus der Funktion erhält.

Eine Lambda-Funktion, die Sie einer Kampagne zuweisen, wird als Amazon-Pinpoint-Erweiterung bezeichnet.

Mit den definierten CampaignHook-Einstellungen ruft Amazon Pinpoint automatisch die Lambda-Funktion auf, wenn die Kampagne ausgeführt wird, bevor die Nachricht der Kampagne gesendet wird. Wenn Amazon Pinpoint die Funktion aufruft, stellt es Ereignisdaten über die Nachrichtenzustellung bereit. Diese Daten schließen das Kampagnensegment ein. Dies ist die Liste der Endpunkte, an die Amazon Pinpoint die Nachricht sendet.

Wenn der CampaignHook-Modus auf FILTER gesetzt ist, gestattet Amazon Pinpoint der Funktion, das Segment zu ändern und zurückzugeben, bevor die Nachricht gesendet wird. Beispielsweise könnte die Funktion die Endpunktdefinitionen mit Attributen aktualisieren, die Daten aus einer Quelle außerhalb von Amazon Pinpoint enthalten. Die Funktion könnte das Segment auch filtern, indem bestimmte Endpunkte abhängig von den Bedingungen in Ihrem Funktionscode entfernt werden. Nachdem Amazon Pinpoint das geänderte Segment aus Ihrer Funktion erhalten hat, sendet es die Nachricht an alle Endpunkte des Segments unter Verwendung des Bereitstellungskanals der Kampagne.

Durch die Verarbeitung Ihrer Segmente haben Sie mehr Kontrolle darüber, an wen Sie Nachrichten senden und was diese Nachrichten enthalten. AWS Lambda Sie können Ihre Kampagnen in Echtzeit anpassen, wenn die Nachrichten der Kampagne Nachrichten gesendet werden. Das Filtern von Segmenten ermöglicht Ihnen, präziser definierte Untergruppen Ihrer Segmente anzusprechen. Das Hinzufügen oder Aktualisieren von Endpunkt-Attributen ermöglicht Ihnen, neue Daten für Nachrichtenvariablen bereitzustellen.

Anmerkung

Sie können auch die CampaignHook-Einstellungen verwenden, um eine Lambda-Funktion zuzuweisen, die die Nachrichtenzustellung verarbeitet. Diese Art Funktion ist nützlich, wenn Nachrichten über benutzerdefinierte Kanäle zugestellt werden sollen, die Amazon Pinpoint nicht unterstützt, z. B. Social Media-Plattformen. Weitere Informationen finden Sie unter Erstellen von benutzerdefinierten Kanälen in Amazon Pinpoint.

Wenn Sie einen Lambda-Hook mit Amazon Pinpoint aufrufen, muss sich die Lambda-Funktion auch in derselben Region wie das Amazon-Pinpoint-Projekt befinden.

Um Kampagnensegmente mit zu ändern AWS Lambda, erstellen Sie zunächst eine Funktion, die die von Amazon Pinpoint gesendeten Eventdaten verarbeitet und ein modifiziertes Segment zurückgibt. Anschließend autorisieren Sie Amazon Pinpoint, die Funktion aufzurufen, indem Sie eine Lambda-Funktionsrichtlinie zuweisen. Schließlich weisen Sie der Funktion eine oder mehrere Kampagnen zu, indem Sie die CampaignHook-Einstellungen definieren.

Weitere Codebeispiele finden Sie unter Codebeispiele.

Ereignisdaten

Wenn Amazon Pinpoint Ihre Lambda-Funktion aufruft, stellt es die folgende Nutzlast als Ereignisdaten bereit:

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

AWS Lambda übergibt die Ereignisdaten an Ihren Funktionscode. Die Ereignisdaten stellen die folgenden Attribute bereit:

• MessageConfiguration: Hat dieselbe Struktur wie das DirectMessageConfiguration-Objekt der Nachrichten-Ressource in der Amazon-Pinpoint-API.

• ApplicationId: Die ID des Amazon-Pinpoint-Projekts, zu dem die Kampagne gehört.

• CampaignId: Die ID der Amazon-Pinpoint-Kampagne, für die die Funktion aufgerufen wurde.

• TreatmentId: Die ID einer Kampagnenvariante, die für A/B-Tests verwendet wird.

• ActivityId: Die ID der Aktivität, die von der Kampagne ausgeführt wird.

• ScheduledTime: Datum/Uhrzeit, an dem/zu der die Kampagnennachrichten im Format ISO 8601 zugestellt werden.

• Endpoints: Eine Karte, die Endpunkt-IDs Endpunktdefinitionen zuordnet. Jede Ereignisdaten-Nutzlast enthält bis zu 50 Endpunkte. Wenn das Kampagnensegment mehr als 50 Endpunkte enthält, ruft Amazon Pinpoint die Funktion wiederholt mit bis zu 50 Endpunkten auf, bis alle Endpunkte verarbeitet wurden.

Erstellen einer Lambda-Funktion

Informationen zum Erstellen einer Lambda-Funktion finden Sie unter Erste Schritte im AWS Lambda -Entwicklerhandbuch. Denken Sie bei der Erstellung der Funktion daran, dass die Nachrichtenzustellung unter folgenden Bedingungen fehlschlägt:

• Die Lambda-Funktion benötigt mehr als 15 Sekunden, um das modifizierte Segment zurückzugeben.

• Amazon Pinpoint kann den Rückgabewert der Funktion nicht decodieren.

• Die Funktion benötigt mehr als 3 Versuche von Amazon Pinpoint für einen erfolgreichen Aufruf.

Amazon Pinpoint akzeptiert nur Endpunktdefinitionen im Rückgabewert der Funktion. Die Funktion kann keine anderen Elemente in den Ereignisdaten ändern.

Beispiel-Lambda-Funktion

Ihre Lambda-Funktion verarbeitet die von Amazon Pinpoint gesendeten Ereignisdaten und gibt die geänderten Endpunkte zurück, wie in der folgenden Beispielprozedur gezeigt, die in Node.js geschrieben ist:

'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 übergibt die Ereignisdaten der Prozedur als event-Parameter.

In diesem Beispiel durchläuft die Prozedur jeden Endpunkt im event.Endpoints-Objekt und fügt dem Endpunkt ein neues Attribut hinzu, CreditScore. Der Wert des CreditScore-Attributs ist einfach eine Zufallszahl.

Die console.log() Anweisung protokolliert das Ereignis in CloudWatch Logs.

Die callback()-Anweisung gibt die geänderten Endpunkte an Amazon Pinpoint zurück. Normalerweise ist der callback-Parameter optional in Node.js Lambda-Funktionen, aber in diesem Kontext ist er erforderlich, da die Funktion die aktualisierten Endpunkte an Amazon Pinpoint zurückgeben muss.

Ihre Funktion muss Endpunkte im selben Format zurückgeben, wie von den Ereignisdaten bereitgestellt. Dabei handelt es sich um ein Schema, das Endpunkt-IDs Endpunktdefinitionen zuweist, wie im folgenden Beispiel:

{
    "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": {}
    }
}

Die Beispiel-Funktion ändert das event.Endpoints-Objekt, das sie in den Ereignisdaten erhalten hat, und gibt es zurück.

Optional können Sie die Attribute TitleOverride und BodyOverride in die Endpunktdefinitionen aufnehmen, die Sie zurückgeben.

Anmerkung

Wenn Sie mit dieser Lösung Nachrichten senden, berücksichtigt Amazon Pinpoint die Attribute TitleOverride und BodyOverride nur für Endpunkte, bei denen der Wert des ChannelType-Attributs einen der folgenden Werte hat: ADM, APNS, APNS_SANDBOX, APNS_VOIP, APNS_VOIP_SANDBOX, BAIDU, GCM oder SMS.

Amazon Pinpoint berücksichtigt nicht diese Attribute für Endpunkte, bei denen der Wert des ChannelType-Attributs EMAIL ist.

Zuweisen einer Lambda-Funktionsrichtlinie

Bevor Sie Ihre Lambda-Funktion verwenden können, um Ihre Endpunkte zu verarbeiten, müssen Sie Amazon Pinpoint autorisieren, Ihre Lambda-Funktion aufzurufen. Um eine Aufrufberechtigung zu erteilen, weisen Sie der Funktion eine Lambda-Funktionsrichtlinie zu. Eine Lambda-Funktionsrichtlinie ist eine ressourcenbasierte Richtlinie, die bestimmt, welche Entitäten Ihre Funktion verwenden dürfen, und welche Aktionen diese Entitäten durchführen können.

Weitere Informationen finden Sie unter Verwenden von ressourcenbasierten Richtlinien für AWS Lambda im AWS Lambda -Entwicklerhandbuch.

Beispiel für eine Funktionsrichtlinie

Mit der folgenden Richtlinie wird dem Amazon-Pinpoint-Service-Prinzipal die Berechtigung erteilt, die lambda:InvokeFunction-Aktion für eine bestimmte Kampagne (campaign-id) zu verwenden:

{
  "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"
    }
  }
}

Ihre Funktionsrichtlinie benötigt einen Condition-Block, der einen AWS:SourceArn-Schlüssel beinhaltet. Dieser Code gibt an, welche Amazon-Pinpoint-Kampagne die Funktion aufrufen darf. In diesem Beispiel erteilt die Richtlinie eine Berechtigung für nur eine einzelne Kampagne. Der Condition Block muss auch einen AWS:SourceAccount Schlüssel enthalten, der steuert, welches AWS Konto die Aktion aufrufen kann.

Um eine allgemeinere Richtlinie zu schreiben, verwenden Sie Wildcards (*), die mehrere Zeichen darstellen. Beispielsweise können Sie den folgenden Condition-Block verwenden, um einer beliebigen Kampagne in einem bestimmten Amazon-Pinpoint-Projekt (application-id) zu gestatten, die Funktion aufzurufen:

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

Wenn Sie die Lambda-Funktion als Standardfunktion verwenden möchten, die von allen Kampagnen für ein Projekt verwendet wird, empfehlen wir, den Condition-Block für die Richtlinie auf die zuvor beschriebene Weise zu konfigurieren. Informationen zum Festlegen einer Lambda-Funktion als Standard für alle Kampagnen in einem Projekt finden Sie unter Zuweisen einer Lambda-Funktion zu einer Kampagne.

Erteilen der Amazon-Pinpoint-Aufrufberechtigung

Sie können die AWS Command Line Interface (AWS CLI) verwenden, um der Lambda-Funktionsrichtlinie, die Ihrer Lambda-Funktion zugewiesen ist, Berechtigungen hinzuzufügen. Um Amazon Pinpoint zu erlauben, eine Funktion für eine bestimmte Kampagne aufzurufen, verwenden Sie den Lambda-Befehl add-permission, wie im folgenden Beispiel gezeigt:

$ 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

Sie können Ihre Kampagnen-IDs mit dem Befehl get-campaigns in der AWS CLI nachschlagen. Sie können Ihre Anwendungs-ID auch mit dem Befehl get-apps nachschlagen.

Wenn Sie den Lambda-Befehl add-permission ausführen, gibt Lambda die folgende Ausgabe zurück:

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

Der Statement-Wert ist eine JSON-Zeichenfolgenversion der Anweisung, die der Lambda-Funktionsrichtlinie hinzugefügt wurde.

Zuweisen einer Lambda-Funktion zu einer Kampagne

Sie können eine Lambda-Funktion einer einzelnen Amazon-Pinpoint-Kampagne zuweisen. Sie können auch die Lambda-Funktion als Standard festlegen, der von allen Kampagnen für ein Projekt verwendet wird, außer für Kampagnen, für die Sie separat eine Funktion zuweisen.

Um eine Lambda-Funktion einer individuellen Kampagne zuzuweisen, verwenden Sie die Amazon-Pinpoint-API, um ein Campaign-Objekt zu erstellen oder zu aktualisieren und sein CampaignHook-Attribut zu definieren. Um eine Lambda-Funktion als Standard für alle Kampagnen in einem Projekt festzulege, erstellen Sie die Settings-Ressource für dieses Projekt und definieren ihr CampaignHook-Objekt.

In beiden Fällen legen Sie die folgenden CampaignHook-Attribute fest:

• LambdaFunctionName: Der Name oder ARN der Lambda-Funktion, die Amazon Pinpoint aufruft, bevor es Nachrichten für die Kampagne sendet.

• Mode – Eingestellt auf FILTER. Mit diesem Modus ruft Amazon Pinpoint die Funktion auf und wartet, bis sie die geänderten Endpunkte zurückgibt. Nachdem es sie erhalten hat, sendet Amazon Pinpoint die Nachricht. Amazon Pinpoint wartet bis zu 15 Sekunden, bevor die Zustellung von Nachrichten als fehlgeschlagen betrachtet wird.

Mit für eine Kampagne definierten CampaignHook-Einstellungen ruft Amazon Pinpoint die angegebene Lambda-Funktion auf, bevor die Nachrichten der Kampagne gesendet werden. Amazon Pinpoint wartet, bis es die geänderten Endpunkte von der Funktion erhalten hat. Wenn Amazon Pinpoint die aktualisierten Endpunkte empfängt, setzt es die Nachrichtenzustellung unter Verwendung der aktualisierten Endpunktdaten fort.