Amazon Pinpoint
開発者ガイド

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

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

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

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

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

メッセージ変数の詳細については、『Amazon Pinpoint ユーザーガイド』 の「メッセージ変数」を参照してください。

注記

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

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 Developer Guide』の「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 に返します。通常、callback パラメータは Node.js Lambda 関数ではオプションですが、このコンテキストでは、関数が更新されたエンドポイントを 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 属性のみを尊重します: SMSGCMAPNSAPNS_SANDBOXAPNS_VOIPAPNS_VOIP_SANDBOXADM、または BAIDU

Amazon Pinpoint は、ChannelType 属性の値が EMAIL であるエンドポイントに対してこれらの属性を受け入れません

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

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

詳細については、『AWS Lambda Developer Guide』の「AWS Lambda でリソースベースのポリシーを使用する (Lambda 関数ポリシー)」を参照してください。

関数ポリシーの例

次のポリシーでは、lambda:InvokeFunction アクションを使用するアクセス許可を、Amazon Pinpoint サービスプリンシパルに付与します。

{ "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": { "ArnLike": { "AWS:SourceArn": "arn:aws:mobiletargeting:us-east-1:account-id:/apps/application-id/campaigns/campaign-id" } } }

関数ポリシーは、Condition キーを含む AWS:SourceArn ブロックを必要とします。このコードは、関数を呼び出すために許可される Amazon Pinpoint キャンペーンを指定します。この例では、ポリシーは 1 つのキャンペーン ID のみにアクセス許可を付与します。より一般的なポリシーを記述するには、複数文字に一致するワイルドカード (*) を使用します。たとえば、次の Condition ブロックを使用して、AWS アカウントの任意の Amazon Pinpoint キャンペーンに関数の呼び出しを許可できます。

"Condition": { "ArnLike": { "AWS:SourceArn": "arn:aws:mobiletargeting:us-east-1:account-id:/apps/*" } }

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-arn arn:aws:mobiletargeting:us-east-1:account-id:/apps/application-id/campaigns/campaign-id

--source-arn パラメータのキャンペーン ID を指定する場合は、Amazon Pinpoint の get-campaigns コマンドと AWS CLI を使用して、キャンペーン ID を参照できます。このコマンドには、--application-id パラメータが必要です。アプリケーション ID を参照するには、https://console.aws.amazon.com/pinpoint/ で Amazon Pinpoint コンソールにサインインし、[Projects] ページに移動します。コンソールには各プロジェクトの [ID] が表示されます。これはプロジェクトのアプリケーション ID です。

Lambda の add-permission コマンドを実行すると、AWS 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\"}}}" }

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 が更新されたエンドポイントを受信する場合、更新されたエンドポイントデータを使用して、メッセージの配信を続行します。