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

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

自定义消息 Lambda 触发器

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

请求包含 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

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

用户名参数

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

clientMetadata

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

自定义消息响应参数

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

smsMessage

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

emailMessage

要发送给用户的自定义电子邮件。必须包含请求中收到的 codeParameter 值。如果 EmailSendingAccount 不是DEVELOPER, EmailMessage 返回,400错误代码 com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException 将被丢弃。emailMessage 只有当 UserPool的 EmailSendingAccount 是DEVELOPER。

emailSubject

自定义消息的主题行。如果 EmailSendingAccount 不是DEVELOPER, EmailMessage 返回,400错误代码 com.amazonaws.cognito.identity.idp.model.InvalidLambdaResponseException 将被丢弃。emailSubject 只有当 UserPool的 EmailSendingAccount 是DEVELOPER。

注册自定义消息示例

当服务要求应用程序向用户发送验证码时，系统会调用此 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>"
  }
}