导入格式配额和验证 - Amazon DynamoDB
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

导入格式配额和验证

导入配额

在 us-east-1、us-west-2 和 eu-west-1 区域中,从 Amazon S3 导入 DynamoDB 可以支持多达 50 个并发导入作业,每次导入源对象的总大小为 15TB。在所有其他区域,最多支持 50 个总大小为 1TB 的并发导入任务。在所有区域中,每个导入任务最多可处理 5000 个 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.”(有些项目未通过验证检查且未导入。请检查 CloudWatch 错误日志以了解更多详细信息。)

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

配置错误

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

常见配置错误包括 Amazon S3 存储桶的 URL 错误,以及无权访问 Amazon S3 存储桶、CloudWatch Logs 和用于解密 Amazon S3 对象的 Amazon KMS 密钥。有关更多信息,请参阅使用数据密钥

验证源 Amazon S3 对象

要验证源 S3 对象,请执行以下步骤。

  1. 验证数据格式和压缩类型

    • 确保指定前缀下所有匹配的 Amazon S3 对象具有相同格式(DYNAMODB_JSON、DYNAMODB_ION、CSV)

    • 确保指定前缀下所有匹配的 Amazon S3 对象都以相同的方式进行压缩(GZIP、ZSTD、NONE)

      注意

      Amazon S3 对象不需要具有相应的扩展名(.csv/.json/.ion/.gz/.zstd 等),因为 ImportTable 调用中指定的输入格式优先。

  2. 验证导入数据是否符合所需的表架构

    • 确保源数据中的每个项目都有主键。对于导入,排序键是可选的。

    • 确保与主键和任何排序键关联的属性类型与表和 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 中。

示例 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)" } }

FailureCodeS3NoSuchBucket,且 FailureMessag 包含诸如请求 ID 和引发错误的服务等详细信息。由于错误是在数据导入表之前捕获的,因此不会创建新的 DynamoDB 表。在某些情况下,如果在数据导入开始后遇到这些错误,则会保留包含部分已导入数据的表。

要修复此错误,请确保源 Amazon S3 存储桶存在,然后重新启动导入过程。