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

> Sincronize eventos personalizados do Elasticsearch para o OneSignal para acionar Jornadas automatizadas e campanhas de mensagens personalizadas baseadas no comportamento do usuário.

export const DATA_TYPE_0 = "campos de documento de evento"

export const PLATFORM_0 = "Elasticsearch"

export const COLUMN_HEADER_0 = "Campo Elasticsearch"

export const PROPERTIES_DESCRIPTION_0 = "Objeto aninhado ou campos achatados"

## Visão geral

A integração OneSignal + Elasticsearch permite a sincronização automática de eventos personalizados do seu cluster Elasticsearch para o OneSignal. Isso permite que você acione Jornadas automatizadas e campanhas de mensagens personalizadas baseadas em dados comportamentais de usuários armazenados em seu mecanismo de busca e analytics.

***

## Requisitos

* Acesso a [Event Streams](/docs/pt-BR/event-streams) para eventos de mensagem de saída (Limitações de plano e excedentes se aplicam)
* Acesso a [Custom Events](/docs/pt-BR/custom-events) para sincronização de eventos de entrada (Limitações de plano e excedentes se aplicam)
* [Plano de Conta Atualizado](https://onesignal.com/pricing) (não disponível em apps gratuitos)

### Elasticsearch

* **Cluster Elasticsearch** (versão 7.0 ou superior recomendada)
* **Credenciais de autenticação** (chave API, usuário/senha ou certificado)
* **Índices de eventos** contendo dados comportamentais com estrutura de documento adequada
* **Acesso de rede** do OneSignal ao seu cluster Elasticsearch

***

## Configuração

<Steps>
  <Step title="Configurar acesso ao Elasticsearch">
    Certifique-se de que o OneSignal pode se conectar ao seu cluster Elasticsearch:

    **Para Elasticsearch Cloud:**

    * Navegue até **Security** no seu console Elasticsearch Cloud
    * Crie uma chave API com permissões de leitura para índices de eventos
    * Anote seu **Cloud ID** e **API Key**

    **Para Elasticsearch auto-hospedado:**

    * Configure autenticação (autenticação básica ou chave API)
    * Certifique-se de que seu cluster é acessível dos endereços IP do OneSignal
    * Anote a **URL do endpoint** do seu cluster e **credenciais**
  </Step>

  <Step title="Criar usuário dedicado (recomendado)">
    Crie um usuário dedicado para o OneSignal com acesso somente leitura aos índices de eventos:

    ```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="Adicionar integração no OneSignal">
    No OneSignal, vá para **Data > Integrations** e clique em **Add Integration**.

    Selecione **Elasticsearch** e forneça:

    * **Cluster URL**: Seu endpoint Elasticsearch (por exemplo, `https://your-cluster.es.amazonaws.com`)
    * **Authentication Method**: API Key, Basic Auth ou Certificate
    * **Username/Password** ou **API Key**: Credenciais de autenticação
    * **Cloud ID** (se estiver usando Elasticsearch Cloud): Seu Cloud ID de implantação
  </Step>

  <Step title="Configurar fonte de dados de eventos">
    Especifique o índice Elasticsearch contendo seus dados de eventos:

    * **Index Pattern**: Índice ou padrão de índice contendo eventos (por exemplo, `events-*`)
    * **Event Query**: Elasticsearch Query DSL opcional para filtrar documentos de eventos
    * **Time Field**: Campo de timestamp para filtragem baseada em tempo (por exemplo, `@timestamp`)

    Seus documentos de eventos devem conter campos para:

    * Nome/tipo do evento (String)
    * Identificador do usuário (String)
    * Timestamp do evento (Date)
    * Propriedades adicionais do evento (Object)
  </Step>

  <Step title="Testar a conexão">
    Clique em **Test Connection** para verificar se o OneSignal pode acessar seu cluster Elasticsearch e ler dados de eventos.
  </Step>
</Steps>

***

### Mapeamento de dados de evento

Mapeie seu {DATA_TYPE_0} {PLATFORM_0} para o formato de eventos personalizados do OneSignal:

| Campo OneSignal | {COLUMN_HEADER_0} | Descrição                  | Obrigatório |
| --------------- | ----------------- | -------------------------- | ----------- |
| `name`          | `event_name`      | Identificador de evento    | Sim         |
| `external_id`   | `user_id`         | Identificador de usuário   | Sim         |
| `timestamp`     | `event_timestamp` | Quando o evento ocorreu    | Não         |
| `properties`    | `event_data`      | {PROPERTIES_DESCRIPTION_0} | Não         |

***

## Configuração Avançada

### Filtragem Query DSL

Use Elasticsearch Query DSL para filtrar e transformar dados de eventos antes de sincronizar com o 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.*"
  ]
}
```

### Configuração de Padrão de Índice

Consulte eficientemente através de múltiplos índices:

* **Índices baseados em tempo**: Use padrões como `events-2024-*` para dados particionados por tempo
* **Roteamento**: Garanta roteamento consistente para consultas baseadas em usuário
* **Aliases**: Use aliases de índice para gerenciamento simplificado

### Otimização de Desempenho

Otimize consultas para grandes volumes de eventos:

* **Filtragem de campos**: Use filtragem `_source` para recuperar apenas campos necessários
* **Scroll API**: Para grandes conjuntos de resultados, OneSignal usa paginação scroll
* **Date math**: Use date math do Elasticsearch para filtragem eficiente baseada em tempo

<Warning>
  Certifique-se de que seu cluster Elasticsearch tem recursos suficientes para lidar com as consultas do OneSignal sem afetar outras aplicações usando o cluster.
</Warning>

***

## FAQ

### Com que frequência o OneSignal sincroniza eventos do Elasticsearch?

O OneSignal sincroniza dados de eventos baseado em seu cronograma configurado, com um intervalo mínimo de 15 minutos.

### Posso sincronizar eventos de múltiplos índices Elasticsearch?

Sim, você pode usar padrões de índice (por exemplo, `events-*`) para consultar através de múltiplos índices, ou criar múltiplas integrações para diferentes grupos de índices.

### O que acontece se meu cluster Elasticsearch ficar temporariamente indisponível?

OneSignal tentará novamente conexões com backoff exponencial. A sincronização de eventos será retomada automaticamente uma vez que seu cluster esteja acessível novamente.