建立使用者匯入 CSV 檔案

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

下載 CSV 檔案標頭 (主控台)

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

若要下載 CSV 檔案標頭

1. 前往 Amazon Cognito 主控台。您可能會收到提示，要求您輸入 AWS 憑證。

2. 選擇 User Pools (使用者集區)。

3. 從清單中選擇現有的使用者集區。

4. 選擇 Users (使用者) 索引標籤。

5. 在 Import users (匯入使用者) 區段，選擇 Create an import job (建立匯入任務)。

6. 在 Upload CSV (上傳 CSV) 之下，選取 template.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 檔案中的直欄順序不重要。

• 第一列之後的每一列各包含一個使用者的屬性值。

• 標頭中的所有直欄都必須存在，但不需要在每個直欄中提供值。

• 以下是必要屬性：

  • cognito:username

  • cognito:mfa_enabled

  • email_verified 或 phone_number_verified

    • 每個使用者必須至少有其中一個自動驗證屬性為 true。自動驗證屬性是當新使用者加入您的使用者集區時，Amazon Cognito 自動傳送代碼的電子郵件地址或電話號碼。

    • 使用者集區必須至少有一個自動驗證的屬性，可以是 email_verified 或 phone_number_verified。如果使用者集區沒有自動驗證屬性，匯入任務將不會啟動。

    • 如果使用者集區只有一個自動驗證屬性，則必須為每個使用者驗證該屬性。例如，如果使用者集區只有 phone_number 是自動驗證屬性，則每個使用者的 phone_number_verified 值必須為 true。

    注意

    為了讓使用者能夠重設密碼，他們必須要有已驗證的電子郵件或電話號碼。Amazon Cognito 會將包含重設密碼代碼的訊息傳送至 CSV 檔案中指定的電子郵件或電話號碼。如果訊息是傳送到電話號碼，則是透過 SMS 訊息傳送。如需更多詳細資訊，請參閱 註冊時驗證聯絡資訊。

  • email (如果 email_verified 為 true)

  • phone_number (如果 phone_number_verified 為 true)

  • 在您建立使用者集區時標記為必要的任何屬性

• 字串形式的屬性值不能用引號括住。

• 如果屬性值包含逗號，您必須在逗號前面放置斜線 (\)。這是因為 CSV 檔案中的欄位是以逗號分隔。

• CSV 檔案內容應該是沒有位元組順序標記的 UTF-8 格式。

• cognito:username 是必要欄位，並且在您的使用者集區中必須是唯一的。它可以是任何 Unicode 字串，但是不能包含空格或 Tab。

• 如果有 birthdate 值，其格式必須為 mm/dd/yyyy。這表示，例如生日是 1985 年 2 月 1 日，則必須編碼為 02/01/1985。

• cognito:mfa_enabled 是必要欄位。如果您在使用者集區中將多重要素驗證 (MFA) 設定為必要項目，則所有使用者的這個欄位必須為 true。如果您將 MFA 設為關閉，則所有使用者的這個欄位必須為 false。如果您將 MFA 設為選用，則這個欄位可以是 true 或 false，但不能空白。

• 列的長度上限為 16,000 個字元。

• CSV 檔案大小上限為 100 MB。

• 檔案中的列數 (使用者數) 上限為 500,000。此上限不包括標題列。

• updated_at 欄位值應該是 epoch 時間 (以秒為單位)，例如：1471453471。

• 屬性值中的任何首尾空格都會截去。

下列清單是沒有自訂屬性之使用者集區的 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,,,,,,,[e-mail],TRUE,,02/01/1985,,,[phone],TRUE,123 Any Street,,FALSE
Jane,,Jane,Roe,,,,,,,[e-mail],TRUE,,01/01/1985,,,[phone],TRUE,100 Main Street,,FALSE