> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Elasticsearch

> Elasticsearch에서 OneSignal로 사용자 지정 이벤트를 동기화하여 사용자 행동을 기반으로 자동화된 Journeys 및 개인화된 메시징 캠페인을 트리거하세요.

export const PLATFORM_0 = "Elasticsearch"

export const DATA_TYPE_0 = "이벤트 문서 필드"

export const COLUMN_HEADER_0 = "Elasticsearch 필드"

export const PROPERTIES_DESCRIPTION_0 = "중첩 객체 또는 평면화된 필드"

## 개요

OneSignal + Elasticsearch 통합은 Elasticsearch 클러스터에서 OneSignal로 사용자 지정 이벤트를 자동으로 동기화할 수 있게 합니다. 이를 통해 검색 및 분석 엔진에 저장된 사용자 행동 데이터를 기반으로 자동화된 Journeys 및 개인화된 메시징 캠페인을 트리거할 수 있습니다.

***

## 요구 사항

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### Elasticsearch

* **Elasticsearch 클러스터**(버전 7.0 이상 권장)
* **인증 자격 증명**(API 키, 사용자 이름/비밀번호 또는 인증서)
* 적절한 문서 구조를 가진 행동 데이터를 포함하는 **이벤트 인덱스**
* OneSignal에서 Elasticsearch 클러스터로의 **네트워크 액세스**

***

## 설정

<Steps>
  <Step title="Elasticsearch 액세스 구성">
    OneSignal이 Elasticsearch 클러스터에 연결할 수 있는지 확인하세요:

    **Elasticsearch Cloud의 경우:**

    * Elasticsearch Cloud 콘솔에서 **Security**로 이동
    * 이벤트 인덱스에 대한 읽기 권한이 있는 API 키 생성
    * **Cloud ID** 및 **API Key** 기록

    **자체 호스팅 Elasticsearch의 경우:**

    * 인증 구성(기본 인증 또는 API 키)
    * OneSignal의 IP 주소에서 클러스터에 액세스할 수 있는지 확인
    * 클러스터 **endpoint URL** 및 **credentials** 기록
  </Step>

  <Step title="전용 사용자 만들기(권장)">
    이벤트 인덱스에 대한 읽기 전용 액세스 권한이 있는 OneSignal 전용 사용자를 만드세요:

    ```json theme={null}
    PUT _security/user/onesignal_reader
    {
      "password": "strong_password",
      "roles": ["onesignal_events_reader"]
    }

    PUT _security/role/onesignal_events_reader
    {
      "indices": [
        {
          "names": ["events-*", "user_events"],
          "privileges": ["read", "view_index_metadata"]
        }
      ]
    }
    ```
  </Step>

  <Step title="OneSignal에서 통합 추가">
    OneSignal에서 **Data > Integrations**으로 이동하여 **Add Integration**을 클릭합니다.

    **Elasticsearch**를 선택하고 다음을 제공하세요:

    * **Cluster URL**: Elasticsearch 엔드포인트(예: `https://your-cluster.es.amazonaws.com`)
    * **Authentication Method**: API Key, Basic Auth 또는 Certificate
    * **Username/Password** 또는 **API Key**: 인증 자격 증명
    * **Cloud ID**(Elasticsearch Cloud를 사용하는 경우): 배포 Cloud ID
  </Step>

  <Step title="이벤트 데이터 소스 구성">
    이벤트 데이터를 포함하는 Elasticsearch 인덱스를 지정하세요:

    * **Index Pattern**: 이벤트를 포함하는 인덱스 또는 인덱스 패턴(예: `events-*`)
    * **Event Query**: 이벤트 문서를 필터링하기 위한 선택적 Elasticsearch Query DSL
    * **Time Field**: 시간 기반 필터링을 위한 타임스탬프 필드(예: `@timestamp`)

    이벤트 문서에는 다음 필드가 포함되어야 합니다:

    * 이벤트 이름/유형(String)
    * 사용자 식별자(String)
    * 이벤트 타임스탬프(Date)
    * 추가 이벤트 속성(Object)
  </Step>

  <Step title="연결 테스트">
    **Test Connection**을 클릭하여 OneSignal이 Elasticsearch 클러스터에 액세스하고 이벤트 데이터를 읽을 수 있는지 확인하세요.
  </Step>
</Steps>

***

### 이벤트 데이터 매핑

{PLATFORM_0} {DATA_TYPE_0}를 OneSignal의 사용자 지정 이벤트 형식에 매핑합니다:

| OneSignal 필드  | {COLUMN_HEADER_0} | 설명                         | 필수  |
| ------------- | ----------------- | -------------------------- | --- |
| `name`        | `event_name`      | 이벤트 식별자                    | Yes |
| `external_id` | `user_id`         | 사용자 식별자                    | Yes |
| `timestamp`   | `event_timestamp` | 이벤트가 발생한 시간                | No  |
| `properties`  | `event_data`      | {PROPERTIES_DESCRIPTION_0} | No  |

***

## 고급 구성

### Query DSL 필터링

Elasticsearch Query DSL을 사용하여 OneSignal에 동기화하기 전에 이벤트 데이터를 필터링하고 변환하세요:

```json theme={null}
{
  "query": {
    "bool": {
      "must": [
        {
          "range": {
            "@timestamp": {
              "gte": "now-7d"
            }
          }
        },
        {
          "terms": {
            "event_name": ["purchase", "signup", "upgrade"]
          }
        }
      ],
      "must_not": [
        {
          "term": {
            "test_user": true
          }
        }
      ]
    }
  },
  "_source": [
    "event_name",
    "user_id",
    "@timestamp",
    "properties.*"
  ]
}
```

### 인덱스 패턴 구성

여러 인덱스를 효율적으로 쿼리하세요:

* **시간 기반 인덱스**: 시간 분할 데이터에 `events-2024-*`와 같은 패턴 사용
* **라우팅**: 사용자 기반 쿼리에 대한 일관된 라우팅 보장
* **별칭**: 간소화된 관리를 위해 인덱스 별칭 사용

### 성능 최적화

대량 이벤트 볼륨에 대한 쿼리를 최적화하세요:

* **필드 필터링**: `_source` 필터링을 사용하여 필요한 필드만 검색
* **Scroll API**: 대량 결과 세트의 경우 OneSignal은 스크롤 페이지네이션 사용
* **날짜 수학**: 효율적인 시간 기반 필터링을 위해 Elasticsearch 날짜 수학 사용

<Warning>
  Elasticsearch 클러스터에 클러스터를 사용하는 다른 애플리케이션에 영향을 주지 않고 OneSignal의 쿼리를 처리할 수 있는 충분한 리소스가 있는지 확인하세요.
</Warning>

***

## FAQ

### OneSignal은 Elasticsearch에서 이벤트를 얼마나 자주 동기화하나요?

OneSignal은 구성된 일정에 따라 이벤트 데이터를 동기화하며 최소 간격은 15분입니다.

### 여러 Elasticsearch 인덱스에서 이벤트를 동기화할 수 있나요?

예, 인덱스 패턴(예: `events-*`)을 사용하여 여러 인덱스를 쿼리하거나 다른 인덱스 그룹에 대해 여러 통합을 만들 수 있습니다.

### Elasticsearch 클러스터를 일시적으로 사용할 수 없는 경우 어떻게 되나요?

OneSignal은 지수 백오프로 연결을 재시도합니다. 클러스터에 다시 액세스할 수 있게 되면 이벤트 동기화가 자동으로 재개됩니다.