本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 搭配 Amazon DocumentDB 使用 OpenSearch 擷取管道 您可以使用 [DocumentDB](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/documentdb/) 外掛程式將文件變更串流至 Amazon OpenSearch Service，例如建立、更新和刪除。管道支援變更資料擷取 (CDC)，如果可用，或 API 輪詢以進行大規模、低延遲串流。 您可以使用或不使用完整初始快照來處理資料。完整快照會擷取整個 Amazon DocumentDB 集合，並將其上傳至 Amazon S3。然後，管道會將資料傳送至一或多個 OpenSearch 索引。擷取快照後，管道會同步進行中的變更以維持一致性，並最終擷取近乎即時的更新。 如果您已經擁有來自其他來源的完整快照，或只需要處理新事件，則可以在沒有快照的情況下串流。在此情況下，管道會直接從 Amazon DocumentDB 變更串流讀取，而無需初始大量載入。 如果您啟用串流，則必須[在 Amazon DocumentDB 集合上啟用變更串流](https://docs.aws.amazon.com/documentdb/latest/developerguide/change_streams.html#change_streams-enabling)。 Amazon DocumentDB 不過，如果您只執行完全載入或匯出，則不需要變更串流。 ## 先決條件 建立 OpenSearch Ingestion 管道之前，請執行下列步驟： 1. 遵循《Amazon DocumentDB 開發人員指南》中的[建立 Amazon DocumentDB 叢集中的步驟，建立具有讀取資料許可的 Amazon DocumentDB 叢集](https://docs.aws.amazon.com/documentdb/latest/developerguide/get-started-guide.html#cloud9-cluster)。 *Amazon DocumentDB * 如果您使用 CDC 基礎設施，請將 Amazon DocumentDB 叢集設定為發佈變更串流。 1. 在您的 Amazon DocumentDB 叢集上啟用 TLS。 1. 設定私有地址空間的 VPC CIDR，以便與 OpenSearch Ingestion 搭配使用。 1. 使用 在 Amazon DocumentDB 叢集上設定身分驗證 AWS Secrets Manager。依照 [Amazon DocumentDB 自動輪換密碼中的步驟啟用秘密輪](https://docs.aws.amazon.com/documentdb/latest/developerguide/security.managing-users.html#security.managing-users-rotating-passwords)換。如需詳細資訊，請參閱 [Amazon DocumentDB 中使用角色型存取控制和安全性進行資料庫存取](https://docs.aws.amazon.com/documentdb/latest/developerguide/role_based_access_control.html)。 [ Amazon DocumentDB](https://docs.aws.amazon.com/documentdb/latest/developerguide/security.html) 1. 如果您使用變更串流來訂閱 Amazon DocumentDB 集合上的資料變更，請使用 `change_stream_log_retention_duration` 參數將保留期間延長至最多 7 天，以避免資料遺失。根據預設，變更串流事件會在記錄事件後存放 3 小時，這不足以容納大型集合。若要修改變更串流保留期間，請參閱[修改變更串流日誌保留期間](https://docs.aws.amazon.com/documentdb/latest/developerguide/change_streams.html#change_streams-modifying_log_retention)。 1. 建立 OpenSearch Service 網域或 OpenSearch Serverless 集合。如需詳細資訊，請參閱[建立 OpenSearch Service 網域](createupdatedomains.md#createdomains)及[建立集合](serverless-create.md)。 1. 將[資源型政策](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ac.html#ac-types-resource)連接至您的網域，或將[資料存取政策](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/serverless-data-access.html)連接至您的集合。這些存取政策允許 OpenSearch Ingestion 將資料從 Amazon DocumentDB 叢集寫入您的網域或集合。 下列範例網域存取政策允許您在下一個步驟中建立的管道角色將資料寫入網域。請務必`resource`使用自己的 ARN 更新 。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::{{444455556666}}:role/{{pipeline-role}}" }, "Action": [ "es:DescribeDomain", "es:ESHttp*" ], "Resource": [ "arn:aws:es:{{us-east-1}}:{{111122223333}}:domain/{{domain-name}}" ] } ] } ``` ------ 若要建立具有正確許可的 IAM 角色，以存取寫入資料至集合或網域，請參閱 [在 Amazon OpenSearch 擷取中設定角色和使用者](pipeline-security-overview.md)。 ## 步驟 1：設定管道角色 在您設定 Amazon DocumentDB 管道先決條件之後，[請設定您要在管道組態中使用的管道角色](pipeline-security-overview.md#pipeline-security-sink)，並在角色中新增下列 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:{{us-east-1}}:{{111122223333}}:secret:{{secret-name}}" ] }, { "Effect": "Allow", "Action": [ "ec2:AttachNetworkInterface", "ec2:CreateNetworkInterface", "ec2:CreateNetworkInterfacePermission", "ec2:DeleteNetworkInterface", "ec2:DeleteNetworkInterfacePermission", "ec2:DetachNetworkInterface", "ec2:DescribeNetworkInterfaces" ], "Resource": [ "arn:aws:ec2:*:{{111122223333}}:network-interface/*", "arn:aws:ec2:*:{{111122223333}}:subnet/*", "arn:aws:ec2:*:{{111122223333}}: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 藍圖來建立此管道。如需詳細資訊，請參閱[使用藍圖](pipeline-blueprint.md)。 如果您使用 AWS 管理主控台 建立管道，也必須將管道連接至 VPC，才能使用 Amazon DocumentDB 做為來源。若要這樣做，請尋找**來源網路選項**區段，選取**連接至 VPC** 核取方塊，然後從其中一個提供的預設選項中選擇 CIDR。您可以從私有地址空間使用任何 CIDR，如 [RFC 1918 最佳實務](https://datatracker.ietf.org/doc/html/rfc1918)所定義。 若要提供自訂 CIDR，請從下拉式功能表中選取**其他**。若要避免 OpenSearch Ingestion 和 Amazon DocumentDB 之間的 IP 地址發生衝突，請確定 Amazon DocumentDB VPC CIDR 與 OpenSearch Ingestion 的 CIDR 不同。 如需詳細資訊，請參閱[設定管道的 VPC 存取](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/pipeline-security.html#pipeline-vpc-configure)。 ## 資料一致性 管道會持續輪詢或接收來自 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 [支援整數](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)。 | | Long | OpenSearch 會自動將 Amazon DocumentDB 長值映射至 OpenSearch 長。
OpenSearch 會根據第一個傳送的文件動態對應 欄位。如果您在 Amazon DocumentDB 中具有相同屬性的混合資料類型，則自動映射可能會失敗。
例如，如果您的第一個文件具有很長的屬性，而稍後的文件具有與整數相同的屬性，則 OpenSearch 無法擷取第二個文件。在這些情況下，您應該提供明確的映射範本，選擇最靈活的數字類型，如下所示：
{
 "template": {
  "mappings": {
   "properties": {
    "MixedNumberField": {
     "type": "float"
    }
   }
  }
 }
}
| Amazon DocumentDB [支援長時間](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)。 | | String | OpenSearch 會自動將字串值映射為文字。在某些情況下，例如列舉值，您可以映射到關鍵字類型。
下列範例示範如何將名為 的 Amazon DocumentDB 屬性映射`PartType`至 OpenSearch 關鍵字。
{
 "template": {
  "mappings": {
   "properties": {
    "PartType": {
     "type": "keyword"
    }
   }
  }
 }
}
| Amazon DocumentDB [支援字串](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)。 | | Double | OpenSearch 會自動將 Amazon DocumentDB 雙值映射至 OpenSearch 雙值。
OpenSearch 會根據第一個傳送的文件動態對應 欄位。如果您在 Amazon DocumentDB 中具有相同屬性的混合資料類型，則自動映射可能會失敗。
例如，如果您的第一個文件具有很長的屬性，而稍後的文件具有與整數相同的屬性，則 OpenSearch 無法擷取第二個文件。在這些情況下，您應該提供明確的映射範本，選擇最靈活的數字類型，如下所示：
{
 "template": {
  "mappings": {
   "properties": {
    "MixedNumberField": {
     "type": "float"
    }
   }
  }
 }
}
| Amazon DocumentDB [支援雙工](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)。 | | Date | 根據預設，日期會映射到 OpenSearch 中的整數。您可以定義自訂映射範本，將日期映射至 OpenSearch 日期。
{
 "template": {
  "mappings": {
   "properties": {
    "myDateField": {
     "type": "date",
     "format": "epoch_second"
    }
   }
  }
 }
}
| Amazon DocumentDB 支援[日期](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)。 | | 時間戳記 | 根據預設，時間戳記會映射至 OpenSearch 中的整數。您可以定義自訂映射範本，將日期映射至 OpenSearch 日期。
{
 "template": {
  "mappings": {
   "properties": {
    "myTimestampField": {
     "type": "date",
     "format": "epoch_second"
    }
   }
  }
 }
}
| Amazon DocumentDB [支援時間戳記](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)。 | | Boolean | OpenSearch 會將 Amazon DocumentDB 布林類型映射至 OpenSearch 布林類型。 | Amazon DocumentDB 支援[布林值類型屬性](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)。 | | Decimal (小數) | OpenSearch 會將 Amazon DocumentDB 映射屬性映射至巢狀欄位。相同的映射適用於巢狀欄位。
下列範例會將巢狀欄位中的字串映射至 OpenSearch 中的關鍵字類型：
{
 "template": {
  "mappings": {
   "properties": {
    "myDecimalField": {
     "type": "double"
    }
   }
  }
 }
}

使用此自訂映射，您可以使用雙階精確度查詢和彙總 欄位。原始值會在 OpenSearch 文件的 `_source` 屬性中保留完整精確度。如果沒有此映射，OpenSearch 預設會使用文字。 | Amazon DocumentDB [支援小數](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)。 | | 規則表達式 | regex 類型會建立巢狀欄位。這些包括 {{}}.pattern和 {{}}.options。 | Amazon DocumentDB 支援[規則表達式](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)。 | | 二進位資料 | OpenSearch 會自動將 Amazon DocumentDB 二進位資料映射至 OpenSearch 文字。您可以提供映射，將這些項目寫入 OpenSearch 中的二進位欄位。
下列範例示範如何將名為 的 Amazon DocumentDB 欄位映射`imageData`至 OpenSearch 二進位欄位。
{
 "template": {
  "mappings": {
   "properties": {
    "imageData": {
     "type": "binary"
    }
   }
  }
 }
}
| Amazon DocumentDB 支援[二進位資料欄位](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)。 | | ObjectId | 具有類型 objectId 的欄位會映射至 OpenSearch 文字欄位。值將是 objectId 的字串表示法。 | Amazon DocumentDB 支援 [objectIds](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)。 | | Null | OpenSearch 可以使用 Amazon DocumentDB null 類型擷取文件。它會將值儲存為文件中的 null 值。沒有此類型的映射，且此欄位無法編製索引或搜尋。
如果相同屬性名稱用於 null 類型，然後變更為不同類型，例如字串，則 OpenSearch 會為第一個非 Null 值建立動態映射。後續值仍然可以是 Amazon DocumentDB null 值。 | Amazon DocumentDB 支援 [null 類型欄位](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)。 | | 未定義 | OpenSearch 可以擷取 Amazon DocumentDB 未定義類型的文件。它會將值儲存為文件中的 null 值。沒有此類型的映射，且此欄位無法編製索引或搜尋。
如果未定義類型使用相同的欄位名稱，然後變更為不同的類型，例如字串，則 OpenSearch 會為第一個未定義值建立動態映射。後續值仍然可以是 Amazon DocumentDB 未定義的值。 | Amazon DocumentDB 支援[未定義的類型欄位](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)。 | | MinKey | OpenSearch 可以使用 Amazon DocumentDB minKey 類型擷取文件。它會將值儲存為文件中的 null 值。沒有此類型的映射，且此欄位無法編製索引或搜尋。
如果 minKey 類型使用相同的欄位名稱，然後變更為不同的類型，例如字串，則 OpenSearch 會為第一個非 minKey 值建立動態映射。後續值仍然可以是 Amazon DocumentDB minKey 值。 | Amazon DocumentDB 支援 [minKey 類型欄位](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)。 | | MaxKey | OpenSearch 可以使用 Amazon DocumentDB maxKey 類型擷取文件。它會將值儲存為文件中的 null 值。沒有此類型的映射，且此欄位無法編製索引或搜尋。
如果 maxKey 類型使用相同的欄位名稱，然後變更為不同的類型，例如字串，則 OpenSearch 會為第一個非maxKey 值建立動態映射。後續值仍然可以是 Amazon DocumentDB maxKey 值。 | Amazon DocumentDB 支援 [maxKey 類型欄位](https://docs.aws.amazon.com/documentdb/latest/developerguide/mongo-apis.html#mongo-apis-data-types)。 | 建議您在 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 叢集做為其來源。 + OpenSearch Ingestion 與 Amazon DocumentDB 整合特別支援以 Amazon DocumentDB 執行個體為基礎的叢集。它不支援 Amazon DocumentDB 彈性叢集。 + OpenSearch Ingestion 整合僅支援 AWS Secrets Manager 做為 Amazon DocumentDB 叢集的身分驗證機制。 + 您無法更新現有的管道組態，以從不同的資料庫或集合擷取資料。您必須改為建立新的管道。 ## 建議 CloudWatch 警示 為了獲得最佳效能，我們建議您在建立 OpenSearch Ingestion 管道以存取 Amazon DocumentDB 叢集做為來源時，使用下列 CloudWatch 警示。 | CloudWatch 警示 | Description | | --- | --- | | {{}}.doucmentdb.credentialsChanged | 此指標表示 AWS 秘密輪換的頻率。 | | {{}}.doucmentdb.executorRefreshErrors | 此指標表示重新整理 AWS 秘密失敗。 | | {{}}.doucmentdb.exportRecordsTotal | 此指標表示從 Amazon DocumentDB 匯出的記錄數。 | | {{}}.doucmentdb.exportRecordsProcessed | 此指標表示 OpenSearch Ingestion 管道處理的記錄數目。 | | {{}}.doucmentdb.exportRecordProcessingErrors | 此指標表示從 Amazon DocumentDB 叢集讀取資料時OpenSearch 擷取管道中的處理錯誤數目。 | | {{}}.doucmentdb.exportRecordsSuccessTotal | 此指標表示成功處理的匯出記錄總數。 | | {{}}.doucmentdb.exportRecordsFailedTotal | 此指標表示無法處理的匯出記錄總數。 | | {{}}.doucmentdb.bytesReceived | 此指標表示 OpenSearch Ingestion 管道收到的位元組總數。 | | {{}}.doucmentdb.bytesProcessed | 此指標表示 OpenSearch Ingestion 管道處理的位元組總數。 | | {{}}.doucmentdb.exportPartitionQueryTotal | 此指標表示匯出分割區總計。 | | {{}}.doucmentdb.streamRecordsSuccessTotal | 此指標表示從串流成功處理的記錄數量。 | | {{}}.doucmentdb.streamRecordsFailedTotal | 此指標表示無法從串流處理的記錄總數。 |