匯入格式配額與驗證

匯入配額

Amazon S3 的 DynamoDB 匯入可支援多達 50 個並行匯入任務，在 us-east-1、us-west-2 和 eu-west-1 區域的匯入來源物件大小總計達 15TB。在所有其他區域中，最多支援 50 個並行匯入任務，大小總計為 1TB。每個匯入任務在所有區域中最多可以佔用 50，000 個 Amazon S3 物件。這些預設配額會套用至每個帳戶。如果您覺得需要修改這些配額，請聯絡您的客戶團隊，我們會根據此原則進行考量 case-by-case。如需 DynamoDB 限制的詳細資訊，請參閱 Service Quotas。

驗證錯誤

在匯入流程期間，DynamoDB 可能會在剖析資料時遇到錯誤。對於每個錯誤，DynamoDB 會發出 CloudWatch 日誌，並保留所遇到錯誤總數的計數。如果 Amazon S3 物件本身格式錯誤或其內容無法形成 DynamoDB 項目，我們可能會略過處理物件的剩餘部分。

注意

如果 Amazon S3 資料來源有多個共用相同索引鍵的項目，這些項目將會覆寫，直到僅留下一個項目為止。這看起來像是匯入了 1 個項目而忽略了其他項目。重複的項目將以隨機順序覆寫，不會計入錯誤，也不會傳送到 CloudWatch 日誌。

匯入完成後，您可以查看匯入的項目總數、錯誤總數，以及處理的項目總數。如需進一步的疑難排解，您也可以檢查所匯入項目的總大小與所處理資料的總大小。

匯入錯誤有三種類別：API驗證錯誤、資料驗證錯誤和組態錯誤。

API 驗證錯誤

API 驗證錯誤是來自同步的項目層級錯誤API。常見原因是許可問題、缺少必要參數以及參數驗證失敗。API 有關呼叫失敗原因的詳細資訊，包含在ImportTable請求所擲出的例外狀況中。

驗證錯誤

資料驗證錯誤可能發生在項目層級或檔案層級。匯入期間，會先根據 DynamoDB 規則驗證項目，然後再匯入目標資料表。當項目驗證失敗且未匯入時，匯入任務會略過該項目，並繼續下一個項目。在任務結束時，匯入狀態會使用 FAILED 設定為 FailureCode， ItemValidationError 而 FailureMessage 「部分項目未通過驗證檢查且未匯入。請檢查 CloudWatch 錯誤日誌以取得更多詳細資訊。」

資料驗證錯誤的常見原因包括物件無法剖析、物件格式不正確（輸入指定 DYNAMODB_JSON，但物件不在 DYNAMODB_JSON)，以及結構描述與指定的來源資料表索引鍵不相符。

組態錯誤

組態錯誤通常是因為權限驗證而導致的工作流程錯誤。匯入工作流程會在接受請求之後檢查某些權限。如果呼叫 Amazon S3 或 CloudWatch 程序等任何必要相依性時發生問題，會將匯入狀態標記為 FAILED。所以 failureCode 和 failureMessage 指向失敗原因。在適用的情況下，失敗訊息也會包含請求 ID，您可以用來調查失敗的原因 CloudTrail。

常見的組態錯誤包括 Amazon S3 儲存貯URL體發生錯誤，而且沒有存取 Amazon S3 儲存貯體、 CloudWatch 日誌和用於解密 Amazon S3 物件之 AWS KMS 金鑰的許可。如需詳細資訊，請參閱使用與資料金鑰。

驗證 Amazon S3 物件

若要驗證來源 S3 物件，請執行下列步驟。

驗證資料格式與壓縮類型
- 確定指定字首下所有相符的 Amazon S3 物件具有相同的格式 (DYNAMODB_JSON、DYNAMODB_ION、CSV)
- 確定指定字首下所有相符的 Amazon S3 物件都以相同的方式壓縮 (GZIP、ZSTD、NONE)
  
  注意
  Amazon S3 物件不需要具有對應的副檔名 (.csv / .json / .ion / .gz / .zstd 等），因為 ImportTable 呼叫中指定的輸入格式為優先。
驗證匯入資料是否符合所需的資料表結構描述
- 請確定來源資料中的每個項目都有主索引鍵。匯入的排序索引鍵為選用。
- 請確定與主索引鍵和任何排序索引鍵相關聯的屬性類型符合資料表和GSI結構描述中的屬性類型，如資料表建立參數中所述

故障診斷

CloudWatch 日誌

對於失敗的匯入任務，詳細的錯誤訊息會發佈到 CloudWatch 日誌。若要存取這些日誌，請先 ImportArn 從輸出擷取，並使用此命令 describe-import：


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，其中 FailureMessag 包含請求 ID 等詳細資訊以及擲出錯誤服務。由於在將資料匯入資料表之前就已發現錯誤，因此不會建立新的 DynamoDB 資料表。部分情況下，若資料開始匯入後才遇到這些錯誤，就會保留含有部分匯入資料的資料表。

若要修正此錯誤，請確定來源 Amazon S3 儲存貯體存在，然後重新啟動匯入程序。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

匯入格式

最佳實務