기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Amazon OpenSearch Serverless 컬렉션으로 데이터 수집
이 섹션에서는 Amazon OpenSearch Serverless 컬렉션으로의 데이터 수집을 위해 지원되는 수집 파이프라인에 대한 세부 정보를 제공합니다. 또한 OpenSearch API 작업과 상호 작용하는 데 사용할 수 있는 일부 클라이언트도 다룹니다. OpenSearch Serverless와 통합하려면 클라이언트가 OpenSearch 2.x 버전과 호환되어야 합니다.
**Topics**
+ [최소 필수 권한](#serverless-ingestion-permissions)
+ [OpenSearch Ingestion](#serverless-osis-ingestion)
+ [Fluent Bit](#serverless-fluentbit)
+ [Amazon Data Firehose](#serverless-kdf)
+ [Go](#serverless-go)
+ [Java](#serverless-java)
+ [JavaScript](#serverless-javascript)
+ [Logstash](#serverless-logstash)
+ [Python](#serverless-python)
+ [Ruby](#serverless-ruby)
+ [다른 클라이언트로 HTTP 요청 서명](#serverless-signing)
## 최소 필수 권한
데이터를 OpenSearch Serverless 컬렉션으로 수집하려면 데이터를 쓰는 보안 주체가 [데이터 액세스 정책](serverless-data-access.md)에 할당된 다음과 같은 최소 권한이 있어야 합니다.
```
[
{
"Rules":[
{
"ResourceType":"index",
"Resource":[
"index/{{target-collection}}/{{logs}}"
],
"Permission":[
"aoss:CreateIndex",
"aoss:WriteDocument",
"aoss:UpdateIndex"
]
}
],
"Principal":[
"arn:aws:iam::{{123456789012}}:user/{{my-user}}"
]
}
]
```
추가 인덱스에 쓰려는 경우 권한이 더 광범위할 수 있습니다. 예를 들어 단일 대상 인덱스를 지정하는 대신 모든 인덱스(index/{{target-collection}}/\*) 또는 인덱스 하위 집합(index/{{target-collection}}/{{logs\*}})에 대한 권한을 허용할 수 있습니다.
사용 가능한 모든 OpenSearch API 작업 및 관련 권한에 대한 참조는 [Amazon OpenSearch Serverless에서 지원되는 작업 및 플러그인](serverless-genref.md)을(를) 참조하세요.
## OpenSearch Ingestion
타사 클라이언트를 사용하여 OpenSearch Ingestion 컬렉션으로 직접 데이터를 보내는 대신 Amazon OpenSearch Ingestion을 사용할 수 있습니다. 데이터 생산자를 구성하면 데이터를 OpenSearch Ingestion으로 전송하고, 이를 통해 사용자가 지정한 컬렉션에 데이터를 자동으로 전송합니다. 전송 전에 데이터를 변환하도록 OpenSearch Ingestion을 구성할 수도 있습니다. 자세한 내용은 [Amazon OpenSearch Ingestion 개요](ingestion.md) 단원을 참조하십시오.
OpenSearch Ingestion 파이프라인에는 싱크로 구성된 OpenSearch Serverless 컬렉션에 쓸 수 있는 권한이 필요합니다. 이러한 권한에는 컬렉션을 설명하고 컬렉션에 HTTP 요청을 보내는 기능이 포함됩니다. OpenSearch Ingestion을 사용하여 컬렉션에 데이터를 추가하는 방법에 대한 지침은 [컬렉션에 대한 액세스 권한을 Amazon OpenSearch Ingestion 파이프라인에 부여](pipeline-collection-access.md) 섹션을 참조하세요.
OpenSearch Ingestion을 시작하려면 [튜토리얼: Amazon OpenSearch Ingestion을 사용하여 컬렉션에 데이터 수집](osis-serverless-get-started.md)(을)를 참조하세요.
## Fluent Bit
[AWS for Fluent Bit 이미지](https://github.com/aws/aws-for-fluent-bit#public-images)와 [OpenSearch 출력 플러그인](https://docs.fluentbit.io/manual/pipeline/outputs/opensearch)을 사용하여 데이터를 OpenSearch Serverless 컬렉션으로 수집할 수 있습니다.
**참고**
OpenSearch Serverless와 통합하려면 Fluent Bit AWS 용 이미지 버전 2.30.0 이상이 있어야 합니다.
**구성의 예제**:
구성 파일의 이 샘플 출력 섹션에서는 OpenSearch Serverless 컬렉션을 대상으로 사용하는 방법을 보여줍니다. 중요한 추가 사항은 `AWS_Service_Name` 파라미터인 `aoss`입니다. `Host`는 컬렉션 엔드포인트입니다.
```
[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 {{}}
AWS_Service_Name aoss
tls On
Suppress_Type_Name On
```
## Amazon Data Firehose
Firehose는 전송 대상으로 OpenSearch Serverless를 지원합니다. OpenSearch Serverless로 데이터를 전송하는 지침은 **Amazon Data Firehose 개발자 안내서에서 [Kinesis Data Firehose 전송 스트림 생성](https://docs.aws.amazon.com/firehose/latest/dev/basic-create.html) 및 [대상에 대한 OpenSearch Serverless 선택](https://docs.aws.amazon.com/firehose/latest/dev/create-destination.html#create-destination-opensearch-serverless)을 참조하세요.
전송을 위해 Firehose에 제공하는 IAM 역할은 대상 컬렉션에 대한 `aoss:WriteDocument` 최소 권한이 있는 데이터 액세스 정책 내에서 지정되어야 하며 데이터를 전송할 기존 인덱스가 있어야 합니다. 자세한 내용은 [최소 필수 권한](#serverless-ingestion-permissions) 단원을 참조하십시오.
OpenSearch Serverless로 데이터를 보내기 전에 데이터에 대한 변환을 수행해야 할 수 있습니다. Lambda 함수로 이 태스크를 수행하는 방법에 대한 자세한 내용은 동일한 안내서의 [Amazon Kinesis Data Firehose Data 데이터 변환](https://docs.aws.amazon.com/firehose/latest/dev/data-transformation.html)을 참조하세요.
## Go
다음 샘플 코드는 Go용 [opensearch-go](https://github.com/opensearch-project/opensearch-go) 클라이언트를 사용하여 지정된 OpenSearch Serverless 컬렉션에 대한 보안 연결을 설정하고 단일 인덱스를 생성합니다. `region` 및 `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(""),
config.WithCredentialsProvider(
getCredentialProvider("", "", ""),
),
)
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
다음 샘플 코드는 Java용 [opensearch-java](https://search.maven.org/artifact/org.opensearch.client/opensearch-java) 클라이언트를 사용하여 지정된 OpenSearch Serverless 컬렉션에 대한 보안 연결을 설정하고 단일 인덱스를 생성합니다. `region` 및 `host`의 값을 입력해야 합니다.
OpenSearch Service **도메인과 비교했을 때 중요한 차이점은 서비스 이름(`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();
```
다음 샘플 코드는 다시 보안 연결을 설정한 다음, 인덱스를 검색합니다.
```
import org.opensearch.client.opensearch.OpenSearchClient;
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
다음 샘플 코드는 JavaScript용 [opensearch-js](https://www.npmjs.com/package/@opensearch-project/opensearch) 클라이언트를 사용하여 지정된 OpenSearch Serverless 컬렉션에 대한 보안 연결을 설정하고, 단일 인덱스를 생성하고, 문서를 추가하고, 인덱스를 삭제합니다. `node` 및 `region`의 값을 입력해야 합니다.
OpenSearch Service **도메인과 비교했을 때 중요한 차이점은 서비스 이름(`aoss` 대신 `es`)입니다.
------
#### [ Version 3 ]
이 예시는 Node.js의 JavaScript용 SDK [버전 3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/)을 사용합니다.
```
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 ]
이 예시는 Node.js의 JavaScript용 SDK [버전 2](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/)를 사용합니다.
```
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
[Logstash OpenSearch 플러그인](https://github.com/opensearch-project/logstash-output-opensearch)을 사용하여 OpenSearch Serverless 컬렉션에 로그를 게시할 수 있습니다.
**Logstash를 사용하여 OpenSearch Serverless로 데이터 보내기**
1. Docker 또는 Linux를 사용하여 [logstash-output-opensearch](https://github.com/opensearch-project/logstash-output-opensearch) 플러그인 *2.0.0 또는 이후* 버전을 설치합니다.
------
#### [ Docker ]
Docker는 OpenSearch 출력 플러그인 [opensearchproject/logstash-oss-with-opensearch-output-plugin](https://hub.docker.com/r/opensearchproject/logstash-oss-with-opensearch-output-plugin/tags?page=1&ordering=last_updated&name=8.4.0)이 사전 설치된 Logstash OSS 소프트웨어를 호스팅합니다. 다른 이미지와 마찬가지로 이미지를 가져올 수 있습니다.
```
docker pull opensearchproject/logstash-oss-with-opensearch-output-plugin:latest
```
------
#### [ Linux ]
아직 설치하지 않았다면 먼저 [최신 버전의 Logstash를 설치](https://www.elastic.co/guide/en/logstash/current/installing-logstash.html)합니다. 그런 다음 출력 플러그인 버전 2.0.0을 설치합니다.
```
cd logstash-8.5.0/
bin/logstash-plugin install --version 2.0.0 logstash-output-opensearch{{ }}
```
플러그인이 이미 설치되어 있는 경우 최신 버전으로 업데이트합니다.
```
bin/logstash-plugin update logstash-output-opensearch{{ }}
```
플러그인 버전 2.0.0부터 AWS SDK는 버전 3을 사용합니다. 8.4.0 이전 버전의 Logstash를 사용하는 경우 사전 설치된 AWS 플러그인을 제거하고 `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
```
------
1. OpenSearch 출력 플러그인이 OpenSearch Serverless와 함께 작동하려면 logstash.conf의 `opensearch` 출력 섹션을 다음과 같이 수정해야 합니다.
+ `aoss`를 `auth_type`의 `service_name`으로 지정합니다.
+ `hosts`에 대한 컬렉션 엔드포인트를 지정합니다.
+ 파라미터 `default_server_major_version` 및 `legacy_template`을 추가합니다. 이러한 파라미터는 플러그인이 OpenSearch Serverless와 함께 작동하는 데 필요합니다.
```
output {
opensearch {
hosts => "{{collection-endpoint}}:443"
auth_type => {
...
service_name => 'aoss'
}
default_server_major_version => 2
legacy_template => false
}
}
```
이 예시 구성 파일은 S3 버킷의 파일에서 입력값을 가져와서 OpenSearch 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
}
}
```
1. 그런 다음 새 구성으로 Logstash를 실행하여 플러그인을 테스트합니다.
```
bin/logstash -f config/{{test-plugin}}.conf
```
## Python
다음 샘플 코드는 Python용 [opensearch-py](https://pypi.org/project/opensearch-py/) 클라이언트를 사용하여 지정된 OpenSearch Serverless 컬렉션에 대한 보안 연결을 설정하고, 단일 인덱스를 생성하고, 해당 인덱스를 검색합니다. `region` 및 `host`의 값을 입력해야 합니다.
OpenSearch Service **도메인과 비교했을 때 중요한 차이점은 서비스 이름(`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
`opensearch-aws-sigv4` gem은 즉시 OpenSearch Service와 함께 OpenSearch Serverless에 대한 액세스 권한을 제공합니다. 이 gem의 종속 항목이므로 [opensearch-ruby](https://rubygems.org/gems/opensearch-ruby) 클라이언트의 모든 기능을 가지고 있습니다.
Sigv4 서명자를 인스턴스화할 때 `aoss`를 서비스 이름으로 지정합니다.
```
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)
```
## 다른 클라이언트로 HTTP 요청 서명
다른 클라이언트로 HTTP 요청을 구성하는 경우 OpenSearch Serverless 컬렉션에 대한 [요청에 서명](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)할 때 다음 요구 사항이 적용됩니다.
+ 서비스 이름을 `aoss`로 지정합니다.
+ `x-amz-content-sha256` 헤더는 모든 AWS 서명 버전 4 요청에 필요합니다. 요청 페이로드의 해시를 제공합니다. 요청 페이로드가 있는 경우 값을 보안 해시 알고리즘(SHA) 암호화 해시(SHA256)로 설정합니다. 요청 페이로드가 없는 경우 값을 빈 문자열의 해시인 `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`(으)로 설정합니다.
**Topics**
+ [cURL을 사용한 인덱싱](#serverless-signing-curl)
+ [Postman을 사용한 인덱싱](#serverless-signing-postman)
### cURL을 사용한 인덱싱
다음 예제 요청은 클라이언트 URL 요청 라이브러리(cURL)를 사용하여 컬렉션 내에서 `movies-index` 인덱스로 단일 문서를 전송합니다.
```
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"}'
```
### Postman을 사용한 인덱싱
다음 이미지는 Postman을 사용하여 컬렉션에 요청을 전송하는 방법을 보여줍니다. 인증 지침은 [Postman의 Authenticate with AWS Signature authentication workflow](https://learning.postman.com/docs/sending-requests/authorization/aws-signature/)를 참조하세요.
