本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 建立 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 來源的管道指定下列路徑：
![\[Input field for specifying the path for ingestion, with an example path entered.\]](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`。
路徑必須以斜線 (/) 開頭，可包含特殊字元 '-'、'\$1'、'.' 和 '/'，以及`${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 接收器，請設定下列欄位：
| 設定 | Description |
| --- | --- |
| 網路政策名稱（僅限無伺服器接收器） | 如果您選取 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)。
選擇**下一步**。
#### 設定管道
設定下列其他管道設定：
| 設定 | Description |
| --- | --- |
| 管道名稱 | 管道的唯一名稱。 |
| 持久性緩衝區 | 持久性緩衝會將您的資料儲存在跨多個可用區域的磁碟型緩衝區中。如需詳細資訊，請參閱[持久性緩衝](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) 操作。
# 使用藍圖
與其從頭開始建立管道定義，您可以使用*組態藍圖*，這些藍圖是預先設定的範本，用於常見的擷取案例，例如追蹤分析或 Apache 日誌。組態藍圖可協助您輕鬆佈建管道，而無需從頭開始撰寫組態。
## 主控台
**使用管道藍圖**
1. 登入 OpenSearch Ingestion 主控台，網址為 https：//[https://console.aws.amazon.com/aos/osis/home](https://console.aws.amazon.com/aos/osis/home#osis/ingestion-pipelines)。您將進入管道頁面。
1. 選擇 **Create pipeline (建立管道)**。
1. 從使用案例清單中選擇藍圖，然後選擇**選取藍圖**。管道組態會為您選取的使用案例填入子管道。
管道藍圖無效。您需要根據選取的來源指定其他設定。
## CLI
若要使用 取得所有可用藍圖的清單 AWS CLI，請傳送 [list-pipeline-blueprints](https://docs.aws.amazon.com/cli/latest/reference/osis/list-pipeline-blueprints.html) 請求。
```
aws osis list-pipeline-blueprints
```
請求會傳回所有可用藍圖的清單。
若要取得特定藍圖的詳細資訊，請使用 [get-pipeline-blueprint](https://docs.aws.amazon.com/cli/latest/reference/osis/get-pipeline-blueprint.html) 命令：
```
aws osis get-pipeline-blueprint --blueprint-name AWS-ApacheLogPipeline
```
此請求會傳回 Apache 日誌管道藍圖的內容：
```
{
"Blueprint":{
"PipelineConfigurationBody":"###\n # Limitations: https://docs.aws.amazon.com/opensearch-service/latest/ingestion/ingestion.html#ingestion-limitations\n###\n###\n # apache-log-pipeline:\n # This pipeline receives logs via http (e.g. FluentBit), extracts important values from the logs by matching\n # the value in the 'log' key against the grok common Apache log pattern. The grokked logs are then sent\n # to OpenSearch to an index named 'logs'\n###\n\nversion: \"2\"\napache-log-pipeline:\n source:\n http:\n # Provide the path for ingestion. ${pipelineName} will be replaced with pipeline name configured for this pipeline.\n # In this case it would be \"/apache-log-pipeline/logs\". This will be the FluentBit output URI value.\n path: \"/${pipelineName}/logs\"\n processor:\n - grok:\n match:\n log: [ \"%{COMMONAPACHELOG_DATATYPED}\" ]\n sink:\n - opensearch:\n # Provide an AWS OpenSearch Service domain endpoint\n # hosts: [ \"https://search-mydomain-1a2a3a4a5a6a7a8a9a0a9a8a7a.us-east-1.es.amazonaws.com\" ]\n aws:\n # Provide the region of the domain.\n # region: \"us-east-1\"\n # Enable the 'serverless' flag if the sink is an Amazon OpenSearch Serverless collection\n # serverless: true\n index: \"logs\"\n # Enable the S3 DLQ to capture any failed requests in an S3 bucket\n # dlq:\n # s3:\n # Provide an S3 bucket\n # bucket: \"your-dlq-bucket-name\"\n # Provide a key path prefix for the failed requests\n # key_path_prefix: \"${pipelineName}/logs/dlq\"\n # Provide the region of the bucket.\n # region: \"us-east-1\"\n # Provide a Role ARN with access to the bucket. This role should have a trust relationship with osis-pipelines.amazonaws.com\n"
"BlueprintName":"AWS-ApacheLogPipeline"
}
}
```
## OpenSearch 擷取 API
若要使用 OpenSearch Ingestion API 取得管道藍圖的相關資訊，請使用 [ListPipelineBlueprints](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_osis_ListPipelineBlueprints.html) 和 [GetPipelineBlueprint](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_osis_GetPipelineBlueprint.html) 操作。