本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用清单传输特定的文件或对象
*清单*是您要传输的文件或对象 Amazon DataSync 的列表。例如，不必传输可能包含数百万个对象的 S3 存储桶中的所有内容，而是只 DataSync 传输您在清单中列出的对象。
清单与[筛选条件](filtering.md)类似，但清单可让您准确确定要传输的文件或对象，而不是符合筛选模式的数据。
**注意**
增强模式任务清单文件允许的最大大小为 20 GB。
## 创建清单
清单是逗号分隔值 (CSV) 格式的文件，它列出了源位置中要 DataSync 传输的文件或对象。如果源位置是 S3 存储桶，您还可以包含要传输的对象版本。
**Topics**
+ [指南要求](#transferring-with-manifest-guidelines)
+ [示例清单](#manifest-examples)
### 指南要求
使用这些指南来帮助您创建适用于的清单 DataSync。
------
#### [ Do ]
+ 指定要传输的每个文件或对象的完整路径。
您不能只指定一个目录或文件夹，然后希望传输其中的所有内容。对于这种情况，请考虑使用[包含筛选条件](filtering.md)，而不是清单。
+ 确保每个文件或对象路径都与您在配置 DataSync 源位置时指定的挂载路径、文件夹、目录或前缀相关。
例如，假设您[配置了一个 S3 位置](create-s3-location.md#create-s3-location-how-to)，其前缀名为 `photos`。该前缀包括一个要传输的对象 `my-picture.png`。然后，在清单中，您只需要指定对象（`my-picture.png`），而不是前缀和对象（`photos/my-picture.png`）。
+ 要指定 Amazon S3 对象版本 IDs，请使用逗号分隔对象的路径和版本 ID。
下面的示例展示了包含两个字段的清单条目。第一个字段包含一个名为 `picture1.png` 的对象。第二个字段用逗号分隔，包含版本 ID `111111`：
```
picture1.png,111111
```
+ 在以下情况下使用引号：
+ 当路径包含特殊字符（逗号、引号和行尾）时：
`"filename,with,commas.txt"`
+ 当路径跨越多行时：
```
"this
is
a
filename.txt"
```
+ 当路径包含引号时：
`filename""with""quotes.txt`
这表示名为 `filename"with"quotes.txt` 的路径。
这些引号规则也适用于版本 ID 字段。通常，如果清单字段有引号，必须使用另一个引号将其转义。
+ 用新行分隔每个文件或对象条目。
您可以使用 Linux 风格的换行（换行符或回车符）或 Windows 风格的换行（回车符后跟换行符）来分隔行。
+ 保存您的清单（例如，`my-manifest.csv` 或 `my-manifest.txt`）。
+ 将清单上传到[DataSync 可以访问](#transferring-with-manifest-access)的 S3 存储桶。
此存储桶不必位于您正在使用的同一个 Amazon Web Services 区域 或账户中 DataSync。
------
#### [ Don't ]
+ 只指定一个目录或文件夹，然后希望传输其中的所有内容。
清单只能包含要传输的文件或对象的完整路径。如果您将源位置配置为使用特定的挂载路径、文件夹、目录或前缀，您不必在清单中包含这些内容。
+ 指定超过 4096 个字符的文件或对象路径。
+ 指定超过 1024 字节的文件路径、对象路径或 Amazon S3 对象版本 ID。
+ 指定重复的文件或对象路径。
+ 包含对象版本 ID（如果您的源位置不是 S3 存储桶）。
+ 在一个清单条目中包含两个以上的字段。
一个条目只能包含一个文件或对象路径，以及一个 Amazon S3 对象版本 ID（如适用）。
+ 包含不符合 UTF-8 编码的字符。
+ 在条目字段中，在引号外包含非预期的空格。
------
### 示例清单
使用这些示例来帮助您创建适用于的清单 DataSync。
**包含完整文件或对象路径的清单**
下面的示例展示了带有完整文件或对象传输路径的清单。
```
photos/picture1.png
photos/picture2.png
photos/picture3.png
```
**仅包含对象键的清单**
下面的示例展示了一份清单，其中列出了要从 Amazon S3 源位置传输的对象。由于[位置已配置](create-s3-location.md#create-s3-location-how-to)了前缀 `photos`，因此仅指定了对象键。
```
picture1.png
picture2.png
picture3.png
```
**包含对象路径和版本的清单 IDs**
以下清单示例中的前两个条目包括要传输的特定 Amazon S3 对象版本。
```
photos/picture1.png,111111
photos/picture2.png,121212
photos/picture3.png
```
**包含 UTF-8 字符的清单**
以下示例展示了包含 UTF-8 字符的文件清单。
```
documents/résumé1.pdf
documents/résumé2.pdf
documents/résumé3.pdf
```
## 提供对清单的 DataSync 访问权限
您需要一个 Amazon Identity and Access Management (IAM) 角色来授予对其 S3 存储桶中清单的 DataSync 访问权限。此角色必须包括以下权限：
+ `s3:GetObject`
+ `s3:GetObjectVersion`
您可以在 DataSync 控制台中自动生成此角色，也可以自己创建该角色。
**注意**
如果您的清单位于不同的清单中 Amazon Web Services 账户，则必须手动创建此角色。
### 自动创建 IAM 角色
在控制台中创建或启动转移任务时， DataSync 可以为您创建一个 IAM 角色，该角色具有访问清单所需的`s3:GetObject`和`s3:GetObjectVersion`权限。
**自动创建角色所需的权限**
要自动创建角色，请确保您用于访问 DataSync 控制台的角色具有以下权限：
+ `iam:CreateRole`
+ `iam:CreatePolicy`
+ `iam:AttachRolePolicy`
### 创建 IAM 角色（同一账户）
您可以手动创建访问清单 DataSync 所需的 IAM 角色。以下说明假设您 Amazon Web Services 账户 所在的使用位置相同， DataSync 并且清单的 S3 存储桶位于同一位置。
1. 使用 [https://console.aws.amazon.com/iam/](https://console.amazonaws.cn/iam/) 打开 IAM 控制台。
1. 在左侧导航窗格的**访问管理**下，选择**角色**，然后选择**创建角色**。
1. 在**选择可信实体**页面中，为**可信实体类型**选择 **Amazon Web Services 服务**。
1. 对于 “**用例**”，**DataSync**在下拉列表中进行选择，然后选择**DataSync**。选择**下一步**。
1. 在**添加权限**页面上，选择**下一步**。输入角色名称，然后选择**创建角色**。
1. 在**角色**页面上，搜索您刚刚创建的角色并选择其名称。
1. 在角色的详情页面上，选择**权限**选项卡。选择**添加权限**，然后选择**创建内联策略**。
1. 选择 **JSON** 选项卡，然后将以下示例策略粘贴到策略编辑器中：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Sid": "DataSyncAccessManifest",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:GetObjectVersion"
],
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/my-manifest.csv"
}]
}
```
------
1. 在刚才粘贴的示例策略中，将以下值替换为您自己的值：
1. 将 `amzn-s3-demo-bucket` 替换为托管清单的 S3 存储桶名称。
1. 将 `my-manifest.csv` 替换为清单的文件名称。
1. 选择**下一步**。为您的策略输入名称，然后选择**创建策略**。
1. （推荐）为防止出现[跨服务混淆代理问题](cross-service-confused-deputy-prevention.md)，请执行以下操作：
1. 在角色的详情页面上，选择**信任关系**选项卡。选择**编辑信任策略**。
1. 使用以下示例更新信任策略，其中包括 `aws:SourceArn` 和 `aws:SourceAccount` 全局条件上下文键：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "datasync.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "555555555555"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:datasync:us-east-1:555555555555:*"
}
}
}
]
}
```
------
+ 将每个实例`account-id`替换为您正在使用的 Amazon Web Services 账户 ID DataSync。
+ `region`替换为你正在使用 Amazon Web Services 区域 的地方 DataSync。
1. 选择**更新策略**。
您已经创建了一个允许 DataSync 访问清单的 IAM 角色。在[创建](#manifest-creating-task)或[启动](#manifest-starting-task)任务时指定此角色。
### 创建 IAM 角色（不同账户）
如果您的清单位于属于不同的 S3 存储桶中 Amazon Web Services 账户，则必须手动创建 DataSync 用于访问清单的 IAM 角色。然后，在清单 Amazon Web Services 账户 所在的位置中，您需要在 S3 存储桶策略中包含该角色。
#### 创建角色
1. 使用 [https://console.aws.amazon.com/iam/](https://console.amazonaws.cn/iam/) 打开 IAM 控制台。
1. 在左侧导航窗格的**访问管理**下，选择**角色**，然后选择**创建角色**。
1. 在**选择可信实体**页面中，为**可信实体类型**选择 **Amazon Web Services 服务**。
1. 对于 “**用例**”，**DataSync**在下拉列表中进行选择，然后选择**DataSync**。选择**下一步**。
1. 在**添加权限**页面上，选择**下一步**。输入角色名称，然后选择**创建角色**。
1. 在**角色**页面上，搜索您刚刚创建的角色并选择其名称。
1. 在角色的详情页面上，选择**权限**选项卡。选择**添加权限**，然后选择**创建内联策略**。
1. 选择 **JSON** 选项卡，然后将以下示例策略粘贴到策略编辑器中：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Sid": "DataSyncAccessManifest",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:GetObjectVersion"
],
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/my-manifest.csv"
}]
}
```
------
1. 在刚才粘贴的示例策略中，将以下值替换为您自己的值：
1. 将 `amzn-s3-demo-bucket` 替换为托管清单的 S3 存储桶名称。
1. 将 `my-manifest.csv` 替换为清单的文件名称。
1. 选择**下一步**。为您的策略输入名称，然后选择**创建策略**。
1. （推荐）为防止出现[跨服务混淆代理问题](cross-service-confused-deputy-prevention.md)，请执行以下操作：
1. 在角色的详情页面上，选择**信任关系**选项卡。选择**编辑信任策略**。
1. 使用以下示例更新信任策略，其中包括 `aws:SourceArn` 和 `aws:SourceAccount` 全局条件上下文键：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "datasync.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "000000000000"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:datasync:us-east-1:000000000000:*"
}
}
}
]
}
```
------
+ 将的`account-id`每个实例替换为您正在使用的 Amazon Web Services 账户 ID DataSync。
+ `region`替换为你正在使用 Amazon Web Services 区域 的地方 DataSync。
1. 选择**更新策略**。
您创建了可以包含在 S3 存储桶策略中的 IAM 角色。
#### 更新 S3 存储桶策略以包含角色
创建 IAM 角色后，必须将其添加到清单 Amazon Web Services 账户 所在的另一个存储桶策略中的 S3 存储桶策略中。
1. 在中 Amazon Web Services 管理控制台，切换到包含你的 manfiest 的 S3 存储桶的账户。
1. 打开 Amazon S3 控制台，网址为 [https://console.aws.amazon.com/s3/](https://console.amazonaws.cn/s3/)。
1. 在存储桶的详情页面上，选择**权限**选项卡。
1. 在 **存储桶策略**下，选择 **编辑**并执行以下操作来修改您的 S3 存储桶策略：
1. 更新编辑器中的内容，以包含以下策略声明：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "DataSyncAccessManifestBucket",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:GetObjectVersion"
],
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket"
}
]
}
```
------
1. `account-id`替换为您正在使用的账户 DataSync 的 Amazon Web Services 账户 ID。
1. `datasync-role`替换为您刚刚创建的 DataSync 允许访问清单的 IAM 角色。
1. 将 `amzn-s3-demo-bucket` 替换为在其他 Amazon Web Services 账户中托管清单的 S3 存储桶名称。
1. 选择**保存更改**。
您已经创建了一个 IAM 角色， DataSync 允许您在其他账户中访问您的清单。在[创建](#manifest-creating-task)或[启动](#manifest-starting-task)任务时指定此角色。
## 在创建任务时指定清单
您可以指定 DataSync 要在创建任务时使用的清单。
### 使用控制 DataSync 台
1. 打开 Amazon DataSync 控制台，网址为[https://console.aws.amazon.com/datasync/](https://console.amazonaws.cn/datasync/)。
1. 在左侧导航窗格中，选择**任务**，然后选择**创建任务**。
1. 配置您任务的源位置和目标位置。
有关更多信息，请参阅 [我可以在哪里传输我的数据 Amazon DataSync？](working-with-locations.md)。
1. 对于**要扫描的内容**，请选择**特定文件、对象和文件夹**，然后选择**使用清单**。
1. 对于 **S3 URI**，请选择托管在 S3 存储桶上的清单。
或者，您也可以输入 URI（例如，`s3://bucket/prefix/my-manifest.csv`）。
1. 对于**对象版本**，请选择 DataSync 要使用的清单版本。
默认情况下， DataSync 使用对象的最新版本。
1. 对于**清单访问角色**，执行下列操作之一：
+ 选择 “**自动生成**” DataSync 以自动创建一个 IAM 角色，该角色具有访问其 S3 存储桶中的清单所需的权限。
+ 选择可以访问清单的现有 IAM 角色。
有关更多信息，请参阅 [提供对清单的 DataSync 访问权限](#transferring-with-manifest-access)。
1. 配置所需的任何其他任务设置，然后选择**下一步**。
1. 选择**创建任务**。
### 使用 Amazon CLI
1. 复制以下 `create-task` 命令：
```
aws datasync create-task \
--source-location-arn arn:aws:datasync:us-east-1:123456789012:location/loc-12345678abcdefgh \
--destination-location-arn arn:aws:datasync:us-east-1:123456789012:location/loc-abcdefgh12345678 \
--manifest-config {
"Source": {
"S3": {
"ManifestObjectPath": "s3-object-key-of-manifest",
"BucketAccessRoleArn": "bucket-iam-role",
"S3BucketArn": "amzn-s3-demo-bucket-arn",
"ManifestObjectVersionId": "manifest-version-to-use"
}
}
}
```
1. 对于 `--source-location-arn` 参数，指定数据传输源位置的 Amazon 资源名称（ARN）。
1. 对于 `--destination-location-arn` 参数，指定数据传输目标位置的 ARN。
1. 对于 `--manifest-config` 参数，请执行以下操作：
+ `ManifestObjectPath`：指定清单的 S3 对象键。
+ `BucketAccessRoleArn`— 指定允许 DataSync 访问其 S3 存储桶中的清单的 IAM 角色。
有关更多信息，请参阅 [提供对清单的 DataSync 访问权限](#transferring-with-manifest-access)。
+ `S3BucketArn`：指定托管清单的 S3 存储桶的 ARN。
+ `ManifestObjectVersionId`— 指定 DataSync 要使用的清单版本。
默认情况下， DataSync 使用对象的最新版本。
1. 运行 `create-task` 命令来创建您的任务。
准备就绪后，您可以[启动传输任务](run-task.md)。
## 在启动任务时指定清单
您可以指定 DataSync 要在执行任务时使用的清单。
### 使用控制 DataSync 台
1. 打开 Amazon DataSync 控制台，网址为[https://console.aws.amazon.com/datasync/](https://console.amazonaws.cn/datasync/)。
1. 在左侧导航窗格中，选择**任务**，然后选择要启动的任务。
1. 在任务概览页面，选择**开始**，然后选择**使用覆盖选项开始**。
1. 对于**要扫描的内容**，请选择**特定文件、对象和文件夹**，然后选择**使用清单**。
1. 对于 **S3 URI**，请选择托管在 S3 存储桶上的清单。
或者，您也可以输入 URI（例如，`s3://bucket/prefix/my-manifest.csv`）。
1. 对于**对象版本**，请选择 DataSync 要使用的清单版本。
默认情况下， DataSync 使用对象的最新版本。
1. 对于**清单访问角色**，执行下列操作之一：
+ 选择 “**自动生成**” DataSync 以自动创建 IAM 角色来访问其 S3 存储桶中的清单。
+ 选择可以访问清单的现有 IAM 角色。
有关更多信息，请参阅 [提供对清单的 DataSync 访问权限](#transferring-with-manifest-access)。
1. 选择**开始**，以开始传输。
### 使用 Amazon CLI
1. 复制以下 `start-task-execution` 命令：
```
aws datasync start-task-execution \
--task-arn arn:aws:datasync:us-east-1:123456789012:task/task-12345678abcdefgh \
--manifest-config {
"Source": {
"S3": {
"ManifestObjectPath": "s3-object-key-of-manifest",
"BucketAccessRoleArn": "bucket-iam-role",
"S3BucketArn": "amzn-s3-demo-bucket-arn",
"ManifestObjectVersionId": "manifest-version-to-use"
}
}
}
```
1. 对于 `--task-arn` 参数，请指定要启动的任务的 Amazon 资源名称（ARN）。
1. 对于 `--manifest-config` 参数，请执行以下操作：
+ `ManifestObjectPath`：指定清单的 S3 对象键。
+ `BucketAccessRoleArn`— 指定允许 DataSync 访问其 S3 存储桶中的清单的 IAM 角色。
有关更多信息，请参阅 [提供对清单的 DataSync 访问权限](#transferring-with-manifest-access)。
+ `S3BucketArn`：指定托管清单的 S3 存储桶的 ARN。
+ `ManifestObjectVersionId`— 指定 DataSync 要使用的清单版本。
默认情况下， DataSync 使用对象的最新版本。
1. 运行 `start-task-execution` 命令开始传输。
## 限制
+ 您不能将清单与[筛选条件](filtering.md)一起使用。
+ 您不能只指定一个目录或文件夹，然后希望传输其中的所有内容。对于这种情况，请考虑使用[包含筛选条件](filtering.md)，而不是清单。
+ 您不能使用 “**保留已删除文件**” 任务选项（`PreserveDeletedFiles`在 [API](https://docs.amazonaws.cn/datasync/latest/userguide/API_Options.html#DataSync-Type-Options-PreserveDeletedFiles) 中）来[维护目标中不在源中的文件或对象](configure-metadata.md)。 DataSync 仅传输清单中列出的内容，不会删除目的地中的任何内容。
## 问题排查
**与 `HeadObject` 或 `GetObjectTagging` 相关的错误**
如果您要 IDs 从 S3 存储桶传输具有特定版本的对象，则可能会看到与`HeadObject`或相关的错误`GetObjectTagging`。例如，以下是与 `GetObjectTagging` 相关的错误：
```
[WARN] Failed to read metadata for file /picture1.png (versionId: 111111): S3 Get Object Tagging Failed
[ERROR] S3 Exception: op=GetObjectTagging photos/picture1.png, code=403, type=15, exception=AccessDenied,
msg=Access Denied req-hdrs: content-type=application/xml, x-amz-api-version=2006-03-01 rsp-hdrs: content-type=application/xml,
date=Wed, 07 Feb 2024 20:16:14 GMT, server=AmazonS3, transfer-encoding=chunked,
x-amz-id-2=IOWQ4fDEXAMPLEQM+ey7N9WgVhSnQ6JEXAMPLEZb7hSQDASK+Jd1vEXAMPLEa3Km, x-amz-request-id=79104EXAMPLEB723
```
如果您看到其中任何一个错误，请验证用于访问您的 DataSync S3 源位置的 IAM 角色是否具有以下权限：
+ `s3:GetObjectVersion`
+ `s3:GetObjectVersionTagging`
如果您需要更新角色，使其具有这些权限，请参阅 [为创建 IAM 角色 DataSync 以访问您的 Amazon S3 位置](create-s3-location.md#create-role-manually)。
**错误：`ManifestFileDoesNotExist`**
此错误表示在源中找不到清单中的文件。查看创建清单的[指南](#transferring-with-manifest-guidelines)。
## 后续步骤
如果尚未开始，请[启动任务](run-task.md)。否则，[请监视任务的活动](monitoring-overview.md)。