カスタムメッセージの Lambda トリガー
ユーザーに送信する E メールメッセージと SMS メッセージの外部標準がある場合、または実行時に独自のロジックをユーザーメッセージのフォーマットに適用する場合は、カスタムメッセージトリガーをユーザープールに追加します。カスタムメッセージ Lambda は、ユーザープールが送信する前に、すべての E メールおよび SMS メッセージの内容を受信します。その後、Lambda 関数でメッセージの内容と件名を変更することができます。
Amazon Cognito は、E メールまたは電話による確認メッセージ、または多要素認証 (MFA) コードを送信する前にこのトリガーを呼び出します。カスタムメッセージトリガーを使用して、メッセージを動的にカスタマイズできます。静的なカスタムメッセージは、Amazon Cognito
リクエストには codeParameter
が含まれます。これは、Amazon Cognito がユーザーに配信するコードのプレースホルダーとなる文字列です。メッセージ本文で検証コードを表示する位置に codeParameter
文字列を挿入します。Amazon Cognito がこのレスポンスを受信すると、Amazon Cognito が codeParameter
文字列を実際の検証コードに置き換えます。
注記
CustomMessage_AdminCreateUser
トリガーソースがあるカスタムメッセージの Lambda 関数 はユーザー名と検証コードを返します。管理者が作成したユーザーはユーザー名とコードの両方を受け取る必要があるため、関数からの応答には request.usernameParameter
と request.codeParameter
の両方を含める必要があります。
カスタムメッセージの Lambda トリガーのソース
triggerSource 値 | イベント |
---|---|
CustomMessage_SignUp |
カスタムメッセージ - サインアップ後に確認コードを送信するため。 |
CustomMessage_AdminCreateUser |
カスタムメッセージ – 新規ユーザーに一時パスワードを送信するため。 |
CustomMessage_ResendCode |
カスタムメッセージ – 既存ユーザーに確認コードを再送するため。 |
CustomMessage_ForgotPassword |
カスタムメッセージ - 忘れたパスワードのリクエスト用の確認コードを送信するため。 |
CustomMessage_UpdateUserAttribute |
カスタムメッセージ - ユーザーの E メールまたは電話番号が変更されると、このトリガーは検証コードをそのユーザーに自動的に送信します。他の属性には使用できません。 |
CustomMessage_VerifyUserAttribute |
カスタムメッセージ – ユーザーが手動で新しい E メールや電話番号の認証コードをリクエストすると、このトリガーからユーザーに認証コードが送信されます。 |
CustomMessage_Authentication |
カスタムメッセージ - 認証時に MFA コードを送信するため。 |
カスタムメッセージの Lambda トリガーのパラメータ
Amazon Cognito がこの Lambda 関数に渡すリクエストは、以下のパラメータと Amazon Cognito がすべてのリクエストに追加する共通パラメータを組み合わせたものです。
カスタムメッセージリクエストパラメータ
- userAttributes
-
ユーザー属性を表す 1 つ以上の名前 - 値ペア。
- codeParameter
-
カスタムメッセージで、検証コードのプレースホルダーとして使用する文字列。
- usernameParameter
-
ユーザー名。Amazon Cognito は、管理者が作成したユーザーからのリクエストにこのパラメータを含めます。
- clientMetadata
-
カスタムメッセージのトリガーに指定する Lambda 関数へのカスタム入力として提供できる 1 つ、または複数のキー/値ペア。カスタムメッセージ関数を呼び出すリクエストには、AdminInitiateAuth および InitiateAuth API オペレーションの ClientMetadata パラメータで渡されたデータは含まれません。このデータを Lambda 関数に渡すには、以下の API アクションで ClientMetadata パラメータを使用できます。
カスタムメッセージレスポンスパラメータ
レスポンスで、ユーザーへのメッセージに使用するカスタムテキストを指定します。これらのパラメータに対して Amazon Cognito が適用する文字列制約については、「MessageTemplateType」を参照してください。
- smsMessage
-
ユーザーに送信されるカスタム SMS メッセージ。リクエストで受信する
codeParameter
値を含める必要があります。 - emailMessage
-
ユーザーに送信するカスタム E メールメッセージ。
emailMessage
パラメータで HTML 書式を使用できます。リクエストで受信されるcodeParameter
値を変数{####}
として含める必要があります。Amazon Cognito は、ユーザープールのEmailSendingAccount
属性がDEVELOPER
の場合のみ、emailMessage
パラメータを使用できます。ユーザープールのEmailSendingAccount
属性が、DEVELOPER
ではなく、emailMessage
パラメータが返されると、Amazon Cognito は 400 エラーコードcom.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException
を生成します。Amazon Simple Email Service (Amazon SES) を使用して E メールメッセージを送信する場合、ユーザープールのEmailSendingAccount
属性はDEVELOPER
です。それ以外の場合、値はCOGNITO_DEFAULT
です。 - emailSubject
-
カスタムメッセージの件名。
emailSubject
パラメータは、ユーザープールの EmailSendingAccount 属性がDEVELOPER
の場合にのみ使用できます。ユーザープールのEmailSendingAccount
属性がDEVELOPER
ではなく、Amazon Cognito がemailSubject
パラメータを返した場合、Amazon Cognito は 400 エラーコードcom.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException
を生成します。Amazon Simple Email Service (Amazon SES) を使用して E メールメッセージを送信する場合、ユーザープールのEmailSendingAccount
属性はDEVELOPER
です。それ以外の場合、値はCOGNITO_DEFAULT
です。
サインアップのカスタムメッセージの例
この Lambda 関数の例は、サービスでアプリがユーザーへの検証コードの送信が必要とされる場合に、E メールまたは SMS メッセージをカスタマイズします。
Amazon Cognito は、登録後、検証コードの再送信時、パスワードを忘れた場合、ユーザー属性の検証時といった複数のイベントで Lambda トリガーを呼び出すことができます。レスポンスには、SMS と E メールの両方のメッセージが含まれます。メッセージにはコードのパラメータ "####"
を含める必要があります。このパラメータは、ユーザーが受け取る検証コードのプレースホルダーです。
E メールメッセージの最大長は 20,000 UTF-8 文字です。この長さには検証コードが含まれます。これらの E メールメッセージでは、HTML タグを使用できます。
SMS メッセージの最大長は 140 UTF-8 文字です。この長さには検証コードが含まれます。
Amazon Cognito は Lambda 関数にイベント情報を渡します。関数はレスポンスで、同じイベントオブジェクトを変更と共に Amazon Cognito に返します。Lambda コンソールで、Lambda トリガーに関連するデータを使用したテストイベントをセットアップできます。以下は、このコードサンプルのテストイベントです。
管理者作成ユーザーのカスタムメッセージの例
Amazon Cognito がこのカスタムメッセージ Lambda 関数のサンプルに送信したリクエストは、triggerSource
値が CustomMessage_AdminCreateUser
で、ユーザー名と仮パスワードが含まれます。関数は、リクエストの仮パスワードから ${event.request.codeParameter}
を入力し、リクエストのユーザー名から ${event.request.usernameParameter}
を入力します。
カスタムメッセージは、レスポンスオブジェクトの smsMessage
と emailMessage
に codeParameter
と usernameParameter
の値を挿入する必要があります。この例では、関数は、レスポンスフィールド event.response.smsMessage
と event.response.emailMessage
に同じメッセージを書き込みます。
E メールメッセージの最大長は 20,000 UTF-8 文字です。この長さには検証コードが含まれます。これらの E メールでは HTML タグを使用できます。SMS メッセージの最大長は 140 UTF-8 文字です。この長さには検証コードが含まれます。
レスポンスには、SMS と E メールの両方のメッセージが含まれます。
Amazon Cognito は Lambda 関数にイベント情報を渡します。関数はレスポンスで、同じイベントオブジェクトを変更と共に Amazon Cognito に返します。Lambda コンソールで、Lambda トリガーに関連するデータを使用したテストイベントをセットアップできます。以下は、このコードサンプルのテストイベントです。