カスタムメッセージの Lambda トリガー - Amazon Cognito
トリガーソースパラメータ例: サインアップ例: 作成されたユーザー

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

カスタムメッセージの Lambda トリガー

ユーザーに送信する E メールメッセージと SMS メッセージの外部標準がある場合、または実行時に独自のロジックをユーザーメッセージのフォーマットに適用する場合は、カスタムメッセージトリガーをユーザープールに追加します。カスタムメッセージ Lambda は、ユーザープールが送信する前に、すべての E メールおよび SMS メッセージの内容を受信します。その後、Lambda 関数でメッセージの内容と件名を変更することができます。

Amazon Cognito は、E メールまたは電話による確認メッセージ、または多要素認証 (MFA) コードを送信する前にこのトリガーを呼び出します。カスタムメッセージトリガーを使用して、メッセージを動的にカスタマイズできます。

リクエストには codeParameter が含まれます。これは、Amazon Cognito がユーザーに配信するコードのプレースホルダーとなる文字列です。メッセージ本文で検証コードを表示する位置に codeParameter 文字列を挿入します。Amazon Cognito がこのレスポンスを受信すると、Amazon Cognito が codeParameter 文字列を実際の検証コードに置き換えます。

注記

CustomMessage_AdminCreateUser トリガーソースを持つカスタムメッセージ Lambda 関数の入力イベントには、ユーザー名と検証コードが含まれます。管理者が作成したユーザーはユーザー名とパスワードの両方を受け取る必要があるため、関数からのレスポンスにはユーザー名とパスワードのプレースホルダー変数を含める必要があります。メッセージのプレースホルダーは、 request.usernameParameterおよび の値ですrequest.codeParameter。これらの値は通常 {username}と です{####}。ベストプラクティスとして、変数名をハードコーディングするのではなく、入力値を参照します。

カスタムメッセージの 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 がすべてのリクエストに追加する共通パラメータを組み合わせたものです。

JSON
{
    "request": {
        "userAttributes": {
            "string": "string",
            . . .
        }
        "codeParameter": "####",
        "usernameParameter": "string",
        "clientMetadata": {
            "string": "string",
            . . .
        }
    },
    "response": {
        "smsMessage": "string",
        "emailMessage": "string",
        "emailSubject": "string"
    }
}

カスタムメッセージリクエストパラメータ

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 文字です。この長さには検証コードが含まれます。

Node.js
const handler = async (event) => {
  if (event.triggerSource === "CustomMessage_SignUp") {
    const message = `Thank you for signing up. Your confirmation code is ${event.request.codeParameter}.`;
    event.response.smsMessage = message;
    event.response.emailMessage = message;
    event.response.emailSubject = "Welcome to the service.";
  }
  return event;
};

export { handler };

Amazon Cognito は Lambda 関数にイベント情報を渡します。関数はレスポンスで、同じイベントオブジェクトを変更と共に Amazon Cognito に返します。Lambda コンソールで、Lambda トリガーに関連するデータを使用したテストイベントをセットアップできます。以下は、このコードサンプルのテストイベントです。

JSON
{
	"version": "1",
	"region": "us-west-2",
	"userPoolId": "us-west-2_EXAMPLE",
	"userName": "test-user",
	"callerContext": {
		"awsSdkVersion": "aws-sdk-unknown-unknown",
		"clientId": "1example23456789"
	},
	"triggerSource": "CustomMessage_SignUp",
	"request": {
		"userAttributes": {
			"sub": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
			"cognito:user_status": "CONFIRMED",
			"email_verified": "true",
			"phone_number_verified": "true",
			"phone_number": "+12065551212",
			"email": "test-user@example.com"
		},
		"codeParameter": "{####}",
		"linkParameter": "{##Click Here##}",
		"usernameParameter": "None"
	},
	"response": {
		"smsMessage": "None",
		"emailMessage": "None",
		"emailSubject": "None"
	}
}

管理者作成ユーザーのカスタムメッセージの例

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 メールの両方のメッセージが含まれます。

Node.js
const handler = async (event) => {
  if (event.triggerSource === "CustomMessage_AdminCreateUser") {
    const message = `Welcome to the service. Your user name is ${event.request.usernameParameter}. Your temporary password is ${event.request.codeParameter}`;
    event.response.smsMessage = message;
    event.response.emailMessage = message;
    event.response.emailSubject = "Welcome to the service";
  }
  return event;
};

export { handler };

Amazon Cognito は Lambda 関数にイベント情報を渡します。関数はレスポンスで、同じイベントオブジェクトを変更と共に Amazon Cognito に返します。Lambda コンソールで、Lambda トリガーに関連するデータを使用したテストイベントをセットアップできます。以下は、このコードサンプルのテストイベントです。

JSON
{
  "version": 1,
  "triggerSource": "CustomMessage_AdminCreateUser",
  "region": "<region>",
  "userPoolId": "<userPoolId>",
  "userName": "<userName>",
  "callerContext": {
      "awsSdk": "<calling aws sdk with version>",
      "clientId": "<apps client id>",
      ...
  },
  "request": {
      "userAttributes": {
          "phone_number_verified": false,
          "email_verified": true,
           ...
      },
      "codeParameter": "####",
      "usernameParameter": "username"
  },
  "response": {
      "smsMessage": "<custom message to be sent in the message with code parameter and username parameter>"
      "emailMessage": "<custom message to be sent in the message with code parameter and username parameter>"
      "emailSubject": "<custom email subject>"
  }
}