本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 遷移使用者 Lambda 觸發程序
<a name="user-pool-lambda-migrate-user"></a>

當使用者使用密碼登入時或在忘記密碼流程時，該使用者不存在於使用者集區中，Amazon Cognito 會叫用此觸發程序。Lambda 函數成功傳回後，Amazon Cognito 會在使用者集區中建立使用者。如需使用使用者遷移 Lambda 觸發程序進行身分驗證流程的詳細資訊，請參閱[透過使用者遷移 Lambda 觸發程序匯入使用者](cognito-user-pools-import-using-lambda.md)。

若要在登入時將使用者從現有使用者目錄遷移至 Amazon Cognito 使用者集區，或在忘記密碼流程時使用此 Lambda 觸發程序。

**Topics**
+ [遷移使用者 Lambda 觸發程序來源](#user-pool-lambda-migrate-user-trigger-source)
+ [遷移使用者 Lambda 觸發程序參數](#cognito-user-pools-lambda-trigger-syntax-user-migration)
+ [範例：搭配現有密碼來遷移使用者](#aws-lambda-triggers-user-migration-example-1)

## 遷移使用者 Lambda 觸發程序來源
<a name="user-pool-lambda-migrate-user-trigger-source"></a>


| triggerSource 值 | 事件 | 
| --- | --- | 
| UserMigration\$1Authentication[1](#cognito-migrate-user-passwordless-note) | 登入時的使用者遷移。 | 
| UserMigration\$1ForgotPassword | 忘記密碼流程時的使用者遷移。 | 

1 當使用者使用[無密碼登入](amazon-cognito-user-pools-authentication-flow-methods.md#amazon-cognito-user-pools-authentication-flow-methods-passwordless)進行身分驗證時，Amazon Cognito 不會叫用此觸發。

## 遷移使用者 Lambda 觸發程序參數
<a name="cognito-user-pools-lambda-trigger-syntax-user-migration"></a>

Amazon Cognito 傳遞至此 Lambda 函數的請求，是以下參數和 Amazon Cognito 新增至所有請求的[常用參數](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-working-with-lambda-triggers.html#cognito-user-pools-lambda-trigger-syntax-shared)之組合。

------
#### [ JSON ]

```
{
    "userName": "string",
    "request": {
        "password": "string",
        "validationData": {
            "string": "string",
            . . .
        },
        "clientMetadata": {
            "string": "string",
      	. . .
        }
    },
    "response": {
        "userAttributes": {
            "string": "string",
            . . .
        },
        "finalUserStatus": "string",
        "messageAction": "string",
        "desiredDeliveryMediums": [ "string", . . .],
        "forceAliasCreation": boolean,
        "enableSMSMFA": boolean
    }
}
```

------

### 遷移使用者請求參數
<a name="cognito-user-pools-lambda-trigger-syntax-user-migration-request"></a>

**使用者名稱**  
使用者在登入時輸入的使用者名稱。

**password**  
使用者在登入時輸入的密碼。Amazon Cognito 不會在由忘記密碼流程啟動的請求中傳送此值。

**validationData**  
一或多個鍵值組，包含使用者登入請求中的驗證資料。若要將此資料傳遞至您的 Lambda 函數，您可以使用 [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) 和 [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) API 動作中的 ClientMetadata 參數。

**clientMetadata**  
您可以做為 Lambda 函數的自訂輸入提供的一個或多個鍵值組，該函數用於遷移使用者觸發程序。若要將此資料傳遞至您的 Lambda 函數，您可以使用 [AdminRespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminRespondToAuthChallenge.html) 和 [ForgotPassword](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ForgotPassword.html) API 動作中的 ClientMetadata 參數。

### 遷移使用者回應參數
<a name="cognito-user-pools-lambda-trigger-syntax-user-migration-response"></a>

**userAttributes**  
此欄位為必填。  
此欄位必須包含一或多個 Amazon Cognito 存放在您使用者集區中的使用者描述檔中並作為使用者屬性使用的名稱值組。您可以同時包含標準和自訂使用者屬性。自訂屬性需要 `custom:` 字首以便與標準屬性區分。如需詳細資訊，請參閱[自訂屬性](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-attributes.html#user-pool-settings-custom-attributes.html)。  
若要在忘記密碼流程中重設密碼，使用者必須擁有經驗證的電子郵件地址或經驗證的電話號碼。Amazon Cognito 會將包含重設密碼代碼的訊息，傳送至使用者屬性中的電子郵件地址或電話號碼。    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/cognito/latest/developerguide/user-pool-lambda-migrate-user.html)

**finalUserStatus**  
您可以將此參數設定為 `CONFIRMED` 以自動確認您的使用者，如此一來使用者即可使用先前的密碼登入。當您將使用者設定為 `CONFIRMED`，使用者無需進行額外的動作就能登入。如果您沒有將此屬性設定為 `CONFIRMED`，它被設定為 `RESET_REQUIRED`。  
`RESET_REQUIRED` 的 `finalUserStatus` 意味著使用者在登入時必須於遷移後立即變更密碼，並且您的用户端應用程式必須在身分驗證流程中處理 `PasswordResetRequiredException`。  
Amazon Cognito 不會強制執行您在使用 Lambda 觸發程序進行遷移期間為使用者集區設定的密碼強度政策。如果密碼不符合您設定的密碼政策，Amazon Cognito 仍會接受密碼，以便繼續遷移使用者。若要強制執行密碼強度政策，並拒絕不符合政策的密碼，請驗證程式碼中的密碼強度。如果密碼不符合政策，就將 finalUserStatus 設定為 `RESET_REQUIRED`。

**messageAction**  
您可以將此參數設定為 `SUPPRESS` 以拒絕傳送 Amazon Cognito 通常會向新使用者傳送的歡迎訊息。如果您的函數未傳回此參數，Amazon Cognito 會傳送歡迎訊息。

**desiredDeliveryMediums**  
您可以將此參數設定為 `EMAIL` 以透過電子郵件傳送歡迎訊息，或是設為 `SMS` 以透過簡訊傳送歡迎訊息。如果您的函數未傳回此參數，Amazon Cognito 會透過簡訊傳送歡迎訊息。

**forceAliasCreation**  
如果您將此參數設定為 `TRUE`，而 UserAttributes 參數中的電話號碼或電子郵件地址已存在做為不同使用者的別名，則 API 呼叫會將別名從之前的使用者遷移到新建立的使用者。先前的使用者將無法再使用該別名登入。  
如果您將此參數設定為 `FALSE`，而且別名已存在，Amazon Cognito 不會遷移使用者，並且會將錯誤傳回用户端應用程式。  
如果您未傳回此參數，Amazon Cognito 會假定其值為「false」。

**enableSMSMFA**  
將此參數設定為 `true`，以要求遷移的使用者完成 SMS 文字訊息多重要素驗證 (MFA) 才能登入。您的使用者集區必須啟用 MFA。請求參數中的用戶屬性必須包含電話號碼，否則該用戶的遷移將失敗。

## 範例：搭配現有密碼來遷移使用者
<a name="aws-lambda-triggers-user-migration-example-1"></a>

此範例 Lambda 函數會使用現有密碼遷移使用者，並避免歡迎訊息從 Amazon Cognito 中出現。

------
#### [ Node.js ]

```
exports.handler = (event, context, callback) => {
  var user;

  if (event.triggerSource == "UserMigration_Authentication") {
    // authenticate the user with your existing user directory service
    user = authenticateUser(event.userName, event.request.password);
    if (user) {
      event.response.userAttributes = {
        email: user.emailAddress,
        email_verified: "true",
      };
      event.response.finalUserStatus = "CONFIRMED";
      event.response.messageAction = "SUPPRESS";
      context.succeed(event);
    } else {
      // Return error to Amazon Cognito
      callback("Bad password");
    }
  } else if (event.triggerSource == "UserMigration_ForgotPassword") {
    // Lookup the user in your existing user directory service
    user = lookupUser(event.userName);
    if (user) {
      event.response.userAttributes = {
        email: user.emailAddress,
        // required to enable password-reset code to be sent to user
        email_verified: "true",
      };
      event.response.messageAction = "SUPPRESS";
      context.succeed(event);
    } else {
      // Return error to Amazon Cognito
      callback("Bad password");
    }
  } else {
    // Return error to Amazon Cognito
    callback("Bad triggerSource " + event.triggerSource);
  }
};
```

------