AWS Lambda を使用したセグメントのカスタマイズ

これはパブリックベータリリースの機能に関するプレリリースドキュメントです。このドキュメントは変更される可能性があります。

AWS Lambda 関数を使用して、Amazon Pinpoint キャンペーンに対象者を取り込む方法を調整できます。AWS Lambda では、Amazon Pinpoint がキャンペーンのメッセージを送信するときに、キャンペーンのセグメントを変更することができます。

AWS Lambda はサーバーをプロビジョニングしたり管理しなくてもコードを実行するために使用できるコンピューティングサービスです。コードをパッケージ化し、Lambda 関数として Lambda にアップロードします。関数が呼び出されたときに、Lambda によって関数が実行されます。この操作は手動で行うことも、イベントに応じて自動的に行うこともできます。詳細については、『AWS Lambda デベロッパーガイド』を参照してください。

キャンペーンに Lambda 関数を割り当てるには、Amazon Pinpoint API のキャンペーンリソースを使用して、キャンペーンの CampaignHook 設定を定義します。これらの設定には、Lambda 関数名が含まれます。CampaignHook モードも含まれます。これは、Amazon Pinpoint が関数から戻り値を受け取るかどうかを指定します。

キャンペーンに割り当てる Lambda 関数を、Amazon Pinpoint の拡張機能と呼びます。

CampaignHook 設定が定義されると、Amazon Pinpoint はキャンペーンを実行する際、メッセージの送信前に自動的に Lambda 関数を呼び出します。Amazon Pinpoint が関数を呼び出すと、メッセージ配信に関するイベントデータを提供します。このデータには、キャンペーンのセグメントが含まれます。これは Amazon Pinpoint がメッセージを送信するエンドポイントのリストです。

CampaignHook モードが FILTER に設定されている場合、Amazon Pinpoint により、関数はメッセージを送信する前に、セグメントを変更して返すことができます。例えば、関数は、Amazon Pinpoint の外部にあるソースからのデータを含む属性でエンドポイント定義を更新する場合があります。または、関数コードの条件に基づいて、特定のエンドポイントを削除してセグメントをフィルタリングする場合があります。Amazon Pinpoint が変更されたセグメントを関数から受け取ると、キャンペーンの配信チャネルを使用して、各セグメントのエンドポイントにメッセージを送信します。

AWS Lambda でセグメントを処理することにより、メッセージの送信先のユーザーと、メッセージの内容をより詳細に管理できます。キャンペーンメッセージが送信されるときに、キャンペーンをリアルタイムで調整できます。セグメントをフィルタリングすると、サブセットの定義されたサブセットを絞り込んで適用できます。エンドポイント属性を追加または更新しても、メッセージ変数で新しいデータを使用できるようになります。

注記

また、CampaignHook 設定を使用して、メッセージ配信を処理する Lambda 関数を割り当てることもできます。このタイプの関数は、ソーシャルメディアプラットフォームなど、Amazon Pinpoint がサポートしないカスタムチャネルを通じてメッセージを配信するときに役立ちます。詳細については、「Amazon Pinpoint でカスタムチャンネルの作成」を参照してください。

Amazon Pinpoint を使用して Lambda フックを呼び出す場合、Lambda 関数も Amazon Pinpoint プロジェクトと同じリージョンにある必要があります。

AWS Lambda でキャンペーンセグメントを変更するには、まず、Amazon Pinpoint によって送信されたイベントデータを処理し、変更されたセグメントを返す関数を作成します。次に、Lambda 関数ポリシーを割り当てて関数を呼び出すことを Amazon Pinpoint に許可します。最後に、CampaignHook 設定を定義して、1 つ以上のキャンペーンに関数を割り当てます。

イベントデータ

Amazon Pinpoint が Lambda 関数を呼び出すときに、イベントデータとして次のペイロードを提供します。

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

AWS Lambda はイベントデータをユーザーの関数コードに渡します。イベントデータは次の属性を提供します。

• MessageConfiguration – Amazon Pinpoint API のメッセージリソースの DirectMessageConfiguration オブジェクトと同じ構造を持つ。

• ApplicationId – キャンペーンが属する Amazon Pinpoint プロジェクトの ID。

• CampaignId – 関数が呼び出される Amazon Pinpoint キャンペーンの ID。

• TreatmentId – A/B テストに使用されるキャンペーンバリエーションの ID。

• ActivityId – キャンペーンが実行しているアクティビティの ID。

• ScheduledTime – キャンペーンのメッセージが配信される日時 (ISO 8601 形式)。

• Endpoints – エンドポイント ID をエンドポイント定義と関連付けるマップ。各イベントデータのペイロードには最大 50 のエンドポイントが含まれます。キャンペーンセグメントに 50 以上のエンドポイントが含まれる場合、Amazon Pinpoint はすべてのエンドポイントが処理されるまで、繰り返し関数を呼び出します (最大で一度に 50 のエンドポイント)。

Lambda 関数の作成

Lambda 関数の作成方法については、『AWS Lambda デベロッパーガイド』の「開始方法」を参照してください。関数を作成するときは、以下の条件ではメッセージ配信が失敗することに注意してください。

• Lambda 関数では、変更されたセグメントを返すために 15 秒以上かかります。

• Amazon Pinpoint は関数の戻り値をデコードすることはできません。

• この関数では、正常な呼び出しのためには、Amazon Pinpoint から 3 回を超える試行が必要です。

Amazon Pinpoint は、関数の戻り値でのみエンドポイントの定義を受け入れます。関数は、イベントデータで他の要素を変更することはできません。

Lambda 関数の例

Lambda 関数は、Node.js で書かれた次の例のように、Amazon Pinpoint によって送信されたイベントデータを処理し、変更されたエンドポイントを返します。

'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 は event パラメータとしてイベントデータをハンドラに渡します。

この例では、ハンドラは event.Endpoints オブジェクトの各エンドポイントで反復処理し、エンドポイントに新しい属性 CreditScore を追加します。CreditScore 属性の値は、単純にランダムな数値です。

console.log() ステートメントは CloudWatch Logs にイベントのログを記録します。

callback() ステートメントは変更されたエンドポイントを Amazon Pinpoint に返します。通常、Node.js Lambda 関数で callback パラメータはオプションですが、この関数は更新されたエンドポイントを Amazon Pinpoint に返す必要があるため、このコンテキストで必要です。

関数は、イベントデータで提供されるのと同じ形式でエンドポイントを返す必要があります。これは、次の例に示すように、エンドポイント ID とエンドポイント定義を関連付けるマップです。

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

この例の関数では、イベントデータで受信した event.Endpoints オブジェクトを変更して返します。

必要に応じて、返されるエンドポイント定義に TitleOverride および BodyOverride 属性を含めることができます。

注記

このソリューションを使用してメッセージを送信すると、Amazon Pinpoint は、ChannelType 属性の値が次のいずれかの場合、エンドポイントの TitleOverride および BodyOverride 属性のみを尊重します: ADM、APNS、APNS_SANDBOX、APNS_VOIP、APNS_VOIP_SANDBOX、BAIDU、GCM、または SMS。

Amazon Pinpoint は、ChannelType 属性の値が EMAIL であるエンドポイントについては、これらの属性を尊重しません。

Lambda 関数ポリシーの割り当て

Lambda 関数を使用してエンドポイントを処理する前に、Amazon Pinpoint に Lambda 関数の呼び出しを許可する必要があります。呼び出しのアクセス許可を付与するには、関数に Lambda 関数ポリシーを割り当てます。Lambda 関数ポリシーはリソースベースのアクセス許可ポリシーで、関数を使用できるエンティティと、それらのエンティティが実行できるアクションを指定します。

詳細については、『AWS Lambda デベロッパーガイド』の「AWS Lambda のリソースベースのポリシーを使用する」を参照してください。

関数ポリシーの例

以下のポリシーは、Amazon Pinpoint サービスプリンシパルに、特定のキャンペーン (campaign-id) に対して lambda:InvokeFunction アクションを使用する許可を与えるものです。

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

関数ポリシーは、Condition キーを含む AWS:SourceArn ブロックを必要とします。このコードは、関数を呼び出すために許可される Amazon Pinpoint キャンペーンを指定します。この例では、ポリシーは 1 つのキャンペーンのみにアクセス許可を付与します。Condition ブロックは AWS:SourceAccount キーも含まなければなりません。このキーは、どの AWS アカウントがアクションを呼び出すことができるかを制御します。

より一般的なポリシーを記述するには、複数文字に一致するワイルドカード (*) を使用します。例えば、次の Condition ブロックを使用して、特定の Amazon Pinpoint プロジェクト (application-id) の任意のキャンペーンに関数の呼び出しを許可できます。

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

Lambda 関数をプロジェクトのすべてのキャンペーンで使用されるデフォルト関数にする場合は、前述の方法でポリシーの Condition ブロックを構成することをお勧めします。プロジェクト内のすべてのキャンペーンのデフォルトとして Lambda 関数を設定する方法については、キャンペーンへの Lambda 関数の割り当て を参照してください。

Amazon Pinpoint の呼び出し許可の付与

AWS Command Line Interface (AWS CLI) を使用して、Lambda 関数に割り当てられた Lambda 関数ポリシーにアクセス許可を追加できます。Amazon Pinpoint に特定のキャンペーンの関数の呼び出しを許可するには、次の例に示すように Lambda add-permission コマンドを使用します。

$ 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

キャンペーン ID は、AWS CLI のget-campaigns コマンドで調べることができます。また、アプリケーション ID は get-apps コマンドで調べることができます。

Lambda add-permission のコマンドを実行すると、Lambda により以下のような出力が表示されます。

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

Statement 値は、Lambda 関数ポリシーに追加されたステートメントの JSON 文字列バージョンです。

キャンペーンへの Lambda 関数の割り当て

Lambda 関数は個別の Amazon Pinpoint キャンペーンに割り当てることができます。または、個別に関数を割り当てるキャンペーンを除いて、プロジェクトのすべてのキャンペーンで使用されるデフォルトとして、Lambda 関数を設定できます。

Lambda 関数を個別のキャンペーンに割り当てるには、Amazon Pinpoint API を使用して Campaign オブジェクトを作成または更新し、その CampaignHook 属性を定義します。プロジェクトのすべてのキャンペーン用にデフォルトとして Lambda 関数を設定するには、そのプロジェクト用の Settings リソースを作成または更新し、その CampaignHook オブジェクトを定義します。

いずれの場合も、次の CampaignHook 属性を設定します。

• LambdaFunctionName – キャンペーンのメッセージを送信する前に Amazon Pinpoint が呼び出す Lambda 関数の名前または ARN。

• Mode – FILTER に設定します。このモードでは、Amazon Pinpoint はこの関数を呼び出し、変更されたエンドポイントが返されるのを待ちます。エンドポイントを受け取った後、Amazon Pinpointは、メッセージを送信します。Amazon Pinpoint は最大 15 秒待ってから、メッセージ配信を失敗させます。

キャンペーンに対して CampaignHook 設定を定義した状態で、Amazon Pinpoint はキャンペーンのメッセージを送信する前に、指定された Lambda 関数を呼び出します。Amazon Pinpoint は、変更されたエンドポイントの関数からの受け取りを待機します。Amazon Pinpoint が更新されたエンドポイントを受信する場合、更新されたエンドポイントデータを使用して、メッセージの配信を続行します。