在 QLDB 中创建和管理流 - Amazon Quantum Ledger Database (Amazon QLDB)

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

在 QLDB 中创建和管理流

重要

终止支持通知:现有客户将能够使用 Amazon QLDB,直到 2025 年 7 月 31 日终止支持。有关更多详细信息,请参阅将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL

Amazon QLDB 提供 API 操作,用于创建和管理从您的分类账到 Amazon Kinesis Data Streams 的日记账数据流。QLDB 流捕获提交到日记账的每个文档修订,然后将其发送到 Kinesis 数据流。

您可以使用 AWS Management Console、S AWS DK 或 AWS Command Line Interface (AWS CLI) 来创建日记流。此外,您还可以使用 AWS CloudFormation 模板来创建流。有关更多信息,请参阅《AWS CloudFormation 用户指南》中的AWS::QLDB::Stream资源。

流参数

要创建 QLDB 日记账流,您必须提供以下配置参数:

分类账

您想将其日记账数据流式传输到 Kinesis Data Streams 的 QLDB 分类账。

流名称

要分配给 QLDB 日记账流的名称。用户定义的名称有助于识别和指示流的用途。

您的流名称在给定分类账的其他活动的 流中必须是唯一的。流名称与分类账名称具有相同的命名约束,如 Amazon QLDB 资源中的限额和限制 中所定义。

除了流名称外,QLDB 还会为您创建的每个 QLDB 流分配一个流 ID。在给定分类账的所有流中,流 ID 是唯一的,无论其状态如何。

开始日期和时间

开始流式传输日记账数据的开始日期和时间。此值可以是过去的任何日期和时间,但是不能是将来的任何日期和时间。

结束日期和时间

(可选)指定流结束的日期和时间。

如果您创建了一个没有结束时间的无限期流,您必须手动取消它以结束流。您还可以取消一个尚未达到指定结束日期和时间的活动有限流。

目标 Kinesis 数据流

您的数据流写入数据记录的 Kinesis Data Streams 目标资源。要了解如何创建 Kinesis 数据流,请参阅Amazon Kinesis Data Streams 开发者指南 中的 创建和更新数据流

重要
  • 不支持跨账户和跨区域流。指定的Kinesis数据流必须与您的账本位于相同的​​ AWS 区域 和分类账中。

  • 默认情况下,Kinesis Data Streams 中的记录聚合处于启用状态。此选项使 QLDB 能够在单个 Kinesis 数据流记录中发布多个数据记录,从而增加每个 API 调用发送的记录数量。

    记录聚合对记录处理具有重要影响,并且需要在流使用者中取消聚合。要了解更多信息,请参阅 《Amazon Kinesis Data Streams 开发人员指南》 中的 KPL 主要概念以及使用者取消聚合

IAM 角色

允许 QLDB 承担您的 Kinesis 数据流的写入权限的 IAM 角色。您可以使用 QLDB 控制台自动创建此角色,也可以在 IAM 中手动创建该角色。要了解如何手动创建,请参阅流权限

要在请求日记账流时将角色传递给 QLDB,您必须具有对 IAM 角色资源执行 iam:PassRole 操作的权限。

流 ARN

每个 QLDB 日记账流都是分类账的子资源,由 Amazon 资源名称(ARN)进行唯一标识。以下是名为 IiPT4brpZCqCq3f4MTHbYy 分类账​​而且流 ID 为 exampleLedger ​​的 QLDB 流的示例 ARN。

arn:aws:qldb:us-east-1:123456789012:stream/exampleLedger/IiPT4brpZCqCq3f4MTHbYy

以下部分介绍如何使用 AWS Management Console创建和取消 QLDB 流式传输。

AWS Management Console

按照以下步骤,使用 QLDB 控制台创建或取消 QLDB 流。

创建流(控制台)
  1. 登录并打开亚马逊 QLDB 控制台,网址为 /qldb。 AWS Management Console https://console.aws.amazon.com

  2. 在导航窗格中,选择 Streams(流)

  3. 选择 创建 QLDB 流

  4. 创建 QLDB 流页面,输入以下设置:

    • 流名称 - 要分配给 QLDB 日记账流的名称。

    • 分类账 — 要流式传输其日记账数据的分类账。

    • 开始日期和时间:开始流式传输日记账数据的开始时间戳(UTC)。此时间戳默认为当前日期和时间。时间不能在将来中,并且必须早于结束日期和时间

    • 结束日期和时间-(可选)指定流结束时间的互斥的时间戳(UTC)。如果不定义此参数,则流将无限期运行,直到您取消它。

    • 目标流 — 您的数据流向其写入数据记录的 Kinesis Data Streams 目标资源。采用以下 ARN 格式。

      arn:aws:kinesis:aws-region:account-id:stream/kinesis-stream-name

      以下是示例。

      arn:aws:kinesis:us-east-1:123456789012:stream/stream-for-qldb

      不支持跨账户和跨区域流。指定的 Kinesis 数据流必须 AWS 区域 与您的账本相同。

    • 在 Kinesis Data Streams 中启用记录聚合-(默认启用)允许 QLDB 在单个 Kinesis Data Streams 记录中发布多个数据记录,从而增加每个 API 调用发送的记录数量。

    • 服务访问权限 — 授予 QLDB 对您的 Kinesis 数据流的写入权限的 IAM 角色。

      要在请求日记账流时将角色传递给 QLDB,您必须具有对 IAM 角色资源执行 iam:PassRole 操作的权限。

      • 创建和使用新的服务角色 - 让控制台为您创建一个具有指定 Kinesis 数据流所需权限的新角色。

      • 使用现有的服务角色-要了解如何在 IAM 中手动创建此角色,请参阅流权限

    • 标签 –(可选)通过以键值对的形式附加标签来向角色添加元数据。您可以向流中添加标签来帮助组织和标识这些它们。有关更多信息,请参阅为 Amazon QLDB 资源贴标签

      选择添加标签,然后根据需要输入任何键值对。

  5. 根据需要进行设置后,选择 创建 QLDB 流

    如果您的请求提交成功,控制台将返回主页面,并列出您的 QLDB 流及其当前状态。

  6. 在您的流处于活动状态之后,使用 Kinesis 来使用一个使用者应用程序处理您的流数据。

    打开 Kinesis Data Streams 控制台 https://console.aws.amazon.com/kinesis/,网址为。

有关流中数据记录格式的信息,请参阅 QLDB 在 Kinesis 中流记录

要了解如何处理导致错误的流,请参阅处理受损流

取消流(控制台)

取消 QLDB 流后,您将无法重启该流。要恢复向 Kinesis Data Streams 传输数据,您可以创建一个新的 QLDB 流。

  1. 在 /qldb 上打开亚马逊 QLDB 控制台。https://console.aws.amazon.com

  2. 在导航窗格中,选择 Streams(流)

  3. 在 QLDB 流列表中,选择要取消的当前流流。

  4. 选择 取消流。请在提供的框中输入 cancel stream ​​以确认。

有关将 QLDB API 与 SDK 配合 AWS 使用来创建和管理日记流的信息,请参阅。 AWS CLI 在 QLDB 中使用流进行开发

流状态

QLDB 流可能处于以下状态之一:

  • ACTIVE— 当前正在流式传输或等待流式传输数据(对于没有结束时间的无限期流)。

  • COMPLETED— 已成功完成指定时间范围内所有日记账区块的流式传输。这是最终状态。

  • CANCELED— 在指定的结束时间之前由用户请求结束,并且不再主动流式传输数据。这是最终状态。

  • IMPAIRED— 由于出现需要您采取措施的错误,无法向 Kinesis 写入记录。这是一种可恢复的非终止状态。

    如果您在一小时内解决了错误,则流会自动进入 ACTIVE 状态。如果错误在一小时后仍未解决,则流会自动进入 FAILED 状态。

  • FAILED— 由于出错,无法向 Kinesis 写入记录,并且处于无法恢复的终止状态。

下图说明了 QLDB 流资源如何在状态之间转换。

状态图显示了 QLDB 流资源如何在活动、已取消、已完成、受损和失败状态之间转换。

终端流到期

处于终端状态(CANCELEDCOMPLETED、和FAILED)的流资源的保留期为 7 天。此限制到期后,它们会自动被硬删除。

删除终端流后,您将无法再使用 QLDB 控制台或 QLDB API 来描述或列出流资源。

处理受损流

如果您的流遇到错误,它会先移至 IMPAIRED 状态。QLDB 会继续 IMPAIRED重 试流长达一小时。

如果您在一小时内解决了错误,则流会自动进入 ACTIVE 状态。如果错误在一小时后仍未解决,则流会自动进入 FAILED 状态。

受损或失败的流可能由以下错误原因之一:

  • KINESIS_STREAM_NOT_FOUND— 目标 Kinesis Data Streams 资源不存在。验证您在 QLDB 流请求中提供的 Kinesis 数据流是否正确。然后,前往 Kinesis 并创建您指定的数据流。

  • IAM_PERMISSION_REVOKED— QLDB 没有足够的权限将数据记录写入您指定的 Kinesis 数据流。请确认您是否为指定的 Kinesis 数据流定义了一个策略,该策略授予 QLDB 服务(qldb.amazonaws.com)对以下操作的权限:

    • kinesis:PutRecord

    • kinesis:PutRecords

    • kinesis:DescribeStream

    • kinesis:ListShards

监控受损流

如果流受损,QLDB 控制台会显示一条横幅,显示有关该流及其遇到的错误的详细信息。您还可以使用 DescribeJournalKinesisStream API 操作来获取流的状态和潜在的错误原因。

此外,您还可以使用 Amazon CloudWatch 创建用于监控直播IsImpaired指标的警报。有关使用监控 QLDB 指标 CloudWatch的信息,请参阅。Amazon QLDB 指标与维度