本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 從 CSV 檔案將使用者匯入使用者集區
當您有外部身分存放區，以及為新的本機使用者準備使用者集區的時間時，從逗號分隔值 (CSV) 檔案大量使用者匯入可以是遷移到 Amazon Cognito 使用者集區的低成本、低成本選項。CSV 檔案匯入是下載和填入範本檔案的程序，然後在匯入任務中將檔案交給您的使用者集區。您可以使用 CSV 匯入來快速建立測試使用者。您也可以以程式設計方式將檔案填入外部身分存放區的讀取 API 請求，接著將其詳細資訊和屬性剖析為檔案的寫入操作。
根據預設，匯入程序會為**密碼**以外的所有使用者屬性設定值。這表示您的使用者必須在第一次登入時變更密碼。您的使用者在使用此方法匯入時處於 `RESET_REQUIRED` 狀態。
或者，您可以使用其現有的密碼雜湊匯入使用者。當您在匯入任務建立期間指定密碼雜湊演算法，並在 CSV 檔案中包含密碼雜湊時，Amazon Cognito 會使用現有的密碼匯入使用者。這些使用者會以 `CONFIRMED` 狀態建立，並且可以立即登入，而無需重設密碼。如需詳細資訊，請參閱[使用密碼雜湊匯入使用者](#cognito-user-pools-import-password-hash)。
從 CSV 匯入使用者的最低努力方法是在您的使用者集區中啟用[無密碼登入](amazon-cognito-user-pools-authentication-flow-methods.md#amazon-cognito-user-pools-authentication-flow-methods-passwordless)。透過電子郵件地址和電話號碼屬性以及正確的使用者集區組態，使用者可以在匯入任務完成後立即使用電子郵件或簡訊一次性密碼 (OTPs) 登入。如需詳細資訊，請參閱[需要匯入的使用者重設密碼](#cognito-user-pools-using-import-tool-password-reset)。
您也可以使用將 `Permanent` 參數設定為 的 [AdminSetUserPassword](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminSetUserPassword.html) API 請求來設定使用者的密碼`true`。CSV 匯入不會計入使用者集區中的每月計費作用中使用者 MAUs)。不過，密碼重設操作會產生 MAUs。若要在匯入具有密碼的大量使用者時管理成本，而這些使用者可能不會立即處於作用中狀態，請設定您的應用程式，在使用者登入並收到`RESET_REQUIRED`挑戰時提示他們輸入新密碼。
**注意**
每個使用者的建立日期，都是該使用者匯入使用者集區中的時間。建立日期不是匯入的屬性之一。
**建立使用者匯入任務的步驟**
1. 在 AWS Identity and Access Management (IAM) 主控台中建立 Amazon CloudWatch Logs 角色。
1. 建立使用者匯入 .csv 檔案。
1. 建立及執行使用者匯入任務。或者，指定密碼雜湊演算法，以使用其現有的密碼雜湊匯入使用者。
1. 上傳使用者匯入 .csv 檔案。
1. 啟動及執行使用者匯入任務。
1. 使用 CloudWatch 來檢查事件日誌。
1. 如果您未匯入密碼雜湊， 會要求匯入的使用者重設密碼。
**其他資源**
+ [Cognito 使用者設定檔匯出參考架構](https://aws.amazon.com/solutions/implementations/cognito-user-profiles-export-reference-architecture/)，用於在使用者集區之間匯出使用者帳戶
**Topics**
+ [建立 CloudWatch Logs IAM 角色](#cognito-user-pools-using-import-tool-cli-cloudwatch-iam-role)
+ [建立使用者匯入 CSV 檔案](#cognito-user-pools-using-import-tool-csv-header)
+ [建立及執行 Amazon Cognito 使用者集區匯入任務](#cognito-user-pools-creating-import-job)
+ [在 CloudWatch 主控台中檢視使用者集區匯入結果](#cognito-user-pools-using-import-tool-cloudwatch)
+ [需要匯入的使用者重設密碼](#cognito-user-pools-using-import-tool-password-reset)
+ [使用密碼雜湊匯入使用者](#cognito-user-pools-import-password-hash)
## 建立 CloudWatch Logs IAM 角色
如果您是使用 Amazon Cognito CLI 或 API，則您需要建立 CloudWatch IAM 角色。下列程序說明如何建立 IAM 角色，讓 Amazon Cognito 可用來將匯入任務的結果寫入 CloudWatch Logs。
**注意**
在 Amazon Cognito 主控台中建立匯入任務時，可以同時建立 IAM 角色。當您選擇 **Create a new IAM role** (建立新的 IAM 角色) 時，Amazon Cognito 會自動將適當的信任政策和 IAM 政策套用至該角色。
**建立 CloudWatch Logs IAM 角色以進行使用者集區匯入 (AWS CLI、API)**
1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 的 IAM 主控台。
1. 為 建立新的 IAM 角色 AWS 服務。如需進一步說明，請參閱 *AWS Identity and Access Management 使用者指南*中的[為 AWS 服務建立角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html#roles-creatingrole-service-console)。
1. 當您為 **Trusted entity type** (信任的實體類型) 選取**使用案例**時，請選擇任何服務。Amazon Cognito 目前未列在服務使用案例中。
1. 在 **Add permissions** (新增許可) 畫面中，選擇 **Create policy** (建立政策)，然後插入下列政策陳述式。將 {{REGION}} 取代為使用者集 AWS 區域 區的 ，例如 `us-east-1`。使用您的 AWS 帳戶 ID 取代 {{ACCOUNT}}，例如 `111122223333`。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:DescribeLogStreams",
"logs:PutLogEvents"
],
"Resource": [
"arn:aws:logs:{{us-east-1}}:{{111122223333}}:log-group:/aws/cognito/*"
]
}
]
}
```
------
1. 由於您在建立角色時並未選擇 Amazon Cognito 做為受信任的實體，您現在必須手動編輯角色的信任關係。在 IAM 主控台的導覽窗格中，選擇 **Roles** (角色)，然後選擇建立的新角色。
1. 選擇**信任關係**標籤。
1. 選擇**編輯信任政策**。
1. 將下列政策陳述式貼到 **Edit trust policy** (編輯信任政策) 中，取代任何現有的文字：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "cognito-idp.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. 選擇**更新政策**。
1. 請記下 角色 ARN。當您建立匯入任務時，將需要提供此 ARN。
## 建立使用者匯入 CSV 檔案
您必須先建立包含欲匯入使用者及其屬性的逗號分隔值 (CSV) 檔案，才能將現有使用者匯入使用者集區。從您的使用者集區中，您可以擷取含有反映使用者集區屬性結構描述之標頭的使用者匯入檔案。然後，您可以插入符合 [格式化 CSV 檔案](#cognito-user-pools-using-import-tool-formatting-csv-file) 中格式化需求的使用者資訊。
### 下載 CSV 檔案標頭 (主控台)
使用下列程序下載 CSV 標頭檔案。
**若要下載 CSV 檔案標頭**
1. 前往 [Amazon Cognito 主控台](https://console.aws.amazon.com/cognito/home)。系統可能會提示您輸入 AWS 登入資料。
1. 選擇 **User Pools** (使用者集區)。
1. 從清單中選擇現有的使用者集區。
1. 選擇**使用者**選單。
1. 在 **Import users** (匯入使用者) 區段，選擇 **Create an import job** (建立匯入任務)。
1. 在 **Upload CSV** (上傳 CSV) 之下，選取 *template.csv* 連結並下載 CSV 檔案。
### 下載 CSV 檔案標頭 (AWS 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 檔案，以使其包含此標頭以及使用者的屬性值，並依照下列規則將其格式化：
**注意**
如需屬性值的詳細資訊，例如電話號碼的適當格式，請參閱[使用使用者屬性](user-pool-settings-attributes.md)。
+ 檔案中的第一列是所下載的標頭列，其中包含使用者屬性名稱。
+ CSV 檔案中的直欄順序不重要。
+ 第一列之後的每一列各包含一個使用者的屬性值。
+ 標頭中的所有直欄都必須存在，但不需要在每個直欄中提供值。
+ 以下是必要屬性：
+ **cognito:username**
+ **email\_verified** 或 **phone\_number\_verified**
+ 每個使用者必須至少有其中一個自動驗證屬性為 `true`。自動驗證屬性是當新使用者加入您的使用者集區時，Amazon Cognito 自動傳送代碼的電子郵件地址或電話號碼。
+ 使用者集區必須至少有一個自動驗證的屬性，可以是 **email\_verified** 或 **phone\_number\_verified**。如果使用者集區沒有自動驗證屬性，匯入任務將不會啟動。
+ 如果使用者集區只有一個自動驗證屬性，則必須為每個使用者驗證該屬性。例如，如果使用者集區只有 **phone\_number** 是自動驗證屬性，則每個使用者的 **phone\_number\_verified** 值必須為 `true`。
**注意**
為了讓使用者能夠重設密碼，他們必須要有已驗證的電子郵件或電話號碼。Amazon Cognito 會將包含重設密碼代碼的訊息傳送至 CSV 檔案中指定的電子郵件或電話號碼。如果訊息是傳送到電話號碼，則是透過 SMS 訊息傳送。如需詳細資訊，請參閱[註冊時驗證聯絡資訊](signing-up-users-in-your-app.md#allowing-users-to-sign-up-and-confirm-themselves)。
+ **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 要求。如果您已將使用者集區中的多重要素驗證 (MFA) 設定為必要，則所有使用者的此欄位都必須為 `true`或空白。如果您已將 MFA 設定為關閉，則所有使用者的此欄位都必須為 `false`或空白。空白值會將匯入使用者啟用 MFA 的狀態設定為使用者集區所需的狀態。無論您是否設定`cognito:mfa_enabled`值，都可以在沒有有效 MFA 因素的情況下，在 MFA 要求的使用者集區中匯入使用者。處於此狀態的使用者已啟用 MFA，但在設定電子郵件屬性、電話號碼屬性或 TOTP 之前無法登入，且該組態是您使用者集區中的有效 MFA 因素。
+ 列的長度上限為 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,,,,,,,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。
**Topics**
+ [從 CSV 檔案匯入使用者 (主控台)](#cognito-user-pools-using-import-tool-console)
+ [匯入使用者 (AWS CLI)](#cognito-user-pools-using-import-tool-cli)
### 從 CSV 檔案匯入使用者 (主控台)
下列程序說明如何從 CSV 檔案匯入使用者。
**從 CSV 檔案匯入使用者 (主控台)**
1. 前往 [Amazon Cognito 主控台](https://console.aws.amazon.com/cognito/home)。系統可能會提示您輸入 AWS 登入資料。
1. 選擇 **User Pools** (使用者集區)。
1. 從清單中選擇現有的使用者集區。
1. 選擇**使用者**選單。
1. 在 **Import users** (匯入使用者) 區段，選擇 **Create an import job** (建立匯入任務)。
1. 在 **Create import job** (建立匯入任務) 頁面上，輸入 **Job name** (任務名稱)。
1. 選擇**Create a new IAM role** (建立新的 IAM 角色)，或 **Use an existing IAM role** (使用現有的 IAM 角色)。
1. 如果您選擇 **Create a new IAM role** (建立新的 IAM 角色)，請輸入新角色的名稱。Amazon Cognito 會自動建立具有正確許可和信任關係的角色。建立匯入任務的 IAM 主體，必須具備建立 IAM 角色的許可。
1. 如果您選擇 **Use an existing IAM role** (使用現有的 IAM 角色)，請從 **IAM role selection** (IAM 角色選擇) 下的清單中選擇角色。此角色必須具有 [建立 CloudWatch Logs IAM 角色](#cognito-user-pools-using-import-tool-cli-cloudwatch-iam-role) 中所述的許可和信任政策。
1. 在**上傳 CSV** 下，選擇**選擇檔案**並連接您準備的 CSV 檔案。
1. 選擇 **Create job** (建立任務) 以提交任務，但稍後再開始。選擇 **Create and start job** (建立並開始任務)，以提交並立即開始任務。
1. 如果您已建立任務但尚未開始，可以稍後再開始。在**匯入使用者**下的**使用者**選單中，選擇您的匯入任務，然後選取**開始**。您也可以從 AWS SDK 提交 [StartUserImportJob](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_StartUserImportJob.html) API 請求。
1. 在匯入使用者下的 **使用者** 選單中監控使用者**匯入**任務的進度。如果任務未成功，您可以選取 **Status** (狀態) 值。如需其他詳細資訊，請選取 **View the CloudWatch logs for more details** (檢視 CloudWatch 日誌以取得更多詳細資訊)，並在 CloudWatch Logs 主控台中檢視任何問題。
### 匯入使用者 (AWS CLI)
下列 CLI 命令可用來將使用者匯入使用者集區中：
+ `create-user-import-job`
+ `get-csv-header`
+ `describe-user-import-job`
+ `list-user-import-jobs`
+ `start-user-import-job`
+ `stop-user-import-job`
若要取得這些命令的命令列選項清單，請使用 `help` 命令列選項。例如：
```
aws cognito-idp get-csv-header help
```
#### 建立使用者匯入任務
在您建立 CSV 檔案之後，請執行下列 CLI 命令來建立使用者匯入任務，其中 {{JOB\_NAME}} 是您為任務選擇的名稱，{{USER\_POOL\_ID}} 是新使用者會新增至其中的使用者集區 ID，而 {{ROLE\_ARN}} 是您在 [建立 CloudWatch Logs IAM 角色](#cognito-user-pools-using-import-tool-cli-cloudwatch-iam-role) 中收到的角色 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。
**Example 回應：**
```
{
"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`值：
+ `Created` – 任務已建立但未啟動。
+ `Pending` – 轉換狀態。您已啟動任務，但它尚未開始匯入使用者。
+ `InProgress` – 任務已啟動，並且正在匯入使用者。
+ `Stopping` – 您已停止任務，但該任務尚未停止匯入使用者。
+ `Stopped` – 您已停止任務，且該任務已停止匯入使用者。
+ `Succeeded` – 任務已成功完成。
+ `Failed` – 由於發生錯誤，任務已停止。
+ `Expired` – 您已建立任務，但未於 24 到 48 小時內啟動任務。與任務相關聯的所有資料都已刪除，無法啟動任務。
#### 上傳 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}}"
```
**Example 回應範例：**
```
{
"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
```
**Example 回應範例：**
```
{
"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}}"
```
每個帳戶一次只能有一個匯入任務處於作用中狀態。
**Example 回應範例：**
```
{
"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}}"
```
**Example 回應範例：**
```
{
"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 主控台中檢視匯入任務的結果。
**Topics**
+ [檢視結果](#cognito-user-pools-using-import-tool-viewing-the-results)
+ [解譯結果](#cognito-user-pools-using-import-tool-interpreting-the-results)
### 檢視結果
下列步驟說明如何檢視使用者集區匯入結果。
**檢視使用者集區匯入的結果**
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。
1. 選擇 **Logs** (日誌)。
1. 選擇使用者集區匯入任務的日誌群組。日誌群組名稱的格式為 `/aws/cognito/userpools/{{USER_POOL_ID}}/{{USER_POOL_NAME}}`。
1. 選擇您剛才執行的使用者匯入任務的日誌。日誌名稱的格式為 {{JOB\_ID}}/{{JOB\_NAME}}。日誌中的結果會依行號參照您的使用者。使用者資料不會寫入日誌中。針對每個使用者，會顯示類似下列字行：
+ `[SUCCEEDED] Line Number 5956 - The import succeeded.`
+ `[SKIPPED] Line Number 5956 - The user already exists.`
+ `[FAILED] Line Number 5956 - The User Record does not set any of the auto verified attributes to true. (Example: email_verified to true).`
### 解譯結果
成功匯入的使用者狀態會設為 "PasswordReset"。
在下列情況下，將不會匯入使用者，但匯入任務會繼續：
+ 沒有自動驗證屬性設為 `true`。
+ 使用者資料不符合結構描述。
+ 因為內部錯誤，無法匯入使用者。
在下列情況下，匯入任務會失敗：
+ Amazon CloudWatch Logs 角色無法擔任、沒有正確的存取政策或已刪除。
+ 使用者集區已刪除。
+ Amazon Cognito 無法剖析 .csv 檔案。
## 需要匯入的使用者重設密碼
如果您的使用者集區只提供以密碼為基礎的登入，使用者必須在匯入後重設密碼。第一次登入時，他們可以輸入*任何*密碼。Amazon Cognito 會提示他們在 API 回應中輸入來自您應用程式的登入請求中輸入新密碼。
如果您的使用者集區具有無密碼身分驗證因素，Amazon Cognito 會預設為匯入使用者的身分驗證因素。系統不會提示他們輸入新密碼，而且可以立即使用無密碼電子郵件或 SMS OTP 登入。您也可以提示使用者設定密碼，讓他們可以完成其他登入方法，例如 username-password 和 passkey。下列條件適用於使用者匯入後的無密碼登入。
1. 您必須匯入具有對應至可用無密碼登入因素之屬性的使用者。如果使用者可以使用電子郵件地址登入，您必須匯入 `email` 屬性。如果是電話號碼，您必須匯入`phone_number`屬性。如果兩者皆是，請匯入任一屬性的值。
1. 一般而言，使用者匯入`RESET_REQUIRED`的狀態必須重設密碼。如果他們能夠使用無密碼因素登入，Amazon Cognito 會將他們的狀態設定為 `CONFIRMED`。
如需無密碼身分驗證的詳細資訊，包括如何設定以及如何在應用程式中建構身分驗證流程，請參閱 [使用 Amazon Cognito 使用者集區進行身分驗證](authentication.md)。
下列程序說明在您匯入 CSV 檔案`RESET_REQUIRED`後， 中具有本機使用者的自訂登入機制使用者體驗。如果您的使用者使用受管登入來登入，請指示他們選取**忘記密碼？** 選項，提供來自其電子郵件或文字訊息的代碼，並設定密碼。
**需要匯入的使用者重設密碼**
1. 在您的應用程式中，使用隨機密碼透過 `InitiateAuth` 默默地登入目前使用者。
1. Amazon Cognito 會在啟用 `PreventUserExistenceErrors` 時傳回 `NotAuthorizedException`。否則會傳回 `PasswordResetRequiredException`。
1. 您的應用程序發出 `ForgotPassword` API 請求並重設使用者的密碼。
1. 應用程式在 `ForgotPassword` API 請求中提交使用者名稱。
1. Amazon Cognito 會將代碼傳送至已驗證的電子郵件或電話號碼。目的地取決於您在 CSV 檔案中為 `email_verified` 和 `phone_number_verified` 提供的值。對 `ForgotPassword` 請求的回應指示代碼的目的地。
**注意**
您的使用者集區必須經過設定，以驗證電子郵件或電話號碼。如需詳細資訊，請參閱[註冊及確認使用者帳戶](signing-up-users-in-your-app.md)。
1. 您的應用程式會向使用者顯示一則訊息，以檢查代碼傳送的位置，並提示您的使用者輸入代碼和新密碼。
1. 使用者在應用程式中輸入確認碼和新密碼。
1. 應用程式在 `ConfirmForgotPassword` API 請求中提交代碼和新密碼。
1. 您的應用程式將使用者重新導向到登入步驟。
## 使用密碼雜湊匯入使用者
當您將使用者從現有的身分驗證系統遷移至 Amazon Cognito 時，您可以匯入其密碼雜湊及其使用者屬性。然後，您的使用者可以使用現有的密碼立即登入，而無需重設密碼。使用者第一次登入後，Amazon Cognito 會透明地將其登入資料遷移至原生 Amazon Cognito 身分驗證系統。
**重要**
密碼雜湊匯入目前不適用於所有使用者集區。密碼雜湊匯入需要具有增強功能和可擴展性的現代 Amazon Cognito 基礎設施。有些使用者集區仍在先前的基礎設施上， AWS 並將它們升級到新的基礎設施，以解鎖此功能。在 Amazon Cognito 主控台中，合格的使用者集區會在建立匯入任務時顯示密碼雜湊演算法選項，而不合格的集區不會顯示此選項。如需詳細資訊，請參閱 AWS 安全部落格中的 [Amazon Cognito 使用新一代基礎設施解鎖進階功能](https://aws.amazon.com/blogs/security/amazon-cognito-unlocks-advanced-capabilities-with-next-generation-infrastructure/)。
### 密碼雜湊匯入的運作方式
使用密碼雜湊匯入，您可以遷移使用者，同時保留其使用現有密碼登入的能力。匯入程序的運作方式如下：
1. 您可以建立匯入任務，並指定來源系統用來建立密碼雜湊的密碼雜湊演算法。
1. 您可以在 CSV 檔案中包含 `password_hash` 欄，其中包含每個使用者的密碼雜湊值。
1. Amazon Cognito 會使用其密碼雜湊匯入使用者，並以 `CONFIRMED` 狀態建立使用者。使用者可以立即登入。
1. 當使用者第一次登入時，Amazon Cognito 會根據匯入的雜湊驗證其密碼。成功驗證後，Amazon Cognito 會將使用者的登入資料遷移至原生身分驗證系統。
1. 所有後續登入都會使用原生 Amazon Cognito 身分驗證系統。
**重要**
單一匯入任務中的所有密碼雜湊都必須使用相同的演算法。建立匯入任務時，您可以在任務層級指定演算法。
**注意**
在使用者完成第一次登入且 Amazon Cognito 遷移其登入資料之前，您無法對該使用者使用安全遠端密碼 (SRP) 身分驗證。針對具有匯入密碼雜湊且尚未登入的使用者，使用 `USER_PASSWORD_AUTH`或 `ADMIN_USER_PASSWORD_AUTH`流程。
### 支援的密碼雜湊演算法
Amazon Cognito 支援下列用於匯入的密碼雜湊演算法：
`BCRYPT`
bcrypt 自適應雜湊函數。Amazon Cognito 會從雜湊字串擷取所有必要的參數 （鹽、成本因素）。
**格式**：`$2$[cost]$[22-char salt][31-char hash]`
**範例**：`$2b$10$CtA.Rcu/szzn9U00wpUjOuN3vrgJRZycv4aOzcP3GzqzO8UDPEFq6`
**最大成本因素：**10
`SCRYPT`
scrypt 密碼型金鑰衍生函數。Amazon Cognito 會從雜湊字串擷取所有必要的參數。
**格式**：`N$r$p$hexSalt$hexHash`
**範例**：`65536$8$1$304dbaef7c5e828dc19c98f0600d18fe$4f69c498c12cd102d057356facf8d77e8d42407090491ea32c5b038f5a18c099`
**參數上限：**N (CPU/記憶體成本） = 65536，r （區塊大小） = 8，p （平行處理） = 1
`ARGON2ID`
Argon2id 密碼雜湊演算法。Amazon Cognito 會從雜湊字串擷取所有必要的參數。
**格式**：`$argon2id$v=N$m=M,t=T,p=P$salt$hash`
**範例**：`$argon2id$v=19$m=19456,t=2,p=1$ko/G5o1ms+ML08P95sQ8DA$AkVbvWSOqz7Hs3qthhWKxicOWnGLN+MBmpwc3emi5VA`
**最大參數：**m (KiB 中的記憶體） = 19456，t （反覆運算） = 2，p （平行處理） = 1
`PBKDF2_SHA256`
使用 SHA-256 的密碼式金鑰衍生函數 2。Amazon Cognito 會從雜湊字串擷取所有必要的參數。
**格式**：`$pbkdf2-sha256$iterations$salt$hash`
**範例**：`$pbkdf2-sha256$600000$1XZlmwLQ2hhM3JYuCPiArQ$Pfheg9Zi/v5lXU4yyLA0WFUYEd/rlaVbzrM9oMD6IrA`
**重複次數上限：**600000
**注意**
所有支援的演算法都是自我描述的，這表示 Amazon Cognito 可以直接從雜湊字串擷取所有必要的參數 （例如 salt、成本因素和反覆運算）。您只需在建立匯入任務時指定演算法名稱。
如果密碼雜湊的參數值超過上列上限，則該使用者的匯入會失敗。在匯入之前，請檢閱來源系統的密碼雜湊組態，以確保相容性。
### 將密碼雜湊新增至 CSV 檔案
當您下載用於使用者匯入的 CSV 範本時，範本會包含 `password_hash`欄。將您要以現有密碼匯入之使用者的密碼雜湊值填入此欄。
**密碼雜湊匯入的 CSV 格式規則**
+ 當您的匯入任務指定密碼雜湊演算法時，需要 `password_hash`欄。如果您將特定使用者的值保留空白，Amazon Cognito 會在沒有密碼的情況下匯入該使用者，並將使用者設定為 `RESET_REQUIRED` 狀態。
+ 如果您的匯入任務指定密碼雜湊演算法，但您的 CSV 檔案不包含資料`password_hash`欄，則任務會失敗。
+ 如果密碼雜湊值格式錯誤或不符合指定演算法的預期格式，則該使用者的匯入會失敗。Amazon Cognito 不會建立使用者，並在 Amazon CloudWatch Logs 日誌中記錄失敗。
+ 密碼雜湊值區分大小寫。請確定它們符合演算法預期的確切格式。
**Example 具有密碼雜湊的範例 CSV**
下列範例顯示使用 bcrypt 密碼雜湊匯入使用者的 CSV 檔案：
```
cognito:username,email,email_verified,phone_number,phone_number_verified,password_hash
alejandro_rosalez,alejandro_rosalez@example.com,TRUE,+12345550100,TRUE,$2b$10$CtA.Rcu/szzn9U00wpUjOuN3vrgJRZycv4aOzcP3GzqzO8UDPEFq6
mary_major,mary_major@example.com,TRUE,+12345550199,TRUE,$2b$10$CtA.Rcu/szzn9U00wpUjOuN3vrgJRZycv4aOzcP3GzqzO8UDPEFq6
```
### 使用密碼雜湊建立匯入任務 (AWS CLI)
若要匯入具有密碼雜湊的使用者，您必須在建立匯入任務時指定密碼雜湊演算法。匯入任務中的所有使用者都必須使用相同的演算法。
使用下列 AWS Command Line Interface 命令來建立具有密碼雜湊的匯入任務。`--password-hashing-algorithm` 參數指定用來在 CSV 檔案中建立密碼雜湊的演算法。
```
aws cognito-idp create-user-import-job \
--job-name "{{JOB_NAME}}" \
--user-pool-id "{{USER_POOL_ID}}" \
--cloud-watch-logs-role-arn "{{ROLE_ARN}}" \
--password-hashing-algorithm {{BCRYPT}}
```
將 {{BCRYPT}} 取代為其中一個支援的演算法：`BCRYPT`、`ARGON2ID`、 `SCRYPT`或 `PBKDF2_SHA256`。
**Example 回應範例**
```
{
"UserImportJob": {
"Status": "Created",
"SkippedUsers": 0,
"UserPoolId": "{{USER_POOL_ID}}",
"ImportedUsers": 0,
"JobName": "{{JOB_NAME}}",
"JobId": "{{JOB_ID}}",
"PreSignedUrl": "{{PRE_SIGNED_URL}}",
"CloudWatchLogsRoleArn": "{{ROLE_ARN}}",
"PasswordHashingAlgorithm": "BCRYPT",
"FailedUsers": 0,
"CreationDate": 1470957431.965
}
}
```
回應包含 欄位，`PasswordHashingAlgorithm`確認您指定的演算法。將 CSV 檔案上傳至預先簽章的 URL，並啟動任務，如中所述[上傳 CSV 檔案](#cognito-user-pools-using-import-tool-cli-uploading-csv-file)。
### 匯入密碼雜湊後的使用者體驗
使用密碼雜湊匯入的使用者具有下列體驗：
+ **立即登入：**使用者可以在匯入後立即使用現有的密碼登入。使用者不會收到重設密碼的提示。
+ **使用者狀態：**Amazon Cognito 會建立狀態為 `CONFIRMED`而非 的使用者`RESET_REQUIRED`。
+ **透明遷移：**當使用者第一次登入時，Amazon Cognito 會根據匯入的雜湊驗證其密碼。成功驗證後，Amazon Cognito 會將登入資料遷移至原生身分驗證系統。所有後續登入都會使用原生系統。
+ **初始登入延遲：**具有匯入密碼雜湊的使用者第一次登入可能需要比後續登入稍微長一些的時間。Amazon Cognito 必須針對匯入的雜湊驗證密碼，並將登入資料遷移至原生身分驗證系統。
+ **密碼重設：**如果使用者在第一次登入之前重設密碼，則會使用原生 Amazon Cognito 身分驗證系統將匯入的密碼雜湊取代為新密碼。
### 對密碼雜湊匯入錯誤進行故障診斷
如果使用者的密碼雜湊匯入失敗，Amazon Cognito 會在 Amazon CloudWatch Logs 日誌中記錄失敗。常見的錯誤案例包括：
格式不正確的雜湊
密碼雜湊不符合指定演算法的預期格式。確認雜湊格式正確，且符合 中列出的其中一種格式[支援的密碼雜湊演算法](#cognito-user-pools-import-password-hash-algorithms)。
參數超出範圍
密碼雜湊包含超過允許值上限的參數值 （例如成本因素或反覆運算）。對於具有不相容雜湊的使用者，請選擇下列其中一個選項：
+ 將 `password_hash` 欄位保留空白，以匯入沒有密碼雜湊的使用者。Amazon Cognito 會將它們設定為 `RESET_REQUIRED` 狀態，而且他們必須在第一次登入時重設密碼。
+ 使用[使用者遷移 Lambda 觸發](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-migrate-user.html)程序在登入時遷移這些使用者，而不是透過 CSV 匯入。
+ 停用來源系統之前，請在使用者登入現有系統時，使用相容的參數重新雜湊密碼。
演算法不符
使用與匯入任務中指定的演算法不同的演算法建立密碼雜湊。單一匯入任務中的所有雜湊都必須使用相同的演算法。如果您有具有不同演算法的使用者，請為每個演算法建立個別的匯入任務。
缺少 password\_hash 資料欄
您在建立任務時指定密碼雜湊演算法，但 CSV 檔案不包含 `password_hash`欄。將 欄新增至 CSV 檔案或建立新任務，而不指定演算法。
當使用者的密碼雜湊匯入失敗時，Amazon Cognito 不會建立使用者。匯入任務中的其他使用者會繼續處理。檢閱您的 Amazon CloudWatch Logs 日誌，以識別哪些使用者失敗，以及每次失敗的原因。
### 密碼雜湊匯入的安全考量
Amazon Cognito 會將其他安全措施套用至匯入的密碼雜湊：
+ **雙重雜湊：**Amazon Cognito 會在儲存之前重新雜湊所有匯入的密碼雜湊，加上一層額外的密碼編譯保護，無論原始演算法的強度為何。
+ **自動遷移：**第一次身分驗證成功後，Amazon Cognito 會將使用者的登入資料遷移至 Amazon Cognito 所使用的原生安全遠端密碼 (SRP) 通訊協定。這可確保所有使用者最終都使用原生的高安全性身分驗證機制。
+ **資料清除：**匯入任務完成後，Amazon Cognito 會從暫時儲存中移除包含密碼雜湊的上傳 CSV 檔案。
**重要**
將包含密碼雜湊的 CSV 檔案視為敏感資料。在傳輸中保護它，並在匯入完成後安全地刪除它。