导入格式配额和验证

导入配额

在 us-east-1、us-west-2 和 eu-west-1 区域中，从 Amazon S3 导入 DynamoDB 可以支持多达 50 个并发导入作业，每次导入源对象的总大小为 15TB。在所有其他区域，最多支持 50 个总大小为 1TB 的并发导入任务。在所有区域中，每个导入任务最多可处理 50000 个 Amazon S3 对象。会对每个账户使用这些默认配额。如果您认为需要修改这些配额，请联系您的账户团队，团队将根据具体情况考虑配额分配情况。有关 DynamoDB 限制的更多信息，请参阅服务限额。

验证错误

在导入过程中，DynamoDB 在解析数据时可能会遇到错误。对于每个错误，DynamoDB 都会发出一个 CloudWatch 日志，并记录遇到的错误总数。如果 Amazon S3 对象本身格式不正确，或者其内容无法构成 DynamoDB 项目，那么我们可以跳过处理对象的剩余部分。

注意

如果 Amazon S3 数据源有多个项目共享同一个键，则这些项目将被覆盖，只留下最后一个。这样看起来就好像是导入了 1 个项目而忽略了其他项目。重复的项目将被随机覆盖，不计为错误，也不会发送到 CloudWatch 日志中。

导入完成后，您可以看到已导入项目总数、错误总数和已处理项目总数。要进一步排除故障，您还可以检查已导入项目的总大小和已处理数据的总大小。

导入错误分为三类：API 验证错误、数据验证错误和配置错误。

API 验证错误

API 验证错误是来自同步 API 的项目级别错误。常见的原因有权限问题、缺少必需的参数和参数验证失败。有关 API 调用失败原因的详细信息包含在由 ImportTable 请求引发的异常中。

数据验证错误

数据验证错误可能发生在项目级别或文件级别。在导入过程中，将根据 DynamoDB 规则对项目进行验证，然后再导入到目标表中。当项目未通过验证且未导入时，导入作业将跳过该项目，继续处理下一个项目。任务结束时，导入状态设置为 FAILED，并包含 FailureCode、ItemValidationError 和 FailureMessage“Some of the items failed validation checks and were not imported. Please check CloudWatch error logs for more details”。

数据验证错误的常见原因包括对象不可解析、对象格式不正确（输入指定 DYNAMODB_JSON，但对象不是 DYNAMODB_JSON 格式）以及架构与指定的源表键不匹配。

配置错误

配置错误通常是由于权限验证导致的工作流错误。导入工作流在接受请求后会检查一些权限。如果调用任何必需依赖项（如 Amazon S3 或 CloudWatch）时出现问题，则该过程会将导入状态标记为 FAILED。failureCode 和 failureMessage 指出失败的原因。如果适用，失败消息还包含请求 ID，您可以使用该 ID 在 CloudTrail 中调查失败原因。

常见配置错误包括 Amazon S3 存储桶的 URL 错误，以及无权访问 Amazon S3 存储桶、CloudWatch Logs 和用于解密 Amazon S3 对象的 Amazon 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 Logs

对于失败的导入任务，详细的错误消息会发布到 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 中。

示例 describe import：


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 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

导入格式

最佳实践