# OpenSearch Service 연결
<a name="aws-glue-programming-etl-connect-opensearch-home"></a>

AWS Glue for Spark를 사용하여 AWS Glue 4.0 이상 버전에서 OpenSearch Service의 테이블에서 읽고 쓸 수 있습니다. OpenSearch 쿼리를 사용하여 OpenSearch Service에서 읽을 내용을 정의할 수 있습니다. AWS Glue 연결을 통해 AWS Secrets Manager에 저장된 HTTP 기본 인증 보안 인증 정보를 사용하여 OpenSearch Service에 연결합니다. 이 기능은 OpenSearch Service 서버리스와 호환되지 않습니다.

Amazon OpenSearch Service에 대한 자세한 정보는 [Amazon OpenSearch Service 설명서](https://docs.aws.amazon.com/opensearch-service/)를 참조하십시오.

## OpenSearch Service 연결 구성
<a name="aws-glue-programming-etl-connect-opensearch-configure"></a>

AWS Glue에서 OpenSearch Service에 연결하려면 OpenSearch Service 보안 인증 정보를 생성하여 암호에 저장한 다음 해당 AWS Secrets Manager 암호를 OpenSearch Service AWS Glue 연결에 연결해야 합니다.

**사전 조건 ** 
+ Amazon OpenSearch Service 설명서의 지침에 따라 읽으려는 도메인 엔드포인트, *aosEndpoint* 및 포트, *aosPort*를 식별하거나 리소스를 생성하십시오. 도메인 생성에 관해 자세한 내용을 알아보려면 Amazon OpenSearch Service 설명서의 [Amazon OpenSearch Service 도메인 생성 및 관리](https://docs.aws.amazon.com//opensearch-service/latest/developerguide/createupdatedomains.html)를 참조하십시오.

  Amazon OpenSearch Service 도메인 엔드포인트는 기본 형식이 https://search-*domainName*-*unstructuredIdContent*.*region*.es.amazonaws.com입니다. 도메인 엔드포인트에 관해 자세한 내용을 알아보려면 Amazon OpenSearch Service 설명서의 [Amazon OpenSearch Service 도메인 생성 및 관리](https://docs.aws.amazon.com//opensearch-service/latest/developerguide/createupdatedomains.html)를 참조하십시오.

  도메인의 HTTP 기본 보안 인증 정보, *aosUser*와 *aosPassword*를 확인하거나 생성하십시오.

**OpenSearch Service에 대한 연결을 구성하는 방법:**

1. AWS Secrets Manager에서 OpenSearch 보안 인증을 사용하여 보안 암호를 생성합니다. Secrets Manager에서 보안 암호를 생성하려면 AWS Secrets Manager 설명서의 [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html)에서 제공하는 자습서를 따릅니다. 보안 암호를 생성한 후에는 다음 단계를 위해 보안 암호 이름, *secretName*을 유지합니다.
   + **키/값 페어**를 선택하면 값 *aosUser*이 포함된 키 `USERNAME`에 대한 페어를 생성합니다.
   + **키/값 페어**를 선택하면 값 *aosPassword*이 포함된 키 `PASSWORD`에 대한 페어를 생성합니다.

1. AWS Glue 콘솔에서 [AWS Glue 연결 추가](console-connections.md)의 단계에 따라 연결을 생성합니다. 연결을 생성한 후에는 AWS Glue에서 이용하기 위해 연결 이름 *connectionName*을 유지합니다.
   + **연결 유형**을 선택할 때는 OpenSearch Service를 선택합니다.
   + 도메인 엔드포인트를 선택할 때는 *aosEndpoint*를 제공하십시오.
   + 포트를 선택할 때는 *aosPort*를 제공하십시오.
   + **AWS 보안 암호**를 선택할 때 *secretName*을 입력합니다.

AWS Glue OpenSearch Service 연결을 생성한 후에는 AWS Glue 작업을 실행하기 전에 다음 단계를 수행해야 합니다.
+ AWS Glue 작업과 연결된 IAM 역할에 *secretName*을 읽을 수 있는 권한을 부여합니다.
+ AWS Glue 작업 구성에서 **추가 네트워크 연결**로 *connectionName*을 제공합니다.

## OpenSearch Service 인덱스에서 읽기
<a name="aws-glue-programming-etl-connect-opensearch-read"></a>

**사전 조건 ** 
+ 읽으려는 OpenSearch Service 인덱스, *aosIndex*.
+ 인증 및 네트워크 위치 정보를 제공하도록 구성된 AWS Glue OpenSearch Service 연결입니다. 이 정보를 얻으려면 앞 절차인 *OpenSearch Service에 대한 연결을 구성하는 방법*의 단계를 완료하십시오. AWS Glue 연결의 이름인 *connectionName*이 필요합니다.

이 예제는 Amazon OpenSearch Service에서 인덱스을 읽습니다. `pushdown` 파라미터를 제공해야 합니다.

예: 

```
opensearch_read = glueContext.create_dynamic_frame.from_options(
    connection_type="opensearch",
    connection_options={
        "connectionName": "connectionName",
        "opensearch.resource": "aosIndex",
        "pushdown": "true",
    }
)
```

DynamicFrame에 반환되는 결과를 필터링하는 쿼리 문자열을 제공할 수도 있습니다. `opensearch.query`를 구성해야 합니다.

`opensearch.query`는 URL 쿼리 매개 변수 문자열 *queryString* 또는 쿼리 DSL JSON 객체 *queryObject*를 사용할 수 있습니다. 쿼리 DSL에 대한 자세한 내용은 OpenSearch 설명서의 [쿼리 DSL](https://opensearch.org/docs/latest/query-dsl/index/)을 참조하십시오. URL 쿼리 매개 변수 문자열을 제공하려면 정규화된 URL에서처럼 쿼리 앞에 `?q=`를 추가하십시오. 쿼리 DSL 객체를 제공하려면 JSON 객체를 제공하기 전에 문자열을 이스케이프 처리해야 합니다.

예: 

```
            queryObject = "{ "query": { "multi_match": { "query": "Sample", "fields": [ "sample" ] } } }"
            queryString = "?q=queryString"
            
            opensearch_read_query = glueContext.create_dynamic_frame.from_options(
    connection_type="opensearch",
    connection_options={
        "connectionName": "connectionName",
        "opensearch.resource": "aosIndex",
        "opensearch.query": queryString,
        "pushdown": "true",
    }
)
```

특정 구문을 벗어나 쿼리를 작성하는 방법에 대한 자세한 내용은 OpenSearch 설명서의 [쿼리 문자열 구문](https://opensearch.org/docs/latest/query-dsl/full-text/query-string/#query-string-syntax)을 참조하십시오.

배열 형식 데이터가 포함된 OpenSearch 컬렉션에서 읽을 때는 `opensearch.read.field.as.array.include` 파라미터를 사용하여 메서드 직접 호출에서 어떤 필드가 배열 형식인지 지정해야 합니다.

예를 들어 다음 문서를 읽을 때 `genre` 및 `actor` 배열 필드가 나타납니다.

```
{
    "_index": "movies",
    "_id": "2",
    "_version": 1,
    "_seq_no": 0,
    "_primary_term": 1,
    "found": true,
    "_source": {
        "director": "Frankenheimer, John",
        "genre": [
            "Drama",
            "Mystery",
            "Thriller",
            "Crime"
        ],
        "year": 1962,
        "actor": [
            "Lansbury, Angela",
            "Sinatra, Frank",
            "Leigh, Janet",
            "Harvey, Laurence",
            "Silva, Henry",
            "Frees, Paul",
            "Gregory, James",
            "Bissell, Whit",
            "McGiver, John",
            "Parrish, Leslie",
            "Edwards, James",
            "Flowers, Bess",
            "Dhiegh, Khigh",
            "Payne, Julie",
            "Kleeb, Helen",
            "Gray, Joe",
            "Nalder, Reggie",
            "Stevens, Bert",
            "Masters, Michael",
            "Lowell, Tom"
        ],
        "title": "The Manchurian Candidate"
    }
}
```

이 경우 메서드 직접 호출에 해당 필드 이름을 포함하면 됩니다. 예:

```
"opensearch.read.field.as.array.include": "genre,actor"
```

배열 필드가 문서 구조 안에 중첩되어 있는 경우 점 표기법(`"genre,actor,foo.bar.baz"`)을 사용하여 참조하세요. 이는 포함된 문서(`bar`)를 포함하는 포함된 문서(`foo`)를 통해 소스 문서에 포함된 배열(`baz`)을 지정합니다.

## OpenSearch Service 테이블에 쓰기
<a name="aws-glue-programming-etl-connect-opensearch-write"></a>

이 예제에서는 기존 DynamicFrame, *dynamicFrame*의 정보를 OpenSearch Service에 기록합니다. 인덱스에 이미 정보가 있는 경우 AWS Glue는 DynamicFrame의 데이터를 추가합니다. `pushdown` 파라미터를 제공해야 합니다.

**사전 조건 ** 
+ 쓰려는 OpenSearch Service 테이블. 테이블에 대한 식별 정보가 필요합니다. 이 *tableName*이라고 부르겠습니다.
+ 인증 및 네트워크 위치 정보를 제공하도록 구성된 AWS Glue OpenSearch Service 연결입니다. 이 정보를 얻으려면 앞 절차인 *OpenSearch Service에 대한 연결을 구성하는 방법*의 단계를 완료하십시오. AWS Glue 연결의 이름인 *connectionName*이 필요합니다.

예: 

```
glueContext.write_dynamic_frame.from_options(
    frame=dynamicFrame,
    connection_type="opensearch",
    connection_options={
      "connectionName": "connectionName",
      "opensearch.resource": "aosIndex",
    },
)
```

## OpenSearch Service 연결 옵션 참조
<a name="aws-glue-programming-etl-connect-opensearch-reference"></a>
+ `connectionName` - 필수입니다. 읽기 및 쓰기에 사용됩니다. 연결 방법에 인증 및 네트워크 위치 정보를 제공하도록 구성된 AWS Glue OpenSearch Service 연결의 이름입니다.
+ `opensearch.resource` - 필수입니다. 읽기 및 쓰기에 사용됩니다. 유효한 값: OpenSearch 인덱스 이름. 연결 방법이 상호 작용하는 인덱스의 이름입니다.
+ `opensearch.query` — 읽기에 사용됩니다. 유효한 값: 문자열이 JSON으로 이스케이프되거나 이 문자열이 `?`로 시작되는 경우 URL의 검색 부분. 읽을 때 검색해야 하는 항목을 필터링하는 OpenSearch 쿼리입니다. 이 매개변수 사용에 대한 자세한 내용은 이전 섹션 [OpenSearch Service 인덱스에서 읽기](#aws-glue-programming-etl-connect-opensearch-read)를 참조하십시오.
+ `pushdown` - 다음과 같은 경우 필수입니다. 읽기에 사용됩니다. 유효 값: 부울. 데이터베이스가 관련 문서만 반환하도록 Spark가 읽기 쿼리를 OpenSearch에 전달하도록 지시합니다.
+ `opensearch.read.field.as.array.include` - 배열 유형 데이터를 읽을 때 필요합니다. 읽기에 사용됩니다. 유효 값: 쉼표로 구분된 필드 이름 목록. OpenSearch 문서에서 배열로 읽을 필드를 지정합니다. 이 매개변수 사용에 대한 자세한 내용은 이전 섹션 [OpenSearch Service 인덱스에서 읽기](#aws-glue-programming-etl-connect-opensearch-read)를 참조하십시오.