搭配 Amazon DocumentDB 使用 OpenSearch 擷取管道 - Amazon OpenSearch Service

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

搭配 Amazon DocumentDB 使用 OpenSearch 擷取管道

您可以使用 DocumentDB 外掛程式將文件變更串流至 Amazon OpenSearch Service,例如建立、更新和刪除。管道支援變更資料擷取 (CDC),如果可用,或 API 輪詢以進行大規模、低延遲串流。

您可以使用或不使用完整初始快照來處理資料。完整快照會擷取整個 Amazon DocumentDB 集合,並將其上傳至 Amazon S3。然後,管道會將資料傳送至一或多個 OpenSearch 索引。擷取快照後,管道會同步進行中的變更以維持一致性,並最終擷取近乎即時的更新。

如果您已經擁有來自其他來源的完整快照,或只需要處理新事件,則可以在沒有快照的情況下串流。在此情況下,管道會直接從 Amazon DocumentDB 變更串流讀取,而無需初始大量載入。

如果您啟用串流,則必須在 Amazon DocumentDB 集合上啟用變更串流。 Amazon DocumentDB 不過,如果您只執行完全載入或匯出,則不需要變更串流。

先決條件

建立 OpenSearch Ingestion 管道之前,請執行下列步驟:

  1. 遵循《Amazon DocumentDB 開發人員指南》中的建立 Amazon DocumentDB 叢集中的步驟,建立具有讀取資料許可的 Amazon DocumentDB 叢集Amazon DocumentDB 如果您使用 CDC 基礎設施,請將 Amazon DocumentDB 叢集設定為發佈變更串流。

  2. 在您的 Amazon DocumentDB 叢集上啟用 TLS。

  3. 設定私有地址空間的 VPC CIDR,以便與 OpenSearch Ingestion 搭配使用。

  4. 使用 在 Amazon DocumentDB 叢集上設定身分驗證 AWS Secrets Manager。依照 Amazon DocumentDB 自動輪換密碼中的步驟來啟用秘密輪換。如需詳細資訊,請參閱 Amazon DocumentDB 中使用角色型存取控制和安全性進行資料庫存取 Amazon DocumentDB

  5. 如果您使用變更串流來訂閱 Amazon DocumentDB 集合上的資料變更,請使用 change_stream_log_retention_duration 參數將保留期間延長至最多 7 天,以避免資料遺失。根據預設,變更串流事件會在記錄事件後存放 3 小時,這不足以容納大型集合。若要修改變更串流保留期間,請參閱修改變更串流日誌保留期間

  6. 建立 OpenSearch Service 網域或 OpenSearch Serverless 集合。如需詳細資訊,請參閱 建立 OpenSearch Service 網域建立集合

  7. 資源型政策連接至您的網域,或將資料存取政策連接至您的集合。這些存取政策允許 OpenSearch Ingestion 將資料從 Amazon DocumentDB 叢集寫入您的網域或集合。

    下列範例網域存取政策允許您在下一個步驟中建立的管道角色將資料寫入網域。請務必resource使用自己的 ARN 更新 。

    JSON
    { "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 角色,以存取寫入資料至集合或網域,請參閱 在 Amazon OpenSearch Ingestion 中設定角色和使用者

步驟 1:設定管道角色

在您設定 Amazon DocumentDB 管道先決條件之後,請設定您要在管道組態中使用的管道角色,並在角色中新增下列 Amazon DocumentDB 許可:

JSON
{ "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 Ingestion 管道,指定 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: 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" refresh_interval: PT1H

您可以使用預先設定的 Amazon DocumentDB 藍圖來建立此管道。如需詳細資訊,請參閱使用藍圖

如果您使用 AWS Management Console 建立管道,也必須將管道連接至 VPC,才能使用 Amazon DocumentDB 做為來源。若要這樣做,請尋找來源網路選項區段,選取連接至 VPC 核取方塊,然後從其中一個提供的預設選項中選擇 CIDR。您可以從私有地址空間使用任何 CIDR,如 RFC 1918 最佳實務所定義。

若要提供自訂 CIDR,請從下拉式功能表中選取其他。若要避免 OpenSearch Ingestion 和 Amazon DocumentDB 之間的 IP 地址發生衝突,請確定 Amazon DocumentDB VPC CIDR 與 OpenSearch Ingestion 的 CIDR 不同。

如需詳細資訊,請參閱設定管道的 VPC 存取

資料一致性

管道會持續輪詢或接收來自 Amazon DocumentDB 叢集的變更,並更新 OpenSearch 索引中的對應文件,以確保資料一致性。

OpenSearch Ingestion end-to-end確認,以確保資料耐久性。當管道讀取快照或串流時,它會動態建立分割區以進行平行處理。在擷取 OpenSearch 網域或集合中的所有記錄之後,管道收到確認時,會將分割區標記為完成。

如果您想要擷取至 OpenSearch Serverless 搜尋集合,您可以在管道中產生文件 ID。如果您想要擷取 OpenSearch Serverless 時間序列集合,請注意管道不會產生文件 ID,因此您必須在管道接收器組態document_id: "${getMetadata(\"primary_key\")}"中省略 。

OpenSearch 擷取管道也會將傳入的事件動作映射至對應的大量索引動作,以協助擷取文件。這可讓資料保持一致,以便 Amazon DocumentDB 中的每個資料變更都與 OpenSearch 中的對應文件變更進行協調。

映射資料類型

OpenSearch Service 會將每個傳入文件中的資料類型動態映射至 Amazon DocumentDB 中的對應資料類型。下表顯示 OpenSearch Service 如何自動映射各種資料類型。

資料類型 OpenSearch Amazon DocumentDB
Integer

OpenSearch 會自動將 Amazon DocumentDB 整數值映射至 OpenSearch 整數。

OpenSearch 會根據第一個傳送的文件動態對應 欄位。如果您在 Amazon DocumentDB 中具有相同屬性的混合資料類型,則自動映射可能會失敗。

例如,如果您的第一個文件具有很長的屬性,而稍後的文件具有與整數相同的屬性,則 OpenSearch 無法擷取第二個文件。在這些情況下,您應該提供明確的映射範本,選擇最靈活的數字類型,如下所示:

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

Amazon DocumentDB 支援整數

Long

OpenSearch 會自動將 Amazon DocumentDB 長值映射至 OpenSearch 長。

OpenSearch 會根據第一個傳送的文件動態對應 欄位。如果您在 Amazon DocumentDB 中具有相同屬性的混合資料類型,則自動映射可能會失敗。

例如,如果您的第一個文件具有很長的屬性,而稍後的文件具有與整數相同的屬性,則 OpenSearch 無法擷取第二個文件。在這些情況下,您應該提供明確的映射範本,選擇最靈活的數字類型,如下所示:

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

Amazon DocumentDB 支援長時間

字串

OpenSearch 會自動將字串值映射為文字。在某些情況下,例如列舉值,您可以映射到關鍵字類型。

下列範例示範如何將名為 的 Amazon DocumentDB 屬性映射PartType至 OpenSearch 關鍵字。

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

Amazon DocumentDB 支援字串

Double

OpenSearch 會自動將 Amazon DocumentDB 雙值映射至 OpenSearch 雙值。

OpenSearch 會根據第一個傳送的文件動態對應 欄位。如果您在 Amazon DocumentDB 中具有相同屬性的混合資料類型,則自動映射可能會失敗。

例如,如果您的第一個文件具有很長的屬性,而稍後的文件具有與整數相同的屬性,則 OpenSearch 無法擷取第二個文件。在這些情況下,您應該提供明確的映射範本,選擇最靈活的數字類型,如下所示:

{ "template": { "mappings": { "properties": { "MixedNumberField": { "type": "float" } } } } }
Amazon DocumentDB 支援雙工
日期

根據預設,日期會映射到 OpenSearch 中的整數。您可以定義自訂映射範本,將日期映射至 OpenSearch 日期。

{ "template": { "mappings": { "properties": { "myDateField": { "type": "date", "format": "epoch_second" } } } } }
Amazon DocumentDB 支援日期
時間戳記

根據預設,時間戳記會映射至 OpenSearch 中的整數。您可以定義自訂映射範本,將日期映射至 OpenSearch 日期。

{ "template": { "mappings": { "properties": { "myTimestampField": { "type": "date", "format": "epoch_second" } } } } }
Amazon DocumentDB 支援時間戳記
Boolean

OpenSearch 會將 Amazon DocumentDB 布林類型映射至 OpenSearch 布林類型。

Amazon DocumentDB 支援布林值類型屬性

Decimal (小數)

OpenSearch 會將 Amazon DocumentDB 映射屬性映射至巢狀欄位。相同的映射適用於巢狀欄位。

下列範例會將巢狀欄位中的字串映射至 OpenSearch 中的關鍵字類型:

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

使用此自訂映射,您可以使用雙階精確度查詢和彙總 欄位。原始值會在 OpenSearch 文件的 _source 屬性中保留完整精確度。如果沒有此映射,OpenSearch 預設會使用文字。

Amazon DocumentDB 支援小數
規則表達式 regex 類型會建立巢狀欄位。這些包括 <myFieldName>.pattern<myFieldName>.options

Amazon DocumentDB 支援規則表達式

二進位資料

OpenSearch 會自動將 Amazon DocumentDB 二進位資料映射至 OpenSearch 文字。您可以提供映射,將這些項目寫入 OpenSearch 中的二進位欄位。

下列範例示範如何將名為 的 Amazon DocumentDB 欄位映射imageData至 OpenSearch 二進位欄位。

{ "template": { "mappings": { "properties": { "imageData": { "type": "binary" } } } } }
Amazon DocumentDB 支援二進位資料欄位
ObjectId 具有類型 objectId 的欄位會映射至 OpenSearch 文字欄位。值將是 objectId 的字串表示法。 Amazon DocumentDB 支援 objectIds
Null

OpenSearch 可以使用 Amazon DocumentDB null 類型擷取文件。它會將值儲存為文件中的 null 值。沒有此類型的映射,而且此欄位無法編製索引或搜尋。

如果將相同的屬性名稱用於 null 類型,然後變更為不同的類型,例如字串,則 OpenSearch 會為第一個非 Null 值建立動態映射。後續值仍然可以是 Amazon DocumentDB Null 值。

Amazon DocumentDB 支援 null 類型欄位
未定義

OpenSearch 可以擷取 Amazon DocumentDB 未定義類型的文件。它會將值儲存為文件中的 null 值。沒有此類型的映射,而且此欄位無法編製索引或搜尋。

如果未定義類型使用相同的欄位名稱,然後變更為不同的類型,例如字串,則 OpenSearch 會為第一個未定義值建立動態映射。後續值仍然可以是 Amazon DocumentDB 未定義的值。

Amazon DocumentDB 支援未定義的類型欄位
MinKey

OpenSearch 可以使用 Amazon DocumentDB minKey 類型擷取文件。它會將值儲存為文件中的 null 值。沒有此類型的映射,而且此欄位無法編製索引或搜尋。

如果 minKey 類型使用相同的欄位名稱,然後變更為不同的類型,例如字串,則 OpenSearch 會為第一個非 minKey 值建立動態映射。後續的值仍然可以是 Amazon DocumentDB minKey 值。

Amazon DocumentDB 支援 minKey 類型欄位
MaxKey

OpenSearch 可以使用 Amazon DocumentDB maxKey 類型擷取文件。它會將值儲存為文件中的 null 值。沒有此類型的映射,而且此欄位無法編製索引或搜尋。

如果 maxKey 類型使用相同的欄位名稱,然後變更為不同的類型,例如字串,則 OpenSearch 會為第一個非maxKey 值建立動態映射。後續的值仍然可以是 Amazon DocumentDB maxKey 值。

Amazon DocumentDB 支援 maxKey 類型欄位

我們建議您在 OpenSearch Ingestion 管道中設定無效字母佇列 (DLQ)。如果您已設定佇列,OpenSearch Service 會將因動態映射失敗而無法擷取的所有失敗文件傳送至佇列。

如果自動映射失敗,您可以在管道組態template_content中使用 template_type和 來定義明確的映射規則。或者,您可以在啟動管道之前,直接在搜尋網域或集合中建立映射範本。

限制

當您為 Amazon DocumentDB 設定 OpenSearch 擷取管道時,請考慮下列限制:

  • OpenSearch Ingestion 與 Amazon DocumentDB 整合目前不支援跨區域擷取。您的 Amazon DocumentDB 叢集和 OpenSearch Ingestion 管道必須位於相同的 中 AWS 區域。

  • OpenSearch Ingestion 與 Amazon DocumentDB 整合目前不支援跨帳戶擷取。您的 Amazon DocumentDB 叢集和 OpenSearch Ingestion 管道必須位於相同的 中 AWS 帳戶。

  • OpenSearch Ingestion 管道僅支援一個 Amazon DocumentDB 叢集做為其來源。

  • 與 Amazon DocumentDB 的 OpenSearch Ingestion 整合特別支援以 Amazon DocumentDB 執行個體為基礎的叢集。它不支援 Amazon DocumentDB 彈性叢集。

  • OpenSearch Ingestion 整合僅支援 AWS Secrets Manager 作為 Amazon DocumentDB 叢集的身分驗證機制。

  • 您無法更新現有的管道組態,以從不同的資料庫或集合擷取資料。您必須改為建立新的管道。

建議 CloudWatch 警示

為了獲得最佳效能,我們建議您在建立 OpenSearch 擷取管道以存取 Amazon DocumentDB 叢集做為來源時,使用下列 CloudWatch 警示。

CloudWatch 警示 描述
<pipeline-name>.doucmentdb.credentialsChanged

此指標表示 AWS 秘密輪換的頻率。

<pipeline-name>.doucmentdb.executorRefreshErrors

此指標表示重新整理 AWS 秘密失敗。

<pipeline-name>.doucmentdb.exportRecordsTotal

此指標表示從 Amazon DocumentDB 匯出的記錄數目。

<pipeline-name>.doucmentdb.exportRecordsProcessed

此指標表示 OpenSearch Ingestion 管道處理的記錄數量。

<pipeline-name>.doucmentdb.exportRecordProcessingErrors

此指標表示從 Amazon DocumentDB 叢集讀取資料時OpenSearch 擷取管道中的處理錯誤數目。

<pipeline-name>.doucmentdb.exportRecordsSuccessTotal

此指標表示成功處理的匯出記錄總數。

<pipeline-name>.doucmentdb.exportRecordsFailedTotal

此指標表示無法處理的匯出記錄總數。

<pipeline-name>.doucmentdb.bytesReceived

此指標表示 OpenSearch Ingestion 管道收到的位元組總數。

<pipeline-name>.doucmentdb.bytesProcessed

此指標表示 OpenSearch Ingestion 管道處理的位元組總數。

<pipeline-name>.doucmentdb.exportPartitionQueryTotal

此指標表示匯出分割區總計。

<pipeline-name>.doucmentdb.streamRecordsSuccessTotal

此指標表示從串流成功處理的記錄數量。

<pipeline-name>.doucmentdb.streamRecordsFailedTotal

此指標表示無法從串流處理的記錄總數。