本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 建立 Amazon OpenSearch Ingestion 管道 *管道*是 Amazon OpenSearch Ingestion 用來將資料從其*來源* （資料來源） 移動到其*目的地* （資料來源） 的機制。在 OpenSearch Ingestion 中，目的地一律是單一 Amazon OpenSearch Service 網域，而資料來源可能是 Amazon S3、Fluent Bit 或 OpenTelemetry Collector 等用戶端。 如需詳細資訊，請參閱 OpenSearch 文件中的[管道](https://opensearch.org/docs/latest/clients/data-prepper/pipelines/)。 **Topics** + [先決條件和必要的 IAM 角色](#manage-pipeline-prerequisites) + [所需的 IAM 許可](#create-pipeline-permissions) + [指定管道版本](#pipeline-version) + [指定擷取路徑](#pipeline-path) + [建立管道](#create-pipeline) + [追蹤管道建立的狀態](#get-pipeline-progress) + [使用藍圖](pipeline-blueprint.md) ## 先決條件和必要的 IAM 角色 若要建立 OpenSearch Ingestion 管道，您必須擁有下列資源： + OpenSearch Ingestion 擔任的 IAM 角色稱為*管道角色*，以便寫入目的地。您可以事先建立此角色，也可以讓 OpenSearch Ingestion 在您建立管道時自動建立角色。 + 做為接收器的 OpenSearch Service 網域或 OpenSearch Serverless 集合。如果您要寫入網域，它必須執行 OpenSearch 1.0 或更新版本，或 Elasticsearch 7.4 或更新版本。目的地必須具有存取政策，將適當的許可授予您的 IAM 管道角色。 如需建立這些資源的說明，請參閱下列主題： + [授予 Amazon OpenSearch Ingestion 管道對網域的存取權](pipeline-domain-access.md) + [授予 Amazon OpenSearch Ingestion 管道對集合的存取權](pipeline-collection-access.md) **注意** 如果您要寫入使用精細存取控制的網域，則需要完成額外的步驟。請參閱 [映射管道角色 （僅適用於使用精細存取控制的網域）](pipeline-domain-access.md#pipeline-access-domain-fgac)。 ## 所需的 IAM 許可 OpenSearch Ingestion 使用下列 IAM 許可來建立管道： + `osis:CreatePipeline` – 建立管道。 + `osis:ValidatePipeline` – 檢查管道組態是否有效。 + `iam:CreateRole` 和 `iam:AttachPolicy` – 讓 OpenSearch Ingestion 自動為您建立管道角色。 + `iam:PassRole` – 將管道角色傳遞至 OpenSearch Ingestion，以便將資料寫入網域。此許可必須位於[管道角色資源](pipeline-domain-access.md#pipeline-access-configure)上，或者`*`如果您計劃在每個管道中使用不同的角色。 例如，下列政策會授予建立管道的許可： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Resource":"*", "Action":[ "osis:CreatePipeline", "osis:ListPipelineBlueprints", "osis:ValidatePipeline" ] }, { "Resource":[ "arn:aws:iam::{{111122223333}}:role/{{pipeline-role}}" ], "Effect":"Allow", "Action":[ "iam:CreateRole", "iam:AttachRolePolicy", "iam:PassRole" ] } ] } ``` ------ OpenSearch Ingestion 也包含名為 的許可`osis:Ingest`，這是使用 [Signature 第 4 版](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)將已簽署的請求傳送至管道的必要許可。如需詳細資訊，請參閱[建立擷取角色](configure-client.md#configure-client-auth)。 **注意** 此外，第一個在帳戶中建立管道的使用者必須具有 `iam:CreateServiceLinkedRole`動作的許可。如需詳細資訊，請參閱[管道角色資源](pipeline-security.md#pipeline-vpc-slr)。 如需每個許可的詳細資訊，請參閱*《服務授權參考*》中的 [ OpenSearch Ingestion 的動作、資源和條件索引鍵](https://docs.aws.amazon.com/service-authorization/latest/reference/list_opensearchingestionservice.html)。 ## 指定管道版本 當您使用組態編輯器建立管道時，您必須指定管道將執行的主要 [Data Prepper 版本](https://github.com/opensearch-project/data-prepper/releases)。若要指定 版本，請在管道組態中包含 `version`選項： ``` {{version: "2"}} log-pipeline: source: ... ``` 當您選擇**建立**時，OpenSearch Ingestion 會決定您指定之主要版本的最新可用*次要*版本，並使用該版本佈建管道。例如，如果您指定 `version: "2"`，且 Data Prepper 的最新支援版本為 2.1.1，則 OpenSearch Ingestion 會將您的管道佈建為 2.1.1 版。我們不會公開顯示管道正在執行的次要版本。 若要在 Data Prepper 的新主要版本可用時升級管道，請編輯管道組態並指定新版本。您無法將管道降級至舊版。 **注意** OpenSearch Ingestion 不會立即支援新版本的 Data Prepper。當新版本可公開使用，以及在 OpenSearch Ingestion 中支援時，會有一些延遲。此外，OpenSearch Ingestion 可能完全不支援某些主要或次要版本。如需完整清單，請參閱[支援的資料準備版本](ingestion.md#ingestion-supported-versions)。 每當您變更啟動藍/綠部署的管道時，OpenSearch Ingestion 都可以將其升級到目前為管道設定的主要版本的最新次要版本。如需詳細資訊，請參閱[管道更新的藍/綠部署](update-pipeline.md#pipeline-bg)。除非您在管道組態中明確更新 `version`選項，否則 OpenSearch Ingestion 無法變更管道的主要版本。 ## 指定擷取路徑 對於提取型來源，例如 [OTel 追蹤](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/otel-trace/)和 [OTel 指標](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sources/otel-metrics-source/)，OpenSearch Ingestion 需要來源組態中的其他`path`選項。路徑是字串，例如 `/log/ingest`，代表擷取的 URI 路徑。此路徑會定義您用來將資料傳送至管道的 URI。 例如，假設您為具有 HTTP 來源的管道指定下列路徑： ![路徑欄位包含範例值 /my/test_path。](http://docs.aws.amazon.com/zh_tw/opensearch-service/latest/developerguide/images/ingestion-path.png) 當您將[資料擷取](configure-client.md)至管道時，您必須在用戶端組態中指定下列端點：`https://{{pipeline-name-abc123}}.{{us-west-2}}.osis.amazonaws.com/{{my}}/{{test_path}}`。 路徑必須以斜線 (/) 開頭，可包含特殊字元 '-'、'\_'、'.' 和 '/'，以及`${pipelineName}`預留位置。如果您使用 `${pipelineName}`（例如 `/${pipelineName}/test_path`)，OpenSearch Ingestion 會將變數取代為相關聯的子管道名稱。 ## 建立管道 本節說明如何使用 OpenSearch Service 主控台和 建立 OpenSearch Ingestion 管道 AWS CLI。 ### 主控台 若要建立管道，請登入位於 https：//[https://console.aws.amazon.com/aos/osis/home](https://console.aws.amazon.com/aos/osis/home#osis/ingestion-pipelines) 的 Amazon OpenSearch Service 主控台，然後選擇**建立管道**。 選擇空白管道，或選擇組態藍圖。藍圖包含適用於各種常見使用案例的預先設定管道。如需詳細資訊，請參閱[使用藍圖](pipeline-blueprint.md)。 選擇**選取藍圖**。 #### 設定來源 1. 如果您是從空白管道開始，請從下拉式選單中選取來源。可用的來源可能包括其他 AWS 服務、OpenTelemetry 或 HTTP。如需詳細資訊，請參閱[將 Amazon OpenSearch Ingestion 管道與其他 服務和應用程式整合](configure-client.md)。 1. 根據您選擇的來源，為來源設定其他設定。例如，若要使用 Amazon S3 做為來源，您必須從管道指定 Amazon SQS 佇列的 URL 來接收訊息。如需支援的來源外掛程式清單及其文件的連結，請參閱 [Amazon OpenSearch Ingestion 管道支援的外掛程式和選項](pipeline-config-reference.md)。 1. 對於某些來源，您必須指定**來源網路選項**。選擇 **VPC 存取**或**公有存取**。如果選擇 **Public access (公開存取)**，請跳到下一步驟。如果您選擇 **VPC 存取**，請設定下列設定： [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/opensearch-service/latest/developerguide/creating-pipeline.html) 如需詳細資訊，請參閱[設定 Amazon OpenSearch Ingestion 管道的 VPC 存取](pipeline-security.md)。 1. 選擇**下一步**。 #### 設定處理器 將一或多個處理器新增至您的管道。處理器是子管道中的元件，可讓您在將記錄發佈至網域或集合目的地之前篩選、轉換和豐富事件。如需支援的處理器清單及其文件的連結，請參閱 [Amazon OpenSearch Ingestion 管道支援的外掛程式和選項](pipeline-config-reference.md)。 您可以選擇**動作**並新增下列項目： + **條件式路由** – 根據特定條件，將事件路由到不同的目的地。如需詳細資訊，請參閱[條件式路由](https://opensearch.org/docs/latest/data-prepper/pipelines/pipelines/#conditional-routing)。 + **子管道** – 每個子管道是單一來源、零或多個處理器和單一接收器的組合。只有一個子管道可以有外部來源。所有其他 必須具有整體管道組態中其他子管道的來源。單一管道組態可以包含 1-10 個子管道。 選擇**下一步**。 #### 設定接收器 選取管道發佈記錄的目的地。每個子管道必須至少包含一個接收器。您最多可以將 10 個接收器新增至管道。 對於 OpenSearch 接收器，請設定下列欄位： | 設定 | 說明 | | --- | --- | | 網路政策名稱（僅限無伺服器接收器） | 如果您選取 OpenSearch Serverless 集合，請輸入**網路政策名稱**。OpenSearch Ingestion 會在政策不存在時建立政策，或使用規則更新政策，以授予連線至管道和集合的 VPC 端點存取權。如需詳細資訊，請參閱[授予 Amazon OpenSearch Ingestion 管道對集合的存取權](pipeline-collection-access.md)。 | | 索引名稱 | 管道傳送資料的索引名稱。如果尚未存在，OpenSearch Ingestion 會建立此索引。 | | 索引映射選項 | 選擇管道如何將文件及其欄位存放和索引到 OpenSearch 接收器。如果您選取**動態映射**，OpenSearch 會在您為文件編製索引時自動新增欄位。如果您選取**自訂映射**，請輸入索引映射範本。如需詳細資訊，請參閱[索引範本](https://opensearch.org/docs/latest/im-plugin/index-templates/)。 | | 啟用 DLQ | 設定管道的 Amazon S3 無效字母佇列 (DLQ)。如需詳細資訊，請參閱[無效信件佇列](osis-features-overview.md#osis-features-dlq)。 | | 其他設定 | 設定 OpenSearch 接收器的進階選項。如需詳細資訊，請參閱 Data Prepper 文件中的[組態選項](https://opensearch.org/docs/latest/data-prepper/pipelines/configuration/sinks/opensearch/#configuration-options)。 | 若要新增 Amazon S3 接收器，請選擇**新增接收器**和 **Amazon S3**。如需詳細資訊，請參閱[Amazon S3 做為目的地](configure-client-s3.md#s3-destination)。 選擇**下一步**。 #### 設定管道 設定下列其他管道設定： | 設定 | 說明 | | --- | --- | | 管道名稱 | 管道的唯一名稱。 | | 持久性緩衝區 | 持久性緩衝會將您的資料儲存在跨多個可用區域的磁碟型緩衝區中。如需詳細資訊，請參閱[持久性緩衝](osis-features-overview.md#persistent-buffering)。
如果您啟用持久性緩衝，請選取 AWS Key Management Service 金鑰來加密緩衝資料。 | | 管道容量 | 最小和最大管道容量，以擷取 OpenSearch 運算單位 (OCUs。如需詳細資訊，請參閱[在 Amazon OpenSearch Ingestion 中擴展管道](ingestion-scaling.md)。 | | 管道角色 | IAM 角色，提供管道寫入目的地並從提取型來源讀取所需的許可。您可以自行建立角色，或讓 OpenSearch Ingestion 根據您選擇的使用案例為您建立角色。
如需詳細資訊，請參閱[在 Amazon OpenSearch 擷取中設定角色和使用者](pipeline-security-overview.md)。 | | Tags (標籤) | 將一或多個標籤新增至您的管道。如需詳細資訊，請參閱[標記 Amazon OpenSearch 擷取管道](tag-pipeline.md)。 | | 日誌發佈選項 | 啟用管道日誌發佈至 Amazon CloudWatch Logs。我們建議您啟用日誌發佈，以便更輕鬆地對管道問題進行故障診斷。如需詳細資訊，請參閱[監控管道日誌](monitoring-pipeline-logs.md)。 | 選擇**下一步**，然後檢閱管道組態，然後選擇**建立管道**。 OpenSearch Ingestion 會執行非同步程序來建置管道。一旦管道狀態為 `Active`，您就可以開始擷取資料。 ### AWS CLI [create-pipeline](https://docs.aws.amazon.com/cli/latest/reference/osis/create-pipeline.html) 命令接受管道組態作為字串或在 .yaml 或 .json 檔案中。如果您提供組態做為字串，則必須使用 逸出每行新行`\n`。例如 `"log-pipeline:\n source:\n http:\n processor:\n - grok:\n ...` 下列範例命令會使用下列組態建立管道： + 最少 4 個擷取 OCUs，最多 10 個擷取 OCUs + 在虛擬私有雲端 (VPC) 中佈建 + 已啟用日誌發佈 ``` aws osis create-pipeline \ --pipeline-name {{my-pipeline}} \ --min-units 4 \ --max-units 10 \ --log-publishing-options IsLoggingEnabled=true,CloudWatchLogDestination={LogGroup="{{MyLogGroup}}"} \ --vpc-options SecurityGroupIds={{{sg-12345678}},{{sg-9012345}}},SubnetIds={{subnet-1212234567834asdf}} \ --pipeline-configuration-body "file://{{pipeline-config.yaml}}" \ --pipeline-role-arn arn:aws:iam::{{1234456789012}}:role/{{pipeline-role}} ``` OpenSearch Ingestion 會執行非同步程序來建置管道。一旦管道狀態為 `Active`，您就可以開始擷取資料。若要檢查管道的狀態，請使用 [GetPipeline](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_osis_GetPipeline.html) 命令。 ### OpenSearch 擷取 API 若要使用 OpenSearch Ingestion API 建立 OpenSearch Ingestion 管道，請呼叫 [CreatePipeline](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_osis_CreatePipeline.html) 操作。 成功建立管道後，您可以設定用戶端，並開始將資料擷取到您的 OpenSearch Service 網域。如需詳細資訊，請參閱[將 Amazon OpenSearch Ingestion 管道與其他 服務和應用程式整合](configure-client.md)。 ## 追蹤管道建立的狀態 您可以追蹤管道的狀態，因為 OpenSearch Ingestion 會佈建管道，並準備擷取資料。 ### 主控台 最初建立管道之後，它會經歷多個階段，因為 OpenSearch Ingestion 會準備它來擷取資料。若要檢視管道建立的各個階段，請選擇管道名稱以查看其**管道設定**頁面。在**狀態**下，選擇**檢視詳細資訊**。 管道在可用於擷取資料之前，會經歷下列階段： + **驗證** – 驗證管道組態。當此階段完成時，所有驗證都已成功。 + **建立環境** – 準備和佈建資源。當此階段完成時，就會建立新的管道環境。 + **部署管道** – 部署管道。當此階段完成時，管道已成功部署。 + **檢查管道運作**狀態 – 檢查管道的運作狀態。當此階段完成時，所有運作狀態檢查都已通過。 + **啟用流量** – 啟用管道以擷取資料。當此階段完成時，您可以開始將資料擷取至管道。 ### CLI 使用 [get-pipeline-change-progress](https://docs.aws.amazon.com/cli/latest/reference/osis/get-pipeline-change-progress.html) 命令來檢查管道的狀態。下列 AWS CLI 請求會檢查名為 之管道的狀態`my-pipeline`： ``` aws osis get-pipeline-change-progress \ --pipeline-name {{my-pipeline}} ``` **回應：** ``` { "ChangeProgressStatuses": { "ChangeProgressStages": [ { "Description": "Validating pipeline configuration", "LastUpdated": 1.671055851E9, "Name": "VALIDATION", "Status": "PENDING" } ], "StartTime": 1.671055851E9, "Status": "PROCESSING", "TotalNumberOfStages": 5 } } ``` ### OpenSearch 擷取 API 若要使用 OpenSearch Ingestion API 追蹤管道建立的狀態，請呼叫 [GetPipelineChangeProgress](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_osis_GetPipelineChangeProgress.html) 操作。