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á.
# Gerenciando plug-ins personalizados no Amazon OpenSearch Service
Usando plug-ins personalizados para o OpenSearch Serviço, você pode estender a OpenSearch funcionalidade em áreas como análise de linguagem, filtragem personalizada, classificação e muito mais, possibilitando a criação de experiências de pesquisa personalizadas. Os plug-ins personalizados para OpenSearch podem ser desenvolvidos estendendo a `org.opensearch.plugins.Plugin` classe e, em seguida, empacotando-a em um `.zip` arquivo.
As seguintes extensões de plug-in são atualmente suportadas pelo Amazon OpenSearch Service:
+ **AnalysisPlugin**— amplia a funcionalidade de análise adicionando, por exemplo, analisadores personalizados, tokenizadores de caracteres ou filtros para processamento de texto.
+ **SearchPlugin**— aprimora os recursos de pesquisa com tipos de consulta personalizados, algoritmos de similaridade, opções de sugestão e agregações.
+ **MapperPlugin**— Permite criar tipos de campo personalizados e suas configurações de mapeamento no OpenSearch, permitindo definir como diferentes tipos de dados devem ser armazenados e indexados.
+ **ScriptPlugin**— Permite adicionar recursos de script personalizados a OpenSearch, por exemplo, scripts personalizados para operações como pontuação, classificação e transformações de valores de campo durante a pesquisa ou indexação.
Você pode usar o console do OpenSearch Service ou os comandos de API existentes para pacotes personalizados para carregar e associar o plug-in ao cluster do Amazon OpenSearch Service. Você também pode usar o [DescribePackages](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_DescribePackages.html)comando para descrever todos os pacotes em sua conta e visualizar detalhes, como detalhes da OpenSearch versão e do erro. OpenSearch O serviço valida o pacote de plug-ins quanto à compatibilidade de versões, vulnerabilidades de segurança e operações permitidas do plug-in. Para saber mais sobre pacotes personalizados, consulte [Importação e gerenciamento de pacotes no Amazon Service OpenSearch](custom-packages.md).
**OpenSearch versão e Região da AWS suporte**
Os plug-ins personalizados são compatíveis com domínios OpenSearch de serviço que executam a OpenSearch versão 2.15 da seguinte forma: Regiões da AWS
+ Leste dos EUA (Ohio) (us-east-2)
+ Leste dos EUA (Norte da Virgínia) (us-east-1)
+ Oeste dos EUA (Oregon) (us-west-2)
+ Ásia-Pacífico (Mumbai) (ap-south-1)
+ Ásia-Pacífico (Seul) (ap-northeast-2)
+ Ásia-Pacífico (Singapura) (ap-southeast-1)
+ Ásia-Pacífico (Sydney) (ap-southeast-2)
+ Ásia Pacific (Tóquio) (ap-northeast-1)
+ Canadá (Central) (ca-central-1)
+ Europa (Frankfurt) (eu-central-1)
+ Europa (Irlanda) (eu-west-1)
+ Europa (Londres) (eu-west-2)
+ Europa (Paris) (eu-west-3)
+ América do Sul (São Paulo) (sa-east-1)
**nota**
Os plug-ins personalizados contêm código desenvolvido pelo usuário. Os problemas, incluindo violações de SLA, causados por código desenvolvido pelo usuário não são elegíveis a créditos de SLA. Para obter mais informações, consulte [Amazon OpenSearch Service - Service Level Agreement](https://aws.amazon.com/opensearch-service/sla/).
**Topics**
+ [Cotas de plug-ins](#plugin-limits)
+ [Pré-requisitos](#custom-plugin-prerequisites)
+ [Solução de problemas](#custom-plugin-troubleshooting)
+ [Instalar um plug-in personalizado usando o console](#custom-plugin-install-console)
+ [Gerenciando plug-ins personalizados usando o AWS CLI](#managing-custom-plugins-cli)
+ [AWS KMS Integração de pacotes personalizados do Amazon OpenSearch Service](custom-package-kms-integration.md)
## Cotas de plug-ins
+ Você pode criar até 25 plugins personalizados por conta, por região.
+ O tamanho máximo de um plug-in sem compactação é 1 GB.
+ O número máximo de servidores que podem ser associados a um único domínio é 20. Essa cota se aplica a todos os tipos de plug-in combinados: opcionais, de terceiros e personalizados.
+ Os plug-ins personalizados são compatíveis com domínios que executam a OpenSearch versão 2.15 ou posterior.
+ O arquivo `descriptor.properties` do plug-in deve ser compatível com uma versão de mecanismo semelhante à 2.15.0 ou qualquer versão 2.x.x, na qual a versão do patch é definida como zero.
## Pré-requisitos
Antes de instalar um plug-in personalizado e associá-lo a um domínio, certifique-se de que os seguintes requisitos são atendidos:
+ A versão do mecanismo compatível com o plug-in no arquivo `descriptor.properties` deve ser semelhante à `2.15.0` ou `2.x.0`. Ou seja, a versão do patch deve ser zero.
+ Os seguintes atributos devem estar habilitados no domínio:
+ [Node-to-node criptografia](ntn.md)
+ [Criptografia em repouso](encryption-at-rest.md)
+ [`EnforceHTTPS` está definido como 'verdadeiro'](createupdatedomains.md)
Veja também [opensearch-https-required](https://docs.aws.amazon.com/config/latest/developerguide/opensearch-https-required.html)no *Guia do AWS Config desenvolvedor*.
+ Os clientes devem ser compatíveis com a **Policy-Min-TLS-1-2-PFS-2023-10**. É possível especificar essa compatibilidade usando o comando a seguir. Substitua *placeholder value* o por suas próprias informações:
```
aws opensearch update-domain-config \
--domain-name domain-name \
--domain-endpoint-options '{"TLSSecurityPolicy":"Policy-Min-TLS-1-2-PFS-2023-10" }'
```
Para obter mais informações, consulte [DomainEndpointOptions](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_DomainEndpointOptions.html)a *Amazon OpenSearch Service API Reference*.
## Solução de problemas
Se o sistema retornar o erro `PluginValidationFailureReason : The provided plugin could not be loaded`, consulte [Ocorre falha na instalação do plug-in personalizado devido a incompatibilidade entre versões](handling-errors.md#troubleshooting-custom-plugins) para obter informações de solução de problemas.
## Instalar um plug-in personalizado usando o console
Para associar um plug-in de terceiros a um domínio, primeiro importe a licença e a configuração do plug-in como pacotes.
**Para instalar um plug-in personalizado**
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, selecione **Pacotes**.
1. Escolha **Importar pacote**.
1. Em **Nome**, insira um nome exclusivo e fácil de identificar para o plug-in.
1. (Opcional) Em **Descrição**, forneça todos os detalhes úteis sobre o pacote ou sua finalidade.
1. Em **Tipo de pacote**, escolha **Plug-in**.
1. Em **Origem do pacote**, insira o caminho ou navegue até o arquivo ZIP do plug-in no Amazon S3.
1. Para a **versão do OpenSearch mecanismo**, escolha a versão compatível com OpenSearch o plug-in.
1. Em **Criptografia de pacote**, escolha se a chave de criptografia do pacote será personalizada ou não. Por padrão, o OpenSearch Service criptografa o pacote do plug-in com um Chave pertencente à AWS. Também é possível usar uma chave gerenciada pelo cliente.
1. Escolha **Importar**.
Depois de importar o pacote do plug-in, associe-o a um domínio. Para instruções, consulte [Importar e associar um pacote a um domínio](custom-packages.md#associate-console).
## Gerenciando plug-ins personalizados usando o AWS CLI
Você pode usar o AWS CLI para gerenciar várias tarefas personalizadas do plug-in.
**Topics**
+ [Instalando um plug-in personalizado usando o AWS CLI](#custom-plugin-install-cli)
+ [Atualizando um plug-in personalizado usando o AWS CLI](#custom-plugin-update-cli)
+ [Crie ou atualize um plug-in personalizado com uma AWS KMS chave de segurança](#custom-plugin-kms-key-security-cli)
+ [Atualizando um domínio OpenSearch de serviço com plug-ins personalizados para uma versão posterior do OpenSearch uso do AWS CLI](#custom-plugin-domain-upgrade-cli)
+ [Desinstalar e visualizar o status de desassociação de um plug-in personalizado](#custom-plugin-uninstall-cli)
### Instalando um plug-in personalizado usando o AWS CLI
**Antes de começar**
Antes de associar um plug-in personalizado ao domínio, você deve carregá-lo em um bucket do Amazon Simple Storage Service (Amazon S3). O bucket deve estar localizado no mesmo Região da AWS local em que você pretende usar o plug-in. Para mais informações sobre carregar um objeto em um buckets do S3, consulte [Fazer upload de objetos](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html) no *Guia do usuário do Amazon Simple Storage Service*.
Se o pacote contiver informações sensíveis, especifique a criptografia no lado do servidor com chaves gerenciadas pelo S3 ao carregá-lo. Depois de carregar o arquivo, anote o caminho do S3. O formato do caminho é `s3://amzn-s3-demo-bucket/file-path/file-name`.
**nota**
Opcionalmente, você pode proteger um plug-in personalizado ao criar o plug-in especificando uma chave AWS Key Management Service (AWS KMS). Para mais informações, consulte [Crie ou atualize um plug-in personalizado com uma AWS KMS chave de segurança](#custom-plugin-kms-key-security-cli).
**Para instalar um plug-in personalizado usando o AWS CLI**
1. Crie um novo pacote para seu plug-in personalizado executando o seguinte comando [create-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/create-package.html) e garantindo que os seguintes requisitos sejam atendidos:
+ O bucket e a localização da chave devem apontar para o arquivo `.zip` do plug-in em um bucket do S3 na conta em que você executa os comandos.
+ O bucket do S3 deve estar na mesma região em que o pacote está sendo criado.
+ Somente arquivos `.zip` são compatíveis com pacotes `ZIP-PLUGIN`.
+ O conteúdo do arquivo `.zip` deve seguir a estrutura de diretórios conforme esperado pelo plug-in.
+ O valor fornecido em `--engine-version` deve estar no formato `OpenSearch_{MAJOR}.{MINOR}`. Por exemplo: **OpenSearch\$12.17**.
Substitua *placeholder values* o por suas próprias informações:
```
aws opensearch create-package \
--package-name package-name \
--region region \
--package-type ZIP-PLUGIN \
--package-source S3BucketName=amzn-s3-demo-bucket,S3Key=s3-key \
--engine-version opensearch-version
```
1. (Opcional) Visualize o status da operação `create-package`, incluindo quaisquer descobertas de validação e vulnerabilidade de segurança, usando o comando [describe-packages](https://docs.aws.amazon.com/cli/latest/reference/es/describe-packages.html). Substitua *placeholder values* o por suas próprias informações:
```
aws opensearch describe-packages \
--region region \
--filters '[{"Name": "PackageType","Value": ["ZIP-PLUGIN"]}, {"Name": "PackageName","Value": ["package-name"]}]'
```
O comando retorna informações semelhantes às seguintes:
```
{
"PackageDetailsList": [{
"PackageID": "pkg-identifier",
"PackageName": "package-name",
"PackageType": "ZIP-PLUGIN",
"PackageStatus": "VALIDATION_FAILED",
"CreatedAt": "2024-11-11T13:07:18.297000-08:00",
"LastUpdatedAt": "2024-11-11T13:10:13.843000-08:00",
"ErrorDetails": {
"ErrorType": "",
"ErrorMessage": "PluginValidationFailureReason : Dependency Scan reported 3 vulnerabilities for the plugin: CVE-2022-23307, CVE-2019-17571, CVE-2022-23305"
},
"EngineVersion": "OpenSearch_2.15",
"AllowListedUserList": [],
"PackageOwner": "OWNER-XXXX"
}]
}
```
**nota**
Durante a `create-package` operação, o Amazon OpenSearch Service verifica o `ZIP-PLUGIN` valor da compatibilidade de versões, extensões de plug-in suportadas e vulnerabilidades de segurança. As vulnerabilidades de segurança são examinadas usando o serviço [Amazon Inspector](https://aws.amazon.com/inspector/getting-started/). Os resultados dessas verificações são mostrados no campo `ErrorDetails` da resposta da API.
1. Use o comando [associate-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-package.html) para associar o plug-in ao domínio de OpenSearch serviço de sua escolha usando o ID do pacote criado na etapa anterior.
**dica**
Se você tiver vários plug-ins, poderá usar o comando [associate-packages](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-packages.html) para associar vários pacotes a um domínio em uma única operação.
Substitua *placeholder values* o por suas próprias informações:
```
aws opensearch associate-package \
--domain-name domain-name \
--region region \
--package-id package-id
```
**nota**
O plug-in é instalado e desinstalado usando um [processo de implantação azul/verde](managedomains-configuration-changes.md).
1. (Opcional) Use o [list-packages-for-domain](https://docs.aws.amazon.com/cli/latest/reference/opensearch/list-packages-for-domain.html)comando para visualizar o status da associação. O status da associação se altera à medida que o fluxo de trabalho avança de `ASSOCIATING` para `ACTIVE`. O status da associação passa para ATIVO após a conclusão da instalação do plug-in, e ele está pronto para uso.
Substitua *placeholder values* por suas próprias informações.
```
aws opensearch list-packages-for-domain \
--region region \
--domain-name domain-name
```
### Atualizando um plug-in personalizado usando o AWS CLI
Use o comando [update-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/update-package.html) para fazer alterações em um plug-in.
**nota**
Opcionalmente, você pode proteger um plug-in personalizado ao atualizar o plug-in especificando uma chave AWS Key Management Service (AWS KMS). Para mais informações, consulte [Crie ou atualize um plug-in personalizado com uma AWS KMS chave de segurança](#custom-plugin-kms-key-security-cli).
**Para atualizar um plug-in personalizado usando o AWS CLI**
+ Execute o comando a seguir. Substitua *placeholder values* por suas próprias informações.
```
aws opensearch update-package \
--region region \
--package-id package-id \
--package-source S3BucketName=amzn-s3-demo-bucket,S3Key=s3-key \
--package-description description
```
Depois de atualizar um pacote, você pode usar o comando [associate-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-package.html) ou [associate-packages](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-packages.html) para aplicar atualizações de pacote em um domínio.
**nota**
Você pode auditar, criar, atualizar, associar e desassociar operações no plug-in usando AWS CloudTrail. Para obter mais informações, consulte [Monitorando chamadas OpenSearch de API do Amazon Service com AWS CloudTrail](managedomains-cloudtrailauditing.md).
### Crie ou atualize um plug-in personalizado com uma AWS KMS chave de segurança
Opcionalmente, você pode proteger um plug-in personalizado ao atualizá-lo ou atualizá-lo especificando uma chave do AWS KMS . Para fazer isso, defina `PackageEncryptionOptions` como `true` e especifique o nome do recurso da Amazon (ARN) da chave, como mostrado nos exemplos a seguir.
**Exemplo: criar um plug-in personalizado com AWS KMS chave de segurança**
```
aws opensearch create-package \
--region us-east-2 --package-name my-custom-package \
--package-type ZIP-PLUGIN \
--package-source S3BucketName=amzn-s3-demo-bucket,S3Key=my-s3-key
--engine-version OpenSearch_2.15
"PackageConfigOptions": {
...
}
"PackageEncryptionOptions": {
"Enabled": true,
"KmsKeyId":"arn:aws:kms:us-east-2:111222333444:key/2ba228d5-1d09-456c-ash9-daf42EXAMPLE"
}
```
**Exemplo: atualizar um plug-in personalizado com a AWS KMS chave de segurança**
```
aws opensearch update-package \
--region us-east-2 --package-name my-custom-package \
--package-type ZIP-PLUGIN \
--package-source S3BucketName=amzn-s3-demo-bucket,S3Key=my-s3-key
--engine-version OpenSearch_2.15
"PackageConfigOptions": {
...
}
"PackageEncryptionOptions": {
"Enabled": true,
"KmsKeyId":"arn:aws:kms:us-east-2:111222333444:key/2ba228d5-1d09-456c-ash9-daf42EXAMPLE"
}
```
**Importante**
Se a AWS KMS chave especificada for desativada ou excluída, ela poderá deixar o cluster associado inoperacional.
Para obter mais informações sobre AWS KMS integração com pacotes personalizados,[AWS KMS Integração de pacotes personalizados do Amazon OpenSearch Service](custom-package-kms-integration.md).
### Atualizando um domínio OpenSearch de serviço com plug-ins personalizados para uma versão posterior do OpenSearch uso do AWS CLI
Quando você precisar atualizar um domínio OpenSearch de serviço que usa plug-ins personalizados para uma versão posterior do OpenSearch, conclua os processos a seguir.
**Para atualizar um domínio OpenSearch de serviço com plug-ins personalizados para uma versão posterior do OpenSearch uso do AWS CLI**
1. Use o comando create-package para criar um novo pacote para seu plug-in especificando a nova versão. OpenSearch
O nome do pacote deve ser o mesmo para o plug-in de todas as versões do mecanismo. A alteração do nome do pacote faz com que o processo de atualização do domínio falhe durante a blue/green implantação.
1. Atualize o domínio para a versão acima seguindo as etapas em [Atualizando domínios do Amazon OpenSearch Service](version-migration.md).
Durante esse processo, o Amazon OpenSearch Service desassocia a versão anterior do pacote de plug-ins e instala a nova versão usando uma implantação. blue/green
### Desinstalar e visualizar o status de desassociação de um plug-in personalizado
Para desinstalar o plug-in de qualquer domínio, use o comando [dissociate-package](https://docs.aws.amazon.com/cli/latest/reference/es/dissociate-package.html). A execução desse comando também remove as configurações ou pacotes de licença relacionados. Em seguida, você pode usar o [list-packages-for-domain](https://docs.aws.amazon.com/cli/latest/reference/es/list-packages-for-domain.html)comando para visualizar o status da dissociação.
**dica**
Você também pode usar o comando [dissociate-packages](https://docs.aws.amazon.com/cli/latest/reference/opensearch/dissociate-packages.html) para desinstalar vários plug-ins de um domínio em uma única operação.
**Para desinstalar e visualizar o status de desassociação de um plug-in personalizado**
1. Desabilite o plug-in em todos os índices. Faça isso antes de desassociar o pacote de plug-in.
Se você tentar desinstalar um plug-in antes de desativá-lo de todos os índices, o processo de blue/green implantação permanecerá preso no `Processing` estado.
1. Execute o comando a seguir para desinstalar o plug-in. Substitua *placeholder values* por suas próprias informações.
```
aws opensearch dissociate-package \
--region region \
--package-id plugin-package-id \
--domain-name domain name
```
1. (Opcional) Execute o [list-packages-for-domain](https://docs.aws.amazon.com/cli/latest/reference/opensearch/list-packages-for-domain.html)comando para ver o status da dissociação.