Amazon Elasticsearch Service 的自定义程序包 - Amazon Elasticsearch Service
程序包权限要求将程序包上传到 Amazon S3导入和关联程序包使用带弹性搜索的自定义软件包更新自定义程序包取消关联并删除软件包
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 Amazon Web Services 服务入门。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

Amazon Elasticsearch Service 的自定义程序包

Amazon Elasticsearch Service (Amazon ES) 允许您上传自定义字典文件，例如停用词和同义词，以用于集群。这些类型的文件的通用术语是程序包。字典文件通过告诉 Elasticsearch 忽略某些高频字词或将诸如 “软冻蛋奶”、” 冰淇淋” 和 “冰激凌” 等词语视为等效，从而改善搜索结果。它们也可以改进词干提取，如在日语 (kuromoji) 分析插件中。

程序包权限要求

没有管理员权限的用户需要某些Amazon Identity and Access Management(IAM) 操作来管理软件包：

  • es:CreatePackage-在亚马逊 ES 地区创建包裹

  • es:DeletePackage-从 Amazon ES 地区删除软件包

  • es:AssociatePackage-将软件包与域关联

  • es:DissociatePackage-将程序包与域取消关联

您还需要对自定义软件包所在的 Amazon S3 存储桶路径或对象的权限。

授予 IAM 中的所有权限，而不是域访问策略中的权限。有关更多信息，请参阅 Amazon Elasticsearch Service 中的 Identity and Access Management。

将程序包上传到 Amazon S3

您必须将程序包上传到 Amazon S3 存储桶，然后才能将程序包与您的域关联。有关说明，请参阅上传 S3 对象中的Amazon Simple Storage Service 入门指南。

如果您的软件包包含敏感信息，请指定使用 S3 托管密钥进行服务器端加密。当你上传它。Amazon ES 无法访问您使用Amazon KMS主密钥。

上传文件后，记下其 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 字典）使用多个文件，并且在文件系统上需要自己的目录。目前，Amazon ES 仅支持单文件字典。

导入和关联程序包

控制台是将程序包导入到 Amazon ES 中并将程序包与域关联的最简单方法。从 Amazon S3 导入软件包时，Amazon ES 存储自己的程序包副本，并使用 AES-256 以及 Amazon ES 托管密钥自动加密该副本。

导入包并将其与域关联（控制台）

  1. 在 Amazon Elasticsearch Service 控制台中，选择软件包。

  2. 选择 Import。

  3. 为程序包提供描述性名称。

  4. 提供文件的 S3 路径，然后选择 Import (导入)。

  5. 返回到 Packages (程序包) 屏幕。

  6. 当程序包状态为 Available (可用) 时，选择它。然后选择 Associate to a domain (关联到域)。

  7. 选择一个域，然后选择 Associate (关联)。

  8. 在导航窗格中，选择您的域，然后选择 Packages (程序包) 选项卡。

  9. 当程序包状态为 Available (可用) 时，记下它的 ID。使用analyzers/id中的文件路径针对 Elasticsearch 的请求。

或者，使用 Amazon CLI、开发工具包或配置 API 导入和关联程序包。有关更多信息，请参阅 。Amazon CLI命令参考和Amazon Elasticsearch Service 的配置 API 参考。

使用带弹性搜索的自定义软件包

将文件与域关联后，您可以在创建标记器和标记筛选条件时，在诸如 synonyms_path、stopwords_path 和 user_dictionary 等参数中使用该文件。确切的参数因对象而异。多个对象支持 synonyms_path 和 stopwords_path，但 user_dictionary 专用于 kuromoji 插件。以下示例将同义词文件添加到新索引中： 

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）添加到映射中，并告诉 Elasticsearch 将新的分析器用作其搜索分析器。您可以看到它仍然使用标准分析器作为其索引分析器。

最后，请注意"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"
    }
  }
}

在这种情况下，Elasticsearch 会返回以下响应：

{
  "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 指标，并根据需要扩展集群。

更新自定义程序包

将新版本的程序包上传到 Amazon S3 会不是Amazon Elasticsearch Service 上的程序包会自动更新程序包。Amazon ES 存储自己的文件副本，因此，如果您将新版本上传到 S3，则必须手动更新该版本。

您的每个关联域存储其自己的文件副本。为了保持搜索行为的可预测性，域将继续使用其当前的软件包版本，直到您明确更新它们。

更新自定义程序包（控制台）

要更新自定义软件包，请在Amazon S3 Control，在 Amazon ES 中更新软件包，然后应用更新。

  1. 在 Amazon ES 控制台中，选择软件包。

  2. 选择一个软件包，然后更新软件包。

  3. 提供文件的 S3 路径，然后选择更新软件包。

  4. 返回到 Packages (程序包) 屏幕。

  5. 当软件包状态更改为Available下，将其选择。然后选择一个或多个关联域应用更新，并确认。等待关联状态更改为处于活动状态。

  6. 接下来的步骤因您配置索引的方式而异：

    • 如果您的域运行 Elasticsearch 7.8 或更高版本，并且仅使用带有可更新字段设置为 true，您无需再采取任何进一步操作。亚马逊 ES 自动更新您的索引，使用_ 开放式发布/刷新 _ 搜索 _ 分析器 API。

    • 如果您的域运行较早版本的 Elasticsearch、使用索引分析器或者不使用updateable字段中，请参阅手动索引更新。

虽然控制台是最简单的方法，但您还可以使用Amazon CLI、开发工具包或配置 API 更新 Amazon ES 程序包。有关更多信息，请参阅 。Amazon CLI命令参考和Amazon Elasticsearch Service 的配置 API 参考。

自动化软件包更新 (Python)

您可以使用 SDK 自动执行更新过程，而不是在控制台中手动更新软件包。以下示例 Python 脚本将新的软件包文件上传到 Amazon S3，更新 Amazon ES 中的软件包，并将新软件包应用到指定的域。确认更新成功后，它会对 Elasticsearch 进行示例调用，以证明新的同义词已被应用。

必须提供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 ES 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 ES 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()
awsauth = AWS4Auth(credentials.access_key, credentials.secret_key, region, service, session_token=credentials.token)

# ****** Upload file to S3 ******

def upload_to_s3(file_name, bucket_name, s3_key):

  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.')

# ****** Update the package in ES *******

def update_package(package_id, bucket_name, s3_key):

  es = boto3.client('es')
  print(package_id, bucket_name, s3_key)
  response = es.update_package(
      PackageID= package_id,
      PackageSource={
          'S3BucketName': bucket_name,
          'S3Key': s3_key
      }
  )
  print(response)

# Associate the package to the domain
def associate_package(package_id, domain_name):

  es = boto3.client('es')
  response = es.associate_package(PackageID=package_id, DomainName=domain_name)
  print(response)
  print('Associating...')

# Wait for the package to be updated
def wait_for_update(domain_name, package_id):

  es = boto3.client('es')
  response = es.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)

# ****** Make sample search call to ES ******

def sample_search(query):

  path = '_search'
  params = {'q': query}
  url = host + path
  response = requests.get(url, params=params, auth=awsauth)
  print('Searching for ' + '"' + query + '"')
  print(response.text)
注意

如果您在运行脚本时收到 “未找到软件包” 错误时使用Amazon CLI，这可能意味着 Bto3 正在使用〜 /.aws/config 中指定的任何区域，这不是您的 S3 存储桶所在的区域。或者运行aws configure并指定正确的区域，或者将区域显式添加到客户端： 

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

手动索引更新

要使用更新的软件包，如果满足以下任何条件，则必须手动更新索引：

  • 您的域名运行弹性搜索 7.7 或更早版本。

  • 您可以使用自定义软件包作为索引分析器。

  • 您可以使用自定义软件包作为搜索分析器，但不包括可更新字段中返回的子位置类型。

要使用新的程序包文件更新分析器，您有两种选择：

  • 关闭并打开要更新的任何索引：

    POST my-index/_close
POST my-index/_open

  • 重新索引。首先，创建使用更新的同义词文件（或全新文件）的索引：

    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

取消关联并删除软件包

将程序包与域取消关联意味着：在创建新索引时，您不能再使用该文件。任何已经使用该文件的索引都可以继续使用它。

控制台是将程序包与域取消关联并将其从 Amazon ES 删除的最简单方法。从 Amazon ES 删除软件包不是将其从 Amazon S3 上的原始位置删除。

将程序包与域取消关联并将其从 Amazon ES（控制台）删除：

  1. 转至 https://aws.amazon.com，然后选择 Sign In to the Console (登录控制台)。

  2. 在 Analytics 下，选择 Elasticsearch Service。

  3. 在导航窗格中，选择您的域，然后选择 Packages (程序包) 选项卡。

  4. 选择程序包、Actions (操作)，然后选择则 Dissociate (取消关联)。确认您的选择。

  5. 等待程序包从列表中消失。您可能需要刷新浏览器。

  6. 如果要将程序包与其他域一起使用，请在此处停止。要继续删除程序包，请在导航窗格中选择 Packages (程序包)。

  7. 选择程序包，然后选择 Delete (删除)。

或者，使用 Amazon CLI、开发工具包或配置 API 取消程序包关联并删除程序包。有关更多信息，请参阅 。Amazon CLI命令参考和Amazon Elasticsearch Service 的配置 API 参考。