# 导入格式配额和验证
## 导入配额
在 us-east-1、us-west-2 和 eu-west-1 区域中，从 Amazon S3 导入 DynamoDB 可以支持多达 50 个并发导入作业，每次导入源对象的总大小为 15TB。在所有其他区域，最多支持 50 个总大小为 1TB 的并发导入任务。在所有区域中，每个导入任务最多可处理 50000 个 Amazon S3 对象。会对每个账户使用这些默认配额。如果您认为需要修改这些配额，请联系您的账户团队，团队将根据具体情况考虑配额分配情况。有关 DynamoDB 限制的更多信息，请参阅[服务限额](ServiceQuotas.html)。
## 验证错误
在导入过程中，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\$1JSON，但对象不是 DYNAMODB\$1JSON 格式）以及架构与指定的源表键不匹配。
### 配置错误
配置错误通常是由于权限验证导致的工作流错误。导入工作流在接受请求后会检查一些权限。如果调用任何必需依赖项（如 Amazon S3 或 CloudWatch）时出现问题，则该过程会将导入状态标记为 FAILED。`failureCode` 和 `failureMessage` 指出失败的原因。如果适用，失败消息还包含请求 ID，您可以使用该 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、NONE）
**注意**
Amazon S3 对象不需要具有相应的扩展名（.csv/.json/.ion/.gz/.zstd 等），因为 ImportTable 调用中指定的输入格式优先。
1. 验证导入数据是否符合所需的表架构
+ 确保源数据中的每个项目都有主键。对于导入，排序键是可选的。
+ 确保与主键和任何排序键关联的属性类型与表和 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)"
}
}
```
`FailureCode` 为 `S3NoSuchBucket`，且 `FailureMessage` 包含诸如请求 ID 和引发错误的服务等详细信息。由于错误是在数据导入表之前捕获的，因此不会创建新的 DynamoDB 表。在某些情况下，如果在数据导入开始后遇到这些错误，则会保留包含部分已导入数据的表。
要修复此错误，请确保源 Amazon S3 存储桶存在，然后重新启动导入过程。