Daten in Amazon OpenSearch Serverless-Sammlungen aufnehmen

Diese Abschnitte enthalten Einzelheiten zu den unterstützten Ingest-Pipelines für die Datenaufnahme in Amazon Serverless Collections. OpenSearch Sie behandeln auch einige der Clients, mit denen Sie mit den Vorgängen interagieren können. OpenSearch API Ihre Clients sollten mit OpenSearch 2.x kompatibel sein, um sie in OpenSearch Serverless integrieren zu können.

Erforderliche Mindestberechtigungen

Um Daten in eine OpenSearch serverlose Sammlung aufzunehmen, muss dem Principal, der die Daten schreibt, in einer Datenzugriffsrichtlinie die folgenden Mindestberechtigungen zugewiesen werden:

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

Die Berechtigungen können umfassender sein, wenn Sie in zusätzliche Indizes schreiben möchten. Anstatt beispielsweise einen einzelnen Zielindex anzugeben, können Sie Berechtigungen für alle Indizes gewähren (index/target-collection/*) oder eine Teilmenge von Indizes (index/target-collection/logs*).

Eine Referenz aller verfügbaren OpenSearch API Operationen und der zugehörigen Berechtigungen finden Sie unter. Unterstützte Operationen und Plugins in Amazon OpenSearch Serverless

OpenSearch Verschlucken

Anstatt einen Drittanbieter-Client zu verwenden, um Daten direkt an eine OpenSearch serverlose Sammlung zu senden, können Sie Amazon OpenSearch Ingestion verwenden. Sie konfigurieren Ihre Datenproduzenten so, dass sie Daten an OpenSearch Ingestion senden, und Ingestion übermittelt die Daten automatisch an die von Ihnen angegebene Sammlung. Sie können OpenSearch Ingestion auch so konfigurieren, dass Ihre Daten vor der Bereitstellung transformiert werden. Weitere Informationen finden Sie unter OpenSearch Einnahme durch Amazon.

Eine OpenSearch Ingestion-Pipeline benötigt die Berechtigung, in eine OpenSearch serverlose Sammlung zu schreiben, die als Senke konfiguriert ist. Zu diesen Berechtigungen gehört die Möglichkeit, die Sammlung zu beschreiben und HTTP Anfragen an sie zu senden. Anweisungen zur Verwendung von OpenSearch Ingestion zum Hinzufügen von Daten zu einer Sammlung finden Sie unter. Amazon OpenSearch Ingestion-Pipelines Zugriff auf Sammlungen gewähren

Informationen zu den ersten Schritten mit OpenSearch Ingestion finden Sie unter. Tutorial: Daten mit Amazon OpenSearch Ingestion in eine Sammlung aufnehmen

Fluent Bit

Sie können verwenden AWS für Fluent Bit Image und das OpenSearch Output-Plugin, um Daten in OpenSearch serverlose Sammlungen aufzunehmen.

Anmerkung

Sie benötigen Version 2.30.0 oder höher von AWS für Fluent Bit Image, um es in Serverless zu integrieren. OpenSearch

Beispielkonfiguration:

Dieser Beispielausgabeabschnitt der Konfigurationsdatei zeigt, wie eine OpenSearch serverlose Sammlung als Ziel verwendet wird. Die wichtige Ergänzung ist der AWS_Service_Name-Parameter, der aoss ist. Host ist der Sammlungsendpunkt.

[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 unterstützt OpenSearch Serverless als Lieferziel. Anweisungen zum Senden von Daten an OpenSearch Serverless finden Sie unter Creating a Kinesis Data Firehose Delivery Stream and Choose OpenSearch Serverless for Your Destination im Amazon Data Firehose Developer Guide.

Die IAM Rolle, die Sie Firehose für die Bereitstellung zur Verfügung stellen, muss in einer Datenzugriffsrichtlinie mit der aoss:WriteDocument Mindestberechtigung für die Zielsammlung angegeben werden, und Sie müssen über einen bereits vorhandenen Index verfügen, an den Daten gesendet werden können. Weitere Informationen finden Sie unter Erforderliche Mindestberechtigungen.

Bevor Sie Daten an OpenSearch Serverless senden, müssen Sie möglicherweise Transformationen an den Daten durchführen. Weitere Informationen über die Verwendung von Lambda-Funktionen zur Ausführung dieser Aufgabe finden Sie unter Amazon Kinesis Data Firehose Datentransformation im selben Handbuch.

Go

Der folgende Beispielcode verwendet den opensearch-go-Client für Go, um eine sichere Verbindung zur angegebenen OpenSearch Serverless-Sammlung herzustellen und einen einzelnen Index zu erstellen. Sie müssen Werte für region und host angeben.

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

Der folgende Beispielcode verwendet den opensearch-java-Client für Java, um eine sichere Verbindung zur angegebenen OpenSearch Serverless-Sammlung herzustellen und einen einzelnen Index zu erstellen. Sie müssen Werte für region und host angeben.

Der wichtige Unterschied zu OpenSearch Service-Domains ist der Dienstname (aossanstelle von). 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();   

Der folgende Beispielcode stellt erneut eine sichere Verbindung her und durchsucht dann einen Index.

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

Im folgenden Beispielcode wird der opensearch-js-Client verwendet, JavaScript um eine sichere Verbindung zur angegebenen OpenSearch Serverless-Sammlung herzustellen, einen einzelnen Index zu erstellen, ein Dokument hinzuzufügen und den Index zu löschen. Sie müssen Werte für node und region angeben.

Der wichtige Unterschied zu OpenSearch Dienstdomänen ist der Dienstname (aossanstelle von). es

Version 3

In diesem Beispiel wird Version 3 von SDK for JavaScript in Node.js verwendet.

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

In diesem Beispiel wird Version 2 von SDK for JavaScript in Node.js verwendet.

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

Sie können das OpenSearch Logstash-Plugin verwenden, um Logs in OpenSearch serverlosen Sammlungen zu veröffentlichen.

Um Logstash zu verwenden, um Daten an Serverless zu senden OpenSearch

1. Installieren Sie Version 2.0.0 oder höher des logstash-output-opensearchPlugins mit Docker oder Linux.

   Docker

   Docker hostet die OSS Logstash-Software mit dem vorinstallierten Ausgabe-Plugin: opensearchproject/ OpenSearch -output-plugin. logstash-oss-with-opensearch Sie können das Image wie jedes andere Image abrufen:

   docker pull opensearchproject/logstash-oss-with-opensearch-output-plugin:latest

   Linux

   Installieren Sie zunächst die neueste Version von Logstash, falls Sie dies noch nicht getan haben. Installieren Sie anschließend Version 2.0.0 des Ausgabe-Plugins:

   cd logstash-8.5.0/
   bin/logstash-plugin install --version 2.0.0 logstash-output-opensearch 

   Wenn das Plugin bereits installiert ist, aktualisieren Sie es auf die neueste Version:

   bin/logstash-plugin update logstash-output-opensearch 

   Ab Version 2.0.0 des Plugins ist AWS SDKverwendet Version 3. Wenn Sie eine Logstash-Version vor 8.4.0 verwenden, müssen Sie alle vorinstallierten Versionen entfernen AWS Plugins und installiere das 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

2. Damit das OpenSearch Ausgabe-Plugin mit OpenSearch Serverless funktioniert, müssen Sie die folgenden Änderungen am opensearch Ausgabebereich von logstash.conf vornehmen:

   • Geben Sie aoss als service_name unter auth_type an.

   • Geben Sie Ihren Sammlungsendpunkt für hosts an.

   • Fügen Sie die Parameter default_server_major_version und legacy_template hinzu. Diese Parameter sind erforderlich, damit das Plugin mit Serverless funktioniert. OpenSearch

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

   Diese Beispielkonfigurationsdatei verwendet ihre Eingabe aus Dateien in einem S3-Bucket und sendet sie an eine OpenSearch Serverless-Sammlung:

   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
     }
   }

3. Führen Sie dann Logstash mit der neuen Konfiguration aus, um das Plugin zu testen:

   bin/logstash -f config/test-plugin.conf

Python

Der folgende Beispielcode verwendet den opensearch-py-Client für Python, um eine sichere Verbindung zur angegebenen OpenSearch Serverless-Sammlung herzustellen, einen einzelnen Index zu erstellen und diesen Index zu durchsuchen. Sie müssen Werte für region und host angeben.

Der wichtige Unterschied zu OpenSearch Dienstdomänen ist der Dienstname (aossanstelle von). 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

Das opensearch-aws-sigv4 Gem bietet standardmäßig Zugriff auf OpenSearch Serverless und OpenSearch Service. Es hat alle Funktionen des opensearch-ruby-Clients, da es von diesem Gem abhängig ist.

Geben Sie bei der Instanziierung des Sigv4-Signers aoss als Servicenamen an:

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)

Signieren HTTP von Anfragen mit anderen Clients

Die folgenden Anforderungen gelten für das Signieren von Anfragen an OpenSearch serverlose Sammlungen, wenn Sie HTTP Anfragen mit anderen Clients erstellen.

• Sie müssen den Service-Namen als aoss angeben.

• Der x-amz-content-sha256 Header ist für alle erforderlich AWS Anfragen zur Signaturversion 4. Es stellt einen Hash der Anforderungsnutzlast bereit. Wenn es eine Nutzlast für eine Anfrage gibt, setzen Sie den Wert auf den kryptografischen Hash des Secure Hash Algorithm (SHASHA256). Wenn keine Anforderungsnutzlast vorhanden ist, setzen Sie den Wert auf e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855, was der Hash einer leeren Zeichenfolge ist.

Themen

• Indizierung mit c URL
• Indizierung mit Postman

Indizierung mit c URL

Die folgende Beispielanforderung verwendet die Client URL Request Library (cURL), um ein einzelnes Dokument an einen Index zu senden, der movies-index innerhalb einer Sammlung benannt ist:

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"}'

Indizierung mit Postman

Die folgende Abbildung zeigt, wie Sie mit Postman Anfragen an eine Sammlung senden. Anweisungen zur Authentifizierung finden Sie unter Authentifizieren mit AWS Arbeitsablauf zur Signaturauthentifizierung in Postman.