套件許可要求將套件上傳至 Amazon S3 匯入和關聯套件使用套件搭配 OpenSearch 更新套件字典的手動索引更新解除關聯並移除套件

Amazon OpenSearch 服務的定制包

Amazon Ser OpenSearch vice 可讓您上傳自訂字典檔案 (例如停用字和同義字)，並提供數個預先封裝的選用外掛程式，讓您與網域建立關聯。這兩種類型的文件的通用術語是包。

字典文件通過告訴忽略某些高頻單詞或 OpenSearch 將諸如「冰淇淋」，「意式冰淇淋」和「冰淇淋」等詞語對待，從而改善您的搜索結果。它們還可以提高字根還原的能力，例如在 Japanese (kuromoji) Analysis 分析外掛程式。

可選插件可以為您的域提供附加功能。例如，您可以使用 Amazon Personalize 外掛程式為您提供個人化的搜尋結果。可選插件使用ZIP-PLUGIN包類型。如需選用外掛程式的詳細資訊，請參閱Amazon OpenSearch 服務中的引擎版本的插件。

套件許可要求

沒有管理員存取權的使用者需要特定 AWS Identity and Access Management (IAM) 動作才能管理套件：

es:CreatePackage-在 OpenSearch 服務區域中建立套件
es:DeletePackage-從 OpenSearch 服務區域刪除套件
es:AssociatePackage - 將套件關聯到網域
es:DissociatePackage - 取消套件與網域的關聯

您也需要自訂套件所在的 Amazon S3 儲存貯體路徑或物件的許可。

授予 IAM 內的所有許可，而不是在網域存取政策中。如需詳細資訊，請參閱 Amazon OpenSearch 服務中的 Identity and Access Management。

將套件上傳至 Amazon S3

本節介紹了如何上傳自定義字典包，因為可選插件包已經預先安裝。您必須先將自訂字典上傳到 Amazon S3 儲存貯體，才能將自訂字典與網域建立關聯。如需指示說明，請參閱 Amazon Simple Storage Service 使用者指南中的上傳物件。支持的插件不需要上傳。

如果您的字典包含敏感資訊，請在上傳時使用 S3 管理的金鑰指定伺服器端加密。 OpenSearch 服務無法存取您使用 AWS KMS 金鑰保護的 S3 上的檔案。

上傳檔案後，請記下其 S3 路徑。路徑格式為 s3://bucket-name/file-path/file-name。

您可以使用下列同義字檔案進行測試。另存為 synonyms.txt。


danish, croissant, pastry
ice cream, gelato, frozen custard
sneaker, tennis shoe, running shoe
basketball shoe, hightop

某些字典 (例如 Hunspell 字典) 會使用多個檔案並要求在檔案系統上使用自己的字典。目前， OpenSearch 服務僅支援單一檔案字典。

匯入和關聯套件

控制台是將自定義字典導入 OpenSearch 服務的最簡單方法。當您從 Amazon S3 匯入字典時， OpenSearch 服務會存放自己的套件副本，並使用 AES-256 與 OpenSearch 服務受管金鑰自動加密該副本。

可選插件已經預先安裝在 OpenSearch 服務中，因此您不需要自己上傳它們，但您確實需要將插件與域關聯。可用的外掛程式會列在主控台的「套件」畫面上。

在 Amazon OpenSearch 服務主控台中，選擇套件。
選擇 Import package (匯入套件)。
為自訂字典指定描述性名稱。
提供檔案的 S3 路徑，然後選擇 Submit (提交)。
返回 Packages (套件) 畫面。
當封裝狀態為 Available (可用) 時，請加以選取。可選插件將自動可用。
選擇「關聯至網域」。
選取網域，然後選擇 Associate (關聯)。
在導覽窗格中，選擇您的網域，然後移至 Packages (套件) 索引標籤。
如果封裝是自訂字典，請在套件變成「可用」時記下 ID。用analyzers/id作要求中的檔案路徑 OpenSearch。

或者，使用 AWS CLI、SDK 或設定 API 匯入和關聯套件。如需詳細資訊，請參閱AWS CLI 命令參考和 Amazon OpenSearch 服務 API 參考。

使用套件搭配 OpenSearch

本節介紹如何使用這兩種類型的軟件包：自定義字典和可選插件。

使用自訂字典

將檔案與網域建立關聯後，您可以在建立分詞器和字符篩選條件時在 synonyms_path、stopwords_path 和 user_dictionary 等參數中使用該檔案。確切的參數因物件而異。多個物件可支援 synonyms_path 和 stopwords_path，但 user_dictionary 專屬於 kuromoji 外掛程式。

對於 IK (中文) 分析外掛程式，您可以將自訂字典檔案做為自定套件上傳，並將其與一個網域相關聯，且外掛程式會自動將其掛載，不需要 user_dictionary 參數。如果您的檔案是同義詞檔案，請使用 synonyms_path 參數。

以下範例會將同義字檔案新增至新索引：


PUT my-index
{
  "settings": {
    "index": {
      "analysis": {
        "analyzer": {
          "my_analyzer": {
            "type": "custom",
            "tokenizer": "standard",
            "filter": ["my_filter"]
          }
        },
        "filter": {
          "my_filter": {
            "type": "synonym",
            "synonyms_path": "analyzers/F111111111",
            "updateable": true
          }
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "description": {
        "type": "text",
        "analyzer": "standard",
        "search_analyzer": "my_analyzer"
      }
    }
  }
}

此請求建立使用標準分詞器和同義詞字符篩選條件索引的自訂分析器。

分詞器會根據一組規則將字符分解為字符 (通常是字詞)。最簡單的例子是空格分詞器，每次遇到一個空白字符時，便會將前面的字元分解為字符。一個更複雜的例子是標準分詞器，它會使用一組基於語法的規則跨多種語言作業。
字符篩選條件會新增、修改或刪除字符。例如，同義字字符篩選條件會在同義字清單中找到單字時加入字符。停止字符篩選條件會在停止字詞清單中找到字詞時移除標記。

此請求還將一個文本字段（description）添加到映射，並告訴使 OpenSearch 用新的分析器作為其搜索分析器。您可以看到它仍然使用標準分析器作為其索引分析器。

最後，請注意字符篩選器中的 "updateable": true 行。此欄位僅適用於搜尋分析器，不適用於索引分析器，如果您稍後想要自動更新搜尋分析器，此欄位就非常重要。

為了測試，我們加入了一些文件索引：


POST _bulk
{ "index": { "_index": "my-index", "_id": "1" } }
{ "description": "ice cream" }
{ "index": { "_index": "my-index", "_id": "2" } }
{ "description": "croissant" }
{ "index": { "_index": "my-index", "_id": "3" } }
{ "description": "tennis shoe" }
{ "index": { "_index": "my-index", "_id": "4" } }
{ "description": "hightop" }

然後使用同義詞來搜尋它們：


GET my-index/_search
{
  "query": {
    "match": {
      "description": "gelato"
    }
  }
}

在此情況下，會 OpenSearch 傳回下列回應：


{
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.99463606,
    "hits": [{
      "_index": "my-index",
      "_type": "_doc",
      "_id": "1",
      "_score": 0.99463606,
      "_source": {
        "description": "ice cream"
      }
    }]
  }
}

提示

字典檔案使用與其大小呈正比的 Java 堆積空間。例如，2 GiB 的字典檔案可能會在節點上使用 2 GiB 的堆積空間。如果您使用大型檔案，請確保節點有足夠的堆積空間可容納這些檔案。監控 JVMMemoryPressure 指標，並視需要擴展您的叢集。

使用可選插件

OpenSearch 服務可讓您將預先安裝的選用 OpenSearch 外掛程式與網域建立關聯。選用的外掛程式套件與特定 OpenSearch 版本相容，而且只能與該版本的網域相關聯。您網域的可用套件清單包括所有支援與您的網域版本相容的外掛程式。將外掛程式與網域建立關聯後，網域上的安裝程序便會開始。然後，您可以在向 OpenSearch 服務發出請求時引用並使用該插件。

關聯和解除外掛程式需要藍/綠部署。如需詳細資訊，請參閱通常會導致藍/綠部署的變更。

可選插件包括語言分析儀和自定義搜索結果。例如，Amazon Personalize 搜尋排名外掛程式使用機器學習來為您的客戶個人化搜尋結果。如需有關此外掛程式的詳細資訊，請參閱個人化搜尋結果。 OpenSearch如需所有支援外掛程式的清單，請參閱Amazon OpenSearch 服務中的引擎版本的插件。

酢橘插件

對於 Sudachi 插件，當您重新關聯字典文件時，它不會立即反映在域上。當下一個藍/綠部署在網域上執行時，做為組態變更或其他更新的一部分時，字典會重新整理。或者，您也可以使用更新的資料建立新套件、使用這個新套件建立新索引、將現有索引重新建立索引至新索引，然後刪除舊索引。如果您偏好使用重新建立索引的方法，請使用索引別名，這樣就不會中斷流量。

此外，Sudachi 插件僅支持二進制 Sudachi 字典，您可以通過 CreatePackageAPI 操作上傳該字典。有關預構建的系統字典和用於編譯用戶字典的過程的信息，請參閱 Sudachi 文檔。

下面的示例演示瞭如何將系統和用戶字典與 Sudachi 標記生成器一起使用。您必須將這些字典上傳為具有類型的自訂套件，TXT-DICTIONARY並在其他設定中提供其套件 ID。


PUT sudachi_sample
{
  "settings": {
    "index": {
      "analysis": {
        "tokenizer": {
          "sudachi_tokenizer": {
            "type": "sudachi_tokenizer",
            "additional_settings": "{\"systemDict\": \"<system-dictionary-package-id>\",\"userDict\": [\"<user-dictionary-package-id>\"]}"
        }
        },
        "analyzer": {
          "sudachi_analyzer": {
            "filter": ["my_searchfilter"],
            "tokenizer": "sudachi_tokenizer",
            "type": "custom"
          }
        },
        "filter":{
          "my_searchfilter": {
            "type": "sudachi_split",
            "mode": "search"
          }
        }
      }
    }
  }
}

更新套件

本節僅介紹如何更新自訂字典套件，因為選用的外掛程式套件已經為您更新。將新版本的字典上傳到 Amazon S3 並不會自動更新 Amazon OpenSearch 服務上的套件。 OpenSearch 服務會儲存自己的檔案副本，因此如果您將新版本上傳到 S3，則必須手動更新它。

每個關聯網域也都會儲存其自己的檔案副本。為了保持搜尋行為可預測，網域會繼續使用其目前的套件版本，直到您明確更新它們為止。若要更新自訂套件，請修改中的檔案 Amazon S3 Control、更新 OpenSearch Service 中的套件，然後套用更新。

在 [ OpenSearch 服務] 主控台中，選擇 [套件]。
選擇套件和 Update (更新)。
提供檔案的 S3 路徑，然後選擇 Update package (更新套件)。
返回 Packages (套件) 畫面。
當套件狀態變為 Available (可用) 時，請加以選取。然後選擇一個或多個關聯網域，選擇 Apply update (套用更新) 並確認。等待關聯狀態變為 Active (作用中)。
接下來的步驟會有所不同，這取決於您如何設定索引：
- 如果您的網域正在執行 OpenSearch 或 Elasticsearch 7.8 或更新版本，且僅使用可更新欄位設定為 true 的搜尋分析器，則不需要採取任何進一步的動作。 OpenSearch 服務會使用外掛程式/搜尋分析器 API 自動更新您的索引。
- 如果您的網域執行 Elasticsearch 7.7 或更早版本，請使用索引分析器，或未使用updateable欄位，請參閱。字典的手動索引更新

雖然主控台是最簡單的方法，但您也可以使用 AWS CLI、SDK 或設定 API 來更新 OpenSearch 服務套件。如需詳細資訊，請參閱AWS CLI 命令參考和 Amazon OpenSearch 服務 API 參考。

您可以使用開發套件來自動化更新程序，而不是在主控台中手動更新套件。下列範例 Python 指令碼會將新套件檔案上傳至 Amazon S3、更新 OpenSearch 服務中的套件，並將新套件套用至指定的網域。確認更新成功後，它會進行範例呼叫，以 OpenSearch展示已套用新的同義字。

您必須提供 host、region、file_name、bucket_name、s3_key、package_id、domain_name 和 query 的值。


from requests_aws4auth import AWS4Auth
import boto3
import requests
import time
import json
import sys

host = ''  # The OpenSearch domain endpoint with https:// and a trailing slash. For example, https://my-test-domain.us-east-1.es.amazonaws.com/
region = ''  # For example, us-east-1
file_name = ''  # The path to the file to upload
bucket_name = ''  # The name of the S3 bucket to upload to
s3_key = ''  # The name of the S3 key (file name) to upload to
package_id = ''  # The unique identifier of the OpenSearch package to update
domain_name = ''  # The domain to associate the package with
query = ''  # A test query to confirm the package has been successfully updated

service = 'es'
credentials = boto3.Session().get_credentials()
client = boto3.client('opensearch')
awsauth = AWS4Auth(credentials.access_key, credentials.secret_key,
                   region, service, session_token=credentials.token)


def upload_to_s3(file_name, bucket_name, s3_key):
    """Uploads file to S3"""
    s3 = boto3.client('s3')
    try:
        s3.upload_file(file_name, bucket_name, s3_key)
        print('Upload successful')
        return True
    except FileNotFoundError:
        sys.exit('File not found. Make sure you specified the correct file path.')


def update_package(package_id, bucket_name, s3_key):
    """Updates the package in OpenSearch Service"""
    print(package_id, bucket_name, s3_key)
    response = client.update_package(
        PackageID=package_id,
        PackageSource={
            'S3BucketName': bucket_name,
            'S3Key': s3_key
        }
    )
    print(response)


def associate_package(package_id, domain_name):
    """Associates the package to the domain"""
    response = client.associate_package(
        PackageID=package_id, DomainName=domain_name)
    print(response)
    print('Associating...')


def wait_for_update(domain_name, package_id):
    """Waits for the package to be updated"""
    response = client.list_packages_for_domain(DomainName=domain_name)
    package_details = response['DomainPackageDetailsList']
    for package in package_details:
        if package['PackageID'] == package_id:
            status = package['DomainPackageStatus']
            if status == 'ACTIVE':
                print('Association successful.')
                return
            elif status == 'ASSOCIATION_FAILED':
                sys.exit('Association failed. Please try again.')
            else:
                time.sleep(10)  # Wait 10 seconds before rechecking the status
                wait_for_update(domain_name, package_id)


def sample_search(query):
    """Makes a sample search call to OpenSearch"""
    path = '_search'
    params = {'q': query}
    url = host + path
    response = requests.get(url, params=params, auth=awsauth)
    print('Searching for ' + '"' + query + '"')
    print(response.text)

注意

如果您在使用執行指令碼時收到「找不到套件」錯誤 AWS CLI，可能表示 Boto3 正在使用 ~/.aws/config 中指定的任何區域，而不是 S3 儲存貯體所在的區域。執行 aws configure 並指定正確的區域，或者明確地將區域新增至用戶端：


client = boto3.client('opensearch', region_name='us-east-1')

字典的手動索引更新

手動索引更新僅適用於自訂字典，不適用於選用的外掛程式。若要使用更新的字典，必須在符合下列任一條件時手動更新索引：

您的網域執行 Elasticsearch 7.7 或更早版本。
您使用自訂套件作為索引分析器。
您使用自訂套件作為搜索分析器，但不包含 updateable (可更新) 欄位。

若要使用新套件檔案更新分析器，您有兩個選項：

關閉並開啟您要更新的任何索引：
```
POST my-index/_close
POST my-index/_open
```

對索引進行重新索引。首先，建立使用更新的同義字檔案 (或全新檔案) 的索引。請注意，僅支援 UTF-8。


PUT my-new-index
{
  "settings": {
    "index": {
      "analysis": {
        "analyzer": {
          "synonym_analyzer": {
            "type": "custom",
            "tokenizer": "standard",
            "filter": ["synonym_filter"]
          }
        },
        "filter": {
          "synonym_filter": {
            "type": "synonym",
            "synonyms_path": "analyzers/F222222222"
          }
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "description": {
        "type": "text",
        "analyzer": "synonym_analyzer"
      }
    }
  }
}

然後將舊索引重新索引到該新索引：


POST _reindex
{
  "source": {
    "index": "my-index"
  },
  "dest": {
    "index": "my-new-index"
  }
}

如果您經常更新索引分析器，請使用索引別名來維持最新索引的一致路徑：


POST _aliases
{
  "actions": [
    {
      "remove": {
        "index": "my-index",
        "alias": "latest-index"
      }
    },
    {
      "add": {
        "index": "my-new-index",
        "alias": "latest-index"
      }
    }
  ]
}

如果您不需要舊索引，請將其刪除：


DELETE my-index

解除關聯並移除套件

將套件 (無論是自訂字典或選用外掛程式) 與網域分離，表示您在建立新索引時無法再使用該套件。解除關聯套件之後，使用該套件的現有索引就無法再使用它。您必須先從任何索引中移除套件，才能將其解除關聯，否則分離會失敗。

主控台是將套件與網域分離並從服務中移除的最簡單方法。 OpenSearch 從 OpenSearch 服務移除套件並不會將其從 Amazon S3 上的原始位置移除。

前往 https://aws.amazon.com，然後選擇 Sign In to the Console (登入主控台)。
在分析下，選擇 Amazon OpenSearch 服務。
在導覽窗格中，選擇您的網域，然後選擇 Packages (套件) 標籤。
選擇套件，Actions (動作)，然後選擇 Dissociate (解除關聯)。確認您的選擇。
等待套件從清單中消失。您可能需要重新整理瀏覽器。
如果您想要將套件與其他網域搭配使用，請在這裡停止。若要繼續移除套件（如果它是自訂字典），請在導覽窗格中選擇「封裝」。
選取套件並選擇 Delete (刪除)。

或者，使用 AWS CLI、SDK 或設定 API 來分離和移除套件。如需詳細資訊，請參閱AWS CLI 命令參考和 Amazon OpenSearch 服務 API 參考。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

搜尋資料

SQL 支援