本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在 Amazon OpenSearch Service 中管理自訂外掛程式
使用 OpenSearch Service 的自訂外掛程式，您可以在語言分析、自訂篩選、排名等領域擴展 OpenSearch 功能，讓您可以打造個人化的搜尋體驗。OpenSearch 的自訂外掛程式可以透過擴展 `org.opensearch.plugins.Plugin`類別，然後將其封裝在 `.zip` 檔案中來開發。
Amazon OpenSearch Service 目前支援下列外掛程式延伸：
+ **AnalysisPlugin** – 透過新增自訂分析器、角色字符化器或用於文字處理的篩選條件來擴展分析功能。
+ **SearchPlugin** – 使用自訂查詢類型、相似性演算法、建議選項和彙總增強搜尋功能。
+ **MapperPlugin** – 可讓您在 OpenSearch 中建立自訂欄位類型及其映射組態，讓您定義應如何存放和編製索引不同類型的資料。
+ **ScriptPlugin** – 可讓您將自訂指令碼功能新增至 OpenSearch，例如，在搜尋或編製索引期間進行評分、排序和欄位值轉換等操作的自訂指令碼。
您可以使用 OpenSearch Service 主控台或現有 API 命令來上傳自訂套件，並將外掛程式與 Amazon OpenSearch Service 叢集建立關聯。您也可以使用 [DescribePackages](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_DescribePackages.html) 命令來描述您帳戶中的所有套件，以及檢視 OpenSearch 版本和錯誤詳細資訊等詳細資訊。OpenSearch Service 會驗證外掛程式套件的版本相容性、安全性漏洞和允許的外掛程式操作。如需自訂套件的詳細資訊，請參閱 [在 Amazon OpenSearch Service 中匯入和管理套件](custom-packages.md)。
**OpenSearch 版本和 AWS 區域 支援**
執行 OpenSearch 2.15 版的 OpenSearch Service 網域支援自訂外掛程式，如下所示 AWS 區域：
+ 美國東部 (俄亥俄) (us-east-2)
+ 美國東部 (維吉尼亞北部) (us-east-1)
+ 美國西部 (奧勒岡) (us-west-2)
+ 亞太區域 (孟買) (ap-south-1)
+ 亞太區域 (首爾) (ap-northeast-2)
+ 亞太地區 (新加坡) (ap-southeast-1)
+ 亞太地區 (雪梨) (ap-southeast-2)
+ 亞太地區 (東京) (ap-northeast-1)
+ 加拿大 (中部) (ca-central-1)
+ 歐洲 (法蘭克福) (eu-central-1)
+ 歐洲 (愛爾蘭) (eu-west-1)
+ 歐洲 (倫敦) (eu-west-2)
+ 歐洲 (巴黎) (eu-west-3)
+ 南美洲 (聖保羅) (sa-east-1)
**注意**
自訂外掛程式包含使用者開發的程式碼。任何由使用者開發的程式碼引起的問題，包括 SLA 違規，都不符合 SLA 點數的資格。如需詳細資訊，請參閱 [Amazon OpenSearch Service - 服務水準協議](https://aws.amazon.com/opensearch-service/sla/)。
**Topics**
+ [外掛程式配額](#plugin-limits)
+ [先決條件](#custom-plugin-prerequisites)
+ [疑難排解](#custom-plugin-troubleshooting)
+ [使用主控台安裝自訂外掛程式](#custom-plugin-install-console)
+ [使用 管理自訂外掛程式 AWS CLI](#managing-custom-plugins-cli)
+ [Amazon OpenSearch Service 自訂套件 AWS KMS 整合](custom-package-kms-integration.md)
## 外掛程式配額
+ 每個區域每個帳戶最多可以建立 25 個自訂外掛程式。
+ 外掛程式的未壓縮大小上限為 1 GB。
+ 可以與單一網域相關聯的外掛程式數目上限為 20。此配額適用於所有合併的外掛程式類型：選用、第三方和自訂。
+ 執行 OpenSearch 2.15 版或更新版本的網域支援自訂外掛程式。
+ 外掛程式`descriptor.properties`的檔案必須支援類似 2.15.0 或任何 2.x.x 版本的引擎版本，其中修補程式版本設定為零。
## 先決條件
安裝自訂外掛程式並將其與網域建立關聯之前，請確定您符合下列要求：
+ `descriptor.properties` 檔案中外掛程式支援的引擎版本應類似於 `2.15.0`或 `2.x.0`。也就是說，修補程式版本必須為零。
+ 您的網域必須啟用下列功能：
+ [節點對節點加密](ntn.md)
+ [靜態加密](encryption-at-rest.md)
+ [`EnforceHTTPS` 設定為 'true'](createupdatedomains.md)
另請參閱《 *AWS Config 開發人員指南*》中的 [opensearch-https-required](https://docs.aws.amazon.com/config/latest/developerguide/opensearch-https-required.html)。
+ 用戶端必須支援 **Policy-Min-TLS-1-2-PFS-2023-10**。您可以使用下列命令指定此支援。將*預留位置值*取代為您自己的資訊：
```
aws opensearch update-domain-config \
--domain-name domain-name \
--domain-endpoint-options '{"TLSSecurityPolicy":"Policy-Min-TLS-1-2-PFS-2023-10" }'
```
如需詳細資訊，請參閱《*Amazon OpenSearch Service API 參考*》中的 [DomainEndpointOptions](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_DomainEndpointOptions.html)。
## 疑難排解
如果系統傳回錯誤 `PluginValidationFailureReason : The provided plugin could not be loaded`，請參閱 [由於版本相容性，自訂外掛程式安裝失敗](handling-errors.md#troubleshooting-custom-plugins) 以取得故障診斷資訊。
## 使用主控台安裝自訂外掛程式
若要將第三方外掛程式與網域建立關聯，請先將外掛程式授權和組態匯入為套件。
**安裝自訂外掛程式**
1. 登入 Amazon OpenSearch Service 主控台，網址為 https：//[https://console.aws.amazon.com/aos/home](https://console.aws.amazon.com/aos/home)。
1. 在左側導覽窗格中，選擇**套件**。
1. 選擇 **Import package** (匯入套件)。
1. 在**名稱**中，輸入唯一且易於識別的外掛程式名稱。
1. （選用） 針對**描述**，提供套件或其用途的任何實用詳細資訊。
1. 針對**套件類型**，選擇**外掛程式**。
1. 針對**套件來源**，輸入路徑或瀏覽至 Amazon S3 中的外掛程式 ZIP 檔案。
1. 針對 **OpenSearch 引擎版本**，選擇外掛程式支援的 OpenSearch 版本。
1. 針對**套件加密**，選擇是否要自訂套件的加密金鑰。根據預設，OpenSearch Service 會使用 加密外掛程式套件 AWS 擁有的金鑰。您可以改為使用客戶受管金鑰。
1. 選擇**匯入**。
匯入外掛程式套件之後，請將其與網域建立關聯。如需說明，請參閱[匯入套件並將其與網域建立關聯](custom-packages.md#associate-console)。
## 使用 管理自訂外掛程式 AWS CLI
您可以使用 AWS CLI 來管理許多自訂外掛程式任務。
**Topics**
+ [使用 安裝自訂外掛程式 AWS CLI](#custom-plugin-install-cli)
+ [使用 更新自訂外掛程式 AWS CLI](#custom-plugin-update-cli)
+ [建立或更新具有 AWS KMS 金鑰安全性的自訂外掛程式](#custom-plugin-kms-key-security-cli)
+ [使用 將具有自訂外掛程式的 OpenSearch Service 網域升級至較新版本的 OpenSearch AWS CLI](#custom-plugin-domain-upgrade-cli)
+ [解除安裝和檢視自訂外掛程式的取消關聯狀態](#custom-plugin-uninstall-cli)
### 使用 安裝自訂外掛程式 AWS CLI
**開始之前**
您必須先將自訂外掛程式上傳至 Amazon Simple Storage Service (Amazon S3) 儲存貯體，才能將自訂外掛程式與網域建立關聯。儲存貯體必須位於您打算使用外掛程式的相同 AWS 區域 位置。如需有關將物件新增至 S3 儲存貯體的資訊，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[上傳物件](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html)。
如果您的外掛程式包含敏感資訊，請在上傳時以 S3-managed金鑰指定伺服器端加密。上傳檔案後，請記下其 S3 路徑。路徑格式為 `s3://amzn-s3-demo-bucket/file-path/file-name`。
**注意**
建立外掛程式時，您可以指定 AWS Key Management Service (AWS KMS) 金鑰，選擇性地保護自訂外掛程式。如需相關資訊，請參閱[建立或更新具有 AWS KMS 金鑰安全性的自訂外掛程式](#custom-plugin-kms-key-security-cli)。
**使用 安裝自訂外掛程式 AWS CLI**
1. 執行下列 [create-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/create-package.html) 命令來為您的自訂外掛程式建立新的套件，確保符合下列要求：
+ 儲存貯體和金鑰位置必須指向您執行命令之帳戶中 S3 儲存貯體中的外掛程式`.zip`檔案。
+ S3 儲存貯體必須位於建立套件的相同區域中。
+ `ZIP-PLUGIN` 套件僅支援 `.zip` 檔案。
+ `.zip` 檔案的內容必須遵循外掛程式預期的目錄結構。
+ 的值格式`--engine-version`必須為 `OpenSearch_{MAJOR}.{MINOR}`。例如：**OpenSearch\$12.17**。
將*預留位置值*取代為您自己的資訊：
```
aws opensearch create-package \
--package-name package-name \
--region region \
--package-type ZIP-PLUGIN \
--package-source S3BucketName=amzn-s3-demo-bucket,S3Key=s3-key \
--engine-version opensearch-version
```
1. （選用） 使用 [describe-packages](https://docs.aws.amazon.com/cli/latest/reference/es/describe-packages.html) 命令檢視`create-package`操作的狀態，包括任何驗證和安全性漏洞問題清單。將*預留位置值*取代為您自己的資訊：
```
aws opensearch describe-packages \
--region region \
--filters '[{"Name": "PackageType","Value": ["ZIP-PLUGIN"]}, {"Name": "PackageName","Value": ["package-name"]}]'
```
此命令會傳回與以下內容相似的資訊：
```
{
"PackageDetailsList": [{
"PackageID": "pkg-identifier",
"PackageName": "package-name",
"PackageType": "ZIP-PLUGIN",
"PackageStatus": "VALIDATION_FAILED",
"CreatedAt": "2024-11-11T13:07:18.297000-08:00",
"LastUpdatedAt": "2024-11-11T13:10:13.843000-08:00",
"ErrorDetails": {
"ErrorType": "",
"ErrorMessage": "PluginValidationFailureReason : Dependency Scan reported 3 vulnerabilities for the plugin: CVE-2022-23307, CVE-2019-17571, CVE-2022-23305"
},
"EngineVersion": "OpenSearch_2.15",
"AllowListedUserList": [],
"PackageOwner": "OWNER-XXXX"
}]
}
```
**注意**
在`create-package`操作期間，Amazon OpenSearch Service 會檢查版本相容性、支援的外掛程式延伸模組和安全性漏洞`ZIP-PLUGIN`的值。使用 [Amazon Inspector](https://aws.amazon.com/inspector/getting-started/) 服務掃描安全漏洞。這些檢查的結果會顯示在 API 回應的 `ErrorDetails` 欄位中。
1. 使用 [associate-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-package.html) 命令，使用上一個步驟中建立之套件的套件 ID，將外掛程式與您選擇的 OpenSearch Service 網域建立關聯。
**提示**
如果您有多個外掛程式，您可以改為使用 [associate-packages](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-packages.html) 命令，在單一操作中將多個套件與網域建立關聯。
將*預留位置值*取代為您自己的資訊：
```
aws opensearch associate-package \
--domain-name domain-name \
--region region \
--package-id package-id
```
**注意**
外掛程式是使用[藍/綠部署程序](managedomains-configuration-changes.md)進行安裝和解除安裝。
1. （選用） 使用 [list-packages-for-domain](https://docs.aws.amazon.com/cli/latest/reference/opensearch/list-packages-for-domain.html) 命令來檢視關聯的狀態。關聯狀態會隨著工作流程從 進展`ASSOCIATING`至 而變更`ACTIVE`。外掛程式安裝完成且外掛程式已就緒可供使用後，關聯狀態會變更為 ACTIVE。
使用您的資訊取代*預留位置的值*。
```
aws opensearch list-packages-for-domain \
--region region \
--domain-name domain-name
```
### 使用 更新自訂外掛程式 AWS CLI
使用 [update-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/update-package.html) 命令來變更外掛程式。
**注意**
當您指定 AWS Key Management Service (AWS KMS) 金鑰更新外掛程式時，您可以選擇保護自訂外掛程式。如需相關資訊，請參閱[建立或更新具有 AWS KMS 金鑰安全性的自訂外掛程式](#custom-plugin-kms-key-security-cli)。
**使用 更新自訂外掛程式 AWS CLI**
+ 執行下列命令。使用您的資訊取代*預留位置的值*。
```
aws opensearch update-package \
--region region \
--package-id package-id \
--package-source S3BucketName=amzn-s3-demo-bucket,S3Key=s3-key \
--package-description description
```
更新套件後，您可以使用 [associate-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-package.html) 或 [associate-packages](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-packages.html) 命令，將套件更新套用至網域。
**注意**
您可以使用 稽核、建立、更新、關聯和取消關聯外掛程式上的操作 AWS CloudTrail。如需詳細資訊，請參閱[使用 監控 Amazon OpenSearch Service API 呼叫 AWS CloudTrail](managedomains-cloudtrailauditing.md)。
### 建立或更新具有 AWS KMS 金鑰安全性的自訂外掛程式
您可以在建立或更新外掛程式時，透過指定 AWS KMS 金鑰來保護自訂外掛程式。若要達成此目的，請將 `PackageEncryptionOptions` 設定為 ，`true`並指定金鑰的 Amazon Resource Name (ARN)，如下列範例所示。
**範例：建立具有 AWS KMS 金鑰安全性的自訂外掛程式**
```
aws opensearch create-package \
--region us-east-2 --package-name my-custom-package \
--package-type ZIP-PLUGIN \
--package-source S3BucketName=amzn-s3-demo-bucket,S3Key=my-s3-key
--engine-version OpenSearch_2.15
"PackageConfigOptions": {
...
}
"PackageEncryptionOptions": {
"Enabled": true,
"KmsKeyId":"arn:aws:kms:us-east-2:111222333444:key/2ba228d5-1d09-456c-ash9-daf42EXAMPLE"
}
```
**範例：使用 AWS KMS 金鑰安全性更新自訂外掛程式**
```
aws opensearch update-package \
--region us-east-2 --package-name my-custom-package \
--package-type ZIP-PLUGIN \
--package-source S3BucketName=amzn-s3-demo-bucket,S3Key=my-s3-key
--engine-version OpenSearch_2.15
"PackageConfigOptions": {
...
}
"PackageEncryptionOptions": {
"Enabled": true,
"KmsKeyId":"arn:aws:kms:us-east-2:111222333444:key/2ba228d5-1d09-456c-ash9-daf42EXAMPLE"
}
```
**重要**
如果您指定的 AWS KMS 金鑰已停用或刪除，可能會讓相關聯的叢集無法運作。
如需與自訂套件 AWS KMS 整合的詳細資訊，請參閱[Amazon OpenSearch Service 自訂套件 AWS KMS 整合](custom-package-kms-integration.md)。
### 使用 將具有自訂外掛程式的 OpenSearch Service 網域升級至較新版本的 OpenSearch AWS CLI
當您需要將使用自訂外掛程式的 OpenSearch Service 網域升級至較新版本的 OpenSearch 時，請完成下列程序。
**使用 將具有自訂外掛程式的 OpenSearch Service 網域升級至較新版本的 OpenSearch AWS CLI**
1. 使用 create-package 命令為您的外掛程式建立新的套件，以指定新的 OpenSearch 版本。
確保所有引擎版本的外掛程式的套件名稱相同。變更套件名稱會導致網域升級程序在藍/綠部署期間失敗。
1. 遵循中的步驟，將您的網域升級至更高版本[升級 Amazon OpenSearch Service 網域](version-migration.md)。
在此過程中，Amazon OpenSearch Service 會取消與舊版外掛程式套件的關聯，並使用藍/綠部署安裝新版本。
### 解除安裝和檢視自訂外掛程式的取消關聯狀態
若要從任何網域解除安裝外掛程式，您可以使用 [dissociate-package](https://docs.aws.amazon.com/cli/latest/reference/es/dissociate-package.html) 命令。執行此命令也會移除任何相關的組態或授權套件。然後，您可以使用 [list-packages-for-domain](https://docs.aws.amazon.com/cli/latest/reference/es/list-packages-for-domain.html) 命令來檢視取消關聯的狀態。
**提示**
您也可以使用 [dissociate-packages](https://docs.aws.amazon.com/cli/latest/reference/opensearch/dissociate-packages.html) 命令，在單一操作中從網域解除安裝多個外掛程式。
**解除安裝並檢視自訂外掛程式的取消關聯狀態**
1. 在每個索引中停用外掛程式。這必須在取消外掛程式套件的關聯之前完成。
如果您在從每個索引停用外掛程式之前嘗試解除安裝外掛程式，藍/綠部署程序會維持在 `Processing` 狀態。
1. 執行下列命令來解除安裝外掛程式。使用您的資訊取代*預留位置的值*。
```
aws opensearch dissociate-package \
--region region \
--package-id plugin-package-id \
--domain-name domain name
```
1. （選用） 執行 [list-packages-for-domain](https://docs.aws.amazon.com/cli/latest/reference/opensearch/list-packages-for-domain.html) 命令，以檢視取消關聯的狀態。