自定义消息 Lambda 触发器
Amazon Cognito 在发送电子邮件或电话验证消息或多重验证 (MFA) 代码前调用此触发器,让您能够动态自定义消息。您可以在 Amazon Cognito 控制台的消息自定义选项卡中编辑静态自定义消息。
请求包含 codeParameter
,这是一个字符串,用作发送给用户的代码的占位符。将 codeParameter
字符串插入消息正文中您要插入验证码的位置。收到此响应后,Amazon Cognito 服务会将 codeParameter
字符串替换为实际验证码。
注意
具有 CustomMessage_AdminCreateUser
触发器的自定义消息 Lambda 函数将返回用户名和验证码,所以请求必须包含 request.usernameParameter
和 request.codeParameter
。
自定义消息 Lambda 触发器源
triggerSource 值 | 触发事件 |
---|---|
CustomMessage_SignUp |
自定义消息 – 在注册后发送确认代码。 |
CustomMessage_AdminCreateUser |
自定义消息 – 向新用户发送临时密码。 |
CustomMessage_ResendCode |
自定义消息 – 向现有用户重新发送确认代码。 |
CustomMessage_ForgotPassword |
自定义消息 – 针对“忘记密码”请求发送确认代码。 |
CustomMessage_UpdateUserAttribute |
自定义消息 – 当用户的电子邮件或电话号码发生更改时,此触发器自动向用户发送验证码。不可用于其他属性。 |
CustomMessage_VerifyUserAttribute |
自定义消息 – 当用户针对新的电子邮件或电话号码手动请求验证码时,此触发器向用户发送验证码。 |
CustomMessage_Authentication |
自定义消息 – 在身份验证过程中发送 MFA 代码。 |
自定义消息 Lambda 触发器参数
这些是此 Lambda 函数除常用参数以外还必需的参数。
- JSON
{ "request": { "userAttributes": { "
string
": "string
", . . . } "codeParameter": "####
", "usernameParameter": "string
", "clientMetadata": { "string
": "string
", . . . } }, "response": { "smsMessage": "string
", "emailMessage": "string
", "emailSubject": "string
" } }
自定义消息请求参数
- userAttributes
-
表示用户属性的一个或多个名称/值对。
- codeParameter
-
一个字符串,用作自定义消息中验证码的占位符。
- usernameParameter
-
用户名参数。这是管理员创建用户流程的必要请求参数。
- clientMetadata
-
一个或多个键值对,您可以将其作为自定义输入内容提供给 Lambda 函数,该函数是为自定义消息触发器指定的。您可以使用以下 API 操作中的 ClientMetadata 参数将此数据传递给 Lambda 函数。
自定义消息响应参数
在响应中,您指定要在发送给用户的消息中使用的自定义文本。
- smsMessage
-
要发送给用户的自定义 SMS 消息。必须包含请求中收到的
codeParameter
值。 - emailMessage
-
要发送给用户的自定义电子邮件。必须包含请求中收到的
codeParameter
值。 - emailSubject
-
自定义消息的主题行。
注册自定义消息示例
当服务要求应用程序向用户发送验证码时,系统会调用此 Lambda 函数自定义电子邮件或短信。
系统可以在多个时间点调用 Lambda 触发器:注册后、重新发送验证码时、忘记密码时或验证用户属性时。响应包含电子邮件和 SMS 消息。消息必须包含代码参数 "####"
,该参数是发送给用户的验证码的占位符。
对于电子邮件,消息的最大长度为 20,000 个 UTF-8 字符,其中包括验证代码。可以在这些电子邮件中使用 HTML 标签。
SMS 的最大长度为 140 个 UTF-8 字符,其中包括验证码。
- Node.js
exports.handler = (event, context, callback) => { // if(event.userPoolId === "theSpecialUserPool") { // Identify why was this function invoked if(event.triggerSource === "CustomMessage_SignUp") { // Ensure that your message contains event.request.codeParameter. This is the placeholder for code that will be sent event.response.smsMessage = "Welcome to the service. Your confirmation code is " + event.request.codeParameter; event.response.emailSubject = "Welcome to the service"; event.response.emailMessage = "Thank you for signing up. " + event.request.codeParameter + " is your verification code"; } // Create custom message for other events } // Customize messages for other user pools // Return to Amazon Cognito callback(null, event); };
Amazon Cognito 将事件信息传递给 Lambda 函数。然后该函数将同一事件对象返回到 Amazon Cognito,同时在响应中返回任何更改。在 Lambda 控制台中,您可以使用与 Lambda 触发器相关的数据设置测试事件。下面是此代码示例的测试事件:
- JSON
{ "version": 1, "triggerSource": "CustomMessage_SignUp/CustomMessage_ResendCode/CustomMessage_ForgotPassword/CustomMessage_VerifyUserAttribute", "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": "####" }, "response": { "smsMessage": "<custom message to be sent in the message with code parameter>
" "emailMessage": "<custom message to be sent in the message with code parameter>
" "emailSubject": "<custom email subject>
" } }
管理员创建用户的自定义消息示例
具有 CustomMessage_AdminCreateUser
触发器的自定义消息 Lambda 函数将返回用户名和验证码,所以消息正文中将包含 request.usernameParameter
和 request.codeParameter
。
代码参数值 "####"
是临时密码的占位符,"username" 是向您的用户提供的用户名占位符。
对于电子邮件,消息的最大长度为 20,000 个 UTF-8 字符,其中包括验证代码。可以在这些电子邮件中使用 HTML 标签。SMS 的最大长度为 140 个 UTF-8 字符,其中包括验证码。
响应包含电子邮件和 SMS 消息。
- Node.js
exports.handler = (event, context, callback) => { // if(event.userPoolId === "theSpecialUserPool") { // Identify why was this function invoked if(event.triggerSource === "CustomMessage_AdminCreateUser") { // Ensure that your message contains event.request.codeParameter event.request.usernameParameter. This is the placeholder for the code and username that will be sent to your user. event.response.smsMessage = "Welcome to the service. Your user name is " + event.request.usernameParameter + " Your temporary password is " + event.request.codeParameter; event.response.emailSubject = "Welcome to the service"; event.response.emailMessage = "Welcome to the service. Your user name is " + event.request.usernameParameter + " Your temporary password is " + event.request.codeParameter; } // Create custom message for other events } // Customize messages for other user pools // Return to Amazon Cognito callback(null, event); };
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>
" } }