通过 CSV 文件将用户导入用户池中

如果您有外部身份存储，并且有时间为新的本地用户准备用户池，那么在迁移到 Amazon Cognito 用户池，选择从逗号分隔值（CSV）文件批量导入用户既省时省力，又可降低成本。CSV 文件导入是先下载和填入模板文件，然后在导入任务中将该文件移交给用户池的过程。您可以使用 CSV 导入来快速创建测试用户。您还可以通过编程的方式，使用读取 API 请求从外部身份存储中获取数据，然后解析这些数据的详细信息和属性，再将它们写入到文件中。

导入过程会设置所有用户属性的值，不过 password 除外。不支持导入密码，因为安全妥善做法要求密码不能为纯文本，而我们不支持导入哈希。这意味着，用户必须在首次登录时更改密码。使用此方法导入用户时，用户处于 RESET_REQUIRED 状态。

从 CSV 导入用户最省力的方法是在用户池中激活无密码登录。借助电子邮件地址和电话号码属性以及正确的用户池配置，用户可以在导入任务完成后立即使用电子邮件或短信一次性密码 (OTPs) 登录。有关更多信息，请参阅 要求导入的用户重置密码。

您还可以通过将Permanent参数设置为 AdminSetUserPasswordAPI 请求来设置用户的密码true。CSV 导入不会计入用户池中按月计费的活跃用户 (MAUs)。但是，确实会生成密码重置操作。 MAUs要在导入大量使用密码但可能无法立即激活的用户时管理成本，请将您的应用程序设置为在用户登录并接受RESET_REQUIRED质询时提示他们输入新密码。

创建日 CloudWatch 志 IAM 角色

如果您使用的是 Amazon Cognito CLI 或 API，则需要创建一个 CloudWatch IAM 角色。以下过程介绍如何创建一个 IAM 角色，Amazon Cognito 可以使用该角色将导入任务的结果写入日志。 CloudWatch

创建用户导入 CSV 文件

您必须先创建逗号分隔值（CSV，Comma-Separated Value）文件，在其中包含要导入的用户及其属性，然后才能将现有用户导入用户群体中。从用户群体中，您可以检索其标头反映了您的用户群体的属性架构的用户导入文件。然后，您可以插入符合 设置 CSV 文件的格式 中的格式要求的用户信息。

下载 CSV 文件标头（控制台）

使用以下步骤下载 CSV 标头文件。

下载 CSV 文件标头（Amazon CLI）

要获取正确标题的列表，请从 “导入用户” 下的 “用户” 菜单中选择 “创建导入任务”。在随后的对话框中，选择下载包含您的用户池属性的模板文件的template.csv链接。

您也可以运行以下 CLI 命令，其中USER_POOL_ID是要将用户导入到的用户池的用户池标识符：

aws cognito-idp get-csv-header --user-pool-id "USER_POOL_ID"

示例响应:

{
    "CSVHeader": [
        "name",
        "given_name",
        "family_name",
        "middle_name",
        "nickname",
        "preferred_username",
        "profile",
        "picture",
        "website",
        "email",
        "email_verified",
        "gender",
        "birthdate",
        "zoneinfo",
        "locale",
        "phone_number",
        "phone_number_verified",
        "address",
        "updated_at",
        "cognito:mfa_enabled",
        "cognito:username"
    ],
    "UserPoolId": "USER_POOL_ID"
}

设置 CSV 文件的格式

下载的用户导入 CSV 标头文件类似于以下字符串。它还包括您已添加到用户群体的所有自定义属性。

cognito:username,name,given_name,family_name,middle_name,nickname,preferred_username,profile,picture,website,email,email_verified,gender,birthdate,zoneinfo,locale,phone_number,phone_number_verified,address,updated_at,cognito:mfa_enabled

编辑 CSV 文件，以使文件包含此标头和用户的属性值，并根据以下规则设置格式：

以下列表是没有自定义属性的用户群体的 CSV 导入文件示例。您的用户群体架构可能与此示例有所不同。在这种情况下，您必须在从用户群体下载的 CSV 模板中提供测试值。

cognito:username,name,given_name,family_name,middle_name,nickname,preferred_username,profile,picture,website,email,email_verified,gender,birthdate,zoneinfo,locale,phone_number,phone_number_verified,address,updated_at,cognito:mfa_enabled
John,,John,Doe,,,,,,,johndoe@example.com,TRUE,,02/01/1985,,,+12345550100,TRUE,123 Any Street,,FALSE
Jane,,Jane,Roe,,,,,,,janeroe@example.com,TRUE,,01/01/1985,,,+12345550199,TRUE,100 Main Street,,FALSE

创建并运行 Amazon Cognito 用户池导入任务

本节介绍如何使用 Amazon Cognito 控制台和 Amazon Command Line Interface ()Amazon CLI创建和运行用户池导入任务。

从 CSV 文件导入用户（控制台）

以下过程介绍了如何从 CSV 文件导入用户。

导入用户（Amazon CLI）

以下 CLI 命令可用于将用户导入到用户池：

要获取这些命令的命令行选项列表，请使用 help 命令行选项。例如：

aws cognito-idp get-csv-header help

创建用户导入任务

创建 CSV 文件后，通过运行以下 CLI 命令创建用户导入任务，其中JOB_NAME是您为任务选择的名称，USER_POOL_ID是要向其中添加新用户的用户池的用户池 ID，ROLE_ARN也是您在中收到的角色 ARN：创建日 CloudWatch 志 IAM 角色

aws cognito-idp create-user-import-job --job-name "JOB_NAME" --user-pool-id "USER_POOL_ID" --cloud-watch-logs-role-arn "ROLE_ARN"

响应中PRE_SIGNED_URL返回的有效期为 15 分钟。在此之后，它将过期，而您必须创建新的用户导入任务以获取新的 URL。

{
    "UserImportJob": {
        "Status": "Created",
        "SkippedUsers": 0,
        "UserPoolId": "USER_POOL_ID",
        "ImportedUsers": 0,
        "JobName": "JOB_NAME",
        "JobId": "JOB_ID",
        "PreSignedUrl": "PRE_SIGNED_URL",
        "CloudWatchLogsRoleArn": "ROLE_ARN",
        "FailedUsers": 0,
        "CreationDate": 1470957431.965
    }
}

用户导入任务的状态值

在对用户导入命令的响应中，您将看到以下 Status 值当中的其中一个值：

上传 CSV 文件

使用以下 curl 命令将包含用户数据的 CSV 文件上传到您从 create-user-import-job 命令的响应中获取的预签名 URL。

curl -v -T "PATH_TO_CSV_FILE" -H "x-amz-server-side-encryption:aws:kms" "PRE_SIGNED_URL"

在此命令的输出中，查找 "We are completely uploaded and fine" 这一短语。此短语表示文件已成功上传。运行导入任务后，您的用户池不会将信息保留在导入文件中。它们完成或过期后，Amazon Cognito 会删除您上传的 CSV 文件。

描述用户导入任务

要获取用户导入任务的描述，请使用以下命令，其中USER_POOL_ID是您的用户池 ID，JOB_ID是您创建用户导入任务时返回的任务 ID。

aws cognito-idp describe-user-import-job --user-pool-id "USER_POOL_ID" --job-id "JOB_ID"

{
    "UserImportJob": {
        "Status": "Created",
        "SkippedUsers": 0,
        "UserPoolId": "USER_POOL_ID",
        "ImportedUsers": 0,
        "JobName": "JOB_NAME",
        "JobId": "JOB_ID",
        "PreSignedUrl": "PRE_SIGNED_URL",
        "CloudWatchLogsRoleArn":"ROLE_ARN",
        "FailedUsers": 0,
        "CreationDate": 1470957431.965
    }
}

在前面的示例输出中，PRE_SIGNED_URL是您将 CSV 文件上传到的网址。ROLE_ARN是您在创建角色时收到的 CloudWatch 日志角色 ARN。

列出用户导入任务

要列出用户导入任务，请使用以下命令：

aws cognito-idp list-user-import-jobs --user-pool-id "USER_POOL_ID" --max-results 2

{
    "UserImportJobs": [
        {
            "Status": "Created",
            "SkippedUsers": 0,
            "UserPoolId": "USER_POOL_ID",
            "ImportedUsers": 0,
            "JobName": "JOB_NAME",
            "JobId": "JOB_ID",
            "PreSignedUrl":"PRE_SIGNED_URL",
            "CloudWatchLogsRoleArn":"ROLE_ARN",
            "FailedUsers": 0,
            "CreationDate": 1470957431.965
        },
        {
            "CompletionDate": 1470954227.701,
            "StartDate": 1470954226.086,
            "Status": "Failed",
            "UserPoolId": "USER_POOL_ID",
            "ImportedUsers": 0,
            "SkippedUsers": 0,
            "JobName": "JOB_NAME",
            "CompletionMessage": "Too many users have failed or been skipped during the import.",
            "JobId": "JOB_ID",
            "PreSignedUrl":"PRE_SIGNED_URL",
            "CloudWatchLogsRoleArn":"ROLE_ARN",
            "FailedUsers": 5,
            "CreationDate": 1470953929.313
        }
    ],
    "PaginationToken": "PAGINATION_TOKEN"
}

任务按创建日期 (从近到远) 排列。第二个任务之后的PAGINATION_TOKEN字符串表示此列表命令还有其他结果。要列出更多结果，请使用 --pagination-token 选项，如下所示：

aws cognito-idp list-user-import-jobs --user-pool-id "USER_POOL_ID" --max-results 10 --pagination-token "PAGINATION_TOKEN"

启动用户导入任务

要启动用户导入任务，请使用以下命令：

aws cognito-idp start-user-import-job --user-pool-id "USER_POOL_ID" --job-id "JOB_ID"

每个账户每次只能有一个导入任务处于活动状态。

{
    "UserImportJob": {
        "Status": "Pending",
        "StartDate": 1470957851.483,
        "UserPoolId": "USER_POOL_ID",
        "ImportedUsers": 0,
        "SkippedUsers": 0,
        "JobName": "JOB_NAME",
        "JobId": "JOB_ID",
        "PreSignedUrl":"PRE_SIGNED_URL",
        "CloudWatchLogsRoleArn": "ROLE_ARN",
        "FailedUsers": 0,
        "CreationDate": 1470957431.965
    }
}

停止用户导入任务

要停止正在进行的用户导入任务，请使用以下命令。停止任务后，无法重新启动该任务。

aws cognito-idp stop-user-import-job --user-pool-id "USER_POOL_ID" --job-id "JOB_ID"

{
    "UserImportJob": {
        "CompletionDate": 1470958050.571,
        "StartDate": 1470958047.797,
        "Status": "Stopped",
        "UserPoolId": "USER_POOL_ID",
        "ImportedUsers": 0,
        "SkippedUsers": 0,
        "JobName": "JOB_NAME",
        "CompletionMessage": "The Import Job was stopped by the developer.",
        "JobId": "JOB_ID",
        "PreSignedUrl":"PRE_SIGNED_URL",
        "CloudWatchLogsRoleArn": "ROLE_ARN",
        "FailedUsers": 0,
        "CreationDate": 1470957972.387
    }
}

在 CloudWatch 控制台中查看用户池导入结果

您可以在 Amazon CloudWatch 控制台中查看导入任务的结果。

查看结果

以下步骤介绍了如何查看用户池导入结果。

解析结果

成功导入的用户的状态设置为 “PasswordReset”。

在以下情况下，将不会导入用户，但导入任务将继续：

在以下情况下，导入任务将失败：

要求导入的用户重置密码

如果您的用户池仅提供基于密码的登录，则用户必须在导入密码后重置密码。他们第一次登录时可以输入任何密码。Amazon Cognito 会在 API 响应您的应用程序的登录请求时提示他们输入新密码。

如果您的用户池具有无密码身份验证因子，Amazon Cognito 会默认为导入用户的身份验证系数。他们不会被提示输入新密码，他们可以立即使用无密码电子邮件或 SMS OTP 登录。您还可以提示用户设置密码，以便他们可以完成其他登录方法，例如用户名密码和密钥。以下条件适用于用户导入后的无密码登录。

有关无密码身份验证的更多信息，包括如何设置无密码身份验证以及如何在应用程序中构建身份验证流程，请参阅。使用 Amazon Cognito 用户池进行身份验证

以下过程描述了在导入 CSV 文件RESET_REQUIRED后，在自定义登录机制中使用本地用户的用户体验。如果您的用户使用托管登录方式登录，请他们选择 “忘记密码？” 选项，提供他们的电子邮件或短信中的代码，然后设置密码。