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

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

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

您可以使用 AdminSetUserPassword API 请求，将 Permanent 参数设置为 true 来设置用户的密码。CSV 导入不会计入用户池中的计费月活跃用户（MAU）。但密码重置操作会生成 MAU。要在导入大量可能不会立即处于活动状态的用户时控制成本，请将您的应用程序设置为在用户登录并收到 RESET_REQUIRED 质询时提示他们输入新密码。

创建 CloudWatch Logs IAM 角色

如果您使用的是 Amazon Cognito CLI 或 API，则需要创建一个 CloudWatch IAM 角色。以下过程描述了如何创建 IAM 角色，Amazon Cognito 可以使用该角色将导入作业的结果写入 CloudWatch Logs。

创建用户导入 CSV 文件

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

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

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

下载 CSV 文件标头（Amazon CLI）

要获取一系列正确的标头，请运行以下 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 是您在 创建 CloudWatch Logs IAM 角色 中收到的角色 ARN：

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" 这一短语。此短语表示文件已成功上传。

描述用户导入任务

要获取用户导入任务的描述，请使用以下命令，其中，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 文件的目标 URL。ROLE_ARN 是您创建角色时收到的 CloudWatch Logs 角色 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”。

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

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

要求导入的用户重置密码

每个导入的用户第一次登录并输入任意密码时，系统都会要求其输入新密码。以下过程描述了您导入 CSV 文件后，本地用户在自定义应用程序中的用户体验。如果您的用户使用托管 UI 登录，Amazon Cognito 会在其首次登录时提示他们设置新密码。