Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Gestione dei plugin personalizzati in Amazon Service OpenSearch Utilizzando i plug-in personalizzati per OpenSearch Service, puoi estendere le OpenSearch funzionalità in aree come l'analisi del linguaggio, il filtraggio personalizzato, il posizionamento e altro ancora, consentendoti di creare esperienze di ricerca personalizzate. OpenSearch È possibile sviluppare plugin personalizzati per estendendo la `org.opensearch.plugins.Plugin` classe e quindi impacchettandola in un file. `.zip` Le seguenti estensioni dei plugin sono attualmente supportate da Amazon OpenSearch Service: + **AnalysisPlugin**— Estende la funzionalità di analisi aggiungendo, ad esempio, analizzatori personalizzati, tokenizzatori di caratteri o filtri per l'elaborazione del testo. + **SearchPlugin**— Migliora le funzionalità di ricerca con tipi di query personalizzati, algoritmi di somiglianza, opzioni di suggerimento e aggregazioni. + **MapperPlugin**— Consente di creare tipi di campo personalizzati e le relative configurazioni di mappatura OpenSearch, consentendo di definire in che modo i diversi tipi di dati devono essere archiviati e indicizzati. + **ScriptPlugin**— Consente di aggiungere funzionalità di script personalizzate, ad esempio OpenSearch, agli script personalizzati per operazioni come l'assegnazione di punteggi, l'ordinamento e le trasformazioni dei valori dei campi durante la ricerca o l'indicizzazione. + **SearchPipelinePlugin**— Consente di personalizzare l'esperienza di ricerca su Amazon OpenSearch Service aggiungendo funzionalità di pipeline di ricerca personalizzate, ad esempio `SearchPhaseResultsProcessor` implementazioni personalizzate che vengono eseguite tra le fasi di ricerca a livello di nodo di coordinamento, il reranking di ricerca ibrido per combinare più strategie di punteggio e pipeline di ricerca federate che aggregano i risultati su più fonti di dati. Puoi utilizzare la console OpenSearch di servizio o i comandi API esistenti per pacchetti personalizzati per caricare e associare il plug-in al cluster Amazon OpenSearch Service. Puoi anche usare il [DescribePackages](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_DescribePackages.html)comando per descrivere tutti i pacchetti del tuo account e per visualizzare dettagli come la OpenSearch versione e i dettagli degli errori. OpenSearch Il servizio convalida il pacchetto di plug-in per verificare la compatibilità delle versioni, le vulnerabilità di sicurezza e le operazioni consentite del plug-in. Per ulteriori informazioni sui pacchetti personalizzati, consulta. [Importazione e gestione di pacchetti in Amazon Service OpenSearch](custom-packages.md) **OpenSearch versione e Regione AWS supporto** I plugin personalizzati sono supportati nei domini OpenSearch di servizio che eseguono la OpenSearch versione 2.15 nei seguenti casi: Regioni AWS + Stati Uniti orientali (Ohio) (us-east-2) + Stati Uniti orientali (Virginia settentrionale) (us-east-1) + Stati Uniti occidentali (Oregon) (us-west-2) + Asia Pacifico (Mumbai) (ap-south-1) + Asia Pacifico (Seoul) (ap-northeast-2) + Asia Pacifico (Singapore) (ap-southeast-1) + Asia Pacifico (Sydney) (ap-southeast-2) + Asia Pacifico (Tokyo) (ap-northeast-1) + Canada (Centrale) (ca-central-1) + Europa (Francoforte) (eu-central-1) + Europa (Irlanda) (eu-west-1) + Europa (Londra) (eu-west-2) + Europa (Parigi) (eu-west-3) + Sud America (San Paolo) (sa-east-1) **Nota** I plugin personalizzati contengono codice sviluppato dall'utente. Eventuali problemi, comprese le violazioni degli SLA, causati dal codice sviluppato dagli utenti non danno diritto ai crediti SLA. Per ulteriori informazioni, consulta [Amazon OpenSearch Service - Service Level Agreement](https://aws.amazon.com/opensearch-service/sla/). **Topics** + [Quote dei plugin](#plugin-limits) + [Prerequisiti](#custom-plugin-prerequisites) + [Risoluzione dei problemi](#custom-plugin-troubleshooting) + [Installazione di un plug-in personalizzato tramite la console](#custom-plugin-install-console) + [Gestire i plugin personalizzati utilizzando il AWS CLI](#managing-custom-plugins-cli) + [AWS KMS Integrazione di pacchetti personalizzati Amazon OpenSearch Service](custom-package-kms-integration.md) ## Quote dei plugin + Puoi creare fino a 25 plugin personalizzati per account per regione. + La dimensione massima non compressa per un plug-in è di 1 GB. + Il numero massimo di plugin che possono essere associati a un singolo dominio è 20. Questa quota si applica a tutti i tipi di plugin combinati: opzionali, di terze parti e personalizzati. + I plugin personalizzati sono supportati nei domini che eseguono la OpenSearch versione 2.15 o successiva. + Il `descriptor.properties` file del plug-in deve supportare una versione del motore simile alla 2.15.0 o qualsiasi versione 2.x.x, in cui la versione della patch è impostata su zero. ## Prerequisiti Prima di installare un plug-in personalizzato e associarlo a un dominio, assicurati di soddisfare i seguenti requisiti: + La versione del motore supportata per il plugin nel `descriptor.properties` file deve essere simile a `2.15.0` o`2.x.0`. Cioè, la versione della patch deve essere zero. + Le seguenti funzionalità devono essere abilitate sul tuo dominio: + [Node-to-node crittografia](ntn.md) + [Crittografia dei dati inattivi](encryption-at-rest.md) + [`EnforceHTTPS`è impostato su «true»](createupdatedomains.md) Vedi anche [opensearch-https-required](https://docs.aws.amazon.com/config/latest/developerguide/opensearch-https-required.html)nella *Guida per gli AWS Config sviluppatori*. + I client devono supportare **Policy-MIN-TLS-1-2-pfs-2023-10**. È possibile specificare questo supporto utilizzando il seguente comando. {{placeholder value}}Sostituiscili con le tue informazioni: ``` aws opensearch update-domain-config \ --domain-name {{domain-name}} \ --domain-endpoint-options '{"TLSSecurityPolicy":"Policy-Min-TLS-1-2-PFS-2023-10" }' ``` Per ulteriori informazioni, [DomainEndpointOptions](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_DomainEndpointOptions.html)consulta l'*Amazon OpenSearch Service API Reference*. ## Risoluzione dei problemi Se il sistema restituisce l'errore`PluginValidationFailureReason : The provided plugin could not be loaded`, consulta [L'installazione del plug-in personalizzato non riesce a causa della compatibilità della versione](handling-errors.md#troubleshooting-custom-plugins) per informazioni sulla risoluzione dei problemi. ## Installazione di un plug-in personalizzato tramite la console Per associare un plug-in di terze parti a un dominio, importate innanzitutto la licenza e la configurazione del plug-in come pacchetti. **Per installare un plugin personalizzato** 1. Accedi alla console di Amazon OpenSearch Service da [https://console.aws.amazon.com/aos/casa](https://console.aws.amazon.com/aos/home). 1. Nel riquadro di navigazione a sinistra, scegli **Pacchetti**. 1. Scegli **Importa pacchetto**. 1. Per **Nome**, inserisci un nome univoco e facilmente identificabile per il plugin. 1. (Facoltativo) In **Descrizione**, fornite tutti i dettagli utili sul pacchetto o sul suo scopo. 1. Per **Tipo di pacchetto**, scegli **Plugin**. 1. Per **Package source**, inserisci il percorso o cerca il file ZIP del plugin in Amazon S3. 1. Per la **versione OpenSearch del motore**, scegli la versione OpenSearch supportata dal plugin. 1. Per **Package encryption**, scegli se personalizzare la chiave di crittografia per il pacchetto. Per impostazione predefinita, OpenSearch Service crittografa il pacchetto del plug-in con un Chiave di proprietà di AWS. Puoi invece utilizzare una chiave gestita dal cliente. 1. Scegli **Importa**. Dopo aver importato il pacchetto del plugin, associalo a un dominio. Per istruzioni, consulta [Importa e associa un pacchetto a un dominio](custom-packages.md#associate-console). ## Gestire i plugin personalizzati utilizzando il AWS CLI È possibile utilizzare il AWS CLI per gestire una serie di attività personalizzate relative ai plug-in. **Topics** + [Installazione di un plug-in personalizzato utilizzando il AWS CLI](#custom-plugin-install-cli) + [Aggiornamento di un plug-in personalizzato utilizzando il AWS CLI](#custom-plugin-update-cli) + [Crea o aggiorna un plug-in personalizzato con una AWS KMS chiave di sicurezza](#custom-plugin-kms-key-security-cli) + [Aggiornamento di un dominio OpenSearch di servizio con plug-in personalizzati a una versione successiva di utilizzo di OpenSearch AWS CLI](#custom-plugin-domain-upgrade-cli) + [Disinstallazione e visualizzazione dello stato di dissociazione di un plug-in personalizzato](#custom-plugin-uninstall-cli) ### Installazione di un plug-in personalizzato utilizzando il AWS CLI **Prima di iniziare** Prima di poter associare un plug-in personalizzato al tuo dominio, devi caricarlo in un bucket Amazon Simple Storage Service (Amazon S3). Il bucket deve trovarsi nello stesso Regione AWS punto in cui intendi utilizzare il plug-in. Per informazioni sull'aggiunta di un oggetto a un bucket S3, consulta [Caricamento di oggetti](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html) nella *Amazon Simple Storage Service* User Guide. Se il plug-in contiene informazioni sensibili, specifica la crittografia lato server con chiavi gestite da S3 al momento del caricamento. Dopo aver caricato il file, prendere nota del suo percorso S3. Il formato del percorso è `s3://{{amzn-s3-demo-bucket}}/{{file-path}}{{/file-name}}`. **Nota** Facoltativamente, puoi proteggere un plug-in personalizzato quando crei il plug-in specificando una chiave (). AWS Key Management Service AWS KMS Per informazioni, consulta [Crea o aggiorna un plug-in personalizzato con una AWS KMS chiave di sicurezza](#custom-plugin-kms-key-security-cli). **Per installare un plugin personalizzato utilizzando il AWS CLI** 1. Crea un nuovo pacchetto per il tuo plugin personalizzato eseguendo il seguente comando [create-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/create-package.html), assicurandoti che siano soddisfatti i seguenti requisiti: + La posizione del bucket e della chiave deve puntare al `.zip` file del plug-in in un bucket S3 dell'account in cui stai eseguendo i comandi. + Il bucket S3 deve trovarsi nella stessa regione in cui viene creato il pacchetto. + Per `.zip` `ZIP-PLUGIN` i pacchetti sono supportati solo i file. + Il contenuto del `.zip` file deve seguire la struttura delle cartelle prevista dal plugin. + Il valore di `--engine-version` deve essere nel formato`OpenSearch_{{{MAJOR}}}.{{{MINOR}}}`. Ad esempio: **OpenSearch\_2.17**. {{placeholder values}}Sostituiscili con le tue informazioni: ``` 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. (Facoltativo) Visualizza lo stato dell'`create-package`operazione, inclusi eventuali risultati di convalida e vulnerabilità di sicurezza, utilizzando il comando [describe-packages](https://docs.aws.amazon.com/cli/latest/reference/es/describe-packages.html). Sostituiscili con le tue informazioni{{placeholder values}}: ``` aws opensearch describe-packages \ --region {{region}} \ --filters '[{"Name": "PackageType","Value": ["ZIP-PLUGIN"]}, {"Name": "PackageName","Value": ["{{package-name}}"]}]' ``` Questo comando restituisce informazioni simili alle seguenti: ``` { "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 l'`create-package`operazione, Amazon OpenSearch Service verifica il `ZIP-PLUGIN` valore per la compatibilità delle versioni, le estensioni dei plugin supportate e le vulnerabilità di sicurezza. Le vulnerabilità di sicurezza vengono analizzate utilizzando il servizio [Amazon Inspector](https://aws.amazon.com/inspector/getting-started/). I risultati di questi controlli vengono visualizzati nel `ErrorDetails` campo della risposta dell'API. 1. Utilizzate il comando [associate-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-package.html) per associare il plugin al dominio di OpenSearch servizio di vostra scelta utilizzando l'ID del pacchetto creato nel passaggio precedente. **Suggerimento** Se disponi di più plugin, puoi invece utilizzare il comando [associate-packages per associare più pacchetti](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-packages.html) a un dominio con un'unica operazione. Sostituiscili {{placeholder values}} con le tue informazioni: ``` aws opensearch associate-package \ --domain-name {{domain-name}} \ --region {{region}} \ --package-id {{package-id}} ``` **Nota** Il plugin viene installato e disinstallato utilizzando un processo di distribuzione [blu/verde](managedomains-configuration-changes.md). 1. (Facoltativo) Utilizzate il [list-packages-for-domain](https://docs.aws.amazon.com/cli/latest/reference/opensearch/list-packages-for-domain.html)comando per visualizzare lo stato dell'associazione. Lo stato dell'associazione cambia man mano che il flusso di lavoro avanza da `ASSOCIATING` a`ACTIVE`. Lo stato dell'associazione diventa ATTIVO dopo il completamento dell'installazione del plug-in e il plug-in è pronto per l'uso. Sostituisci {{placeholder values}} con le informazioni appropriate. ``` aws opensearch list-packages-for-domain \ --region {{region}} \ --domain-name {{domain-name}} ``` ### Aggiornamento di un plug-in personalizzato utilizzando il AWS CLI Utilizzate il comando [update-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/update-package.html) per apportare modifiche a un plugin. **Nota** Facoltativamente, puoi proteggere un plug-in personalizzato quando aggiorni il plug-in specificando una AWS Key Management Service chiave ().AWS KMS Per informazioni, consulta [Crea o aggiorna un plug-in personalizzato con una AWS KMS chiave di sicurezza](#custom-plugin-kms-key-security-cli). **Per aggiornare un plug-in personalizzato utilizzando il AWS CLI** + Eseguire il seguente comando seguente. Sostituisci {{placeholder values}} con le informazioni appropriate. ``` aws opensearch update-package \ --region {{region}} \ --package-id {{package-id}} \ --package-source S3BucketName={{amzn-s3-demo-bucket}},S3Key={{s3-key}} \ --package-description {{description}} ``` Dopo aver aggiornato un pacchetto, è possibile utilizzare il comando [associate-package o [associate-packages](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-packages.html)](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-package.html) per applicare gli aggiornamenti del pacchetto a un dominio. **Nota** È possibile controllare, creare, aggiornare, associare e dissociare le operazioni sul plug-in utilizzando. AWS CloudTrail Per ulteriori informazioni, consulta [Monitoraggio delle chiamate API di Amazon OpenSearch Service con AWS CloudTrail](managedomains-cloudtrailauditing.md). ### Crea o aggiorna un plug-in personalizzato con una AWS KMS chiave di sicurezza È possibile proteggere un plug-in personalizzato quando si crea o si aggiorna il plug-in specificando una AWS KMS chiave. A tale scopo, imposta `PackageEncryptionOptions` `true` e specifica l'Amazon Resource Name (ARN) della chiave, come mostrato negli esempi seguenti. **Esempio: crea un plug-in personalizzato con AWS KMS chiave di sicurezza** ``` 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" } ``` **Esempio: aggiorna un plug-in personalizzato con AWS KMS chiave di sicurezza** ``` 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 la AWS KMS chiave specificata è disabilitata o eliminata, può lasciare il cluster associato inoperativo. Per ulteriori informazioni sull' AWS KMS integrazione con pacchetti personalizzati,[AWS KMS Integrazione di pacchetti personalizzati Amazon OpenSearch Service](custom-package-kms-integration.md). ### Aggiornamento di un dominio OpenSearch di servizio con plug-in personalizzati a una versione successiva di utilizzo di OpenSearch AWS CLI Quando devi aggiornare un dominio di OpenSearch servizio che utilizza plug-in personalizzati a una versione successiva di OpenSearch, completa i seguenti processi. **Per aggiornare un dominio OpenSearch di servizio con plug-in personalizzati a una versione successiva utilizzando il OpenSearch AWS CLI** 1. Usa il comando create-package per creare un nuovo pacchetto per il tuo plugin specificando la nuova versione. OpenSearch Assicurati che il nome del pacchetto sia lo stesso per il plugin per tutte le versioni del motore. La modifica del nome del pacchetto causa il fallimento del processo di aggiornamento del dominio durante la blue/green distribuzione. 1. Aggiorna il tuo dominio alla versione superiore seguendo la procedura riportata di seguito[Aggiornamento dei domini Amazon Service OpenSearch](version-migration.md). Durante questo processo, Amazon OpenSearch Service dissocia la versione precedente del pacchetto di plug-in e installa la nuova versione utilizzando una distribuzione. blue/green ### Disinstallazione e visualizzazione dello stato di dissociazione di un plug-in personalizzato [Per disinstallare il plugin da qualsiasi dominio, puoi usare il comando dissociate-package.](https://docs.aws.amazon.com/cli/latest/reference/es/dissociate-package.html) L'esecuzione di questo comando rimuove anche qualsiasi pacchetto di configurazione o licenza correlato. È quindi possibile utilizzare il [list-packages-for-domain](https://docs.aws.amazon.com/cli/latest/reference/es/list-packages-for-domain.html)comando per visualizzare lo stato della dissociazione. **Suggerimento** È inoltre possibile utilizzare il comando [dissociate-packages](https://docs.aws.amazon.com/cli/latest/reference/opensearch/dissociate-packages.html) per disinstallare più plugin da un dominio in un'unica operazione. **Per disinstallare e visualizzare lo stato di dissociazione di un plug-in personalizzato** 1. Disabilita il plugin in ogni indice. Questa operazione deve essere eseguita prima di dissociare il pacchetto del plugin. Se provate a disinstallare un plugin prima di disabilitarlo da tutti gli indici, il processo di blue/green distribuzione rimane bloccato nello stato. `Processing` 1. Eseguite il comando seguente per disinstallare il plugin. Sostituisci {{placeholder values}} con le informazioni appropriate. ``` aws opensearch dissociate-package \ --region {{region}} \ --package-id {{plugin-package-id}} \ --domain-name {{domain name}} ``` 1. (Facoltativo) Eseguite il [list-packages-for-domain](https://docs.aws.amazon.com/cli/latest/reference/opensearch/list-packages-for-domain.html)comando per visualizzare lo stato della dissociazione.