使用清单传输特定的文件或对象 - AWS DataSync
创建清单提供对清单的 DataSync 访问权限在创建任务时指定清单在启动任务时指定清单限制故障排查后续步骤

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

使用清单传输特定的文件或对象

清单是您要传输的文件或对象 AWS DataSync 的列表。例如，不必传输可能包含数百万个对象的 S3 存储桶中的所有内容，而是只 DataSync 传输您在清单中列出的对象。

清单与筛选条件类似，但清单可让您准确确定要传输的文件或对象，而不是符合筛选模式的数据。

注意

包含增强模式任务的清单文件的最大允许大小为 20 GB。

创建清单

清单是逗号分隔值 (CSV) 格式的文件，它列出了源位置中要 DataSync 传输的文件或对象。如果源位置是 S3 存储桶，您还可以包含要传输的对象版本。

指南

使用这些指南来帮助您创建适用于的清单 DataSync。

Do

  • 指定要传输的每个文件或对象的完整路径。

    您不能只指定一个目录或文件夹，然后希望传输其中的所有内容。对于这种情况，请考虑使用包含筛选条件，而不是清单。

  • 确保每个文件或对象路径都与您在配置 DataSync 源位置时指定的挂载路径、文件夹、目录或前缀相关。

    例如，假设您配置了一个 S3 位置，其前缀名为 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 可以访问的 S3 存储桶。

    此存储桶不必位于您使用的同一个 AWS 区域 或账户中 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 源位置传输的对象。由于位置已配置了前缀 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 访问权限

您需要一个 AWS Identity and Access Management (IAM) 角色来授予对其 S3 存储桶中清单的 DataSync 访问权限。此角色必须包括以下权限：

  • s3:GetObject

  • s3:GetObjectVersion

您可以在 DataSync 控制台中自动生成此角色，也可以自己创建该角色。

注意

如果您的清单位于不同的清单中 AWS 账户，则必须手动创建此角色。

在控制台中创建或启动转移任务时， DataSync 可以为您创建一个 IAM 角色，该角色具有访问清单所需的s3:GetObject和s3:GetObjectVersion权限。

自动创建角色所需的权限

要自动创建角色，请确保您用于访问 DataSync 控制台的角色具有以下权限：

  • iam:CreateRole

  • iam:CreatePolicy

  • iam:AttachRolePolicy

您可以手动创建访问清单 DataSync 所需的 IAM 角色。以下说明假设您 AWS 账户 所在的使用位置相同， DataSync 并且清单的 S3 存储桶位于同一位置。

  1. 使用 https://console.aws.amazon.com/iam/ 打开 IAM 控制台。

  2. 在左侧导航窗格的访问管理下，选择角色，然后选择创建角色。

  3. 在选择可信实体页面中，为可信实体类型选择 AWS 服务。

  4. 对于 “用例”，DataSync在下拉列表中进行选择，然后选择DataSync。选择下一步。

  5. 在添加权限页面上，选择下一步。输入角色名称，然后选择创建角色。

  6. 在角色页面上，搜索您刚刚创建的角色并选择其名称。

  7. 在角色的详情页面上，选择权限选项卡。选择添加权限，然后选择创建内联策略。

  8. 选择 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"
    }]
}

  9. 在刚才粘贴的示例策略中，将以下值替换为您自己的值：

    1. 将 amzn-s3-demo-bucket 替换为托管清单的 S3 存储桶名称。

    2. 将 my-manifest.csv 替换为清单的文件名称。

  10. 选择下一步。为您的策略输入名称，然后选择创建策略。

  11. （推荐）为防止出现跨服务混淆代理问题，请执行以下操作：

    1. 在角色的详情页面上，选择信任关系选项卡。选择编辑信任策略。

    2. 使用以下示例更新信任策略，其中包括 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替换为您正在使用的 AWS 账户 ID DataSync。

      • region替换为你正在使用 AWS 区域 的地方 DataSync。

    3. 选择更新策略。

您已经创建了一个允许 DataSync 访问清单的 IAM 角色。在创建或启动任务时指定此角色。

如果您的清单位于属于不同的 S3 存储桶中 AWS 账户，则必须手动创建 DataSync 用于访问清单的 IAM 角色。然后，在清单 AWS 账户 所在的位置中，您需要在 S3 存储桶策略中包含该角色。

创建角色

  1. 使用 https://console.aws.amazon.com/iam/ 打开 IAM 控制台。

  2. 在左侧导航窗格的访问管理下，选择角色，然后选择创建角色。

  3. 在选择可信实体页面中，为可信实体类型选择 AWS 服务。

  4. 对于 “用例”，DataSync在下拉列表中进行选择，然后选择DataSync。选择下一步。

  5. 在添加权限页面上，选择下一步。输入角色名称，然后选择创建角色。

  6. 在角色页面上，搜索您刚刚创建的角色并选择其名称。

  7. 在角色的详情页面上，选择权限选项卡。选择添加权限，然后选择创建内联策略。

  8. 选择 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"
    }]
}

  9. 在刚才粘贴的示例策略中，将以下值替换为您自己的值：

    1. 将 amzn-s3-demo-bucket 替换为托管清单的 S3 存储桶名称。

    2. 将 my-manifest.csv 替换为清单的文件名称。

  10. 选择下一步。为您的策略输入名称，然后选择创建策略。

  11. （推荐）为防止出现跨服务混淆代理问题，请执行以下操作：

    1. 在角色的详情页面上，选择信任关系选项卡。选择编辑信任策略。

    2. 使用以下示例更新信任策略，其中包括 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每个实例替换为您正在使用的 AWS 账户 ID DataSync。

      • region替换为你正在使用 AWS 区域 的地方 DataSync。

    3. 选择更新策略。

您创建了可以包含在 S3 存储桶策略中的 IAM 角色。

更新 S3 存储桶策略以包含角色

创建 IAM 角色后，必须将其添加到清单 AWS 账户 所在的另一个存储桶策略中的 S3 存储桶策略中。

  1. 在中 AWS 管理控制台，切换到包含你的 manfiest 的 S3 存储桶的账户。

  2. 打开 Amazon S3 控制台，网址为 https://console.aws.amazon.com/s3/。

  3. 在存储桶的详情页面上，选择权限选项卡。

  4. 在 存储桶策略下，选择 编辑并执行以下操作来修改您的 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"
    }
  ]
}

    2. account-id替换为您正在使用的账户 DataSync 的 AWS 账户 ID。

    3. datasync-role替换为您刚刚创建的 DataSync 允许访问清单的 IAM 角色。

    4. 将 amzn-s3-demo-bucket 替换为在其他 AWS 账户中托管清单的 S3 存储桶名称。

  5. 选择保存更改。

您已经创建了一个 IAM 角色， DataSync 允许您在其他账户中访问您的清单。在创建或启动任务时指定此角色。

在创建任务时指定清单

您可以指定 DataSync 要在创建任务时使用的清单。

  1. 打开 AWS DataSync 控制台，网址为https://console.aws.amazon.com/datasync/。

  2. 在左侧导航窗格中，选择任务，然后选择创建任务。

  3. 配置您任务的源位置和目标位置。

    有关更多信息，请参阅 我可以在哪里通过 AWS DataSync传输数据？。

  4. 对于要扫描的内容，请选择特定文件、对象和文件夹，然后选择使用清单。

  5. 对于 S3 URI，请选择托管在 S3 存储桶上的清单。

    或者，您也可以输入 URI（例如，s3://bucket/prefix/my-manifest.csv）。

  6. 对于对象版本，请选择 DataSync 要使用的清单版本。

    默认情况下， DataSync 使用对象的最新版本。

  7. 对于清单访问角色，执行下列操作之一：

    • 选择 “自动生成” DataSync 以自动创建一个 IAM 角色，该角色具有访问其 S3 存储桶中的清单所需的权限。

    • 选择可以访问清单的现有 IAM 角色。

    有关更多信息，请参阅 提供对清单的 DataSync 访问权限。

  8. 配置所需的任何其他任务设置，然后选择下一步。

  9. 选择创建任务。

  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" 
        }
      }
  }

  2. 对于 --source-location-arn 参数，指定数据传输源位置的 Amazon 资源名称（ARN）。

  3. 对于 --destination-location-arn 参数，指定数据传输目标位置的 ARN。

  4. 对于 --manifest-config 参数，请执行以下操作：

    • ManifestObjectPath：指定清单的 S3 对象键。

    • BucketAccessRoleArn— 指定允许 DataSync 访问其 S3 存储桶中的清单的 IAM 角色。

      有关更多信息，请参阅 提供对清单的 DataSync 访问权限。

    • S3BucketArn：指定托管清单的 S3 存储桶的 ARN。

    • ManifestObjectVersionId— 指定 DataSync 要使用的清单版本。

      默认情况下， DataSync 使用对象的最新版本。

  5. 运行 create-task 命令来创建您的任务。

准备就绪后，您可以启动传输任务。

在启动任务时指定清单

您可以指定 DataSync 要在执行任务时使用的清单。

  1. 打开 AWS DataSync 控制台，网址为https://console.aws.amazon.com/datasync/。

  2. 在左侧导航窗格中，选择任务，然后选择要启动的任务。

  3. 在任务概览页面，选择开始，然后选择使用覆盖选项开始。

  4. 对于要扫描的内容，请选择特定文件、对象和文件夹，然后选择使用清单。

  5. 对于 S3 URI，请选择托管在 S3 存储桶上的清单。

    或者，您也可以输入 URI（例如，s3://bucket/prefix/my-manifest.csv）。

  6. 对于对象版本，请选择 DataSync 要使用的清单版本。

    默认情况下， DataSync 使用对象的最新版本。

  7. 对于清单访问角色，执行下列操作之一：

    • 选择 “自动生成” DataSync 以自动创建 IAM 角色来访问其 S3 存储桶中的清单。

    • 选择可以访问清单的现有 IAM 角色。

    有关更多信息，请参阅 提供对清单的 DataSync 访问权限。

  8. 选择开始，以开始传输。

  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" 
        }
      }
  }

  2. 对于 --task-arn 参数，请指定要启动的任务的 Amazon 资源名称（ARN）。

  3. 对于 --manifest-config 参数，请执行以下操作：

    • ManifestObjectPath：指定清单的 S3 对象键。

    • BucketAccessRoleArn— 指定允许 DataSync 访问其 S3 存储桶中的清单的 IAM 角色。

      有关更多信息，请参阅 提供对清单的 DataSync 访问权限。

    • S3BucketArn：指定托管清单的 S3 存储桶的 ARN。

    • ManifestObjectVersionId— 指定 DataSync 要使用的清单版本。

      默认情况下， DataSync 使用对象的最新版本。

  4. 运行 start-task-execution 命令开始传输。

限制

  • 您不能将清单与筛选条件一起使用。

  • 您不能只指定一个目录或文件夹，然后希望传输其中的所有内容。对于这种情况，请考虑使用包含筛选条件，而不是清单。

  • 您不能使用 “保留已删除文件” 任务选项（PreserveDeletedFiles在 API 中）来维护目标中不在源中的文件或对象。 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 位置。

错误：ManifestFileDoesNotExist

此错误表示在源代码中找不到清单中的文件。查看创建清单的指南。

后续步骤

如果尚未开始，请启动任务。否则，请监视任务的活动。