Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # Importación y gestión de paquetes en Amazon OpenSearch Service Amazon OpenSearch Service te permite subir archivos de diccionarios personalizados, como palabras vacías y sinónimos, y asociar complementos a tu dominio. Estos complementos pueden ser preempaquetados, personalizados o de terceros, lo que le brinda flexibilidad para ampliar la funcionalidad de su dominio. El término genérico para referirse a todos estos tipos de archivos es *paquetes*. + Los **archivos de diccionario** ayudan a refinar los resultados de búsqueda, ya OpenSearch que indican que hay que ignorar las palabras más frecuentes o tratar términos similares, como «crema congelada», «helado» o «helado», como equivalentes. También pueden mejorar la [derivación](https://en.wikipedia.org/wiki/Stemming), como se observa con el complemento de análisis japonés (kuromoji). + **Los complementos preempaquetados** ofrecen funciones integradas, como el complemento Amazon Personalize para obtener resultados de búsqueda personalizados. Estos complementos utilizan el tipo de paquete `ZIP-PLUGIN`. Para obtener más información, consulte [Plugins por versión de motor en Amazon OpenSearch Service](supported-plugins.md). + **Los complementos personalizados y de terceros** le permiten agregar características personalizadas o integrarlos con sistemas externos, lo que ofrece aún más flexibilidad para su dominio. Al igual que los complementos preempaquetados, sube los complementos personalizados como paquetes `ZIP-PLUGIN`. En el caso de los complementos de terceros, también debe importar los archivos de licencia y configuración del complemento como paquetes independientes y, a continuación, asociarlos todos al dominio. Para obtener más información, consulte los temas siguientes: + [Gestión de complementos personalizados en Amazon OpenSearch Service](custom-plugins.md) + [Instalación de complementos de terceros en Amazon OpenSearch Service](plugins-third-party.md) **nota** Puede asociar un máximo de 20 complementos con un único dominio. Este límite incluye todos los tipos de complementos: opcionales, de terceros y personalizados. **Topics** + [Permisos necesarios](#custom-packages-iam) + [Carga de paquetes en Amazon S3](#custom-packages-gs) + [Importación y asociación de paquetes](#custom-packages-assoc) + [Uso de paquetes con OpenSearch](#custom-packages-using) + [Actualización de paquetes](#custom-packages-updating) + [Actualización manual de los índices con un nuevo diccionario](#custom-packages-updating-index-analyzers) + [Disociación y eliminación de paquetes](#custom-packages-dissoc) + [Gestión de complementos personalizados en Amazon OpenSearch Service](custom-plugins.md) + [Instalación de complementos de terceros en Amazon OpenSearch Service](plugins-third-party.md) ## Permisos necesarios Los usuarios sin acceso de administrador requieren ciertas acciones AWS Identity and Access Management (IAM) para poder administrar los paquetes: + `es:CreatePackage`: crear un paquete + `es:DeletePackage`: eliminar un paquete + `es:AssociatePackage`: asociar un paquete a un dominio + `es:DissociatePackage`: disociar un paquete de un dominio También necesita permisos en la ruta del bucket de Amazon S3 u objeto donde reside el paquete personalizado. Otorgue todos los permisos en IAM, no en la política de acceso al dominio. Para más información, consulte [Identity and Access Management en Amazon OpenSearch Service](ac.md). ## Carga de paquetes en Amazon S3 Esta sección explica cómo cargar paquetes de diccionarios personalizados, dado que los paquetes de complementos prediseñados ya están instalados. Antes de poder asociar un diccionario personalizado a un dominio, debe cargarlo en un bucket de Amazon S3. Para ver las instrucciones, consulte [Carga de objetos](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html) en la *Guía del usuario de Amazon Simple Storage Service*. No es necesario cargar los complementos admitidos. Si su diccionario contiene información confidencial, especifique el [cifrado del lado del servidor con claves administradas por S3 cuando](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingServerSideEncryption.html) lo cargue. OpenSearch El servicio no puede acceder a los archivos de S3 que protejas con una clave. AWS KMS Después de cargar el archivo, tome nota de su ruta de S3. El formato de la ruta es `s3://amzn-s3-demo-bucket/file-path/file-name`. Puede utilizar el siguiente archivo de sinónimos para fines de prueba. Guárdelo como `synonyms.txt`. ``` danish, croissant, pastry ice cream, gelato, frozen custard sneaker, tennis shoe, running shoe basketball shoe, hightop ``` Algunos diccionarios, como los diccionarios Hunspell, utilizan varios archivos y requieren sus propios directorios en el sistema de archivos. En este momento, el OpenSearch servicio solo admite diccionarios de un solo archivo. ## Importación y asociación de paquetes La consola es la forma más sencilla de importar un diccionario personalizado a OpenSearch Service. Al importar un diccionario de Amazon S3, OpenSearch Service almacena su propia copia del paquete y la cifra automáticamente mediante AES-256 con OpenSearch claves administradas por el servicio. Los complementos opcionales ya vienen preinstalados en el OpenSearch Servicio, por lo que no es necesario que los cargue usted mismo, pero sí que tiene que asociar un complemento a un dominio. Los complementos disponibles aparecen en la pantalla **Paquetes** de la consola. ### Para importar y asociar un paquete a un dominio 1. En la consola OpenSearch de Amazon Service, selecciona **Paquetes**. 1. Elija **Import package** (Importar paquete). 1. Asigne al paquete un nombre descriptivo. 1. Proporcione la ruta de S3 al archivo y, a continuación, elija **Importar**. 1. Vuelva a la pantalla **Paquetes**. 1. Cuando el estado del paquete sea **Disponible**, elíjalo. 1. Seleccione **Asociar a un dominio**. 1. Seleccione un dominio y, a continuación, elija **Siguiente**. Revise los paquetes y seleccione **Asociar**. 1. En el panel de navegación, seleccione el dominio y, a continuación, vaya a la pestaña **Paquetes**. 1. Si el paquete es un diccionario personalizado, anote el ID cuando el paquete esté **disponible**. `analyzers/id`Utilízala como ruta del archivo en [las solicitudes para OpenSearch](#custom-packages-using). ## Uso de paquetes con OpenSearch Esta sección explica cómo usar ambos tipos de paquetes: diccionarios personalizados y complementos prediseñados. ### Uso de diccionarios personalizados Después de asociar un archivo a un dominio, puede usarlo en parámetros como `synonyms_path`, `stopwords_path` y `user_dictionary` al crear generadores de tokens y filtros de token. El parámetro exacto varía según el objeto. Varios objetos admiten `synonyms_path` y `stopwords_path`, pero `user_dictionary` es exclusivo del complemento kuromoji. Para el complemento IK (chino) Analysis, puede cargar un archivo de diccionario personalizado en forma de paquete personalizado y asociarlo a un dominio, y el complemento lo recogerá automáticamente sin necesidad de parámetro `user_dictionary`. Si se trata de un archivo de sinónimos, utilice el parámetro `synonyms_path`. El siguiente ejemplo agrega un archivo de sinónimos a un nuevo índice: ``` 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" } } } } ``` Esta solicitud crea un analizador personalizado para el índice que utiliza el generador de tokens estándar y un filtro de token de sinónimos. + Los generadores de tokens dividen las secuencias de caracteres en *tokens* (normalmente palabras) en función de algún conjunto de reglas. El ejemplo más simple es el generador de tokens de espacios en blanco, que divide los caracteres anteriores en un token cada vez que encuentra un carácter de espacio en blanco. Un ejemplo más complejo es el generador de tokens estándar, que utiliza un conjunto de reglas gramaticales para funcionar en muchos idiomas. + Los filtros de tokens agregan, modifican o eliminan tokens. Por ejemplo, un filtro de token de sinónimos agrega tokens cuando encuentra una palabra en la lista de sinónimos. El filtro de tokens de palabras vacías elimina los tokens cuando encuentra una palabra en la lista de palabras vacías. Esta solicitud también agrega un campo de texto (`description`) al mapeo e indica OpenSearch que se use el nuevo analizador como analizador de búsqueda. Puede ver que todavía utiliza el analizador estándar como analizador de índices. Por último, tenga en cuenta la línea `"updateable": true` en el filtro de token. Este campo solo se aplica a los analizadores de búsqueda, no a los analizadores de índice, y es crítico si luego desea [actualizar el analizador de búsqueda](#custom-packages-updating) de forma automática. Con fines de prueba, agregue algunos documentos al índice: ``` 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" } ``` A continuación, use un sinónimo para buscarlos: ``` GET my-index/_search { "query": { "match": { "description": "gelato" } } } ``` En este caso, OpenSearch devuelve la siguiente respuesta: ``` { "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" } }] } } ``` **sugerencia** Los archivos de diccionario utilizan espacio de montón de Java proporcional a su tamaño. Por ejemplo, un archivo de diccionario de 2 GiB podría consumir 2 GiB de espacio de montón en un nodo. Si utiliza archivos de gran tamaño, asegúrese de que los nodos tengan suficiente espacio en el montón para acomodarlos. [Monitoree](managedomains-cloudwatchmetrics.md#managedomains-cloudwatchmetrics-cluster-metrics) la métrica `JVMMemoryPressure` y escale el clúster según sea necesario. ### Uso de complementos preempaquetados OpenSearch El servicio le permite asociar OpenSearch complementos opcionales preinstalados para usarlos con su dominio. Un paquete de complementos preempaquetado es compatible con una OpenSearch versión específica y solo se puede asociar a los dominios con esa versión. La lista de paquetes disponibles para su dominio incluye todos los complementos compatibles con la versión de su dominio. Después de asociar un complemento a un dominio, comienza un proceso de instalación en el dominio. Luego, puedes hacer referencia al complemento y usarlo cuando realices solicitudes al OpenSearch Servicio. La asociación y disociación de un complemento requiere una implementación. blue/green Para obtener más información, consulte [Cambios que suelen provocar blue/green despliegues](managedomains-configuration-changes.md#bg). Los complementos opcionales incluyen analizadores de idioma y resultados de búsqueda personalizados. Por ejemplo, el complemento Amazon Personalize Search Ranking utiliza machine learning para personalizar los resultados de búsqueda para sus clientes. Para obtener más información sobre este complemento, consulte [Personalización](https://docs.aws.amazon.com/personalize/latest/dg/personalize-opensearch.html) de los resultados de búsqueda desde. OpenSearch Para ver una lista de todos los complementos admitidos, consulte [Plugins por versión de motor en Amazon OpenSearch Service](supported-plugins.md). #### Complemento Sudachi En el caso del [complemento Sudachi](https://github.com/WorksApplications/elasticsearch-sudachi), al volver a asociar un archivo de diccionario, no se refleja inmediatamente en el dominio. El diccionario se actualiza cuando se ejecuta la siguiente blue/green implementación en el dominio como parte de un cambio de configuración u otra actualización. Como alternativa, puede crear un nuevo paquete con los datos actualizados, crear un nuevo índice con un nuevo paquete, volver a indexar el índice existente en el nuevo índice y, a continuación, eliminar el índice anterior. Si prefiere utilizar el enfoque de reindexación, utilice un alias de índice para que no se interrumpa el tráfico. Además, el complemento Sudachi solo admite los diccionarios binarios de Sudachi, que se pueden cargar con la operación de la [CreatePackage](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_CreatePackage.html)API. Para obtener información sobre el diccionario del sistema prediseñado y el proceso de compilación de diccionarios de usuario, consulte [Documentación de Sudachi](https://github.com/WorksApplications/elasticsearch-sudachi). **nota** Al cargar archivos de diccionarios binarios a Amazon S3, debe establecer el tipo de contenido del objeto S3 en. `binary/octet-stream` Si `application/octet-stream` se utiliza, se producirá un error en la importación del paquete. En el siguiente ejemplo, se muestra cómo utilizar los diccionarios de sistema y de usuario con el tokenizador de Sudachi. Debe cargar estos diccionarios como paquetes personalizados con el tipo `TXT-DICTIONARY` y proporcionar su paquete IDs en la configuración adicional. ``` 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" } } } } } } ``` ## Actualización de paquetes En esta sección solo se explica cómo actualizar un paquete de diccionarios personalizados, ya que los paquetes de complementos preempaquetados ya están actualizados. Al cargar una nueva versión de un diccionario en Amazon S3, el paquete *no* se actualiza automáticamente en Amazon OpenSearch Service. OpenSearch El servicio almacena su propia copia del archivo, por lo que si subes una nueva versión a S3, tendrás que actualizarla manualmente. Cada uno de los dominios asociados también almacena *su* propia copia del archivo. Para mantener el comportamiento de búsqueda predecible, los dominios siguen utilizando la versión actual del paquete hasta que los actualice explícitamente. Para actualizar un paquete personalizado, modifique el archivo Amazon S3 Control, actualice el paquete en OpenSearch Service y, a continuación, aplique la actualización. ### Consola 1. En la consola OpenSearch de servicio, selecciona **Paquetes**. 1. Seleccione un paquete y luego **Actualizar**. 1. Proporcione una nueva ruta de S3 al archivo y, a continuación, seleccione **Actualizar paquete**. 1. Vuelva a la pantalla **Paquetes**. 1. Cuando el estado del paquete cambie a **Disponible**, selecciónelo. A continuación, seleccione uno o más dominios asociados, **Aplicar actualización** y confirme. Espere a que el estado de asociación cambie a **Activo**. 1. Los siguientes pasos variarán en función de cómo haya configurado los índices: + Si tu dominio ejecuta OpenSearch Elasticsearch 7.8 o una versión posterior y solo usa analizadores de búsqueda con el campo [actualizable](#custom-packages-using) establecido en true, no necesitas realizar ninguna otra acción. OpenSearch [El servicio actualiza automáticamente tus índices mediante la API \$1plugins/\$1refresh\$1search\$1analyzers.](https://docs.opensearch.org/latest/im-plugin/refresh-analyzer/index/) + Si el dominio ejecuta Elasticsearch 7.7 o una versión anterior, utiliza analizadores de índice o no utiliza el campo `updateable`, consulte [Actualización manual de los índices con un nuevo diccionario](#custom-packages-updating-index-analyzers). Si bien la consola es el método más sencillo, también puedes usar la API, o la API de configuración para actualizar los paquetes de servicio. AWS CLI SDKs OpenSearch Para obtener más información, consulta la Referencia de [AWS CLI comandos y la Referencia](https://docs.aws.amazon.com/cli/latest/reference/) de la [API de Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/Welcome.html). ### AWS SDK En lugar de actualizar manualmente un paquete en la consola, puede utilizar el SDKs para automatizar el proceso de actualización. El siguiente script de Python de ejemplo carga un nuevo archivo de paquete en Amazon S3, actualiza el paquete en OpenSearch Service y aplica el nuevo paquete al dominio especificado. Tras confirmar que la actualización se ha realizado correctamente, realiza un ejemplo de llamada para OpenSearch demostrar que se han aplicado los nuevos sinónimos. Debe proporcionar valores para `host`, `region`, `file_name`, `bucket_name`, `s3_key`, `package_id`, `domain_name` y `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) ``` **nota** Si recibes un error que indica que no se ha encontrado el paquete al ejecutar el script AWS CLI, es probable que Boto3 esté utilizando la región especificada en \$1/.aws/config, que no es la región en la que se encuentra tu bucket de S3. Puede ejecutar `aws configure` y especificar la región correcta o agregar explícitamente la región al cliente: ``` client = boto3.client('opensearch', region_name='us-east-1') ``` ## Actualización manual de los índices con un nuevo diccionario Las actualizaciones manuales de índices solo se aplican a los diccionarios personalizados, no a los complementos preempaquetados. Para utilizar un diccionario actualizado, debe actualizar de forma manual los índices, si cumple alguna de las siguientes condiciones: + El dominio ejecuta Elasticsearch 7.7 o anterior. + Utiliza paquetes personalizados como analizadores de índices. + Utiliza paquetes personalizados como analizadores de búsqueda, pero no incluye el campo [actualizable](#custom-packages-using). Para actualizar los analizadores con los nuevos archivos de paquete, dispone de dos opciones: + Cierre y abra los índices que desee actualizar: ``` POST my-index/_close POST my-index/_open ``` + Vuelva a indexar los índices. Primero, cree un índice que utilice el archivo de sinónimos actualizado (o un archivo completamente nuevo). Tenga en cuenta que solo se admite 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" } } } } ``` Luego [vuelva a indexar](https://docs.opensearch.org/latest/opensearch/reindex-data/) el índice anterior con ese nuevo índice: ``` POST _reindex { "source": { "index": "my-index" }, "dest": { "index": "my-new-index" } } ``` Si actualiza con frecuencia los analizadores de índices, utilice [alias de índice](https://docs.opensearch.org/latest/opensearch/index-alias/) para mantener una ruta coherente al índice más reciente: ``` POST _aliases { "actions": [ { "remove": { "index": "my-index", "alias": "latest-index" } }, { "add": { "index": "my-new-index", "alias": "latest-index" } } ] } ``` Si no necesita el índice anterior, elimínelo: ``` DELETE my-index ``` ## Disociación y eliminación de paquetes Si disocia un paquete de un dominio, ya sea un diccionario personalizado o un complemento preempaquetado, ya no podrá usar ese paquete cuando cree nuevos índices. Una vez disociado un paquete, los índices existentes que utilizaban el paquete ya no pueden usarlo. Debe eliminar el paquete de cualquier índice antes de poder disociarlo; de lo contrario, la disociación fallará. La consola es la forma más sencilla de disociar un paquete de un dominio y eliminarlo del Servicio. OpenSearch Al eliminar un paquete del OpenSearch Servicio, *no* se elimina de su ubicación original en Amazon S3. ### Disociar un paquete de un dominio 1. Inicia sesión en la consola OpenSearch de Amazon Service desde [https://console.aws.amazon.com/aos/casa](https://console.aws.amazon.com/aos/home). 1. En el panel de navegación, elija **Dominios**. 1. Elija el dominio y, a continuación, vaya a la pestaña **Paquetes**. 1. Seleccione un paquete, **Acciones** y, a continuación, seleccione **Disociar**. Confirme su elección. 1. Espere a que el paquete desaparezca de la lista. Puede que tenga que actualizar el navegador. 1. Si desea utilizar el paquete con otros dominios, deténgase aquí. Para continuar con la eliminación del paquete (si es un diccionario personalizado), seleccione **Paquetes** en el panel de navegación. 1. Seleccione el paquete y elija **Eliminar**. También puede utilizar la API de configuración o la AWS CLI API de configuración para disociar y eliminar paquetes. SDKs Para obtener más información, consulta la Referencia de [AWS CLI comandos y la Referencia](https://docs.aws.amazon.com/cli/latest/reference/) de la [API de Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/Welcome.html).