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à.
# Importazione e gestione di pacchetti in Amazon Service OpenSearch
Amazon OpenSearch Service ti consente di caricare file di dizionario personalizzati, come parole chiave e sinonimi, e associare plugin al tuo dominio. Questi plugin possono essere preconfezionati, personalizzati o di terze parti, il che ti offre la flessibilità necessaria per estendere le funzionalità del tuo dominio. *Il termine generico per tutti questi tipi di file è pacchetti.*
+ **I file di dizionario** aiutano a perfezionare i risultati di ricerca indicando di OpenSearch ignorare le parole più comuni ad alta frequenza o di trattare termini simili, come «crema pasticcera congelata», «gelato» e «gelato», come equivalenti. Possono anche migliorare lo [stemming](https://en.wikipedia.org/wiki/Stemming), come si è visto con il plugin di analisi giapponese (kuromoji).
+ I **plug-in preconfezionati** offrono funzionalità integrate, come il plug-in Amazon Personalize per risultati di ricerca personalizzati. Questi plugin utilizzano il tipo di pacchetto. `ZIP-PLUGIN` Per ulteriori informazioni, consulta [Plugin per versione del motore in Amazon Service OpenSearch](supported-plugins.md).
+ **I plug-in personalizzati e di terze parti** consentono di aggiungere funzionalità personalizzate o di integrarsi con sistemi esterni, il che offre una flessibilità ancora maggiore per il dominio. Come i plugin preconfezionati, caricate i plugin personalizzati come pacchetti. `ZIP-PLUGIN` Per i plug-in di terze parti, è inoltre necessario importare la licenza del plug-in e i file di configurazione come pacchetti separati, quindi associarli tutti al dominio.
Per ulteriori informazioni, consulta i seguenti argomenti:
+ [Gestione dei plugin personalizzati in Amazon Service OpenSearch](custom-plugins.md)
+ [Installazione di plug-in di terze parti in Amazon Service OpenSearch](plugins-third-party.md)
**Nota**
Puoi associare un massimo di 20 plugin a un singolo dominio. Questo limite include tutti i tipi di plug-in: plug-in opzionali, di terze parti e personalizzati.
**Topics**
+ [Autorizzazioni richieste](#custom-packages-iam)
+ [Caricamento di pacchetti in Amazon S3](#custom-packages-gs)
+ [Importazione e associazione di pacchetti](#custom-packages-assoc)
+ [Utilizzo di pacchetti con OpenSearch](#custom-packages-using)
+ [Aggiornamento dei pacchetti](#custom-packages-updating)
+ [Aggiornamento manuale degli indici con un nuovo dizionario](#custom-packages-updating-index-analyzers)
+ [Dissociazione e rimozione dei pacchetti](#custom-packages-dissoc)
+ [Gestione dei plugin personalizzati in Amazon Service OpenSearch](custom-plugins.md)
+ [Installazione di plug-in di terze parti in Amazon Service OpenSearch](plugins-third-party.md)
## Autorizzazioni richieste
Gli utenti senza accesso come amministratore richiedono determinate azioni AWS Identity and Access Management (IAM) per gestire i pacchetti:
+ `es:CreatePackage`— Creare un pacchetto
+ `es:DeletePackage`— Eliminare un pacchetto
+ `es:AssociatePackage`— Associare un pacchetto a un dominio
+ `es:DissociatePackage`— Dissociare un pacchetto da un dominio
Sono necessarie anche le autorizzazioni per il percorso del bucket Amazon S3 o l'oggetto in cui si trova il pacchetto personalizzato.
Concedere tutte le autorizzazioni all'interno di IAM, non nella policy di accesso al dominio. Per ulteriori informazioni, consultare [Identity and Access Management in Amazon OpenSearch Service](ac.md).
## Caricamento di pacchetti in Amazon S3
Questa sezione spiega come caricare pacchetti di dizionari personalizzati, poiché i pacchetti di plug-in preconfezionati sono già installati. Prima di poter associare un dizionario personalizzato al tuo dominio, devi caricarlo in un bucket Amazon S3. Per le istruzioni, consulta [Caricamento di oggetti](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html) nella *Guida per l'utente di Amazon Simple Storage Service*. I plugin supportati non devono essere caricati.
Se il dizionario contiene informazioni sensibili, specifica la [crittografia lato server con chiavi gestite da S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingServerSideEncryption.html) al momento del caricamento. OpenSearch Il servizio non può accedere ai file in S3 che proteggi utilizzando una chiave. AWS KMS
Dopo aver caricato il file, prendere nota del suo percorso S3. Il formato del percorso è `s3://amzn-s3-demo-bucket/file-path/file-name`.
È possibile utilizzare il seguente file di sinonimi per scopi di test. Salvalo come `synonyms.txt`.
```
danish, croissant, pastry
ice cream, gelato, frozen custard
sneaker, tennis shoe, running shoe
basketball shoe, hightop
```
Alcuni dizionari, come i dizionari Hunspell, utilizzano più file e richiedono le proprie directory nel file system. Al momento, OpenSearch Service supporta solo dizionari a file singolo.
## Importazione e associazione di pacchetti
La console è il modo più semplice per importare un dizionario personalizzato in Service. OpenSearch Quando importi un dizionario da Amazon S3, OpenSearch Service archivia la propria copia del pacchetto e la crittografa automaticamente utilizzando AES-256 con chiavi gestite dal servizio. OpenSearch
I plug-in opzionali sono già preinstallati in OpenSearch Service, quindi non è necessario caricarli personalmente, ma è necessario associare un plug-in a un dominio. I plugin disponibili sono elencati nella schermata **Pacchetti** della console.
### Importa e associa un pacchetto a un dominio
1. Nella console di Amazon OpenSearch Service, scegli **Pacchetti**.
1. Scegli **Importa pacchetto**.
1. Assegnare al pacchetto un nome descrittivo.
1. Fornire il percorso S3 del file e quindi scegliere **Importa**.
1. Tornare alla schermata **Pacchetti** .
1. Quando lo stato del pacchetto è **disponibile**, selezionarlo.
1. Scegli **Associa a un dominio**.
1. Seleziona un dominio, quindi scegli **Avanti**. Esamina i pacchetti e scegli **Associa**.
1. Nel pannello di navigazione, scegliere il dominio e passare alla scheda **Pacchetti**.
1. Se il pacchetto è un dizionario personalizzato, annota l'ID quando il pacchetto diventa **Disponibile**. Utilizza `analyzers/id` come percorso del file nelle [richieste di OpenSearch](#custom-packages-using).
## Utilizzo di pacchetti con OpenSearch
Questa sezione spiega come utilizzare entrambi i tipi di pacchetti: dizionari personalizzati e plugin preconfezionati.
### Usare dizionari personalizzati
Dopo aver associato un file a un dominio, è possibile utilizzarlo in parametri quali `synonyms_path` e `user_dictionary` quando si creano tokenizzatori e filtri token. `stopwords_path` Il parametro esatto varia in base all'oggetto. Diversi oggetti supportano `synonyms_path` e `stopwords_path`, ma `user_dictionary` è esclusivo per il plugin kuromoji.
Per il plug-in IK (Chinese) Analysis, è possibile caricare un file di dizionario personalizzato come pacchetto personalizzato e associarlo a un dominio e il plug-in lo raccoglie automaticamente senza richiedere un parametro `user_dictionary`. Se il file è un file di sinonimi, usa il parametro `synonyms_path`.
Nel seguente esempio viene aggiunto un file di sinonimi a un nuovo indice:
```
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"
}
}
}
}
```
Questa richiesta crea un analizzatore personalizzato per l'indice che utilizza il tokenizer standard e un filtro token sinonimo.
+ I tokenizer scompongono i flussi di caratteri in *token* (in genere parole) in base ad alcune regole. L'esempio più semplice è il tokenizer di whitespace, che scompone i caratteri precedenti in un token ogni volta che incontra un carattere di whitespace. Un esempio più complesso è il tokenizer standard, che utilizza un insieme di regole grammaticali per lavorare in molte lingue.
+ I filtri token aggiungono, modificano o eliminano token. Ad esempio, un filtro token sinonimo aggiunge token quando trova una parola nell'elenco dei sinonimi. Il filtro token di arresto rimuove i token quando trova una parola nell'elenco di parole stop.
Questa richiesta aggiunge anche un campo di testo (`description`) alla mappatura e indica di OpenSearch utilizzare il nuovo analizzatore come analizzatore di ricerca. Si può vedere che come analizzatore di indice è utilizzato ancora l'analizzatore standard.
Infine, prendere nota della riga `"updateable": true` nel filtro token. Questo campo si applica solo agli analizzatori di ricerca non agli analizzatori di indice, ed è critico se in seguito si desidera [aggiornare l'analizzatore di ricerca](#custom-packages-updating) automaticamente.
A scopo di test, aggiungere alcuni documenti all'indice:
```
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" }
```
Quindi cercarli usando un sinonimo:
```
GET my-index/_search
{
"query": {
"match": {
"description": "gelato"
}
}
}
```
In questo caso, OpenSearch restituisce la seguente risposta:
```
{
"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"
}
}]
}
}
```
**Suggerimento**
I file di dizionario utilizzano lo spazio heap Java proporzionale alle loro dimensioni. Ad esempio, un file di dizionario a 2 GiB potrebbe consumare su un nodo 2 GiB di spazio heap. Se si utilizzano file di grandi dimensioni, assicurarsi che i nodi dispongano di spazio heap sufficiente per contenerli. [Monitorare](managedomains-cloudwatchmetrics.md#managedomains-cloudwatchmetrics-cluster-metrics) il parametro `JVMMemoryPressure` e dimensionare il cluster in base alle esigenze.
### Utilizzo di plugin preconfezionati
OpenSearch Il servizio consente di associare OpenSearch plug-in opzionali preinstallati da utilizzare al dominio. Un pacchetto di plug-in preconfezionato è compatibile con una OpenSearch versione specifica e può essere associato solo a domini con quella versione. L'elenco dei pacchetti disponibili per il tuo dominio include tutti i plugin supportati compatibili con la versione del tuo dominio. Dopo aver associato un plug-in a un dominio, inizia un processo di installazione sul dominio. Quindi, puoi fare riferimento e utilizzare il plug-in quando effettui richieste al OpenSearch Servizio.
L'associazione e la dissociazione di un plug-in richiedono una distribuzione. blue/green Per ulteriori informazioni, consulta [Modifiche che di solito causano implementazioni blue/green](managedomains-configuration-changes.md#bg).
I plugin opzionali includono analizzatori linguistici e risultati di ricerca personalizzati. Ad esempio, il plug-in Amazon Personalize Search Ranking utilizza l'apprendimento automatico per personalizzare i risultati di ricerca per i tuoi clienti. Per ulteriori informazioni su questo plugin, consulta [Personalizzazione](https://docs.aws.amazon.com/personalize/latest/dg/personalize-opensearch.html) dei risultati di ricerca da. OpenSearch Per un elenco di tutti i plugin supportati, consulta. [Plugin per versione del motore in Amazon Service OpenSearch](supported-plugins.md)
#### Plugin Sudachi
Per il [plugin Sudachi](https://github.com/WorksApplications/elasticsearch-sudachi), quando riassoci un file di dizionario, questo non si riflette immediatamente sul dominio. Il dizionario si aggiorna quando viene eseguita la blue/green distribuzione successiva sul dominio come parte di una modifica della configurazione o di un altro aggiornamento. In alternativa, è possibile creare un nuovo pacchetto con i dati aggiornati, creare un nuovo indice utilizzando questo nuovo pacchetto, reindicizzare l'indice esistente nel nuovo indice e quindi eliminare il vecchio indice. Se preferisci utilizzare l'approccio di reindicizzazione, utilizza un alias di indice in modo da evitare interruzioni del traffico.
Inoltre, il plugin Sudachi supporta solo dizionari binari Sudachi, che puoi caricare con l'operazione API. [CreatePackage](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/API_CreatePackage.html) [Per informazioni sul dizionario di sistema predefinito e sul processo di compilazione dei dizionari utente, consulta la documentazione Sudachi.](https://github.com/WorksApplications/elasticsearch-sudachi)
**Nota**
Quando carichi file di dizionario binario su Amazon S3, devi impostare il Content-Type dell'oggetto S3 su. `binary/octet-stream` L'utilizzo `application/octet-stream` farà fallire l'importazione del pacchetto.
L'esempio seguente mostra come utilizzare i dizionari di sistema e utente con il tokenizer Sudachi. È necessario caricare questi dizionari come pacchetti personalizzati con tipo `TXT-DICTIONARY` e fornire il relativo pacchetto nelle impostazioni aggiuntive. IDs
```
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"
}
}
}
}
}
}
```
## Aggiornamento dei pacchetti
Questa sezione spiega solo come aggiornare un pacchetto di dizionario personalizzato, poiché i pacchetti di plugin preconfezionati sono già aggiornati automaticamente. Il caricamento di una nuova versione di un dizionario su Amazon S3 *non* aggiorna automaticamente il pacchetto su Amazon OpenSearch Service. OpenSearch Il servizio archivia la propria copia del file, quindi se carichi una nuova versione su S3, devi aggiornarla manualmente.
Ciascuno dei domini associati archivia anche la *propria copia* del file. Per mantenere prevedibile il comportamento di ricerca, i domini continueranno a utilizzare la versione corrente del pacchetto fino a quando non vengono aggiornati esplicitamente. Per aggiornare un pacchetto personalizzato, modifica il file in Amazon S3 Control, aggiorna il pacchetto in OpenSearch Service, quindi applica l'aggiornamento.
### Console
1. Nella console OpenSearch di servizio, scegli **Pacchetti**.
1. Scegli un pacchetto, quindi seleziona **Aggiorna**.
1. Fornisci un nuovo percorso S3 al file, quindi scegli **Aggiorna pacchetto**.
1. Tornare alla schermata **Pacchetti** .
1. Quando lo stato del pacchetto è **Disponibile**, selezionarlo. Scegliere uno o più domini associati, selezionare **Applica aggiornamento** e confermare. Attendere che lo stato dell'associazione cambi in **Attivo**.
1. I passaggi successivi variano a seconda di come hai configurato gli indici:
+ Se il tuo dominio è in esecuzione OpenSearch con Elasticsearch 7.8 o versione successiva e utilizza solo analizzatori di ricerca con il campo [aggiornabile](#custom-packages-using) impostato su true, non devi intraprendere ulteriori azioni. OpenSearch [Il servizio aggiorna automaticamente gli indici utilizzando l'API \$1plugins/\$1refresh\$1search\$1analyzers.](https://docs.opensearch.org/latest/im-plugin/refresh-analyzer/index/)
+ Se il tuo dominio esegue Elasticsearch 7.7 o versioni precedenti, utilizza analizzatori di indici o non utilizza il campo, vedi. `updateable` [Aggiornamento manuale degli indici con un nuovo dizionario](#custom-packages-updating-index-analyzers)
Sebbene la console sia il metodo più semplice, puoi anche utilizzare l'API SDKs, o di configurazione per AWS CLI aggiornare i pacchetti di servizi. OpenSearch Per ulteriori informazioni, consulta [AWS CLI Command Reference](https://docs.aws.amazon.com/cli/latest/reference/) e [Amazon OpenSearch Service API Reference](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/Welcome.html).
### AWS SDK
Invece di aggiornare manualmente un pacchetto nella console, puoi utilizzare il SDKs per automatizzare il processo di aggiornamento. Il seguente script Python di esempio carica un nuovo file di pacchetto su Amazon S3, aggiorna il pacchetto in OpenSearch Service e applica il nuovo pacchetto al dominio specificato. Dopo aver verificato l'avvenuto aggiornamento, esegue una chiamata di esempio per OpenSearch dimostrare che i nuovi sinonimi sono stati applicati.
È necessario fornire valori per `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 ricevi un errore «pacchetto non trovato» quando esegui lo script utilizzando il AWS CLI, probabilmente significa che Boto3 sta utilizzando la regione specificata in \$1/.aws/config, che non è la regione in cui si trova il bucket S3. Esegui `aws configure` e specifica la regione corretta oppure aggiungi esplicitamente la regione al client:
```
client = boto3.client('opensearch', region_name='us-east-1')
```
## Aggiornamento manuale degli indici con un nuovo dizionario
Gli aggiornamenti manuali degli indici si applicano solo ai dizionari personalizzati, non ai plugin preconfezionati. Per utilizzare un dizionario aggiornato, è necessario aggiornare manualmente gli indici se si soddisfa una delle seguenti condizioni:
+ Il dominio esegue Elasticsearch 7.7 o versioni precedenti.
+ I pacchetti personalizzati vengono utilizzati come analizzatori di indice.
+ I pacchetti personalizzati vengono utilizzati come analizzatori di ricerca, ma non includono il campo [aggiornabile](#custom-packages-using).
Per aggiornare gli analizzatori con i file del nuovo pacchetto, sono disponibili due opzioni:
+ Chiudi e apri gli indici da aggiornare:
```
POST my-index/_close
POST my-index/_open
```
+ Reindicizzare gli indici. Innanzitutto, create un indice che utilizzi il file dei sinonimi aggiornato (o un file completamente nuovo). Nota che è supportato solo 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"
}
}
}
}
```
Quindi [reindicizzare](https://docs.opensearch.org/latest/opensearch/reindex-data/) il vecchio indice nel nuovo indice:
```
POST _reindex
{
"source": {
"index": "my-index"
},
"dest": {
"index": "my-new-index"
}
}
```
Se gli analizzatori di indice vengono aggiornati con una certa frequenza, utilizzare gli [alias di indice](https://docs.opensearch.org/latest/opensearch/index-alias/) per mantenere un percorso coerente per l'indice più recente:
```
POST _aliases
{
"actions": [
{
"remove": {
"index": "my-index",
"alias": "latest-index"
}
},
{
"add": {
"index": "my-new-index",
"alias": "latest-index"
}
}
]
}
```
Se il vecchio indice non è necessario, eliminarlo.
```
DELETE my-index
```
## Dissociazione e rimozione dei pacchetti
La dissociazione di un pacchetto, che si tratti di un dizionario personalizzato o di un plug-in preconfezionato, da un dominio significa che non è più possibile utilizzare quel pacchetto quando si creano nuovi indici. Dopo la dissociazione di un pacchetto, gli indici esistenti che lo utilizzavano non possono più utilizzarlo. È necessario rimuovere il pacchetto da qualsiasi indice prima di poterlo dissociare, altrimenti la dissociazione fallisce.
La console è il modo più semplice per dissociare un pacchetto da un dominio e rimuoverlo dal servizio. OpenSearch La rimozione di un pacchetto dal OpenSearch servizio *non* lo rimuove dalla sua posizione originale su Amazon S3.
### Dissocia un pacchetto da un dominio
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, scegli **Domini**.
1. Scegli il dominio, quindi vai alla scheda **Pacchetti**.
1. Scegliere un pacchetto, selezionare **Operazioni**, quindi scegliere **Dissocia**. Conferma la tua scelta.
1. Attendi che il pacchetto scompaia dall'elenco. Potrebbe essere necessario aggiornare il browser.
1. Se desideri utilizzare il pacchetto con altri domini, interrompi questa operazione a questo punto. Per continuare a rimuovere il pacchetto (se si tratta di un dizionario personalizzato), scegli **Pacchetti** nel riquadro di navigazione.
1. Seleziona il pacchetto e scegli **Elimina**.
In alternativa, usa l'API AWS CLI SDKs, o configuration per dissociare e rimuovere i pacchetti. Per ulteriori informazioni, consulta [AWS CLI Command Reference](https://docs.aws.amazon.com/cli/latest/reference/) e [Amazon OpenSearch Service API Reference](https://docs.aws.amazon.com/opensearch-service/latest/APIReference/Welcome.html).
# 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.
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\$12.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.
# AWS KMS Integrazione di pacchetti personalizzati Amazon OpenSearch Service
I pacchetti personalizzati di Amazon OpenSearch Service forniscono la crittografia di default per proteggere `ZIP-PLUGIN` i pacchetti inutilizzati Chiavi gestite da AWS.
+ **Chiavi di proprietà di AWS**— I pacchetti personalizzati di Amazon OpenSearch Service utilizzano queste chiavi per impostazione predefinita per crittografare automaticamente i `ZIP-PLUGIN` pacchetti. Non puoi visualizzare, gestire, utilizzare Chiavi di proprietà di AWS o controllare il loro utilizzo. Tuttavia, non è necessario effettuare alcuna operazione o modificare programmi per proteggere le chiavi che eseguono la crittografia dei dati. Per ulteriori informazioni, consulta la sezione [Chiavi di proprietà di AWS](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-owned-cmk) nella *Guida per gli sviluppatori di AWS Key Management Service *.
+ **Chiavi gestite dal cliente**: puoi aggiungere un secondo livello di crittografia rispetto a quello esistente Chiavi di proprietà di AWS scegliendo una chiave gestita dal cliente al momento della creazione del pacchetto `ZIP-PLUGIN` personalizzato.
I pacchetti personalizzati di Amazon OpenSearch Service supportano l'utilizzo di una chiave simmetrica gestita dal cliente che crei, possiedi e gestisci per aggiungere un secondo livello di crittografia alla crittografia di AWS proprietà esistente. Poiché hai il pieno controllo di questo livello di crittografia, puoi eseguire le seguenti attività:
+ Stabilire e mantenere le policy della chiave
+ Stabilire e mantenere politiche e sovvenzioni AWS Identity and Access Management (IAM)
+ Abilitare e disabilitare le policy della chiave
+ Ruotare i materiali crittografici delle chiavi
+ Aggiungere tag
+ Creare alias delle chiavi
+ Pianificare l’eliminazione di chiavi
Per ulteriori informazioni, consulta [Customer managed keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk) nella *Guida per sviluppatori AWS Key Management Service *.
**Nota**
I pacchetti personalizzati di Amazon OpenSearch Service abilitano automaticamente e gratuitamente la crittografia Chiavi di proprietà di AWS a riposo. Tuttavia, quando si utilizza una chiave gestita dal cliente, vengono applicati dei AWS KMS costi. Per ulteriori informazioni sui prezzi, consulta [Prezzi di AWS Key Management Service](https://aws.amazon.com/kms/pricing/).
## In che modo il OpenSearch servizio di pacchetti personalizzati di Amazon Service utilizza le sovvenzioni in AWS KMS
OpenSearch I pacchetti personalizzati di assistenza richiedono una concessione per utilizzare la chiave gestita dal cliente.
Quando crei un `ZIP-PLUGIN` pacchetto crittografato con una chiave gestita dal cliente, il OpenSearch servizio di pacchetti personalizzati di Amazon Service crea una sovvenzione per tuo conto inviando una [CreateGrant](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html)richiesta a AWS KMS. Concede a AWS KMS Ingive OpenSearch Service l'accesso a una AWS KMS chiave del tuo account. Le sovvenzioni create dai pacchetti personalizzati del OpenSearch Servizio hanno un vincolo che consente le operazioni solo quando la richiesta include un contesto di crittografia con l'ID del pacchetto personalizzato.
I pacchetti personalizzati di Amazon OpenSearch Service richiedono la concessione dell'utilizzo della chiave gestita dal cliente per le seguenti operazioni interne:
| Operation | Description |
| --- | --- |
| DescribeKey | Invia DescribeKey richieste per AWS KMS verificare che l'ID della chiave simmetrica gestita dal cliente inserito durante la creazione del pacchetto di plug-in sia valido. |
| GenerateDataKeyWithoutPlaintext | Invia GenerateDataKeyWithoutPlaintext richieste per AWS KMS generare chiavi dati crittografate dalla chiave gestita dal cliente. |
| GenerateDataKey | Invia GenerateDataKey richieste per AWS KMS generare chiavi di dati per crittografare il pacchetto durante la copia interna. |
| Decrypt | Invia Decrypt richieste per AWS KMS decrittografare le chiavi di dati crittografate in modo che possano essere utilizzate per decrittografare i dati. |
Puoi revocare l'accesso alla concessione o rimuovere l'accesso del servizio alla chiave gestita dal cliente in qualsiasi momento. In tal caso, il OpenSearch Servizio non sarà in grado di accedere ai dati crittografati dalla chiave gestita dal cliente, il che influirà sulle operazioni che dipendono da tali dati. Ad esempio, se tenti di associare un pacchetto di plug-in a cui OpenSearch Service non può accedere, l'operazione restituisce un `AccessDeniedException` errore.
## Creazione di una chiave gestita dal cliente
È possibile creare una chiave simmetrica gestita dal cliente utilizzando Console di gestione AWS o il. AWS KMS APIs
**Per creare una chiave simmetrica gestita dal cliente**
+ *Segui i passaggi descritti nella sezione [Creazione di una chiave KMS nella Guida per](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html#create-symmetric-cmk) gli AWS Key Management Service sviluppatori.*
### Policy della chiave
Le policy della chiave controllano l’accesso alla chiave gestita dal cliente. Ogni chiave gestita dal cliente deve avere esattamente una policy della chiave, che contiene istruzioni che determinano chi può usare la chiave e come la possono usare. Quando crei la chiave gestita dal cliente, è possibile specificare una policy della chiave. Per ulteriori informazioni, consulta [Policy delle chiavi in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) nella *Guida per gli sviluppatori di AWS Key Management Service *.
Per utilizzare la chiave gestita dal cliente con le risorse del plug-in, è necessario consentire le seguenti operazioni API nella politica chiave:
+ `kms:CreateGrant`: aggiunge una concessione a una chiave gestita dal cliente. Concede l'accesso di controllo a una AWS KMS chiave specificata, consentendo l'accesso alle operazioni di concessione richieste dai pacchetti personalizzati del OpenSearch servizio. Per ulteriori informazioni sull'utilizzo delle sovvenzioni, consulta la Guida per gli [AWS KMS sviluppatori](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html).
Ciò consente a OpenSearch Service di eseguire le seguenti operazioni:
+ Chiama `GenerateDataKeyWithoutPlainText` per generare una chiave dati crittografata e archiviarla per ulteriori convalide.
+ Chiama `GenerateDataKey` per copiare internamente il pacchetto del plugin.
+ Chiama `Decrypt` per accedere al pacchetto del plugin internamente.
+ Configurare un principale ritirato per consentire al servizio di `RetireGrant`.
+ `kms:DescribeKey`— Fornisce i dettagli chiave gestiti dal cliente per consentire al OpenSearch Servizio di convalidare la chiave.
+ `kms:GenerateDataKey`,`kms:GenerateDataKeyWithoutPlaintext`, `kms:Decrypt` — Fornisce ai pacchetti personalizzati di OpenSearch Service l'accesso per utilizzare queste operazioni nella concessione.
Di seguito sono riportati alcuni esempi di dichiarazioni politiche che è possibile aggiungere per i pacchetti personalizzati di OpenSearch Service:
```
"Statement" : [
{
"Sid" : "Allow access to principals authorized to use OpenSearch Service custom packages",
"Effect" : "Allow",
"Principal" : {
"AWS" : "*"
},
"Action" : [
"kms:CreateGrant",
"kms:GenerateDataKey",
"kms:GenerateDataKeyWithoutPlaintext",
"kms:Decrypt"
],
"Resource" : "*",
"Condition" : {
"StringEquals" : {
"kms:ViaService" : "custom-packages.region.amazonaws.com"
},
"StringEquals" : {
"kms:EncryptionContext:packageId": "Id of the package"
}
}
},
{
"Sid" : "Allow access to principals authorized to use Amazon OpenSearch Service custom packages",
"Effect" : "Allow",
"Principal" : {
"AWS" : "*"
},
"Action" : [
"kms:DescribeKey"
],
"Resource" : "*",
"Condition" : {
"StringEquals" : {
"kms:ViaService" : "custom-packages.region.amazonaws.com"
}
}
}
]
```
Per ulteriori informazioni sulla specificazione delle autorizzazioni in una politica, consulta [le politiche chiave AWS KMS nella Guida](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) per gli *AWS Key Management Service sviluppatori*.
*Per ulteriori informazioni sulla risoluzione dei problemi di accesso tramite chiave, consulta [Risoluzione dei problemi relativi alle AWS KMS autorizzazioni nella Guida](https://docs.aws.amazon.com/kms/latest/developerguide/policy-evaluation.html) per gli AWS Key Management Service sviluppatori.*
## Specificare una chiave gestita dal cliente per i pacchetti personalizzati OpenSearch di Amazon Service
Puoi specificare una chiave gestita dal cliente come secondo livello di crittografia per `ZIP-PLUGIN` i tuoi pacchetti.
Quando si crea un pacchetto di plug-in, è possibile specificare la chiave dati inserendo un ID di AWS KMS chiave, utilizzato dai pacchetti personalizzati di OpenSearch Service per crittografare il pacchetto di plug-in.
*AWS KMS key ID*: un identificatore chiave per una chiave gestita AWS KMS dal cliente. Immetti l’ID della chiave, l’ARN della chiave, il nome dell’alias o l’ARN dell’alias.
## Contesto di crittografia dei pacchetti personalizzati di Amazon OpenSearch Service
Un contesto di crittografia è un set facoltativo di coppie chiave-valore che contengono ulteriori informazioni contestuali sui dati.
AWS KMS utilizza il contesto di crittografia come dati autenticati aggiuntivi per supportare la crittografia autenticata. Quando includi un contesto di crittografia in una richiesta di crittografia dei dati, AWS KMS associa il contesto di crittografia ai dati crittografati. Per decrittografare i dati, nella richiesta deve essere incluso lo stesso contesto di crittografia.
### Contesto di crittografia dei pacchetti personalizzati di Amazon OpenSearch Service
I pacchetti personalizzati di Amazon OpenSearch Service utilizzano lo stesso contesto di crittografia in tutte le operazioni AWS KMS crittografiche, in cui la chiave è `packageId` e il valore è il pacchetto `package-id` di plug-in.
### Usa il contesto di crittografia per il monitoraggio
Quando si utilizza una chiave simmetrica gestita dal cliente per crittografare il pacchetto di plug-in, è possibile utilizzare il contesto di crittografia nei record e nei registri di controllo per identificare come viene utilizzata la chiave gestita dal cliente. Il contesto di crittografia appare anche nei log generati da AWS CloudTrail o Amazon CloudWatch Logs.
### Utilizzo del contesto di crittografia per controllare l’accesso alla chiave gestita dal cliente
È possibile utilizzare il contesto di crittografia nelle policy delle chiavi e nelle policy IAM come condizioni per controllare l’accesso alla chiave simmetrica gestita dal cliente. È possibile utilizzare i vincoli del contesto di crittografia in una concessione.
OpenSearch I pacchetti personalizzati di servizio utilizzano un vincolo di contesto di crittografia nelle concessioni per controllare l'accesso alla chiave gestita dal cliente nell'account o nella regione. Il vincolo della concessione richiede che le operazioni consentite dalla concessione utilizzino il contesto di crittografia specificato.
Di seguito sono riportati alcuni esempi di istruzioni delle policy della chiave per concedere l’accesso a una chiave gestita dal cliente per un contesto di crittografia specifico. Questa istruzione della policy impone come condizione che le concessioni abbiano un vincolo che specifica il contesto di crittografia.
```
{
"Sid": "Enable DescribeKey",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/ExampleReadOnlyRole"
},
"Action": "kms:DescribeKey",
"Resource": "*"
},
{
"Sid": "Enable OpenSearch Service custom packages to use the key",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/ExampleReadOnlyRole"
},
"Action" : [
"kms:CreateGrant",
"kms:GenerateDataKey",
"kms:GenerateDataKeyWithoutPlaintext",
"kms:Decrypt"
],
"Resource": "*",
"Condition": {
"StringEquals" : {
"kms:EncryptionContext:packageId": "ID of the package"
}
}
}
```
## Monitoraggio delle chiavi di crittografia per OpenSearch il servizio di pacchetti personalizzati
Quando utilizzi una chiave gestita AWS KMS dal cliente con le risorse del OpenSearch servizio Service Custom Packages, puoi utilizzare CloudTrail o CloudWatch Logs per tenere traccia delle richieste a cui vengono inviati i pacchetti OpenSearch personalizzati. AWS KMS
**Ulteriori informazioni**
Le seguenti risorse forniscono ulteriori informazioni sulla crittografia dei dati a riposo.
+ Per ulteriori informazioni sui concetti AWS KMS di base, consulta [AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html)la *Guida per gli AWS Key Management Service sviluppatori*.
+ Per ulteriori informazioni sulle migliori pratiche di sicurezza per AWS KMS, consulta la *guida AWS Prescriptive* Guidance per le [AWS Key Management Service migliori](https://docs.aws.amazon.com/kms/latest/developerguide/best-practices.html) pratiche.
# Installazione di plug-in di terze parti in Amazon Service OpenSearch
Amazon OpenSearch Service supporta plug-in di terze parti di partner selezionati. Questi plugin possono migliorare la OpenSearch configurazione con funzionalità aggiuntive come analizzatori personalizzati, tokenizzatori o funzionalità di crittografia. Segui le istruzioni specifiche di installazione e configurazione fornite dagli sviluppatori di terze parti per garantire la corretta integrazione con il tuo dominio di servizio. OpenSearch
**Nota**
È necessario ottenere e mantenere licenze valide direttamente dagli sviluppatori di terze parti. Alcuni provider potrebbero non abilitare completamente i propri plug-in Regioni AWS, quindi verifica la disponibilità con il fornitore del plug-in.
I seguenti plugin di terze parti sono disponibili per l'uso con OpenSearch Service:
+ **Plugin di crittografia Portal26 (Titanium-lockbox)**: utilizza la crittografia certificata NIST FIPS 140-2 per crittografare i dati durante l'indicizzazione. Include il supporto Bring Your Own Key (BYOK), che consente di gestire le chiavi di crittografia per una maggiore sicurezza. Il plugin è fornito da [Portal26](https://portal26.ai/) e richiede la OpenSearch versione 2.15 o successiva.
+ **Name Match (RNI)**: abbina nomi, organizzazioni, indirizzi e date in oltre 24 lingue, il che migliora la sicurezza e la conformità. Il plugin è fornito da [Babel Street](https://www.babelstreet.com/) e richiede la OpenSearch versione 2.15 o successiva.
**Topics**
+ [Prerequisiti](#prerequisites-partner-plugins)
+ [Installazione di plugin di terze parti](#third-party-partner-plugins-install)
+ [Fasi successive](#third-party-partner-plugins-next)
## Prerequisiti
Prima di installare un plug-in di terze parti, effettuate le seguenti operazioni:
+ Ha ottenuto i file di configurazione e licenza del plug-in e li ha caricati in un bucket Amazon S3. Il bucket deve appartenere allo stesso Regione AWS dominio.
+ Un plug-in di terze parti è un tipo di plug-in personalizzato. Assicurati che il dominio soddisfi i [prerequisiti per i](custom-plugins.md#custom-plugin-prerequisites) plugin personalizzati.
## Installazione di plugin di terze parti
Per associare un plug-in di terze parti a un dominio di OpenSearch servizio, devi prima caricare tre pacchetti separati: il pacchetto di *licenza*, il pacchetto di *configurazione* e il pacchetto del *plug-in*.
+ Il pacchetto di **licenza** include le informazioni sulla licenza o i metadati associati al plug-in, in formato.json o.xml.
+ Il pacchetto **di configurazione** contiene i file di configurazione del plug-in e le risorse e le impostazioni di supporto. Questi file definiscono il comportamento o l'integrazione del plugin con. OpenSearch
+ Il pacchetto del **plugin** contiene il file binario del plugin compilato, che è il codice eseguibile che OpenSearch viene eseguito. Questo è il fulcro della funzionalità del plugin.
Dopo aver caricato entrambi i pacchetti, puoi associare il plugin e la licenza a un dominio compatibile.
### 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 plug-in di terze parti**
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. Innanzitutto, importa il pacchetto di licenza. Scegli **Importa pacchetto**.
1. Per **Tipo di pacchetto**, scegli **Licenza**.
1. Per **Package source**, inserisci il percorso del file JSON o XML della licenza in Amazon S3.
1. Scegli **Importa**. **Il pacchetto viene visualizzato nella scheda **Licenze** della pagina Pacchetti.**
1. Ora, importa la configurazione del plugin. Scegli nuovamente **Importa pacchetto**.
1. Per **Tipo di Package**, scegli **Configuration**.
1. Per **Package source**, inserisci il percorso del file ZIP di configurazione del plug-in in Amazon S3.
1. Scegli **Importa**.
1. Infine, importa il plugin stesso. Scegli **Importa pacchetto**.
1. Per **Tipo di pacchetto**, scegli **Plugin**.
1. Per **Package source**, inserisci il percorso del file ZIP del plug-in in Amazon S3.
1. Seleziona la versione OpenSearch del motore supportata dal plug-in.
1. Scegli **Importa**.
**Per associare un plug-in di terze parti a un dominio**
1. Ora associa la licenza e la configurazione del plugin al dominio. Nel riquadro di navigazione a sinistra, scegli **Domains** (Domini).
1. Scegli il nome del dominio per aprire la configurazione del cluster.
1. Vai alla scheda **Plugin**.
1. Scegli **Associa pacchetti** e seleziona il plugin, la licenza e i pacchetti di configurazione che hai appena importato.
1. Scegli **Seleziona**.
1. Scegli **Next (Successivo)**. Esamina i pacchetti da associare e scegli **Associa**.
### CLI
Innanzitutto, utilizzate il comando [create-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/create-package.html) per creare un nuovo pacchetto che contenga la licenza del plugin. `S3Key`Deve puntare a un file.json o.xml in Amazon S3 che includa il testo o i metadati della licenza.
```
aws opensearch create-package \
--package-name plugin-license-package \
--package-type PACKAGE-LICENSE \
--package-source S3BucketName=my-bucket,S3Key=licenses/my-plugin-license.json
```
Usa nuovamente il comando [create-package per creare un pacchetto](https://docs.aws.amazon.com/cli/latest/reference/opensearch/create-package.html) che contenga la configurazione del plugin. `S3Key`Deve puntare a un file.zip in Amazon S3 che aderisca alla struttura di directory prevista dal plug-in.
```
aws opensearch create-package \
--package-name plugin-config-package \
--package-type PACKAGE-CONFIG \
--package-source S3BucketName=my-bucket,S3Key=path/to/package.zip
```
Usa nuovamente il comando [create-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/create-package.html) per creare un pacchetto che contenga il plugin stesso. `S3Key`Deve puntare al file.zip del plugin in Amazon S3.
```
aws opensearch create-package \
--package-name plugin-package \
--package-type ZIP-PLUGIN \
--package-source S3BucketName=my-bucket,S3Key=path/to/package.zip
```
Infine, usa il comando [associate-package](https://docs.aws.amazon.com/cli/latest/reference/opensearch/associate-package.html) per collegare il plug-in partner, la licenza e la configurazione a un dominio compatibile specificando il pacchetto per ciascuno. IDs Specificate l'ID del plugin come prerequisito per gli altri pacchetti, il che significa che deve essere associato al dominio prima degli altri pacchetti.
```
aws opensearch associate-packages \
--domain-name my-domain \
--package-list '[{"PackageID": "plugin-package-id"},{"PackageID": "license-package-id","PrerequisitePackageIDList":["plugin-package-id"]},{"PackageID":"config-package-id","PrerequisitePackageIDList":["plugin-package-id"]}]'
```
## Fasi successive
Una volta completata l'associazione, potete abilitare il plugin su indici specifici o configurarlo secondo necessità in base alle vostre esigenze. Per applicare la funzionalità dei plug-in di terze parti a indici specifici, modifica le impostazioni dell'indice durante la creazione dell'indice o aggiorna gli indici esistenti. Ad esempio, se il tuo plug-in di terze parti include un [analizzatore personalizzato](https://opensearch.org/docs/latest/analyzers/custom-analyzer/), fai riferimento a esso nelle impostazioni dell'indice.
Per applicare le funzionalità del plug-in in modo uniforme su più indici, utilizzate [modelli di indice](https://opensearch.org/docs/latest/im-plugin/index-templates/) che includono le configurazioni del plug-in. Consultate sempre la documentazione del plugin per capire come configurarne le funzionalità per la vostra configurazione. OpenSearch