> ## 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，以根据用户行为触发自动化 Journey 和个性化消息传送活动。

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。这使您能够根据存储在搜索和分析引擎中的用户行为数据触发自动化 Journey 和个性化消息传送活动。

***

## 要求

* 访问自定义事件（目前处于测试阶段）
* [升级账户计划](https://onesignal.com/pricing)（免费应用不可用）。

### 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 地址访问
    * 记下您的集群 **端点 URL** 和 **凭据**
  </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 中，前往 **数据 > 集成**，然后点击 **添加集成**。

    选择 **Elasticsearch** 并提供：

    * **集群 URL**：您的 Elasticsearch 端点（例如 `https://your-cluster.es.amazonaws.com`）
    * **身份验证方法**：API 密钥、基本身份验证或证书
    * **用户名/密码** 或 **API 密钥**：身份验证凭据
    * **Cloud ID**（如果使用 Elasticsearch Cloud）：您的部署 Cloud ID
  </Step>

  <Step title="配置事件数据源">
    指定包含事件数据的 Elasticsearch 索引：

    * **索引模式**：包含事件的索引或索引模式（例如 `events-*`）
    * **事件查询**：可选的 Elasticsearch Query DSL 来过滤事件文档
    * **时间字段**：用于基于时间过滤的时间戳字段（例如 `@timestamp`）

    您的事件文档应包含以下字段：

    * 事件名称/类型（字符串）
    * 用户标识符（字符串）
    * 事件时间戳（日期）
    * 其他事件属性（对象）
  </Step>

  <Step title="测试连接">
    点击 **测试连接** 以验证 OneSignal 可以访问您的 Elasticsearch 集群并读取事件数据。
  </Step>
</Steps>

***

### 事件数据映射

将您的 {PLATFORM_0} {DATA_TYPE_0} 映射到 OneSignal 的自定义事件格式：

| OneSignal 字段  | {COLUMN_HEADER_0} | 描述                         | 必需 |
| ------------- | ----------------- | -------------------------- | -- |
| `name`        | `event_name`      | 事件标识符                      | 是  |
| `external_id` | `user_id`         | 用户标识符                      | 是  |
| `timestamp`   | `event_timestamp` | 事件发生时间                     | 否  |
| `properties`  | `event_data`      | {PROPERTIES_DESCRIPTION_0} | 否  |

***

## 高级配置

### 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` 过滤仅检索必要字段
* **滚动 API**：对于大结果集，OneSignal 使用滚动分页
* **日期数学**：使用 Elasticsearch 日期数学进行高效的基于时间的过滤

<Warning>
  确保您的 Elasticsearch 集群有足够的资源来处理 OneSignal 的查询，而不会影响使用集群的其他应用程序。
</Warning>

***

## 常见问题

### OneSignal 多久从 Elasticsearch 同步一次事件？

OneSignal 根据您配置的计划同步事件数据，最小间隔为 15 分钟。

### 我可以从多个 Elasticsearch 索引同步事件吗？

是的，您可以使用索引模式（例如 `events-*`）查询多个索引，或为不同的索引组创建多个集成。

### 如果我的 Elasticsearch 集群暂时不可用会怎么样？

OneSignal 将使用指数退避重试连接。一旦您的集群再次可访问，事件同步将自动恢复。