本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 匯入格式配額與驗證
## 匯入配額
Amazon S3 的 DynamoDB 匯入可支援多達 50 個並行匯入任務，在 us-east-1、us-west-2 和 eu-west-1 區域的匯入來源物件大小總計達 15TB。在所有其他區域中，最多支援 50 個並行匯入任務，大小總計為 1TB。每個匯入任務在所有區域中最多可以使用 50,000 個 Amazon S3 物件。這些預設配額會套用至每個帳戶。如果您認為需要修改這些配額，請聯絡您的客戶團隊，我們會根據個別情況進行考慮。如需 DynamoDB 限制的詳細資訊，請參閱 [Service Quotas](ServiceQuotas.html)。
## 驗證錯誤
在匯入流程期間，DynamoDB 可能會在剖析資料時遇到錯誤。DynamoDB 會針對每個錯誤發出一份 CloudWatch 日誌，並保留遇到的錯誤總數計數。如果 Amazon S3 物件本身格式錯誤或其內容無法形成 DynamoDB 項目，我們可能會略過處理物件的剩餘部分。
**注意**
如果 Amazon S3 資料來源有多個共用相同索引鍵的項目，這些項目將會覆寫，直到僅留下一個項目為止。這看起來像是匯入了 1 個項目而忽略了其他項目。重複的項目將以隨機順序覆寫，不會計為錯誤，也不會發出到 CloudWatch 日誌中。
匯入完成後，您可以查看匯入的項目總數、錯誤總數，以及處理的項目總數。如需進一步的疑難排解，您也可以檢查所匯入項目的總大小與所處理資料的總大小。
匯入錯誤分為三類：API 驗證錯誤、資料驗證錯誤和組態錯誤。
### API 驗證錯誤
API 驗證錯誤是來自同步 API 的項目層級錯誤。常見原因是許可問題、缺少必要參數以及參數驗證失敗。`ImportTable` 請求所擲回的例外狀況中，包含 API 呼叫失敗原因的詳細資訊。
### 驗證錯誤
資料驗證錯誤可能發生在項目層級或檔案層級。匯入期間，會先根據 DynamoDB 規則驗證項目，然後再匯入目標資料表。當項目驗證失敗且未匯入時，匯入任務會略過該項目，並繼續下一個項目。工作結束時，匯入狀態會設定為「失敗」，伴隨 FailureCode、ItemValidationError 以及 FailureMessage：「部分項目驗證檢查失敗且未匯入，如需詳細資訊，請檢查 CloudWatch 錯誤日誌。」
造成資料驗證錯誤的常見原因包括物件無法剖析、物件格式不正確 (輸入指定 DYNAMODB\$1JSON，但物件不在 DYNAMODB\$1JSON 中)，以及結構描述與指定來源資料表的金鑰不相符。
### 組態錯誤
組態錯誤通常是因為權限驗證而導致的工作流程錯誤。匯入工作流程會在接受請求之後檢查某些權限。如果在呼叫 Amazon S3 或 CloudWatch 等任何必要的相依性時發生問題，則流程會將匯入狀態標示為「失敗」。所以 `failureCode` 和 `failureMessage` 指向失敗原因。在適用的情況下，失敗訊息還包含請求 ID，您可以用來調查 CloudTrail 中失敗的原因。
常見的組態錯誤包括 Amazon S3 儲存貯體的 URL 錯誤，而且沒有存取 Amazon S3 儲存貯體、CloudWatch Logs 和用於解密 Amazon S3 物件的 AWS KMS 金鑰的許可。如需詳細資訊，請參閱[使用與資料金鑰](encryption.usagenotes.html#dynamodb-kms)。
### 驗證 Amazon S3 物件
若要驗證來源 S3 物件，請執行下列步驟。
1. 驗證資料格式與壓縮類型
+ 請確認指定字首下的所有相符 Amazon S3 物件都具有相同的格式 (DYNAMODB\$1JSON、DYNAMODB\$1ION、CSV)
+ 請確認指定字首下的所有相符 Amazon S3 物件都以相同的方式壓縮 (GZIP、ZSTD、無)
**注意**
Amazon S3 物件不需要具有對應的副檔名 (.csv / .json / .ion / .gz / .zstd 等)，因為應以 ImportTable 呼叫中指定的輸入格式優先。
1. 驗證匯入資料是否符合所需的資料表結構描述
+ 請確定來源資料中的每個項目都有主索引鍵。匯入的排序索引鍵為選用。
+ 請確定與主索引鍵和排序索引鍵相關聯的屬性類別符合 Table 和 GSI 結構描述中的屬性類別，如資料表建立參數所指定
### 疑難排解
#### CloudWatch 日誌
對於匯入失敗的工作，詳細錯誤訊息會張貼到 CloudWatch 日誌。若要存取這些日誌，請先從輸出擷取 ImportArn，然後使用此命令進行描述匯入：
```
aws dynamodb describe-import --import-arn arn:aws:dynamodb:us-east-1:ACCOUNT:table/target-table/import/01658528578619-c4d4e311
}
```
輸出範例：
```
aws dynamodb describe-import --import-arn "arn:aws:dynamodb:us-east-1:531234567890:table/target-table/import/01658528578619-c4d4e311"
{
"ImportTableDescription": {
"ImportArn": "arn:aws:dynamodb:us-east-1:ACCOUNT:table/target-table/import/01658528578619-c4d4e311",
"ImportStatus": "FAILED",
"TableArn": "arn:aws:dynamodb:us-east-1:ACCOUNT:table/target-table",
"TableId": "7b7ecc22-302f-4039-8ea9-8e7c3eb2bcb8",
"ClientToken": "30f8891c-e478-47f4-af4a-67a5c3b595e3",
"S3BucketSource": {
"S3BucketOwner": "ACCOUNT",
"S3Bucket": "my-import-source",
"S3KeyPrefix": "import-test"
},
"ErrorCount": 1,
"CloudWatchLogGroupArn": "arn:aws:logs:us-east-1:ACCOUNT:log-group:/aws-dynamodb/imports:*",
"InputFormat": "CSV",
"InputCompressionType": "NONE",
"TableCreationParameters": {
"TableName": "target-table",
"AttributeDefinitions": [
{
"AttributeName": "pk",
"AttributeType": "S"
}
],
"KeySchema": [
{
"AttributeName": "pk",
"KeyType": "HASH"
}
],
"BillingMode": "PAY_PER_REQUEST"
},
"StartTime": 1658528578.619,
"EndTime": 1658528750.628,
"ProcessedSizeBytes": 70,
"ProcessedItemCount": 1,
"ImportedItemCount": 0,
"FailureCode": "ItemValidationError",
"FailureMessage": "Some of the items failed validation checks and were not imported. Please check CloudWatch error logs for more details."
}
}
```
從上述回應擷取日誌群組並匯入 ID，並用其擷取錯誤日誌。匯入 ID 是 `ImportArn` 欄位的最後一個路徑元素。日誌群組的名稱為 `/aws-dynamodb/imports`。錯誤日誌串流的名稱為 `import-id/error`。此例子中，為 `01658528578619-c4d4e311/error`。
#### 缺少項目中的金鑰 pk
如果來源 S3 物件不包含作為參數的主索引鍵，匯入將會失敗。例如，當您將匯入的主索引鍵定義為欄名稱「pk」時。
```
aws dynamodb import-table —s3-bucket-source S3Bucket=my-import-source,S3KeyPrefix=import-test.csv \
—input-format CSV --table-creation-parameters '{"TableName":"target-table","KeySchema": \
[{"AttributeName":"pk","KeyType":"HASH"}],"AttributeDefinitions":[{"AttributeName":"pk","AttributeType":"S"}],"BillingMode":"PAY_PER_REQUEST"}'
```
來源物件 `import-test.csv` 中缺少欄「pk」，其中包含下列內容：
```
title,artist,year_of_release
The Dark Side of the Moon,Pink Floyd,1973
```
由於資料來源中缺少主索引鍵，因此這項匯入會因為項目驗證錯誤而失敗。
CloudWatch 錯誤日誌範例：
```
aws logs get-log-events —log-group-name /aws-dynamodb/imports —log-stream-name 01658528578619-c4d4e311/error
{
"events": [
{
"timestamp": 1658528745319,
"message": "{\"itemS3Pointer\":{\"bucket\":\"my-import-source\",\"key\":\"import-test.csv\",\"itemIndex\":0},\"importArn\":\"arn:aws:dynamodb:us-east-1:531234567890:table/target-table/import/01658528578619-c4d4e311\",\"errorMessages\":[\"One or more parameter values were invalid: Missing the key pk in the item\"]}",
"ingestionTime": 1658528745414
}
],
"nextForwardToken": "f/36986426953797707963335499204463414460239026137054642176/s",
"nextBackwardToken": "b/36986426953797707963335499204463414460239026137054642176/s"
}
```
此錯誤日誌表示「一個或多個參數值無效：缺少項目中的金鑰 pk」。由於此匯入工作失敗，現在存在資料表「target-table」但其為空白，因為沒有匯入任何項目。已處理第一個項目，物件的項目驗證失敗。
若要修正此問題，請先將「target-table」刪除 (若不再需要)。然後使用來源物件中存在的主索引鍵欄名稱，或將來源資料更新為：
```
pk,title,artist,year_of_release
Albums::Rock::Classic::1973::AlbumId::ALB25,The Dark Side of the Moon,Pink Floyd,1973
```
#### 目標資料表存在
當您啟動匯入工作並收到回應時，如下所示：
```
An error occurred (ResourceInUseException) when calling the ImportTable operation: Table already exists: target-table
```
若要修正此錯誤，您必須選擇不存在的資料表名稱，然後再一次匯入。
#### 指定的儲存貯體不存在
如果來源儲存貯體不存在，匯入將失敗，並會在 CloudWatch 中記錄錯誤訊息詳細資料。
描述匯入範例：
```
aws dynamodb —endpoint-url $ENDPOINT describe-import —import-arn "arn:aws:dynamodb:us-east-1:531234567890:table/target-table/import/01658530687105-e6035287"
{
"ImportTableDescription": {
"ImportArn": "arn:aws:dynamodb:us-east-1:ACCOUNT:table/target-table/import/01658530687105-e6035287",
"ImportStatus": "FAILED",
"TableArn": "arn:aws:dynamodb:us-east-1:ACCOUNT:table/target-table",
"TableId": "e1215a82-b8d1-45a8-b2e2-14b9dd8eb99c",
"ClientToken": "3048e16a-069b-47a6-9dfb-9c259fd2fb6f",
"S3BucketSource": {
"S3BucketOwner": "531234567890",
"S3Bucket": "BUCKET_DOES_NOT_EXIST",
"S3KeyPrefix": "import-test"
},
"ErrorCount": 0,
"CloudWatchLogGroupArn": "arn:aws:logs:us-east-1:ACCOUNT:log-group:/aws-dynamodb/imports:*",
"InputFormat": "CSV",
"InputCompressionType": "NONE",
"TableCreationParameters": {
"TableName": "target-table",
"AttributeDefinitions": [
{
"AttributeName": "pk",
"AttributeType": "S"
}
],
"KeySchema": [
{
"AttributeName": "pk",
"KeyType": "HASH"
}
],
"BillingMode": "PAY_PER_REQUEST"
},
"StartTime": 1658530687.105,
"EndTime": 1658530701.873,
"ProcessedSizeBytes": 0,
"ProcessedItemCount": 0,
"ImportedItemCount": 0,
"FailureCode": "S3NoSuchBucket",
"FailureMessage": "The specified bucket does not exist (Service: Amazon S3; Status Code: 404; Error Code: NoSuchBucket; Request ID: Q4W6QYYFDWY6WAKH; S3 Extended Request ID: ObqSlLeIMJpQqHLRX2C5Sy7n+8g6iGPwy7ixg7eEeTuEkg/+chU/JF+RbliWytMlkUlUcuCLTrI=; Proxy: null)"
}
}
```
此 `FailureCode` 為 `S3NoSuchBucket`，其中 `FailureMessage` 包含請求 ID 等詳細資訊以及擲出錯誤服務。由於在將資料匯入資料表之前就已發現錯誤，因此不會建立新的 DynamoDB 資料表。部分情況下，若資料開始匯入後才遇到這些錯誤，就會保留含有部分匯入資料的資料表。
若要修正此錯誤，請確定來源 Amazon S3 儲存貯體存在，然後重新啟動匯入程序。