翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # Amazon OpenSearch Service でのパッケージのインポートと管理 Amazon OpenSearch Service では、ストップワードや類義語などのカスタム辞書ファイルをアップロードして、プラグインをドメインに関連付けることができます。これらのプラグインは、パッケージ済み、カスタム、またはサードパーティーのいずれかであり、ドメインの機能を柔軟に拡張できます。これらすべてのタイプのファイルの総称は、*パッケージ*です。 + **辞書ファイル**は、よくある頻出語を無視したり、「フローズンカスタード」、「ジェラート」、「アイスクリーム」などの類似した用語を同等に扱ったりするように OpenSearch に指示することで、検索結果を改善します。また、日本語 (kuromoji) 分析プラグインで見られるように、[ステミング](https://en.wikipedia.org/wiki/Stemming)を改善することもできます。 + **パッケージ済みプラグイン**は、パーソナライズされた検索結果を実現する Amazon Personalize プラグインなどの組み込み機能を提供します。これらのプラグインは、`ZIP-PLUGIN` パッケージタイプを使用します。詳細については、「[Amazon OpenSearch Service のエンジンバージョンに応じたプラグイン](supported-plugins.md)」を参照してください。 + **カスタムプラグインおよびサードパーティープラグイン**を使用すると、カスタマイズされた機能を追加したり、外部システムと統合したりできるため、ドメインの柔軟性がさらに向上します。パッケージ済みプラグインと同様に、カスタムプラグインを `ZIP-PLUGIN` パッケージとしてアップロードします。サードパーティープラグインの場合は、プラグインのライセンスファイルと設定ファイルも個別のパッケージとしてインポートし、これらすべてをドメインに関連付ける必要があります。 詳細については、以下の各トピックを参照してください。 + [Amazon OpenSearch Service でのカスタムプラグイン管理](custom-plugins.md) + [Amazon OpenSearch Service でのサードパーティープラグインのインストール](plugins-third-party.md) **注記** 1 つのドメインには最大 20 個のプラグインを関連付けることができます。この制限には、オプションプラグイン、サードパーティープラグイン、カスタムプラグインを含む、すべてのプラグインタイプが含まれます。 **Topics** + [必要なアクセス許可](#custom-packages-iam) + [Amazon S3 へのパッケージのアップロード](#custom-packages-gs) + [パッケージのインポートと関連付け](#custom-packages-assoc) + [OpenSearch でのパッケージの使用](#custom-packages-using) + [パッケージの更新](#custom-packages-updating) + [新しい辞書でインデックスを手動で更新する](#custom-packages-updating-index-analyzers) + [パッケージの関連付け解除と削除](#custom-packages-dissoc) + [Amazon OpenSearch Service でのカスタムプラグイン管理](custom-plugins.md) + [Amazon OpenSearch Service でのサードパーティープラグインのインストール](plugins-third-party.md) ## 必要なアクセス許可 管理者アクセスのないユーザーは、パッケージを管理するために特定の AWS Identity and Access Management (IAM) アクションが必要です。 + `es:CreatePackage` – パッケーを作成する + `es:DeletePackage` – パッケージを削除する + `es:AssociatePackage` – パッケージをドメインに関連付ける + `es:DissociatePackage` – ドメインからパッケージの関連付けを解除する カスタムパッケージが存在する Amazon S3 バケットパスまたはオブジェクトに対する許可も必要です。 ドメインアクセスポリシー内ではなく、IAM 内のすべての許可を付与します。詳細については、「[Amazon OpenSearch Service での Identity and Access Management](ac.md)」を参照してください。 ## Amazon S3 へのパッケージのアップロード このセクションでは、パッケージ済みプラグインパッケージは既にインストールされていることから、カスタム辞書パッケージをアップロードする方法について説明します。カスタム辞書は、ドメインに関連付ける前に Amazon S3 バケットにアップロードする必要があります。手順については、*Amazon Simple Storage Service ユーザーガイド*の「[オブジェクトのアップロード](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html)」を参照してください。サポートされているプラグインをアップロードする必要はありません。 辞書に機密情報が含まれている場合は、アップロード時に [S3 で管理されたキーによるサーバー側の暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingServerSideEncryption.html)を指定します。OpenSearch Service は、 AWS KMS キーを使用して保護する S3 上のファイルにアクセスできません。 ファイルをアップロードしたら、その S3 パスを書き留めます。パスの形式は `s3://amzn-s3-demo-bucket/file-path/file-name` です。 テスト目的で、次のシノニムファイルを使用できます。`synonyms.txt` と名前を付けて保存します。 ``` danish, croissant, pastry ice cream, gelato, frozen custard sneaker, tennis shoe, running shoe basketball shoe, hightop ``` Hunspell 辞書など一部の辞書では、複数のファイルを使用するため、ファイルシステム上に独自のディレクトリが必要になります。現時点では、OpenSearch Service では単一ファイルの辞書のみがサポートされています。 ## パッケージのインポートと関連付け コンソールは、カスタム辞書を OpenSearch Service にインポートする最も簡単な方法です。Amazon S3 から辞書をインポートすると、OpenSearch Service はパッケージの独自のコピーを保存し、AES-256 を使用して、OpenSearch Service マネージドキーによりそのコピーを自動的に暗号化します。 オプションのプラグインは OpenSearch Service にあらかじめインストールされているので、自分でアップロードする必要はありませんが、プラグインをドメインに関連付ける必要があります。使用可能なプラグインは、コンソールの **[パッケージ]** 画面に一覧表示されます。 ### パッケージをドメインにインポートして関連付ける 1. Amazon OpenSearch Service コンソールで、[**パッケージ**] を選択します。 1. [**パッケージのインポート**] を選択します。 1. パッケージにわかりやすい名前を付けます。 1. ファイルへの S3 パスを指定し、[**インポート**] を選択します。 1. [**パッケージ**] 画面に戻ります。 1. パッケージのステータスが [**使用可能**] の場合は、パッケージを選択します。 1. **[ドメインへの関連付け]** を選択します。 1. ドメインを選択して、**[次へ]** を選択します。パッケージを確認し、**[関連付け]** を選択します。 1. ナビゲーションペインでドメインを選択し、**[パッケージ]** タブに進みます。 1. パッケージがカスタム辞書の場合、パッケージが **[使用可能]** になったら ID を書き留めておきます。[[OpenSearch へのリクエスト](#custom-packages-using)] でファイルパスとして `analyzers/id` を使用します。 ## 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` をメモします。このフィールドは検索アナライザーにのみ適用され、インデックスアナライザーには適用されず、後で[検索アナライザーを更新](#custom-packages-updating)したい場合に不可欠です。 テスト目的のために、インデックスにいくつかのドキュメントを追加します。 ``` 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` メトリクスを[モニタリング](managedomains-cloudwatchmetrics.md#managedomains-cloudwatchmetrics-cluster-metrics)し、必要に応じてクラスターをスケーリングします。 ### パッケージ済みプラグインの使用 OpenSearch Service では、プレインストールされているオプションの OpenSearch プラグインをドメインに関連付けて使用することができます。パッケージ済みプラグインパッケージは特定の OpenSearch バージョンと互換性があり、そのバージョンのドメインにのみ関連付けることができます。ドメインで利用可能なパッケージのリストには、そのドメインバージョンと互換性のある、サポートされているすべてのプラグインが含まれています。プラグインをドメインに関連付けると、ドメインへのインストールプロセスが開始されます。すると、OpenSearch Service にリクエストを送信する際にプラグインを参照して使用できるようになります。 プラグインの関連付けと解除には、ブルー/グリーンデプロイが必要です。詳細については、「[通常は blue/green デプロイの原因となる変更](managedomains-configuration-changes.md#bg)」を参照してください。 オプションのプラグインには、言語アナライザーやカスタマイズされた検索結果が含まれます。例えば、Amazon Personalize Search Ranking プラグインは、機械学習を使用してお客様の検索結果をパーソナライズします。このプラグインの詳細については、「[OpenSearch の検索結果のパーソナライズ](https://docs.aws.amazon.com/personalize/latest/dg/personalize-opensearch.html)」を参照してください。サポートされているすべてのプラグインのリストについては、「[Amazon OpenSearch Service のエンジンバージョンに応じたプラグイン](supported-plugins.md)」を参照してください。 #### Sudachi プラグイン [Sudachi プラグイン](https://github.com/WorksApplications/elasticsearch-sudachi)の場合、ディクショナリファイルを再関連付けしても、すぐにドメインには反映されません。設定変更やその他の更新の一環として、次のブルー/グリーンデプロイがドメインで実行されると、辞書が更新されます。または、更新済みのデータで新しいインデックスを作成し、この新しいパッケージを使用して新しいインデックスを作成し、既存のインデックスを新しいインデックスに再インデックスしてから、古いインデックスを削除することもできます。インデックスの再作成方法を使用する場合は、トラフィックが中断されないようにインデックスエイリアスを使用してください。 さらに、Sudachi プラグインは [CreatePackage](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_CreatePackage.html) API オペレーションでアップロードできるバイナリ Sudachi ディクショナリのみをサポートしています。ビルド済みのシステムディクショナリの詳細およびユーザーディクショナリのコンパイルプロセスについては、[Sudachi のドキュメント](https://github.com/WorksApplications/elasticsearch-sudachi)を参照してください。 **注記** バイナリディクショナリファイルを Amazon S3 にアップロードする場合は、S3 オブジェクトの Content-Type を に設定する必要があります`binary/octet-stream`。を使用すると`application/octet-stream`、パッケージのインポートが失敗します。 次の例は、Sudachi トークナイザでシステムディクショナリとユーザーディクショナリを使用する方法を示しています。これらのディクショナリは、タイプ `TXT-DICTIONARY` のカスタムパッケージとしてアップロードし、追加設定でパッケージ ID を指定する必要があります。 ``` PUT sudachi_sample { "settings": { "index": { "analysis": { "tokenizer": { "sudachi_tokenizer": { "type": "sudachi_tokenizer", "additional_settings": "{\"systemDict\": \"\",\"userDict\": [\"\"]}" } }, "analyzer": { "sudachi_analyzer": { "filter": ["my_searchfilter"], "tokenizer": "sudachi_tokenizer", "type": "custom" } }, "filter":{ "my_searchfilter": { "type": "sudachi_split", "mode": "search" } } } } } } ``` ## パッケージの更新 パッケージ済みのプラグインパッケージはすでに更新されているため、このセクションではカスタム辞書パッケージの更新方法についてのみ説明します。Amazon S3 に新しいバージョンの辞書をアップロードしても、Amazon OpenSearch Service 上のパッケージは自動的に更新*されません*。OpenSearch Service はファイルの独自のコピーを保存するため、新しいバージョンを S3 にアップロードする場合は、ファイルを手動で更新する必要があります。 関連付けられた各ドメインは*その*ファイルの独自のコピーも保存します。検索動作を予測可能に保つために、ドメインは明示的に更新されるまで、現在のパッケージバージョンを引き続き使用します。カスタムパッケージを更新するには、 でファイルを変更し Amazon S3 Control、OpenSearch Service でパッケージを更新してから、更新を適用します。 ### コンソール 1. OpenSearch Service コンソールで、[**パッケージ**] を選択します。 1. パッケージを選択し、[**更新**] を選択します。 1. ファイルへの新しい S3 パスを指定し、**[パッケージを更新]** を選択します。 1. [**パッケージ**] 画面に戻ります。 1. パッケージのステータスが [**使用可能**] に変わったら、それを選択します。次に、関連付けられたドメインを 1 つ以上選択し、[**更新の適用**] を選択し、確定します。関連付けステータスが [**アクティブ**] に変わるまで待ちます。 1. 次の手順は、インデックスの設定方法によって異なります。 + ドメインが OpenSearch または Elasticsearch 7.8 以降を実行していて、[更新可能](#custom-packages-using) フィールドが true に設定されている検索アナライザーのみを使用する場合は、それ以上アクションを実行する必要はありません。OpenSearch Service は、[\$1plugins/\$1refresh\$1search\$1analyzers API](https://docs.opensearch.org/latest/im-plugin/refresh-analyzer/index/) を使用して、自動的にインデックスを更新します。 + ドメインが Elasticsearch 7.7 以前を実行していて、インデックスアナライザーを使用しているか、または `updateable` フィールドを使用していない場合は、「[新しい辞書でインデックスを手動で更新する](#custom-packages-updating-index-analyzers)」を参照してください。 コンソールは最も簡単な方法ですが、 AWS CLI、 SDKs、または設定 API を使用して OpenSearch Service パッケージを更新することもできます。詳細については、「[AWS CLI コマンドリファレンス](https://docs.aws.amazon.com/cli/latest/reference/)」と「[Amazon OpenSearch Service API リファレンス](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/Welcome.html)」を参照してください。 ### AWS SDK コンソールでパッケージを手動で更新する代わりに、SDK を使用して更新プロセスを自動化できます。次のサンプル Python スクリプトは、新しいパッケージファイルを Amazon S3 にアップロードし、OpenSearch Service でパッケージを更新し、指定されたドメインに新しいパッケージを適用します。更新が正常に完了したことを確認した後、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) ``` **注記** を使用してスクリプトを実行するときに「package not found」エラーが表示される場合は AWS CLI、SBoto3S3 が使用している可能性があります。`aws configure` を実行して正しいリージョンを指定するか、明示的にクライアントにそのリージョンを追加します。 ``` client = boto3.client('opensearch', region_name='us-east-1') ``` ## 新しい辞書でインデックスを手動で更新する 手動によるインデックス更新はカスタム辞書にのみ適用され、パッケージ済みプラグインには適用されません。更新された辞書を使用するには、次の条件のいずれかを満たしている場合、インデックスを手動で更新する必要があります。 + ドメインは Elasticsearch 7.7 以前を実行しています。 + カスタムパッケージをインデックスアナライザーとして使用しています。 + 検索アナライザーとしてカスタムパッケージを使用していますが、[[更新可能](#custom-packages-using)] フィールドは含まれていません。 新しいパッケージファイルでアナライザーを更新するには、次の 2 つのオプションがあります。 + 更新するインデックスを閉じて開きます。 ``` 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" } } } } ``` 次に、古いインデックスをその新しいインデックスに[再作成](https://docs.opensearch.org/latest/opensearch/reindex-data/)します。 ``` POST _reindex { "source": { "index": "my-index" }, "dest": { "index": "my-new-index" } } ``` インデックスアナライザーを頻繁に更新する場合は、[インデックスエイリアス](https://docs.opensearch.org/latest/opensearch/index-alias/)を使用して、最新のインデックスへの一貫したパスを維持します。 ``` POST _aliases { "actions": [ { "remove": { "index": "my-index", "alias": "latest-index" } }, { "add": { "index": "my-new-index", "alias": "latest-index" } } ] } ``` 古いインデックスが必要ない場合は、削除します。 ``` DELETE my-index ``` ## パッケージの関連付け解除と削除 カスタム辞書であれパッケージ済みプラグインであれ、ドメインからパッケージを切り離すと、新しいインデックスを作成するときにそのパッケージを使用できなくなります。パッケージの関連付けが解除されると、パッケージを使用していた既存のインデックスでは使用できなくなります。パッケージを関連付け解除する前に、どのインデックスからも削除する必要があります。削除しないと、関連付けの解除は失敗します。 コンソールは、ドメインからパッケージの関連付けを解除し、OpenSearch Service から削除する最も簡単な方法です。OpenSearch サービスからパッケージを削除しても、それはAmazon S3 上の元の場所から削除され*ません*。 ### ドメインからパッケージの関連付けを解除する 1. [https://console.aws.amazon.com/aos/home](https://console.aws.amazon.com/aos/home) で Amazon OpenSearch Service コンソールにサインインします。 1. ナビゲーションペインで、**[ドメイン]** を選択します。 1. ドメインを選択してから、**[パッケージ]** タブに移動します。 1. パッケージを選択して、[**アクション**] を選択し、[**関連付け解除**] を選択します。選択内容を確認します。 1. パッケージがリストから消えるのを待ちます。ブラウザを更新することが必要な場合があります。 1. パッケージを他のドメインで使用する場合は、ここで停止します。パッケージの削除を続行するには (カスタム辞書の場合)、ナビゲーションペインで **[パッケージ]** を選択します。 1. パッケージを選択し、[**削除**] を選択します。 または、 AWS CLI、 SDKs、または 設定 API を使用して、パッケージの関連付けを解除および削除します。詳細については、「[AWS CLI コマンドリファレンス](https://docs.aws.amazon.com/cli/latest/reference/)」と「[Amazon OpenSearch Service API リファレンス](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/Welcome.html)」を参照してください。