使用 EBS 直接 API 访问 EBS 快照的内容 - Amazon Elastic Compute Cloud
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

使用 EBS 直接 API 访问 EBS 快照的内容

您可以使用 Amazon Elastic Block Store (Amazon EBS) 直接 API 创建 EBS 快照,将数据直接写入快照,读取快照上的数据,并标识两个快照之间的差异或发生的更改。如果您是为 Amazon EBS 提供备份服务的独立软件供应商 (ISV),则利用 EBS 直接 API,可以更高效、更具成本效益地通过快照跟踪 EBS 卷上的增量更改。无需从快照创建新卷,然后使用 Amazon Elastic Compute Cloud (Amazon EC2) 实例来比较差异,即可完成此操作。

您可以从本地数据直接创建增量快照到 EBS 卷和云中,以用于快速灾难恢复。通过写入和读取快照的功能,您可以在发生灾难时将本地数据写入 EBS 快照。然后在灾难恢复后,您可以将其从快照恢复到 AWS 或本地。您不再需要构建和维护复杂的机制来将数据复制到 Amazon EBS 或从中复制数据。

本用户指南概述了构成 EBS 直接 API 的元素,并提供了如何有效使用这些元素的示例。有关 API 的操作、数据类型、参数和错误的更多信息,请参阅 EBS 直接 API 参考。有关支持的 AWS 区域、终端节点以及 EBS 直接 API 的服务配额的更多信息,请参阅 AWS General Reference 中的 Amazon EBS 终端节点和配额

了解 EBS 直接 API

下面是您在开始使用 EBS 直接 API 前应了解的关键元素。

定价

您为使用 EBS 直接 API 支付的费用取决于您发出的请求数。有关更多信息,请参阅 Amazon EBS 定价

快照

快照是备份 EBS 卷中的数据的主要方式。使用 EBS 直接 API,您还可以将数据从本地磁盘备份到快照。为节省存储成本,连续快照为增量快照,只包含自上一个快照以来更改的卷数据。有关更多信息,请参阅Amazon EBS 快照

注意

EBS 直接 API 不支持公有快照。

数据块

数据块是快照中的数据片段。每个快照可以包含数千个数据块。快照中的所有数据块都具有固定大小。

数据块索引

数据块索引是数据块在快照中的偏移位置,它用于标识数据块。将 BlockIndex 值与 BlockSize 值相乘 (BlockIndex * BlockSize),以确定逻辑卷中数据的逻辑偏移。

数据块令牌

数据块令牌是快照中的数据块的标识哈希,它用于查找数据块数据。EBS 直接 API 返回的数据块令牌是临时的。它们根据为其指定的到期时间戳发生更改,或者在您为同一个快照运行 ListSnapshotBlocks 或 ListChangedBlocks 请求时发生更改。

校验和

校验和是从数据块中派生的大小很小的基准值,用于检测其传输或存储过程中引入的错误。EBS 直接 API 使用校验和验证数据完整性。从 EBS 快照读取数据时,该服务会为传输的每个数据块提供 Base64 编码的 SHA256 校验和,您可以使用这些校验和进行验证。向 EBS 快照写入数据时,您必须为传输的每个数据块提供一个 Base64 编码的 SHA256 校验和。服务使用提供的校验和验证接收的数据。有关更多信息,请参阅本指南下文中的使用校验和

加密

通过加密,您的数据将转换为无法读取的代码,只能由有权访问加密数据所用密钥的人员破译这些代码,从而为数据提供保护。您可以使用 EBS 直接 API 读取和写入加密快照,但存在一些限制。有关更多信息,请参阅本指南下文中的使用加密

API 操作

EBS 直接 API 由六个操作组成。包含三个读取操作和三个写入操作。读取操作为 ListSnapshotBlocks、ListChangedBlocks 和 GetSnapshotBlock。写入操作为 StartSnapshot、PutSnapshotBlock 和 CompleteSnapshot。以下部分将介绍这些操作。

列出快照数据块

ListSnapshotBlocks 操作返回指定快照中数据块的数据块索引和数据块令牌。

列出已更改的数据块

ListChangedBlocks 操作返回同一卷和快照谱系的两个指定快照之间,存在不同的数据块的数据块索引和数据块令牌。

获取快照数据块

GetSnapshotBlock 操作返回指定快照 ID、数据块索引和数据块令牌的数据块中的数据。

启动快照

StartSnapshot 操作会开始拍照,可以是现有快照的增量快照,或者全新的快照。已开始快照会停留在“待处理”状态,直到通过使用 CompleteSnapshot 操作将其完成。

放置快照数据块

PutSnapshotBlock 操作会将数据以单个数据块的形式添加到已开始快照中。您必须为传输的数据块指定一个 Base64 编码的 SHA256 校验和。该服务会在传输完成以后验证校验和。若该服务计算的校验和与您指定值的不匹配,请求将会失败。

完成快照

CompleteSnapshot 操作会完成一个处于“待处理”状态的已开始快照。然后,该快照的状态会更改为“已完成”。

使用 EBS 直接 API 读取快照

以下步骤介绍了如何使用 EBS 直接 API 读取快照:

  1. 使用 ListSnapshotBlocks 操作可查看快照中数据块的数据块索引和数据块令牌。使用 ListChangedBlocks 操作也可查看同一卷和快照谱系的两个指定快照之间,存在不同的数据块的数据块索引和数据块令牌。这些操作可帮助您标识可能希望获取其数据的数据块的数据块令牌和数据块索引。

  2. 使用 GetSnapshotBlock 操作,指定要获取其数据的数据块的数据块索引和数据块令牌。

有关如何运行这些操作的示例,请参阅本指南后文中的通过命令行使用 EBS 直接 API通过 API 或 AWS 开发工具包使用 EBS 直接 API 部分。

使用 EBS 直接 API 写入增量快照

以下步骤介绍了如何使用 EBS 直接 API 写入增量快照:

  1. 使用 StartSnapshot 操作并指定父快照 ID,可以启动一个快照作为现有快照的增量快照,忽略父快照 ID 可启动新快照。此操作返回处于“待处理”状态的新快照 ID。

  2. 使用 PutSnapshotBlock 操作并指定待处理快照的 ID,以便以单个数据块的形式向其添加数据。您必须为传输的数据块指定一个 Base64 编码的 SHA256 校验和。服务将计算接收到的数据的校验和,并使用您指定的校验和对其进行验证。如果校验和不匹配,则操作失败。

  3. 当您完成将数据添加到待处理快照的操作后,使用 CompleteSnapshot 操作启动一个异步工作流,用于密封快照并将其移动到已完成状态。

重复这些步骤,使用之前创建的快照作为父级创建新的增量快照。

例如,在下图中,快照 A 是启动的第一个新快照。快照 A 用作父快照来启动快照 B。快照 B 用作父快照来启动和创建快照 C。快照 A、B 和 C 均为增量快照。快照 A 用于创建 EBS 卷 1。快照 D 创建自 EBS 卷 1。快照 D 是 A 的增量快照;它不是 B 或 C 的增量快照。


          使用 EBS 直接 API 创建增量快照。

有关如何运行这些操作的示例,请参阅本指南后文中的通过命令行使用 EBS 直接 API通过 API 或 AWS 开发工具包使用 EBS 直接 API 部分。

IAM 用户的权限

AWS Identity and Access Management (IAM) 用户必须具有以下策略才能使用 EBS 直接 API。有关更多信息,请参阅更改 IAM 用户的权限

向 IAM 用户分配以下策略时请小心谨慎。通过分配这些策略,您可以向通过 Amazon EC2 API(例如 CopySnapshot 或 CreateVolume 操作)拒绝其访问同一资源的用户授予访问权限。

以下策略允许对指定 AWS 区域中的所有快照使用读取 EBS 直接 API。在该策略中,将 <Region> 替换为快照的区域。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ebs:ListSnapshotBlocks", "ebs:ListChangedBlocks", "ebs:GetSnapshotBlock" ], "Resource": "arn:aws:ec2:<Region>::snapshot/*" } ] }

以下策略允许在对具有特定键/值标记的快照使用读取 EBS 直接 API。在策略中,将 <Key> 替换为标签的键值,并将 <Value> 替换为标签的值。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ebs:ListSnapshotBlocks", "ebs:ListChangedBlocks", "ebs:GetSnapshotBlock" ], "Resource": "arn:aws:ec2:*::snapshot/*", "Condition": { "StringEqualsIgnoreCase": { "aws:ResourceTag/<Key>": "<Value>" } } } ] }

以下策略允许仅对账户中特定时间范围内的所有快照使用读取 EBS 直接 API。此策略授权基于 aws:CurrentTime 全局条件键使用 EBS 直接 API。在策略中,请务必将显示的日期和时间范围替换为适用于您的策略的日期和时间范围。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ebs:ListSnapshotBlocks", "ebs:ListChangedBlocks", "ebs:GetSnapshotBlock" ], "Resource": "arn:aws:ec2:*::snapshot/*", "Condition": { "DateGreaterThan": { "aws:CurrentTime": "2018-05-29T00:00:00Z" }, "DateLessThan": { "aws:CurrentTime": "2020-05-29T23:59:59Z" } } } ] }

以下策略授予使用 AWS Key Management Service (AWS KMS) 中的特定密钥 ID 解密已加密快照的权限。它授予访问权限,以使用 EBS 快照的默认 AWS KMS 密钥 ID 加密新快照。它还提供了确定账户上是否默认启用了加密的功能。在策略中,将 <Region> 替换为 AWS KMS 密钥的区域,将 <AccountId> 替换为密钥的 AWS 账户的 ID,并将 <KeyId> 替换为用于加密要使用 EBS 直接 API 读取的快照的密钥 ID。

{ "Version": "2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:GenerateDataKey", "kms:GenerateDataKeyWithoutPlaintext", "kms:ReEncrypt*", "kms:CreateGrant", "ec2:CreateTags", "kms:DescribeKey", "ec2:GetEbsDefaultKmsKeyId", "ec2:GetEbsEncryptionByDefault" ], "Resource": "arn:aws:kms:<Region>:<AccountId>:key/<KeyId>" } ] }

有关更多信息,请参阅 IAM 用户指南 中的更改 IAM 用户的权限

以下策略允许对指定 AWS 区域中的所有快照使用写入 EBS 直接 API。在该策略中,将 <Region> 替换为快照的区域。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ebs:StartSnapshot", "ebs:PutSnapshotBlock", "ebs:CompleteSnapshot" ], "Resource": "arn:aws:ec2:<Region>::snapshot/*" } ] }

以下策略允许在对具有特定键/值标记的快照使用写入 EBS 直接 API。在策略中,将 <Key> 替换为标签的键值,并将 <Value> 替换为标签的值。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ebs:StartSnapshot", "ebs:PutSnapshotBlock", "ebs:CompleteSnapshot" ], "Resource": "arn:aws:ec2:*::snapshot/*", "Condition": { "StringEqualsIgnoreCase": { "aws:ResourceTag/<Key>": "<Value>" } } } ] }

以下策略允许使用所有 EBS 直接 API。只有在指定了父快照 ID 时,它才允许执行 StartSnapshot 操作。因此,此策略会阻止在不使用父快照的情况下开始新快照的功能。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "ebs:*", "Resource": "*", "Condition": { "StringEquals": { "ebs:ParentSnapshot": "arn:aws:ec2:*::snapshot/*" } } } ] }

以下策略允许使用所有 EBS 直接 API。它还允许只为新快照创建 user 标签键。此策略还确保用户有权创建标签。StartSnapshot 操作是唯一可以指定标签的操作。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "ebs:*", "Resource": "*", "Condition": { "ForAllValues:StringEquals": { "aws:TagKeys": "user" } } }, { "Effect": "Allow", "Action": "ec2:CreateTags", "Resource": "*" } ] }

以下策略允许仅对账户中特定时间范围内的所有快照使用写入 EBS 直接 API。此策略授权基于 aws:CurrentTime 全局条件键使用 EBS 直接 API。在策略中,请务必将显示的日期和时间范围替换为适用于您的策略的日期和时间范围。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ebs:StartSnapshot", "ebs:PutSnapshotBlock", "ebs:CompleteSnapshot" ], "Resource": "arn:aws:ec2:*::snapshot/*", "Condition": { "DateGreaterThan": { "aws:CurrentTime": "2018-05-29T00:00:00Z" }, "DateLessThan": { "aws:CurrentTime": "2020-05-29T23:59:59Z" } } } ] }

以下策略授予使用 AWS Key Management Service (AWS KMS) 中的特定密钥 ID 解密已加密快照的权限。它授予访问权限,以使用 EBS 快照的默认 AWS KMS 密钥 ID 加密新快照。它还提供了确定账户上是否默认启用了加密的功能。在策略中,将 <Region> 替换为 AWS KMS 密钥的区域,将 <AccountId> 替换为密钥的 AWS 账户的 ID,并将 <KeyId> 替换为用于加密要使用 EBS 直接 API 读取的快照的密钥 ID。

{ "Version": "2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:GenerateDataKey", "kms:GenerateDataKeyWithoutPlaintext", "kms:ReEncrypt*", "kms:CreateGrant", "ec2:CreateTags", "kms:DescribeKey", "ec2:GetEbsDefaultKmsKeyId", "ec2:GetEbsEncryptionByDefault" ], "Resource": "arn:aws:kms:<Region>:<AccountId>:key/<KeyId>" } ] }

有关更多信息,请参阅 IAM 用户指南 中的更改 IAM 用户的权限

使用加密

如果您的 AWS 账户默认启用了 Amazon EBS 加密,则无法使用未加密的父快照启动新快照。您必须首先通过复制父快照来对其进行加密。有关更多信息,请参阅 复制 Amazon EBS 快照默认加密

要开始加密的快照,请指定 AWS KMS 密钥的 Amazon 资源名称 (ARN),或在 StartSnapshot 请求中指定加密的父快照。如果两者都未指定,并且在账户上默认启用了 Amazon EBS 加密,则使用该账户的默认 CMK。如果没有为账户指定默认 CMK,则使用 AWS 托管 CMK。

重要

默认情况下,账户中的所有委托人都可以访问默认的 AWS 托管 CMK,并可将其用于 EBS 加密和解密操作。有关更多信息,请参阅 用于 EBS 加密的默认密钥

您可能需要其他 IAM 权限才能对 EBS 直接 API 使用加密。有关更多信息,请参阅本指南中之前的 IAM 用户的权限部分。

使用签名版本 4 签名

签名版本 4 是将身份验证信息添加到通过 HTTP 发送的 AWS 请求的过程。出于安全考虑,大多数 AWS 请求都必须使用访问密钥(包括访问密钥 ID 和秘密访问密钥)进行签名。这两个密钥通常称为您的安全凭证。有关如何获取账户凭证的信息,请参阅了解并获取您的凭证

如果您打算手动创建 HTTP 请求,则必须了解如何对其签名。当您使用 AWS Command Line Interface (AWS CLI) 或某个 AWS 开发工具包来向 AWS 发出请求时,这些工具会自动使用您在配置工具时指定的访问密钥为您签署请求。当您使用这些工具时,您不必了解如何亲自签署这些请求。

有关更多信息,请参阅 AWS General Reference中的使用 Signature Version 4 签名 AWS 请求

使用校验和

GetSnapshotBlock 操作返回快照的数据块中的数据,而 PutSnapShotBlock 操作会将数据添加到快照的数据块中。传输的数据块数据不在签名版本 4 签名流程中进行签名。因此,使用校验和来验证数据的完整性,如下所示:

  • 使用 GetSnapshotBlock 操作时,响应会使用 x-amz-Checksum 标头为数据块数据提供 Base64 编码的 SHA256 校验和,并使用 x-amz-Checksum-Algorithm 标头提供校验和算法。使用返回的校验和验证数据的完整性。如果生成的校验和与 Amazon EBS 提供的校验和不匹配,您应将数据视为无效,然后重试请求。

  • 使用 PutSnapshotBlock 操作时,您的请求必须使用 x-amz-Checksum 标头为数据块数据提供 Base64 编码的 SHA256 校验和,并使用 x-amz-Checksum-Algorithm 标头提供校验和算法。您提供的校验和将根据 Amazon EBS 生成的校验和进行验证,以验证数据的完整性。如果校验和不相符,请求将失败。

  • 当您使用 CompleteSnapshot 操作时,您的请求可以选择针对添加到快照的完整数据集,提供聚合的 Base64 编码的 SHA256 校验和。使用 x-amz-Checksum 标头提供校验和,使用 x-amz-Checksum-Algorithm 标头提供校验和算法,并使用 x-amz-Checksum-Aggregation-Method 标头提供校验和聚合方法。要使用线性聚合方法生成聚合校验和,请按照数据块索引的升序排列各个写入数据块的校验和,将它们连接成单个字符串,然后使用 SHA256 算法生成整个字符串的校验和。

这些操作中的校验和是签名版本 4 签名流程的一部分。

通过 API 或 AWS 开发工具包使用 EBS 直接 API

EBS 直接 API 参考提供了服务的每个操作和数据类型的描述和语法。您还可以使用一个 AWS 开发工具包来访问适用于您所用编程语言或平台的 API。有关更多信息,请参阅 AWS 开发工具包

EBS 直接 API 需要 AWS 签名版本 4 签名。有关更多信息,请参阅使用签名版本 4 签名

列出快照中的数据块

以下 ListChangedBlocks 示例请求返回快照 snap-0acEXAMPLEcf41648 中数据块的数据块索引和数据块令牌。startingBlockIndex 参数将结果限制为索引大于 1000 的数据块,并且 maxResults 参数将结果限制为前 100 个数据块。

GET /snapshots/snap-0acEXAMPLEcf41648/blocks?maxResults=100&startingBlockIndex=0 HTTP/1.1 Host: ebs.us-east-2.amazonaws.com Accept-Encoding: identity User-Agent: <User agent parameter> X-Amz-Date: 20200617T231953Z Authorization: <Authentication parameter>

以下为上一个请求的示例响应,其中列出了快照中的数据块索引和数据块令牌。使用 GetSnapshotBlock 操作,指定要获取其数据的数据块的数据块索引和数据块令牌。数据块令牌在列出的过期时间之前有效。

HTTP/1.1 200 OK x-amzn-RequestId: d6e5017c-70a8-4539-8830-57f5557f3f27 Content-Type: application/json Content-Length: 2472 Date: Wed, 17 Jun 2020 23:19:56 GMT Connection: keep-alive { "BlockSize": 524288, "Blocks": [ { "BlockIndex": 0, "BlockToken": "AAUBAcuWqOCnDNuKle11s7IIX6jp6FYcC/q8oT93913HhvLvA+3JRrSybp/0" }, { "BlockIndex": 1536, "BlockToken": "AAUBAWudwfmofcrQhGVlLwuRKm2b8ZXPiyrgoykTRC6IU1NbxKWDY1pPjvnV" }, { "BlockIndex": 3072, "BlockToken": "AAUBAV7p6pC5fKAC7TokoNCtAnZhqq27u6YEXZ3MwRevBkDjmMx6iuA6tsBt" }, { "BlockIndex": 3073, "BlockToken": "AAUBAbqt9zpqBUEvtO2HINAfFaWToOwlPjbIsQOlx6JUN/0+iMQl0NtNbnX4" }, … ], "ExpiryTime": 1.59298379649E9, "VolumeSize": 3 }

列出两个快照之间存在不同的数据块

以下 ListChangedBlocks 示例请求返回快照 snap-0acEXAMPLEcf41648snap-0c9EXAMPLE1b30e2f 之间存在不同的数据块的数据块索引和数据块令牌。startingBlockIndex 参数将结果限制为索引大于 0 的数据块,并且 maxResults 参数将结果限制为前 500 个数据块。

GET /snapshots/snap-0c9EXAMPLE1b30e2f/changedblocks?firstSnapshotId=snap-0acEXAMPLEcf41648&maxResults=500&startingBlockIndex=0 HTTP/1.1 Host: ebs.us-east-2.amazonaws.com Accept-Encoding: identity User-Agent: <User agent parameter> X-Amz-Date: 20200617T232546Z Authorization: <Authentication parameter>

以下为上一个请求的示例响应,其中显示了两个快照的数据块索引 0307260026003 存在不同。此外,数据块索引 60026003 仅存在于指定的第一个快照 ID 中,而不存在于第二个快照 ID 中,因为响应中没有列出第二个数据块令牌。

使用 GetSnapshotBlock 操作,指定要获取其数据的数据块的数据块索引和数据块令牌。数据块令牌在列出的过期时间之前有效。

HTTP/1.1 200 OK x-amzn-RequestId: fb0f6743-6d81-4be8-afbe-db11a5bb8a1f Content-Type: application/json Content-Length: 1456 Date: Wed, 17 Jun 2020 23:25:47 GMT Connection: keep-alive { "BlockSize": 524288, "ChangedBlocks": [ { "BlockIndex": 0, "FirstBlockToken": "AAUBAVaWqOCnDNuKle11s7IIX6jp6FYcC/tJuVT1GgP23AuLntwiMdJ+OJkL", "SecondBlockToken": "AAUBASxzy0Y0b33JVRLoYm3NOresCxn5RO+HVFzXW3Y/RwfFaPX2Edx8QHCh" }, { "BlockIndex": 3072, "FirstBlockToken": "AAUBAcHp6pC5fKAC7TokoNCtAnZhqq27u6fxRfZOLEmeXLmHBf2R/Yb24MaS", "SecondBlockToken": "AAUBARGCaufCqBRZC8tEkPYGGkSv3vqvOjJ2xKDi3ljDFiytUxBLXYgTmkid" }, { "BlockIndex": 6002, "FirstBlockToken": "AAABASqX4/NWjvNceoyMUljcRd0DnwbSwNnes1UkoP62CrQXvn47BY5435aw" }, { "BlockIndex": 6003, "FirstBlockToken": "AAABASmJ0O5JxAOce25rF4P1sdRtyIDsX12tFEDunnePYUKOf4PBROuICb2A" }, ... ], "ExpiryTime": 1.592976647009E9, "VolumeSize": 3 }

从快照获取数据块数据

以下 GetSnapshotBlock 示例请求返回快照 snap-0c9EXAMPLE1b30e2f 中,数据块令牌为 AAUBARGCaufCqBRZC8tEkPYGGkSv3vqvOjJ2xKDi3ljDFiytUxBLXYgTmkid 的数据块索引 3072 中的数据。

GET /snapshots/snap-0c9EXAMPLE1b30e2f/blocks/3072?blockToken=AAUBARGCaufCqBRZC8tEkPYGGkSv3vqvOjJ2xKDi3ljDFiytUxBLXYgTmkid HTTP/1.1 Host: ebs.us-east-2.amazonaws.com Accept-Encoding: identity User-Agent: <User agent parameter> X-Amz-Date: 20200617T232838Z Authorization: <Authentication parameter>

以下为上一个请求的示例响应,其中显示了返回的数据的大小、用于验证数据的校验和以及用于生成校验和的算法。二进制数据在响应的正文中传输,并在以下示例中以 BlockData 表示。

HTTP/1.1 200 OK x-amzn-RequestId: 2d0db2fb-bd88-474d-a137-81c4e57d7b9f x-amz-Data-Length: 524288 x-amz-Checksum: Vc0yY2j3qg8bUL9I6GQuI2orTudrQRBDMIhcy7bdEsw= x-amz-Checksum-Algorithm: SHA256 Content-Type: application/octet-stream Content-Length: 524288 Date: Wed, 17 Jun 2020 23:28:38 GMT Connection: keep-alive BlockData

启动快照

以下 StartSnapshot 示例请求启动 8 GiB 快照,使用快照 snap-123EXAMPLE1234567 作为父快照。新快照将是父快照的增量快照。如果在指定的 60 分钟超时期限内,没有针对快照发出放置或完成请求,则快照将转为错误状态。550e8400-e29b-41d4-a716-446655440000 客户端令牌确保请求的幂等性。如果省略了客户端令牌,AWS 开发工具包会自动为您生成一个。有关幂等性的更多信息,请参阅 StartSnapshot API 的幂等性

POST /snapshots HTTP/1.1 Host: ebs.us-east-2.amazonaws.com Accept-Encoding: identity User-Agent: <User agent parameter> X-Amz-Date: 20200618T040724Z Authorization: <Authentication parameter> { "VolumeSize": 8, "ParentSnapshot": snap-123EXAMPLE1234567, "ClientToken": "550e8400-e29b-41d4-a716-446655440000", "Timeout": 60 }

以下为上一个请求的示例响应,其中显示了快照 ID、AWS 账户 ID、状态、卷大小(以 GiB 为单位)以及快照中数据块的大小。快照以“待处理”状态开始。在后续 PutSnapshotBlocks 请求中指定快照 ID,以将数据写入快照。

HTTP/1.1 201 Created x-amzn-RequestId: 929e6eb9-7183-405a-9502-5b7da37c1b18 Content-Type: application/json Content-Length: 181 Date: Thu, 18 Jun 2020 04:07:29 GMT Connection: keep-alive { "BlockSize": 524288, "Description": null, "OwnerId": "138695307491", "Progress": null, "SnapshotId": "snap-052EXAMPLEc85d8dd", "StartTime": null, "Status": "pending", "Tags": null, "VolumeSize": 8 }

将数据放入快照

以下 PutSnapshot 示例请求将 524288 字节的数据写入快照 snap-052EXAMPLEc85d8dd 上的数据块索引 1000。Base64 编码的 QOD3gmEQOXATfJx2Aa34W4FU2nZGyXfqtsUuktOw8DM= 校验和使用 SHA256 算法生成。数据在请求的正文中传输,并在以下示例中以 BlockData 表示。

PUT /snapshots/snap-052EXAMPLEc85d8dd/blocks/1000 HTTP/1.1 Host: ebs.us-east-2.amazonaws.com Accept-Encoding: identity x-amz-Data-Length: 524288 x-amz-Checksum: QOD3gmEQOXATfJx2Aa34W4FU2nZGyXfqtsUuktOw8DM= x-amz-Checksum-Algorithm: SHA256 User-Agent: <User agent parameter> X-Amz-Date: 20200618T042215Z X-Amz-Content-SHA256: UNSIGNED-PAYLOAD Authorization: <Authentication parameter> BlockData

以下为上一个请求的示例响应,其中确认服务接收的数据的数据长度、校验和以及校验和算法。

HTTP/1.1 201 Created x-amzn-RequestId: 643ac797-7e0c-4ad0-8417-97b77b43c57b x-amz-Checksum: QOD3gmEQOXATfJx2Aa34W4FU2nZGyXfqtsUuktOw8DM= x-amz-Checksum-Algorithm: SHA256 Content-Type: application/json Content-Length: 2 Date: Thu, 18 Jun 2020 04:22:12 GMT Connection: keep-alive {}

完成快照

以下 CompleteSnapshot 示例请求完成快照 snap-052EXAMPLEc85d8dd。该命令指定将 5 数据块写入快照。6D3nmwi5f2F0wlh7xX8QprrJBFzDX8aacdOcA3KCM3c= 校验和表示写入快照的完整数据集的校验和。

POST /snapshots/completion/snap-052EXAMPLEc85d8dd HTTP/1.1 Host: ebs.us-east-2.amazonaws.com Accept-Encoding: identity x-amz-ChangedBlocksCount: 5 x-amz-Checksum: 6D3nmwi5f2F0wlh7xX8QprrJBFzDX8aacdOcA3KCM3c= x-amz-Checksum-Algorithm: SHA256 x-amz-Checksum-Aggregation-Method: LINEAR User-Agent: <User agent parameter> X-Amz-Date: 20200618T043158Z Authorization: <Authentication parameter>

以下为上一个请求的示例响应。

HTTP/1.1 202 Accepted x-amzn-RequestId: 06cba5b5-b731-49de-af40-80333ac3a117 Content-Type: application/json Content-Length: 20 Date: Thu, 18 Jun 2020 04:31:50 GMT Connection: keep-alive {"Status":"pending"}

通过命令行使用 EBS 直接 API

以下示例显示如何通过 AWS Command Line Interface (AWS CLI) 使用 EBS 直接 API。有关安装和配置 AWS CLI 的更多信息,请参阅安装 AWS CLI快速配置 AWS CLI

列出快照中的数据块

以下 list-snapshot-blocks 示例命令返回快照 snap-0987654321 中数据块的数据块索引和数据块令牌。--starting-block-index 参数将结果限制为索引大于 1000 的数据块,并且 --max-results 参数将结果限制为前 100 个数据块。

aws ebs list-snapshot-blocks --snapshot-id snap-0987654321 --starting-block-index 1000 --max-results 100

以下为上一个命令的示例响应,其中列出了快照中的数据块索引和数据块令牌。使用 get-snapshot-block 命令,指定要获取其数据的数据块的数据块索引和数据块令牌。数据块令牌在列出的过期时间之前有效。

{ "Blocks": [ { "BlockIndex": 1001, "BlockToken": "AAABAV3/PNhXOynVdMYHUpPsetaSvjLB1dtIGfbJv5OJ0sX855EzGTWos4a4" }, { "BlockIndex": 1002, "BlockToken": "AAABATGQIgwr0WwIuqIMjCA/Sy7e/YoQFZsHejzGNvjKauzNgzeI13YHBfQB" }, { "BlockIndex": 1007, "BlockToken": "AAABAZ9CTuQtUvp/dXqRWw4d07eOgTZ3jvn6hiW30W9duM8MiMw6yQayzF2c" }, { "BlockIndex": 1012, "BlockToken": "AAABAQdzxhw0rVV6PNmsfo/YRIxo9JPR85XxPf1BLjg0Hec6pygYr6laE1p0" }, { "BlockIndex": 1030, "BlockToken": "AAABAaYvPax6mv+iGWLdTUjQtFWouQ7Dqz6nSD9L+CbXnvpkswA6iDID523d" }, { "BlockIndex": 1031, "BlockToken": "AAABATgWZC0XcFwUKvTJbUXMiSPg59KVxJGL+BWBClkw6spzCxJVqDVaTskJ" }, ... ], "ExpiryTime": 1576287332.806, "VolumeSize": 32212254720, "BlockSize": 524288 }

列出两个快照之间存在不同的数据块

以下 list-changed-blocks 示例命令返回快照 snap-1234567890snap-0987654321 之间存在不同的数据块的数据块索引和数据块令牌。--starting-block-index 参数将结果限制为索引大于 0 的数据块,并且 --max-results 参数将结果限制为前 500 个数据块。

aws ebs list-changed-blocks --first-snapshot-id snap-1234567890 --second-snapshot-id snap-0987654321 --starting-block-index 0 --max-results 500

以下为上一个命令的示例响应,其中显示了两个快照的数据块索引 0、6000、6001、6002 和 6003 存在不同。此外,数据块索引 6001、6002 和 6003 仅存在于指定的第一个快照 ID 中,而不存在于第二个快照 ID 中,因为响应中没有列出第二个数据块令牌。

使用 get-snapshot-block 命令,指定要获取其数据的数据块的数据块索引和数据块令牌。数据块令牌在列出的过期时间之前有效。

{ "ChangedBlocks": [ { "BlockIndex": 0, "FirstBlockToken": "AAABAVahm9SO60Dyi0ORySzn2ZjGjW/KN3uygGlS0QOYWesbzBbDnX2dGpmC", "SecondBlockToken": "AAABAf8o0o6UFi1rDbSZGIRaCEdDyBu9TlvtCQxxoKV8qrUPQP7vcM6iWGSr" }, { "BlockIndex": 6000, "FirstBlockToken": "AAABAbYSiZvJ0/R9tz8suI8dSzecLjN4kkazK8inFXVintPkdaVFLfCMQsKe", "SecondBlockToken": "AAABAZnqTdzFmKRpsaMAsDxviVqEI/3jJzI2crq2eFDCgHmyNf777elD9oVR" }, { "BlockIndex": 6001, "FirstBlockToken": "AAABASBpSJ2UAD3PLxJnCt6zun4/T4sU25Bnb8jB5Q6FRXHFqAIAqE04hJoR" }, { "BlockIndex": 6002, "FirstBlockToken": "AAABASqX4/NWjvNceoyMUljcRd0DnwbSwNnes1UkoP62CrQXvn47BY5435aw" }, { "BlockIndex": 6003, "FirstBlockToken": "AAABASmJ0O5JxAOce25rF4P1sdRtyIDsX12tFEDunnePYUKOf4PBROuICb2A" }, ... ], "ExpiryTime": 1576308931.973, "VolumeSize": 32212254720, "BlockSize": 524288, "NextToken": "AAADARqElNng/sV98CYk/bJDCXeLJmLJHnNSkHvLzVaO0zsPH/QM3Bi3zF//O6Mdi/BbJarBnp8h" }

从快照获取数据块数据

以下 get-snapshot-block 示例命令返回快照 snap-1234567890 中,数据块令牌为 AAABASBpSJ2UAD3PLxJnCt6zun4/T4sU25Bnb8jB5Q6FRXHFqAIAqE04hJoR 的数据块索引 6001 中的数据。在 Windows 计算机上,二进制数据将输出到 C:\Temp 目录中的 data 文件。如果您在 Linux 或 Unix 计算机上运行该命令,请将输出路径替换为 /tmp/data 以将数据输出到 /tmp 目录中的 data 文件。

aws ebs get-snapshot-block --snapshot-id snap-1234567890 --block-index 6001 --block-token AAABASBpSJ2UAD3PLxJnCt6zun4/T4sU25Bnb8jB5Q6FRXHFqAIAqE04hJoR C:/Temp/data

以下为上一个命令的示例响应,其中显示了返回的数据的大小、用于验证数据的校验和以及校验和的算法。二进制数据会自动保存到您在请求命令中指定的目录和文件中。

{ "DataLength": "524288", "Checksum": "cf0Y6/Fn0oFa4VyjQPOa/iD0zhTflPTKzxGv2OKowXc=", "ChecksumAlgorithm": "SHA256" }

启动快照

以下 start-snapshot 示例命令启动 8 GiB 快照,使用快照 snap-123EXAMPLE1234567 作为父快照。新快照将是父快照的增量快照。如果在指定的 60 分钟超时期限内,没有针对快照发出放置或完成请求,则快照将转为错误状态。550e8400-e29b-41d4-a716-446655440000 客户端令牌确保请求的幂等性。如果省略了客户端令牌,AWS 开发工具包会自动为您生成一个。有关幂等性的更多信息,请参阅 StartSnapshot API 的幂等性

aws ebs start-snapshot --volume-size 8 --parent-snapshot snap-123EXAMPLE1234567 --timeout 60 --client-token 550e8400-e29b-41d4-a716-446655440000

以下为上一个命令的示例响应,其中显示了快照 ID、AWS 账户 ID、状态、卷大小(以 GiB 为单位)以及快照中数据块的大小。快照以 pending 状态启动。在后续 put-snapshot-block 命令中指定快照 ID 以将数据写入快照,然后使用 complete-snapshot 命令完成快照并将其状态更改为 completed

{ "SnapshotId": "snap-0aaEXAMPLEe306d62", "OwnerId": "111122223333", "Status": "pending", "VolumeSize": 8, "BlockSize": 524288 }

将数据放入快照

以下 put-snapshot 示例命令将 524288 字节的数据写入快照 snap-0aaEXAMPLEe306d62 上的数据块索引 1000。Base64 编码的 QOD3gmEQOXATfJx2Aa34W4FU2nZGyXfqtsUuktOw8DM= 校验和使用 SHA256 算法生成。传输的数据位于 /tmp/data 文件中。

aws ebs put-snapshot-block --snapshot-id snap-0aaEXAMPLEe306d62 --block-index 1 --data-length 524288 --block-data /tmp/data --checksum QOD3gmEQOXATfJx2Aa34W4FU2nZGyXfqtsUuktOw8DM= --checksum-algorithm SHA256

以下为上一个命令的示例响应,其中确认服务接收的数据的数据长度、校验和以及校验和算法。

{ "DataLength": "524288", "Checksum": "QOD3gmEQOXATfJx2Aa34W4FU2nZGyXfqtsUuktOw8DM=", "ChecksumAlgorithm": "SHA256" }

完成快照

以下 complete-snapshot 示例命令完成快照 snap-0aaEXAMPLEe306d62。该命令指定将 5 数据块写入快照。6D3nmwi5f2F0wlh7xX8QprrJBFzDX8aacdOcA3KCM3c= 校验和表示写入快照的完整数据集的校验和。有关校验和的更多信息,请参阅本指南前文中的使用校验和

aws ebs complete-snapshot --snapshot-id snap-0aaEXAMPLEe306d62 --changed-blocks-count 5 --checksum 6D3nmwi5f2F0wlh7xX8QprrJBFzDX8aacdOcA3KCM3c= --checksum-algorithm SHA256 --checksum-aggregation-method LINEAR

以下为上一个命令的示例响应。

{ "Status": "pending" }

优化性能

您可以并发运行 API 请求。假设 PutSnapshotBlock 数据块延迟为 100 毫秒,那么一个线程在一秒内可以处理 10 个请求。此外,假设您的客户端应用程序创建多个线程和连接(例如 100 个连接),那么它每秒可以发出 1000 (10 * 100) 个请求。这对应于大约每秒 500 MB 的吞吐量。

以下列表包含在您应用程序中需要了解的几点:

  • 每个线程是否使用单独的连接? 如果应用程序上的连接受限制,则多线程将等待可用连接,而您会发现吞吐量较低。

  • 应用程序的两个放置请求之间是否有任何等待时间? 这将降低线程的有效吞吐量。

  • 实例的带宽限制 – 如果实例上的带宽与其他应用程序共享,则会限制 PutSnapshotBlock 请求的可用吞吐量。

请确保注意账户中可能运行的其他工作负载,以避免瓶颈。您还应将重试机制内置到 EBS 直接 API 工作流中,以处理限制、超时和服务不可用性。

查看 EBS 直接 API 服务配额以确定您每秒可运行的最大 API 请求数。有关更多信息,请参阅 AWS 一般参考 中的 Amazon Elastic Block Store 终端节点和配额

常见问题

如果快照具有挂起状态,是否可以使用 EBS 直接 API 访问该快照?

不可以。仅当快照具有已完成状态时,才能访问该快照。

EBS 直接 API 是否按数字顺序返回数据块索引?

是。返回的数据块索引是唯一的,并按数字顺序排列。

我是否可以提交 MaxResults 参数值低于 100 的请求?

不可以。您可以使用的最小 MaxResult 参数值为 100。如果您提交 MaxResult 参数值低于 100 的请求,并且快照中的数据块超过 100 个,则 API 将返回至少 100 个结果。

我是否可以并发运行 API 请求?

您可以并发运行 API 请求。请确保注意账户中可能运行的其他工作负载,以避免瓶颈。您还应将重试机制内置到 EBS 直接 API 工作流中,以处理限制、超时和服务不可用性。有关更多信息,请参阅优化性能

查看 EBS 直接 API 服务配额以确定您每秒可运行的 API 请求数。有关更多信息,请参阅 AWS 一般参考 中的 Amazon Elastic Block Store 终端节点和配额

运行 ListChangedBlocks 操作时,是否即使快照中有数据块,也有可能获得空响应?

是。如果快照中几乎没有更改的数据块,则响应可能为空,但 API 将返回下一页令牌值。使用下一页令牌值来继续转到下一页结果。当 API 返回的下一页令牌值为 null 时,您可以确认已到达最后一页结果。

如果同时指定了 NextToken 参数和 StartingBlockIndex 参数,将使用这两者中的哪一个?

使用 NextToken,并忽略 StartingBlockIndex。

数据块令牌和下一个令牌的有效期是多久?

数据块令牌的有效期为七天,下一个令牌的有效期为 60 分钟。

是否支持已加密快照?

是。可以使用 EBS 直接 API 访问加密快照。

要访问已加密快照,用户必须有权访问用于加密快照的密钥和 AWS KMS 解密操作。有关要分配给用户的 AWS KMS 策略,请参阅本指南前面的 IAM 用户的权限部分。

是否支持公有快照?

不支持公有快照。

list snapshot block 是返回快照中的所有数据块索引和数据块令牌,还是仅返回那些写入数据的数据块索引和数据块令牌?

它只返回写入数据的数据块索引和令牌。

我能否获得 EBS 直接 API 在我的账户上发起的所有 API 调用的历史记录,以便用于安全分析和运营方面的故障排除?

是。要获取您账户上的 EBS 直接 API API 调用的历史记录,请在 AWS 管理控制台中打开 AWS CloudTrail。有关更多信息,请参阅使用 AWS CloudTrail 记录 EBS 直接 API 的 API 调用