Autorizzazioni minime richieste OpenSearch Ingestione Fluent Bit Amazon Data Firehose Go Java JavaScript Logstash Python Ruby Altri clienti

Inserimento di dati in raccolte Amazon Serverless OpenSearch

Queste sezioni forniscono dettagli sulle pipeline di importazione supportate per l'inserimento di dati nelle raccolte Amazon OpenSearch Serverless. Esse riguardano anche alcuni client che puoi utilizzare per interagire con le operazioni. OpenSearch API I tuoi client devono essere compatibili con OpenSearch 2.x per integrarsi con OpenSearch Serverless.

Argomenti

Autorizzazioni minime richieste
OpenSearch Ingestione
Fluent Bit
Amazon Data Firehose
Go
Java
JavaScript
Logstash
Python
Ruby
Firma HTTP delle richieste con altri client

Autorizzazioni minime richieste

Per inserire dati in una raccolta OpenSearch Serverless, il responsabile che scrive i dati deve disporre delle seguenti autorizzazioni minime assegnate in una politica di accesso ai dati:


[
   {
      "Rules":[
         {
            "ResourceType":"index",
            "Resource":[
               "index/target-collection/logs"
            ],
            "Permission":[
               "aoss:CreateIndex",
               "aoss:WriteDocument",
               "aoss:UpdateIndex"
            ]
         }
      ],
      "Principal":[
         "arn:aws:iam::123456789012:user/my-user"
      ]
   }
]

Le autorizzazioni possono essere più ampie se prevedi di scrivere su indici aggiuntivi. Ad esempio, anziché specificare un singolo indice di destinazione, è possibile concedere l'autorizzazione a tutti gli indici (index/target-collection/*) o un sottoinsieme di indici (index/target-collection/logs*).

Per un riferimento a tutte le OpenSearch API operazioni disponibili e alle relative autorizzazioni, vedere. Operazioni e plugin supportati in Amazon Serverless OpenSearch

OpenSearch Ingestione

Invece di utilizzare un client di terze parti per inviare dati direttamente a una raccolta OpenSearch Serverless, puoi utilizzare Amazon OpenSearch Ingestion. Puoi configurare i tuoi produttori di dati per inviare dati a OpenSearch Ingestion, che li consegna automaticamente alla raccolta specificata. Puoi anche configurare OpenSearch Ingestion per trasformare i dati prima di consegnarli. Per ulteriori informazioni, consulta OpenSearch Ingestione di Amazon.

Una pipeline OpenSearch di Ingestion necessita dell'autorizzazione per scrivere su una raccolta OpenSearch Serverless configurata come sink. Queste autorizzazioni includono la possibilità di descrivere la raccolta e inviarvi richieste. HTTP Per istruzioni su come utilizzare OpenSearch Ingestion per aggiungere dati a una raccolta, consulta. Concedere alle pipeline OpenSearch di Amazon Ingestion l'accesso alle raccolte

Per iniziare a usare OpenSearch Ingestion, consulta. Tutorial: Inserimento di dati in una raccolta con Amazon Ingestion OpenSearch

Fluent Bit

È possibile utilizzare AWS per l'immagine Fluent Bit e il plug-in OpenSearch di output per inserire dati nelle raccolte OpenSearch Serverless.

Nota

È necessario disporre della versione 2.30.0 o successiva di AWS per l'immagine Fluent Bit per l'integrazione con Serverless. OpenSearch

Configurazione di esempio:

Questa sezione di output di esempio del file di configurazione mostra come utilizzare una raccolta OpenSearch Serverless come destinazione. L'aggiunta importante è il parametro AWS_Service_Name, che è aoss. Host è l'endpoint della raccolta.


[OUTPUT]
    Name  opensearch
    Match *
    Host  collection-endpoint.us-west-2.aoss.amazonaws.com
    Port  443
    Index  my_index
    Trace_Error On
    Trace_Output On
    AWS_Auth On
    AWS_Region <region>
    AWS_Service_Name aoss
    tls     On
    Suppress_Type_Name On

Amazon Data Firehose

Firehose supporta OpenSearch Serverless come destinazione di consegna. Per istruzioni su come inviare dati in OpenSearch Serverless, consulta Creating a Kinesis Data Firehose Delivery Stream e OpenSearch Choose Serverless for Your Destination nella Amazon Data Firehose Developer Guide.

Il IAM ruolo assegnato a Firehose per la consegna deve essere specificato all'interno di una policy di accesso ai dati con l'autorizzazione aoss:WriteDocument minima per la raccolta di destinazione ed è necessario disporre di un indice preesistente a cui inviare i dati. Per ulteriori informazioni, consulta Autorizzazioni minime richieste.

Prima di inviare dati a OpenSearch Serverless, potrebbe essere necessario eseguire delle trasformazioni sui dati. Per ulteriori informazioni su come usare le funzioni Lambda per completare questa attività, consultare Trasformazione dei dati di Amazon Kinesis Data Firehose nella stessa guida.

Go

Il codice di esempio seguente utilizza il client opensearch-go per Go per stabilire una connessione sicura alla raccolta OpenSearch Serverless specificata e creare un singolo indice. È necessario fornire valori per region e host.


package main

import (
  "context"
  "log"
  "strings"
  "github.com/aws/aws-sdk-go-v2/aws"
  "github.com/aws/aws-sdk-go-v2/config"
  opensearch "github.com/opensearch-project/opensearch-go/v2"
  opensearchapi "github.com/opensearch-project/opensearch-go/v2/opensearchapi"
  requestsigner "github.com/opensearch-project/opensearch-go/v2/signer/awsv2"
)

const endpoint = "" // serverless collection endpoint

func main() {
	ctx := context.Background()

	awsCfg, err := config.LoadDefaultConfig(ctx,
		config.WithRegion("<AWS_REGION>"),
		config.WithCredentialsProvider(
			getCredentialProvider("<AWS_ACCESS_KEY>", "<AWS_SECRET_ACCESS_KEY>", "<AWS_SESSION_TOKEN>"),
		),
	)
	if err != nil {
		log.Fatal(err) // don't log.fatal in a production-ready app
	}

	// create an AWS request Signer and load AWS configuration using default config folder or env vars.
	signer, err := requestsigner.NewSignerWithService(awsCfg, "aoss") // "aoss" for Amazon OpenSearch Serverless
	if err != nil {
		log.Fatal(err) // don't log.fatal in a production-ready app
	}

	// create an opensearch client and use the request-signer
	client, err := opensearch.NewClient(opensearch.Config{
		Addresses: []string{endpoint},
		Signer:    signer,
	})
	if err != nil {
		log.Fatal("client creation err", err)
	}

	indexName := "go-test-index"

  // define index mapping
	mapping := strings.NewReader(`{
	 "settings": {
	   "index": {
	        "number_of_shards": 4
	        }
	      }
	 }`)

	// create an index
	createIndex := opensearchapi.IndicesCreateRequest{
		Index: indexName,
    Body: mapping,
	}
	createIndexResponse, err := createIndex.Do(context.Background(), client)
	if err != nil {
		log.Println("Error ", err.Error())
		log.Println("failed to create index ", err)
		log.Fatal("create response body read err", err)
	}
	log.Println(createIndexResponse)

	// delete the index
	deleteIndex := opensearchapi.IndicesDeleteRequest{
		Index: []string{indexName},
	}

	deleteIndexResponse, err := deleteIndex.Do(context.Background(), client)
	if err != nil {
		log.Println("failed to delete index ", err)
		log.Fatal("delete index response body read err", err)
	}
	log.Println("deleting index", deleteIndexResponse)
}

func getCredentialProvider(accessKey, secretAccessKey, token string) aws.CredentialsProviderFunc {
	return func(ctx context.Context) (aws.Credentials, error) {
		c := &aws.Credentials{
			AccessKeyID:     accessKey,
			SecretAccessKey: secretAccessKey,
			SessionToken:    token,
		}
		return *c, nil
	}
}

Java

Il codice di esempio seguente utilizza il client opensearch-java per Java per stabilire una connessione sicura alla raccolta OpenSearch Serverless specificata e creare un singolo indice. È necessario fornire valori per region e host.

La differenza importante rispetto ai domini di OpenSearch servizio è il nome del servizio (anziché). aoss es


// import OpenSearchClient to establish connection to OpenSearch Serverless collection
import org.opensearch.client.opensearch.OpenSearchClient;

SdkHttpClient httpClient = ApacheHttpClient.builder().build();
// create an opensearch client and use the request-signer
OpenSearchClient client = new OpenSearchClient(
    new AwsSdk2Transport(
        httpClient,
        "...us-west-2.aoss.amazonaws.com", // serverless collection endpoint
        "aoss" // signing service name
        Region.US_WEST_2, // signing service region
        AwsSdk2TransportOptions.builder().build()
    )
);

String index = "sample-index";

// create an index
CreateIndexRequest createIndexRequest = new CreateIndexRequest.Builder().index(index).build();
CreateIndexResponse createIndexResponse = client.indices().create(createIndexRequest);
System.out.println("Create index reponse: " + createIndexResponse);

// delete the index
DeleteIndexRequest deleteIndexRequest = new DeleteIndexRequest.Builder().index(index).build();
DeleteIndexResponse deleteIndexResponse = client.indices().delete(deleteIndexRequest);
System.out.println("Delete index reponse: " + deleteIndexResponse);

httpClient.close();

Il codice di esempio seguente stabilisce nuovamente una connessione sicura e quindi esegue la ricerca in un indice.


import org.opensearch.client.opensearch.OpenSearchClient;
>>>>>>> aoss-slr-update

SdkHttpClient httpClient = ApacheHttpClient.builder().build();

OpenSearchClient client = new OpenSearchClient(
    new AwsSdk2Transport(
        httpClient,
        "...us-west-2.aoss.amazonaws.com", // serverless collection endpoint
        "aoss" // signing service name
        Region.US_WEST_2, // signing service region
        AwsSdk2TransportOptions.builder().build()
    )
);

Response response = client.generic()
    .execute(
        Requests.builder()
            .endpoint("/" + "users" + "/_search?typed_keys=true")
            .method("GET")
            .json("{"
                + "    \"query\": {"
                + "        \"match_all\": {}"
                + "    }"
                + "}")
            .build());

httpClient.close();

JavaScript

Il codice di esempio seguente utilizza il client opensearch-js per JavaScript stabilire una connessione sicura alla raccolta OpenSearch Serverless specificata, creare un singolo indice, aggiungere un documento ed eliminare l'indice. È necessario fornire valori per node e region.

La differenza importante rispetto ai domini di OpenSearch servizio è il nome del servizio (anziché). aoss es

Version 3

Questo esempio utilizza la versione 3 del modulo SDK JavaScript in Node.js.


const { defaultProvider } = require('@aws-sdk/credential-provider-node');
const { Client } = require('@opensearch-project/opensearch');
const { AwsSigv4Signer } = require('@opensearch-project/opensearch/aws');

async function main() {
    // create an opensearch client and use the request-signer
    const client = new Client({
        ...AwsSigv4Signer({
            region: 'us-west-2',
            service: 'aoss',
            getCredentials: () => {
                const credentialsProvider = defaultProvider();
                return credentialsProvider();
            },
        }),
        node: '' # // serverless collection endpoint
    });

    const index = 'movies';

    // create index if it doesn't already exist
    if (!(await client.indices.exists({ index })).body) {
        console.log((await client.indices.create({ index })).body);
    }

    // add a document to the index
    const document = { foo: 'bar' };
    const response = await client.index({
        id: '1',
        index: index,
        body: document,
    });
    console.log(response.body);

    // delete the index
    console.log((await client.indices.delete({ index })).body);
}

main();

Version 2

Questo esempio utilizza la versione 2 del SDK modulo JavaScript in Node.js.


const AWS = require('aws-sdk');
const { Client } = require('@opensearch-project/opensearch');
const { AwsSigv4Signer } = require('@opensearch-project/opensearch/aws');

async function main() {
    // create an opensearch client and use the request-signer
    const client = new Client({
        ...AwsSigv4Signer({
            region: 'us-west-2',
            service: 'aoss',
            getCredentials: () =>
                new Promise((resolve, reject) => {
                    AWS.config.getCredentials((err, credentials) => {
                        if (err) {
                            reject(err);
                        } else {
                            resolve(credentials);
                        }
                    });
                }),
        }),
        node: '' # // serverless collection endpoint
    });

    const index = 'movies';

    // create index if it doesn't already exist
    if (!(await client.indices.exists({ index })).body) {
        console.log((await client.indices.create({
            index
        })).body);
    }

    // add a document to the index
    const document = {
        foo: 'bar'
    };
    const response = await client.index({
        id: '1',
        index: index,
        body: document,
    });
    console.log(response.body);

    // delete the index
    console.log((await client.indices.delete({ index })).body);
}

main();

Logstash

È possibile utilizzare il OpenSearch plug-in Logstash per pubblicare i log nelle raccolte Serverless. OpenSearch

Per utilizzare Logstash per inviare dati a Serverless OpenSearch

Installa la versione 2.0.0 o successiva del logstash-output-opensearchplug-in utilizzando Docker o Linux.
Docker
Docker ospita il OSS software Logstash con il plug-in di OpenSearch output preinstallato: opensearchproject/ -output-plugin. logstash-oss-with-opensearch Puoi estrarre l'immagine come qualsiasi altra immagine:
```
docker pull opensearchproject/logstash-oss-with-opensearch-output-plugin:latest
```
Linux
Per prima cosa, se ancora non è stato fatto, installa la versione più recente di Logstash. Quindi, installa la versione 2.0.0 del plug-in di output:
```
cd logstash-8.5.0/
bin/logstash-plugin install --version 2.0.0 logstash-output-opensearch 
```
Se il plug-in è già installato, aggiornalo alla versione più recente:
```
bin/logstash-plugin update logstash-output-opensearch 
```
A partire dalla versione 2.0.0 del plugin, AWS SDKutilizza la versione 3. Se utilizzi una versione di Logstash precedente alla 8.4.0, devi rimuovere tutte le versioni preinstallate AWS plugin e installa il plugin: logstash-integration-aws
```
/usr/share/logstash/bin/logstash-plugin remove logstash-input-s3
/usr/share/logstash/bin/logstash-plugin remove logstash-input-sqs
/usr/share/logstash/bin/logstash-plugin remove logstash-output-s3
/usr/share/logstash/bin/logstash-plugin remove logstash-output-sns
/usr/share/logstash/bin/logstash-plugin remove logstash-output-sqs
/usr/share/logstash/bin/logstash-plugin remove logstash-output-cloudwatch

/usr/share/logstash/bin/logstash-plugin install --version 0.1.0.pre logstash-integration-aws
```

Affinché il plugin OpenSearch di output funzioni con OpenSearch Serverless, è necessario apportare le seguenti modifiche alla sezione di opensearch output di logstash.conf:

Specifica aoss come service_name in auth_type.
Specifica l'endpoint di raccolta per hosts.
Aggiungi i parametri default_server_major_version e legacy_template. Questi parametri sono necessari per il funzionamento del plugin con Serverless. OpenSearch


output {
  opensearch {
    hosts => "collection-endpoint:443"
    auth_type => {
      ...
      service_name => 'aoss'
    }
    default_server_major_version => 2
    legacy_template => false
  }
}

Questo file di configurazione di esempio prende l'input dai file in un bucket S3 e li invia a una OpenSearch raccolta Serverless:


input {
  s3  {
    bucket => "my-s3-bucket"
    region => "us-east-1"
  }
}

output {
  opensearch {
    ecs_compatibility => disabled
    hosts => "https://my-collection-endpoint.us-east-1.aoss.amazonaws.com:443"
    index => my-index
    auth_type => {
      type => 'aws_iam'
      aws_access_key_id => 'your-access-key'
      aws_secret_access_key => 'your-secret-key'
      region => 'us-east-1'
      service_name => 'aoss'
    }
    default_server_major_version => 2
    legacy_template => false
  }
}

Quindi, esegui Logstash con la nuova configurazione per testare il plug-in:
```
bin/logstash -f config/test-plugin.conf
```

Python

Il codice di esempio seguente utilizza il client opensearch-py per Python per stabilire una connessione sicura alla raccolta OpenSearch Serverless specificata, creare un singolo indice e cercare nell'indice. È necessario fornire valori per region e host.

La differenza importante rispetto ai domini di OpenSearch servizio è il nome del servizio (anziché). aoss es


from opensearchpy import OpenSearch, RequestsHttpConnection, AWSV4SignerAuth
import boto3

host = ''  # serverless collection endpoint, without https://
region = ''  # e.g. us-east-1

service = 'aoss'
credentials = boto3.Session().get_credentials()
auth = AWSV4SignerAuth(credentials, region, service)

# create an opensearch client and use the request-signer
client = OpenSearch(
    hosts=[{'host': host, 'port': 443}],
    http_auth=auth,
    use_ssl=True,
    verify_certs=True,
    connection_class=RequestsHttpConnection,
    pool_maxsize=20,
)

# create an index
index_name = 'books-index'
create_response = client.indices.create(
    index_name
)

print('\nCreating index:')
print(create_response)

# index a document
document = {
  'title': 'The Green Mile',
  'director': 'Stephen King',
  'year': '1996'
}

response = client.index(
    index = 'books-index',
    body = document,
    id = '1'
)


# delete the index
delete_response = client.indices.delete(
    index_name
)

print('\nDeleting index:')
print(delete_response)

Ruby

La opensearch-aws-sigv4 gemma fornisce l'accesso OpenSearch immediato a Serverless, insieme a OpenSearch Service. Ha tutte le funzionalità del client opensearch-ruby perché è una dipendenza di questo pacchetto gem.

Quando si crea un'istanza del firmatario Sigv4, specifica aoss come nome del servizio:


require 'opensearch-aws-sigv4'
require 'aws-sigv4'

signer = Aws::Sigv4::Signer.new(service: 'aoss',
                                region: 'us-west-2',
                                access_key_id: 'key_id',
                                secret_access_key: 'secret')

# create an opensearch client and use the request-signer
client = OpenSearch::Aws::Sigv4Client.new(
  { host: 'https://your.amz-opensearch-serverless.endpoint',
    log: true },
  signer)

# create an index
index = 'prime'
client.indices.create(index: index)

# insert data
client.index(index: index, id: '1', body: { name: 'Amazon Echo', 
                                            msrp: '5999', 
                                            year: 2011 })

# query the index
client.search(body: { query: { match: { name: 'Echo' } } })

# delete index entry
client.delete(index: index, id: '1')

# delete the index
client.indices.delete(index: index)

Firma HTTP delle richieste con altri client

I seguenti requisiti si applicano quando si firmano le richieste nelle raccolte OpenSearch Serverless quando si creano HTTP richieste con altri client.

È necessario specificare il nome del servizio come aoss.
L'x-amz-content-sha256intestazione è obbligatoria per tutti AWS Richieste Signature Version 4. Fornisce un hash del payload di richiesta. Se è presente un payload di richiesta, imposta il valore sull'hash crittografico Secure Hash Algorithm (SHA). SHA256 Se non c'è alcun payload di richiesta, imposta il valore su e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855, che è l'hash di una stringa vuota.

Indicizzazione con c URL

La seguente richiesta di esempio utilizza la Client URL Request Library (cURL) per inviare un singolo documento a un indice denominato movies-index all'interno di una raccolta:


curl -XPOST \
    --user "$AWS_ACCESS_KEY_ID":"$AWS_SECRET_ACCESS_KEY" \
    --aws-sigv4 "aws:amz:us-east-1:aoss" \
    --header "x-amz-content-sha256: $REQUEST_PAYLOAD_SHA_HASH" \
    --header "x-amz-security-token: $AWS_SESSION_TOKEN" \
    "https://my-collection-endpoint.us-east-1.aoss.amazonaws.com/movies-index/_doc" \
    -H "Content-Type: application/json" -d '{"title": "Shawshank Redemption"}'

Indicizzazione con Postman

L'immagine seguente mostra come inviare una richiesta a una raccolta utilizzando Postman. Per istruzioni sull'autenticazione, consulta Autenticazione con AWS Flusso di lavoro di autenticazione delle firme in Postman.

JSON response showing creation of a "movies-index" with successful result and no shards.

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Gestione dei limiti di capacità

Sicurezza in modalità serverless OpenSearch