As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Importação e gerenciamento de pacotes no Amazon Service OpenSearch O Amazon OpenSearch Service permite que você faça upload de arquivos de dicionário personalizados, como palavras irrelevantes e sinônimos, e associe plug-ins ao seu domínio. Esses plug-ins podem ser pré-empacotados, personalizados ou de terceiros, o que dá a você flexibilidade para estender a funcionalidade do domínio. O termo genérico para todos esses tipos de arquivos é *pacotes*. + Os **arquivos de dicionário** ajudam a refinar os resultados da pesquisa instruindo OpenSearch a ignorar palavras comuns de alta frequência ou a tratar termos semelhantes, como “creme congelado”, “gelato” e “sorvete”, como equivalentes. Eles também podem melhorar a [redução à raiz](https://en.wikipedia.org/wiki/Stemming), como no plug-in de análise japonês (kuromoji). + **Os plug-ins pré-empacotados** fornecem funcionalidade integrada, como o plug-in Amazon Personalize, para gerar resultados de pesquisa personalizados. Esses plug-ins usam o tipo de pacote `ZIP-PLUGIN`. Para saber mais, consulte [Plugins por versão do mecanismo no Amazon OpenSearch Service](supported-plugins.md). + **Plug-ins personalizados e de terceiros** permitem adicionar atributos personalizados ou integrar com sistemas externos, o que oferece ainda mais flexibilidade ao domínio. Como acontece com os plug-ins pré-empacotados, você carrega os plug-ins personalizados como pacotes da `ZIP-PLUGIN`. Para plug-ins de terceiros, é necessário também importar a licença do plug-in e os arquivos de configuração como pacotes separados e associá-los ao domínio. Para saber mais, consulte os seguintes tópicos: + [Gerenciando plug-ins personalizados no Amazon OpenSearch Service](custom-plugins.md) + [Instalação de plug-ins de terceiros no Amazon OpenSearch Service](plugins-third-party.md) **nota** Você pode associar até 20 plug-ins a um único domínio. Esse limite inclui todos os tipos de plug-ins: opcionais, de terceiros e personalizados. **Topics** + [Permissões obrigatórias](#custom-packages-iam) + [Carregar pacotes para o Amazon S3](#custom-packages-gs) + [Importação e associação de pacotes](#custom-packages-assoc) + [Usando pacotes com OpenSearch](#custom-packages-using) + [Atualização de pacotes](#custom-packages-updating) + [Atualizar manualmente os índices com um novo dicionário](#custom-packages-updating-index-analyzers) + [Dissociação e remoção de pacotes](#custom-packages-dissoc) + [Gerenciando plug-ins personalizados no Amazon OpenSearch Service](custom-plugins.md) + [Instalação de plug-ins de terceiros no Amazon OpenSearch Service](plugins-third-party.md) ## Permissões obrigatórias Usuários sem acesso de administrador precisam de determinadas ações AWS Identity and Access Management (IAM) para gerenciar pacotes: + `es:CreatePackage`: criar um pacote + `es:DeletePackage`: excluir um pacote + `es:AssociatePackage`: associar um pacote a um domínio + `es:DissociatePackage`: desassociar um pacote de um domínio Você também precisa de permissões no caminho do bucket do Amazon S3 ou no objeto em que o pacote personalizado reside. Conceda todas as permissões no IAM, e não na política de acesso ao domínio. Para saber mais, consulte [Identity and Access Management no Amazon OpenSearch Service](ac.md). ## Carregar pacotes para o Amazon S3 Esta seção aborda como carregar pacotes de dicionários personalizados, já que os pacotes de plug-ins pré-empacotados já estão pré-instalados. Antes de associar um dicionário customizado ao seu domínio, você deverá carregá-lo em um bucket do Amazon S3. Para saber mais, consulte [Carregar objetos](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html) no *Manual do usuário do Amazon Simple Storage Service*. Plug-ins compatíveis não precisam ser carregados. Se seu dicionário contiver informações confidenciais, especifique a [criptografia do lado do servidor com chaves gerenciadas pelo S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingServerSideEncryption.html) ao fazer o upload. OpenSearch O serviço não pode acessar arquivos no S3 que você protege usando uma AWS KMS chave. Depois de carregar o arquivo, anote o caminho do S3. O formato do caminho é `s3://amzn-s3-demo-bucket/file-path/file-name`. Você pode usar o seguinte arquivo de sinônimos para fazer testes. Salve-o como `synonyms.txt`. ``` danish, croissant, pastry ice cream, gelato, frozen custard sneaker, tennis shoe, running shoe basketball shoe, hightop ``` Certos dicionários, como dicionários Hunspell, usam vários arquivos e exigem seus próprios diretórios no sistema de arquivos. No momento, o OpenSearch Service oferece suporte apenas a dicionários de arquivo único. ## Importação e associação de pacotes O console é a maneira mais simples de importar um dicionário personalizado para o OpenSearch Service. Quando você importa um dicionário do Amazon S3, o OpenSearch Service armazena sua própria cópia do pacote e criptografa automaticamente essa cópia usando AES-256 com chaves gerenciadas pelo serviço. OpenSearch Os plug-ins opcionais já estão pré-instalados no OpenSearch Service, então você não precisa carregá-los sozinho, mas precisa associar um plug-in a um domínio. Os plug-ins disponíveis estão listados na tela **Pacotes**, no console. ### Importar e associar um pacote a um domínio 1. No console do Amazon OpenSearch Service, escolha **Pacotes**. 1. Escolha **Import package** (Importar pacote). 1. Dê um nome descritivo ao pacote. 1. Forneça o caminho do S3 até o arquivo e selecione **Import (Importar)**. 1. Retorne à tela **Pacotes**. 1. Quando o status do pacote estiver **Disponível**, selecione-o. 1. Escolha **Associar a um domínio**. 1. Selecione um domínio e escolha **Avançar**. Revise os pacotes e escolha **Associar**. 1. No painel de navegação, escolha o domínio vá para a guia **Pacotes**. 1. Se o pacote for um dicionário personalizado, anote o ID quando o pacote se tornar **Disponível**. Use `analyzers/id` como caminho do arquivo em [solicitações para OpenSearch](#custom-packages-using). ## Usando pacotes com OpenSearch Esta seção aborda como usar os dois tipos de pacotes: dicionários personalizados e plug-ins opcionais. ### Uso de dicionários customizados Depois de associar um arquivo a um domínio, será possível usá-lo em parâmetros como `synonyms_path`, `stopwords_path` e `user_dictionary` ao criar tokenizadores e filtros de token. O parâmetro exato varia de acordo com o objeto. Vários objetos oferecem suporte a `synonyms_path` e `stopwords_path`, mas `user_dictionary` é exclusivo para o plug-in kuromoji. Para o plug-in de análise IK (chinês), você pode carregar um arquivo de dicionário personalizado como um pacote personalizado e associá-lo a um domínio, e o plug-in o seleciona automaticamente sem exigir um parâmetro `user_dictionary`. Se seu arquivo for um arquivo de sinônimos, use o parâmetro `synonyms_path`. O seguinte exemplo adiciona um arquivo de sinônimo a um novo í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 solicitação cria um analisador personalizado para o índice que utiliza o tokenizer padrão e um filtro de token de sinônimo. + Os tokenizers quebram fluxos de caracteres em *tokens* (normalmente palavras) de acordo com algum conjunto de regras. O exemplo mais simples é o tokenizer de espaço em branco, que divide os caracteres anteriores em um token cada vez que encontra um caractere de espaço em branco. Um exemplo mais complexo é o tokenizer padrão, que usa um conjunto de regras com base na gramática para trabalhar em vários idiomas. + Os filtros de token adicionam, modificam ou excluem tokens. Por exemplo, um filtro de token de sinônimo adiciona tokens quando encontra uma palavra na lista de sinônimos. O filtro de token de palavras irrelevantes remove tokens quando encontra uma palavra na lista de palavras irrelevantes. Essa solicitação também adiciona um campo de texto (`description`) ao mapeamento e solicita OpenSearch o uso do novo analisador como analisador de pesquisa. Você pode ver que ele ainda usa o analisador padrão como seu analisador de índices. Finalmente, observe a linha `"updateable": true` no filtro de token. Este campo aplica-se somente a analisadores de pesquisas, e não a analisadores de índices, e será crítico se você desejar [atualizar o analisador de pesquisas](#custom-packages-updating) automaticamente. Para fazer testes, adicione alguns documentos ao í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" } ``` Depois, pesquise-os usando um sinônimo: ``` GET my-index/_search { "query": { "match": { "description": "gelato" } } } ``` Nesse caso, OpenSearch retorna a seguinte resposta: ``` { "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" } }] } } ``` **dica** Arquivos de dicionário usam espaço de heap Java proporcional ao seu tamanho. Por exemplo, um arquivo de dicionário de 2 GiB pode consumir 2 GiB de espaço de heap em um nó. Ao usar arquivos grandes, verifique se os nós têm espaço de heap suficiente para acomodá-los. [Monitore](managedomains-cloudwatchmetrics.md#managedomains-cloudwatchmetrics-cluster-metrics) a métrica `JVMMemoryPressure` e dimensione o cluster conforme necessário. ### Usar plug-ins pré-empacotados OpenSearch O serviço permite que você associe OpenSearch plug-ins opcionais pré-instalados para usar com seu domínio. Um pacote de plug-in pré-empacotado é compatível com uma OpenSearch versão específica e só pode ser associado a domínios com essa versão. A lista de pacotes disponíveis para seu domínio inclui todos os plug-ins compatíveis com a versão do seu domínio. Depois de associar um plug-in a um domínio, um processo de instalação no domínio é iniciado. Em seguida, você pode referenciar e usar o plug-in ao fazer solicitações ao OpenSearch Serviço. Associar e dissociar um plug-in requer uma implantação. blue/green Para obter mais informações, consulte [Mudanças que geralmente causam blue/green implantações](managedomains-configuration-changes.md#bg). Plug-ins opcionais incluem analisadores de idioma e resultados de pesquisa personalizados. Por exemplo, o plug-in Amazon Personalize Search Ranking usa machine learning para personalizar os resultados da pesquisa para seus clientes. Para obter mais informações sobre esse plug-in, consulte [Personalização dos resultados da pesquisa de OpenSearch](https://docs.aws.amazon.com/personalize/latest/dg/personalize-opensearch.html). Para obter uma lista de todos os plug-ins compatíveis, consulte [Plugins por versão do mecanismo no Amazon OpenSearch Service](supported-plugins.md). #### Plug-in Sudachi Quando você reassocia um arquivo de dicionário do [plug-in Sudachi](https://github.com/WorksApplications/elasticsearch-sudachi), ele não reflete imediatamente no domínio. O dicionário é atualizado quando a próxima blue/green implantação é executada no domínio como parte de uma alteração de configuração ou outra atualização. Como alternativa, você pode criar um novo pacote com os dados atualizados, criar um novo índice usando esse novo pacote, reindexar o índice existente ao novo e, em seguida, excluir o índice antigo. Se preferir usar a abordagem de reindexação, use um alias de índice para que não haja interrupções no tráfego. Além disso, o plug-in Sudachi suporta apenas dicionários binários do Sudachi, que você pode carregar com a operação da API. [CreatePackage](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_CreatePackage.html) Para obter informações sobre o dicionário do sistema pré-construído e o processo para compilar dicionários do usuário, consulte a [documentação do Sudachi](https://github.com/WorksApplications/elasticsearch-sudachi). **nota** Ao fazer o upload de arquivos de dicionário binário para o Amazon S3, você deve definir o tipo de conteúdo do objeto do S3 como. `binary/octet-stream` O uso `application/octet-stream` fará com que a importação do pacote falhe. O exemplo a seguir demonstra como usar os dicionários do sistema e do usuário com o tokenizador do Sudachi. Você deve carregar esses dicionários como pacotes personalizados com tipo `TXT-DICTIONARY` e fornecer o pacote IDs nas configurações adicionais. ``` 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" } } } } } } ``` ## Atualização de pacotes Esta seção aborda apenas como atualizar um pacote de dicionário personalizado, porque os pacotes de plug-ins pré-empacotados já foram atualizados para você. O upload de uma nova versão de um dicionário para o Amazon S3 *não* atualiza automaticamente o pacote no Amazon OpenSearch Service. OpenSearch O serviço armazena sua própria cópia do arquivo, portanto, se você fizer upload de uma nova versão para o S3, deverá atualizá-la manualmente. Cada um dos seus domínios associados armazena *sua* própria cópia do arquivo também. Para manter o comportamento de pesquisa previsível, os domínios continuarão a usar a versão atual do pacote até que você os atualize explicitamente. Para atualizar um pacote personalizado, modifique o arquivo Amazon S3 Control, atualize o pacote no OpenSearch Serviço e, em seguida, aplique a atualização. ### Console 1. No console de OpenSearch serviço, escolha **Pacotes**. 1. Escolha um pacote e, em seguida, **Atualizar**. 1. Forneça um novo caminho do S3 para o arquivo e escolha **Atualizar pacote**. 1. Retorne à tela **Pacotes**. 1. Quando o status do pacote mudar para **Disponível**, selecione-o. Em seguida, escolha um ou mais domínios associados, **Aplicar atualização** e confirme. Aguarde até que o status da associação mude para **Ativo**. 1. As próximas etapas variam dependendo de como você configurou os índices: + Se seu domínio está executando OpenSearch o Elasticsearch 7.8 ou posterior e usa apenas analisadores de pesquisa com o campo [atualizável](#custom-packages-using) definido como verdadeiro, você não precisa realizar nenhuma ação adicional. OpenSearch O serviço atualiza automaticamente seus índices usando a API [\$1plugins/\$1refresh\$1search\$1analyzers](https://docs.opensearch.org/latest/im-plugin/refresh-analyzer/index/). + Se o seu domínio estiver executando o Elasticsearch 7.7 ou anterior, usa analisadores de índices ou não usa o campo `updateable`, consulte [Atualizar manualmente os índices com um novo dicionário](#custom-packages-updating-index-analyzers). Embora o console seja o método mais simples, você também pode usar a API de configuração AWS CLI SDKs, ou para atualizar pacotes OpenSearch de serviços. Para obter mais informações, consulte a Referência de [AWS CLI Comandos e a Referência](https://docs.aws.amazon.com/cli/latest/reference/) da [API do Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/Welcome.html). ### AWS SDK Em vez de atualizar manualmente um pacote no console, você pode usar o SDKs para automatizar o processo de atualização. O exemplo de script Python a seguir carrega um novo arquivo de pacote no Amazon S3, atualiza o pacote no OpenSearch Service e aplica o novo pacote ao domínio especificado. Depois de confirmar que a atualização foi bem-sucedida, ele faz uma chamada de amostra para OpenSearch demonstrar que os novos sinônimos foram aplicados. Você deve fornecer valores para `host`, `region`, `file_name`, `bucket_name`, `s3_key`, `package_id`, `domain_name` e `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** Se você receber um erro de “pacote não encontrado” ao executar o script usando o AWS CLI, provavelmente significa que o Boto3 está usando a região especificada em \$1/.aws/config, que não é a região em que seu bucket do S3 está. Execute `aws configure` e especifique a região correta ou adicione explicitamente a região ao cliente: ``` client = boto3.client('opensearch', region_name='us-east-1') ``` ## Atualizar manualmente os índices com um novo dicionário As atualizações manuais de índice se aplicam somente aos dicionários personalizados, não aos plug-ins pré-empacotados. Para usar um dicionário atualizado, será necessário atualizar manualmente seus índices se você atender a qualquer uma das seguintes condições: + Seu domínio executa o Elasticsearch 7.7 ou anterior. + Você usa pacotes personalizados como analisadores de índices. + Você usa pacotes personalizados como analisadores de pesquisas, mas não inclui o campo [atualizável](#custom-packages-using). Para atualizar os analisadores com os novos arquivos de pacote, você tem duas opções: + Feche e abra todos os índices que deseja atualizar: ``` POST my-index/_close POST my-index/_open ``` + Reindexe os índices. Primeiro, crie um índice que use o arquivo de sinônimos atualizado (ou um arquivo inteiramente novo). Observe que apenas o UTF-8 é compatível. ``` 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" } } } } ``` Depois [reindexe](https://docs.opensearch.org/latest/opensearch/reindex-data/) o índice antigo para o novo: ``` POST _reindex { "source": { "index": "my-index" }, "dest": { "index": "my-new-index" } } ``` Se você atualiza analisadores de índices com frequência, use [aliases de índices](https://docs.opensearch.org/latest/opensearch/index-alias/) para manter um caminho consistente para o índice mais recente: ``` POST _aliases { "actions": [ { "remove": { "index": "my-index", "alias": "latest-index" } }, { "add": { "index": "my-new-index", "alias": "latest-index" } } ] } ``` Se não precisar do índice antigo, exclua-o: ``` DELETE my-index ``` ## Dissociação e remoção de pacotes Desassociar um pacote, seja um dicionário personalizado ou um plug-in pré-empacotado, de um domínio significa que você não poderá mais usar esse pacote ao criar novos índices. Depois que um pacote é dissociado, os índices existentes que estavam usando o pacote não podem mais usá-lo. Você deve remover o pacote de qualquer índice antes de poder dissociá-lo, caso contrário, a dissociação falhará. O console é a maneira mais simples de dissociar um pacote de um domínio e removê-lo do OpenSearch Serviço. Remover um pacote do OpenSearch Serviço *não* o remove de sua localização original no Amazon S3. ### Desassociar um pacote de um domínio 1. Faça login no console do Amazon OpenSearch Service em [https://console.aws.amazon.com/aos/casa](https://console.aws.amazon.com/aos/home). 1. No painel de navegação à esquerda, escolha **Domínios**. 1. Escolha o domínio e navegue até a guia **Pacotes**. 1. Escolha um pacote, **Ações** e **Dissociar**. Confirme sua escolha. 1. Aguarde até que o pacote desapareça da lista. Talvez seja necessário atualizar o navegador. 1. Se desejar usar o pacote com outros domínios, pare aqui. Para continuar com a remoção do pacote (se for um dicionário customizado), escolha **Pacotes** no painel de navegação. 1. Selecione o pacote e **Excluir**. Como alternativa, use a API de configuração AWS CLI SDKs, ou para dissociar e remover pacotes. Para obter mais informações, consulte a Referência de [AWS CLI Comandos e a Referência](https://docs.aws.amazon.com/cli/latest/reference/) da [API do Amazon OpenSearch Service](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/Welcome.html).