從CSV檔案將使用者匯入使用者集區

當您擁有外部身分存放區，以及為新的本機使用者準備使用者集區的時間時，大量使用者從逗號分隔值 （CSV） 檔案匯入可以是遷移至 Amazon Cognito 使用者集區的低耗用、低成本選項。CSV 檔案匯入是下載和填入範本檔案的程序，然後在匯入任務中將檔案移交給您的使用者集區。您可以使用CSV匯入來快速建立測試使用者。您也可以以程式設計方式將檔案填入外部身分存放區的讀取API請求，接著將其詳細資訊和屬性剖析為檔案的寫入操作。

匯入程序會設定所有使用者屬性的值，只有 password (密碼) 除外。不支援匯入密碼，因為安全最佳實務要求不能以純文字提供密碼，而我們不支援匯入雜湊碼。這表示您的使用者必須在第一次登入時變更密碼。您的使用者在使用此方法匯入時處於 RESET_REQUIRED 狀態。

您可以使用 設定使用者的密碼 AdminSetUserPassword API 請求將 Permanent 參數設定為 true。CSV 匯入不會對使用者集區中的每月計費作用中使用者 （MAUs） 做出貢獻。不過，密碼重設操作會產生 MAUs。若要在匯入大量可能未立即啟用的使用者時管理成本，請設定您的應用程式，在使用者登入並收到RESET_REQUIRED挑戰時提示他們輸入新密碼。

建立 CloudWatch 日誌IAM角色

如果您使用的是 Amazon Cognito CLI或 API，則需要建立 CloudWatch IAM角色。下列程序說明如何建立 Amazon Cognito 可用來將匯入任務的結果寫入 CloudWatch Logs IAM的角色。

建立使用者匯入CSV檔案

您必須先建立逗號分隔值 （CSV） 檔案，其中包含要匯入的使用者及其屬性，才能將現有使用者匯入您的使用者集區。從您的使用者集區中，您可以擷取含有反映使用者集區屬性結構描述之標頭的使用者匯入檔案。然後，您可以插入符合 格式化CSV檔案 中格式化需求的使用者資訊。

下載CSV檔案標頭 （主控台）

使用下列程序下載CSV標頭檔案。

下載CSV檔案標頭 （AWS 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 主控台和 AWS Command Line Interface （） 建立和執行使用者集區匯入任務AWS CLI。

從CSV檔案匯入使用者 （主控台）

下列程序說明如何從 CSV 檔案匯入使用者。

匯入使用者 (AWS 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的檔案上傳至URL您從create-user-import-job命令回應中取得的預先簽章。

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 是您URL上傳CSV檔案的 。所以此 ROLE_ARN 是您建立角色時ARN收到的 CloudWatch Logs 角色。

列出您的使用者匯入任務

若要列出您的使用者匯入任務，請使用下列命令：

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 會在首次登入時提示他們設定新密碼。