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

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

自定义消息 Lambda 触发器

Amazon Cognito 在发送电子邮件或电话验证消息或多重验证 (MFA) 代码前调用此触发器，让您能够动态自定义消息。您可以在消息自定义” 选项卡Amazon Cognito 控制台。

请求包含 codeParameter，这是一个字符串，用作发送给用户的代码的占位符。将 codeParameter 字符串插入消息正文中您要插入验证码的位置。收到此回复后，Amazon Cognito 服务将取代codeParameter字符串与实际验证代码。

注意

自定义消息 Lambda 函数与CustomMessage_AdminCreateUser触发器将返回用户名和验证码，所以请求必须包含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

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

username参数

用户名参数。这是管理员创建用户流程的必要请求参数。

clientMetadata

一个或多个键值对，您可以将其作为自定义输入内容提供给 Lambda 函数，该函数是为自定义消息触发器指定的。您可以使用以下 API 操作中的 ClientMetadata 参数将此数据传递给 Lambda 函数。

自定义消息响应参数

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

smsMessage

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

emailMessage

要发送给用户的自定义电子邮件。必须包含请求中收到的 codeParameter 值。如果 EmailSendingAccount 不是开发者并且返回 EmailMessage 消息，则 400 错误代码com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException仅当用户池的 emailMessage SendingAccount 是 DEVELOPER 时，才允许 EmailMessage。

emailSubject

自定义消息的主题行。如果 EmailSendingAccount 不是开发者并且返回 EmailMessage 消息，则 400 错误代码com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException仅当用户池的 EmailSendingAccount 是 DEVELOPER 时，才允许 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>"
  }
}

管理员创建用户的自定义消息示例

自定义消息 Lambda 函数与CustomMessage_AdminCreateUser触发器将返回用户名和验证码，所以它们将包含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>"
  }
}