自定义消息 Lambda 触发器 - Amazon Cognito
自定义消息触发器源自定义消息 Lambda 触发器参数用于注册的自定义消息示例管理员创建用户的自定义消息示例
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 Amazon Web Services 服务入门。

自定义消息 Lambda 触发器

Amazon Cognito 在发送电子邮件或电话验证消息或多重验证 (MFA) 代码前调用此触发器。您可以使用自定义消息触发器动态自定义消息。您可以在 Amazon Cognito 控制台的 Message Customizations（消息自定义）选项卡中编辑静态自定义消息。

该请求包括 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 自定义消息 – 当用户的电子邮件或电话号码发生更改时，此触发器自动向用户发送验证码。不可用于其他属性。
CustomMessage_VerifyUserAttribute 自定义消息 – 当用户针对新的电子邮件或电话号码手动请求验证码时，此触发器向用户发送验证码。
CustomMessage_Authentication 自定义消息 – 在身份验证过程中发送 MFA 代码。

自定义消息 Lambda 触发器参数

这些是 Amazon Cognito 随同常见参数中的事件信息一起传递给此 Lambda 函数的参数。

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

自定义消息请求参数

userAttributes

表示用户属性的一个或多个名称/值对。

codeParameter

一个字符串，用作自定义消息中验证码的占位符。

usernameParameter

用户名。Amazon Cognito 在管理员创建的用户发出的请求中包含此参数。

clientMetadata

一个或多个键值对，您可以将其作为自定义输入内容提供给为自定义消息触发器指定的 Lambda 函数。调用自定义消息函数的请求不包括在 AdminInitiateAuth 和 InitiateAuth API 操作的 ClientMetadata 参数中传递的数据。要将此数据传递给 Lambda 函数，您可以在以下 API 操作中使用 ClientMetadata 参数：

自定义消息响应参数

在响应中，指定要在发送给用户的消息中使用的自定义文本。

smsMessage

要发送给用户的自定义 SMS 消息。必须包含您在请求中收到的 codeParameter 值。

emailMessage

发送给用户的自定义电子邮件。您可以在 emailMessage 参数中使用 HTML 格式。必须包含您在请求中收到的 codeParameter 值作为变量 {####}。只有在用户池的 EmailSendingAccount 属性为 DEVELOPER 时，Amazon Cognito 才可以使用emailMessage 参数。如果用户池的 EmailSendingAccount 属性不是 DEVELOPER 且返回了 emailMessage 参数，Amazon Cognito 会生成 400 错误代码 com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException. 当您选择使用 Amazon Simple Email Service (Amazon SES) 发送电子邮件时，用户池的 EmailSendingAccount 属性为 DEVELOPER。否则，该值为 COGNITO_DEFAULT。

emailSubject

自定义消息的主题行。只有在用户池的 EmailSendingAccount 属性为 DEVELOPER 时，您才可以使用 emailSubject 参数。如果用户池的 EmailSendingAccount 属性不是 DEVELOPER 且 Amazon Cognito 返回了 emailSubject 参数，Amazon Cognito 会生成 400 错误代码 com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException. 当您选择使用 Amazon Simple Email Service (Amazon SES) 发送电子邮件时，用户池的 EmailSendingAccount 属性为 DEVELOPER。否则，该值为 COGNITO_DEFAULT。

用于注册的自定义消息示例

当服务要求应用程序向用户发送验证码时，此示例 Lambda 函数自定义电子邮件或 SMS 消息。

Amazon Cognito 可以在多个事件中调用 Lambda 触发器：注册后、重新发送验证码时、恢复忘记的密码时或验证用户属性时。响应包括电子邮件和 SMS 消息。该消息必须包含代码参数 "####"。此参数是用户收到的验证码的占位符。

电子邮件的最大长度为 20000 个 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”是用户收到的用户名的占位符。

电子邮件的最大长度为 20000 个 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>"
  }
}