在 Amaz OpenSearch on DocumentDB 中使用采集管道 - 亚马逊 OpenSearch 服务

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

在 Amaz OpenSearch on DocumentDB 中使用采集管道

您可以将 OpenSearch 采集管道与 Amazon DocumentDB 配合使用,将文档更改(例如创建、更新和删除)流式传输到 OpenSearch 亚马逊服务域和馆藏。如果您的Amaz OpenSearch on DocumentDB集群上可用,摄取管道可以利用变更数据捕获 (CDC) 机制,API也可以利用轮询来提供一种高规模、低延迟的方式来持续流式传输来自Amazon DocumentDB集群的数据。

您可以通过两种方式使用 Amazon DocumentDB 作为数据源来处理数据:有或没有完整的初始快照。

完整的初始快照是对整个 Amazon DocumentDB 集合的批量查询。亚马逊 DocumentDB 将此快照上传到亚马逊 S3。从那里,In OpenSearch gestion 管道将其发送到域中的一个索引,或者将其分区到域中的多个索引。为了保持 Amazon DocumentDB 中的数据并保持 OpenSearch 一致,该管道会将 Amazon DocumentDB 集合中的所有创建、更新和删除事件与保存在一个或多个索引中的文档同步。 OpenSearch

当您使用完整的初始快照时,您的 OpenSearch 摄取管道会首先提取快照,然后开始从 Amazon DocumentDB 变更流中读取数据。它最终会赶上,并保持了 Amazon Doc OpenSearch umentDB 和. 之间近乎实时的数据一致性。

您也可以使用 OpenSearch Ingestion 与 Amazon DocumentDB 的集成在没有快照的情况下直播事件。如果您已经拥有来自其他机制的完整快照,或者您只想使用更改流流流流式传输来自 Amazon DocumentDB 集合的时事,请选择此选项。

使用这两个选项,如果您在工作流配置中启用数据流,则必须在 Amazon DocumentDB 馆藏上启用更改流。如果您只使用满载或导出,则无需启用更改流。

先决条件

在创建 OpenSearch 摄取管道之前,请执行以下步骤:

  1. 按照亚马逊 DocumentDB 开发者指南中创建亚马逊 DocumentD B 集群中的步骤,创建具有读取数据权限的 Amazon Documen tD B 集群。如果您使用CDC基础设施,请确保将您的 Amazon DocumentDB 集群配置为发布变更流。

  2. TLS在您的亚马逊文档数据库集群上启用。

  3. 设置一个VPCCIDR私有地址空间以用于 OpenSearch Ingestion。

  4. 使用在您的亚马逊文档数据库集群上设置身份验证。 AWS Secrets Manager按照自动轮换 Amazon DocumentDB 密码中的步骤启用密钥轮换。有关更多信息,请参阅 Amazon DocumentDB 中使用基于角色的访问控制和安全访问数据库

  5. 如果您使用更改流订阅 Amazon DocumentDB 馆藏中的数据更改,请使用参数将保留期延长至最多 7 天,从而避免数据丢失。change_stream_log_retention_duration默认情况下,Change streams 事件将在事件录制后存储 3 小时,这对于大型集合来说是不够的。要修改更改流保留期,请参阅修改更改流日志保留期限

  6. 创建 OpenSearch 服务域或 OpenSearch 无服务器集合。有关更多信息,请参阅创建 OpenSearch 服务域创建集合

  7. 基于资源的策略附加到您的网域,或者将数据访问策略附加到您的馆藏。这些访问策略允许 OpenSearch Ingestion 将数据从您的 Amazon DocumentDB 集群写入您的域名或集合。

    以下示例域访问策略允许您在下一步中创建的管道角色向域写入数据。请务必使用自己的版本resource进行更新ARN。

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::{pipeline-account-id}:role/pipeline-role" }, "Action": [ "es:DescribeDomain", "es:ESHttp*" ], "Resource": [ "arn:aws:es:{region}:{account-id}:domain/domain-name" ] } ] }

    要创建具有访问集合或域名写入数据的正确权限的IAM角色,请参阅域的必需权限集合的必需权限

步骤 1:配置管道角色

设置 Amazon DocumentDB 管道先决条件后,配置要在工作流配置中使用的管道角色,并在该角色中添加以下 Amazon DocumentDB 权限:

{ "Version": "2012-10-17", "Statement": [ { "Sid": "allowS3ListObjectAccess", "Effect": "Allow", "Action": [ "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::{s3_bucket}" ], "Condition": { "StringLike": { "s3:prefix": "{s3_prefix}/*" } } }, { "Sid": "allowReadAndWriteToS3ForExportStream", "Effect": "Allow", "Action": [ "s3:PutObject", "s3:GetObject", "s3:DeleteObject" ], "Resource": [ "arn:aws:s3:::{s3_bucket}/{s3_prefix}/*" ] }, { "Sid": "SecretsManagerReadAccess", "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue" ], "Resource": ["arn:aws:secretsmanager:{region}:{account-id}:secret:secret-name"] }, { "Effect": "Allow", "Action": [ "ec2:AttachNetworkInterface", "ec2:CreateNetworkInterface", "ec2:CreateNetworkInterfacePermission", "ec2:DeleteNetworkInterface", "ec2:DeleteNetworkInterfacePermission", "ec2:DetachNetworkInterface", "ec2:DescribeNetworkInterfaces" ], "Resource": [ "arn:aws:ec2:*:{account-id}:network-interface/*", "arn:aws:ec2:*:{account-id}:subnet/*", "arn:aws:ec2:*:{account-id}:security-group/*" ] }, { "Effect": "Allow", "Action": [ "ec2:DescribeDhcpOptions", "ec2:DescribeRouteTables", "ec2:DescribeSecurityGroups", "ec2:DescribeSubnets", "ec2:DescribeVpcs", "ec2:Describe*" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "ec2:CreateTags" ], "Resource": "arn:aws:ec2:*:*:network-interface/*", "Condition": { "StringEquals": { "aws:RequestTag/OSISManaged": "true" } } } ] }

您必须为用于创建 OpenSearch Ingestion 管道的IAM角色提供上述 Amazon EC2 权限,因为管道使用这些权限在您的中创建和删除网络接口。VPC管道只能通过此网络接口访问 Amazon DocumentDB 集群。

步骤 2:创建管道

然后,您可以配置如下所示的 OpenSearch 摄取管道,该管道将 Amazon DocumentDB 指定为来源。请注意,要填充索引名称,该getMetadata函数将documentdb_collection用作元数据键。如果要在不使用getMetadata方法的情况下使用不同的索引名称,则可以使用该配置index: "my_index_name"

version: "2" documentdb-pipeline: source: documentdb: acknowledgments: true host: "https://docdb-cluster-id.us-east-1.docdb.amazonaws.com" port: 27017 authentication: username: ${aws_secrets:secret:username} password: ${aws_secrets:secret:password} aws: sts_role_arn: "arn:aws:iam::{account-id}:role/pipeline-role" s3_bucket: "bucket-name" s3_region: "bucket-region" s3_prefix: "path" #optional path for storing the temporary data collections: - collection: "dbname.collection" export: true stream: true sink: - opensearch: hosts: ["https://search-mydomain.us-east-1.es.amazonaws.com"] index: "${getMetadata(\"documentdb_collection\")}" index_type: custom document_id: "${getMetadata(\"primary_key\")}" action: "${getMetadata(\"opensearch_action\")}" document_version: "${getMetadata(\"document_version\")}" document_version_type: "external" extension: aws: secrets: secret: secret_id: "my-docdb-secret" region: "us-east-1" sts_role_arn: "arn:aws:iam::{account-id}:role/pipeline-role" refresh_interval: PT1H

您可以使用预先配置的 Amazon DocumentDB 蓝图来创建此管道。有关更多信息,请参阅 使用蓝图创建管道

如果您使用创建管道,则还必须将您的管道附加到您的管道,才能将 Amazon DocumentDB 用作来源。 AWS Management Console VPC为此,请找到 “网络配置” 部分,选中 “连接到” VPC 复选框,然后CIDR从提供的默认选项中选择您的,或者选择自己的选项。您可以按照 RFC1918 年《当前最佳实践》的定义,使用私有地址空间中的任何CIDR一个。

要提供自定义CIDR,请从下拉菜单中选择 “其他”。为避免 OpenSearch Ingestion 和 Amazon DocumentDB 之间的 IP 地址冲突,请确保亚马逊 DocumentDB 与 for Ingestion VPC CIDR 不同。CIDR OpenSearch

有关更多信息,请参阅配置管道的VPC访问权限

数据一致性

该管道通过持续轮询或接收来自 Amazon DocumentDB 集群的更改以及更新索引中的相应文档来确保数据一致性。 OpenSearch

OpenSearch Ingestion 支持 end-to-end 确认,以确保数据的持久性。管道读取快照或流时,它会动态创建分区以进行并行处理。当管道在摄取 OpenSearch 域或集合中的所有记录后收到确认信息时,该管道会将该分区标记为已完成。

如果要收录到 OpenSearch 无服务器搜索集合中,可以在管道中生成文档 ID。如果要采集到 OpenSearch Serverless 时间序列集合,请注意管道不会生成文档 ID,因此您必须在工作流接收器配置document_id: "${getMetadata(\"primary_key\")}"中省略文档 ID。

In OpenSearch gestion 管道还将传入的事件操作映射到相应的批量索引操作中,以帮助采集文档。这样可以保持数据的一致性,从而使 Amazon DocumentDB 中的每一次数据更改都与中的相应文档更改保持一致。 OpenSearch

映射数据类型

OpenSearch 服务将每个传入文档中的数据类型动态映射到 Amazon DocumentDB 中的相应数据类型。下表显示了 S OpenSearch ervice 如何自动映射各种数据类型。

数据类型 OpenSearch Amazon DocumentDB
整数

OpenSearch 自动将 Amazon DocumentDB 的整数值映射到 OpenSearch整数。

OpenSearch 根据第一个发送的文档动态映射字段。如果您在 Amazon DocumentDB 中为同一属性混合使用多种数据类型,则自动映射可能会失败。

例如,如果您的第一个文档的属性很长,而后来的文档具有与整数相同的属性, OpenSearch 则无法收录第二个文档。在这些情况下,您应该提供一个显式的映射模板,该模板可以选择最灵活的数字类型,例如:

{ "template": { "mappings": { "properties": { "MixedNumberField": { "type": "float" } } } } }

亚马逊 DocumentDB 支持整数。

长整型

OpenSearch 自动将 Amazon DocumentDB 的长整数值映射到 OpenSearch多头。

OpenSearch 根据第一个发送的文档动态映射字段。如果您在 Amazon DocumentDB 中为同一属性混合使用多种数据类型,则自动映射可能会失败。

例如,如果您的第一个文档的属性很长,而后来的文档具有与整数相同的属性, OpenSearch 则无法收录第二个文档。在这些情况下,您应该提供一个显式的映射模板,该模板可以选择最灵活的数字类型,例如:

{ "template": { "mappings": { "properties": { "MixedNumberField": { "type": "float" } } } } }

亚马逊 DocumentDB 支持多头。

String

OpenSearch 自动将字符串值映射为文本。在某些情况下(例如枚举值),您可以映射到关键字类型。

以下示例说明如何将名为的 Amazon DocumentDB 属性映射PartType到关键词。 OpenSearch

{ "template": { "mappings": { "properties": { "PartType": { "type": "keyword" } } } } }

亚马逊 DocumentDB 支持字符串。

Double

OpenSearch 自动将 Amazon DocumentDB 双精度值映射到双精度值。 OpenSearch

OpenSearch 根据第一个发送的文档动态映射字段。如果您在 Amazon DocumentDB 中为同一属性混合使用多种数据类型,则自动映射可能会失败。

例如,如果您的第一个文档的属性很长,而后来的文档具有与整数相同的属性, OpenSearch 则无法收录第二个文档。在这些情况下,您应该提供一个显式的映射模板,该模板可以选择最灵活的数字类型,例如:

{ "template": { "mappings": { "properties": { "MixedNumberField": { "type": "float" } } } } }
亚马逊 DocumentDB 支持双打。
Date

默认情况下,日期映射到中的整数 OpenSearch。您可以定义自定义映射模板以将日期映射到 OpenSearch 日期。

{ "template": { "mappings": { "properties": { "myDateField": { "type": "date", "format": "epoch_second" } } } } }
亚马逊 DocumentDB 支持日期。
Timestamp

默认情况下,时间戳映射到中的整数。 OpenSearch您可以定义自定义映射模板以将日期映射到 OpenSearch日期。

{ "template": { "mappings": { "properties": { "myTimestampField": { "type": "date", "format": "epoch_second" } } } } }
亚马逊 DocumentDB 支持时间戳。
布尔值

OpenSearch 将 Amazon DocumentDB 布尔类型映射为 OpenSearch 布尔类型。

亚马逊 DocumentDB 支持布尔类型属性

十进制

OpenSearch 将 Amazon DocumentDB 映射属性映射到嵌套字段。嵌套字段内也适用相同的映射。

以下示例将嵌套字段中的字符串映射到中的关键字类型 OpenSearch:

{ "template": { "mappings": { "properties": { "myDecimalField": { "type": "double" } } } } }

使用此自定义映射,您可以以双级精度查询和聚合字段。原始值保留了 OpenSearch文档_source属性的全部精度。如果没有此映射,则默认 OpenSearch 使用文本。

亚马逊 DocumentDB 支持小数。
正则表达式 正则表达式类型创建嵌套字段。这些包括<myFieldName>.pattern<myFieldName>.options

亚马逊 DocumentDB 支持正则表达式

二进制数据

OpenSearch 自动将 Amazon DocumentDB 二进制数据映射到 OpenSearch文本。您可以提供映射以将它们写成二进制字段 OpenSearch。

以下示例说明如何将名为的 Amazon DocumentDB 字段映射imageData到 OpenSearch 二进制字段。

{ "template": { "mappings": { "properties": { "imageData": { "type": "binary" } } } } }
亚马逊 DocumentDB 支持二进制数据字段
ObjectId 具有 OpenSearch 文本字段 objectId 映射类型的字段。该值将是的字符串表示形式objectId。 亚马逊 DocumentDB 支持。objectIds
Null

OpenSearch 可以收录 Amazon DocumentDB 空类型的文档。它将该值作为空值保存在文档中。此类型没有映射,并且此字段未编制索引或不可搜索。

如果对空类型使用相同的属性名称,然后更改为其他类型(例如字符串),则会为第一个非空值 OpenSearch 创建动态映射。后续值仍然可以是亚马逊 DocumentDB 的空值。

亚马逊 DocumentDB 支持空类型字段
未定义

OpenSearch 可以收录 Amazon DocumentDB 未定义类型的文档。它将该值作为空值保存在文档中。此类型没有映射,并且此字段未编制索引或不可搜索。

如果对未定义的类型使用相同的字段名称,然后更改为其他类型(例如字符串),则会为第一个未定义的值 OpenSearch 创建动态映射。后续值仍然可以是 Amazon DocumentDB 未定义的值。

亚马逊 DocumentDB 支持未定义的类型字段
MinKey

OpenSearch 可以收录 Amazon DocumentDB 类型的 minKey 文档。它将该值作为空值保存在文档中。此类型没有映射,并且此字段未编制索引或不可搜索。

如果对一个 minKey 类型使用相同的字段名称,然后更改为不同的类型(例如字符串),则会为第一个非minKey 值 OpenSearch 创建动态映射。后续值仍然可以是亚马逊文档数据库 minKey 的值。

亚马逊 DocumentDB 支持minKey 类型字段
MaxKey

OpenSearch 可以收录 Amazon DocumentDB 类型的 maxKey 文档。它将该值作为空值保存在文档中。此类型没有映射,并且此字段未编制索引或不可搜索。

如果对一个 maxKey 类型使用相同的字段名称,然后更改为不同的类型(例如字符串),则会为第一个非maxKey 值 OpenSearch 创建动态映射。后续值仍然可以是亚马逊文档数据库 maxKey 的值。

亚马逊 DocumentDB 支持maxKey 类型字段

我们建议您在 OpenSearch 摄取管道中配置死信队列 (DLQ)。如果您已配置队列,S OpenSearch ervice 会将所有因动态映射失败而无法载入的失败文档发送到队列。

如果自动映射失败,则可以在管道配置中使用 template_typetemplate_content 来定义显式映射规则。或者,您可以在启动管道之前直接在搜索域或集合中创建映射模板。

限制

在为 Amazon DocumentDB 设置 OpenSearch 摄取管道时,请考虑以下限制:

  • OpenSearch Ingestion 与 Amazon DocumentDB 的集成目前不支持跨区域提取。您的 Amazon DocumentDB 集群和 OpenSearch 摄取管道必须处于相同的位置。 AWS 区域

  • OpenSearch Ingestion 与 Amazon DocumentDB 的集成目前不支持跨账户提取。您的 Amazon DocumentDB 集群和 OpenSearch 摄取管道必须处于相同的位置。 AWS 账户

  • 一个 OpenSearch 摄取管道仅支持一个 Amazon DocumentDB 集群作为其来源。

  • OpenSearch Ingestion 与亚马逊 DocumentDB 的集成特别支持基于亚马逊文档数据库实例的集群。它不支持亚马逊 DocumentDB 弹性集群。

  • OpenSearch Ingestion 集成仅支持 AWS Secrets Manager 作为您的 Amazon DocumentDB 集群的身份验证机制。

  • 您无法更新现有工作流配置以从其他数据库或集合中提取数据。相反,您必须创建一个新管道。