Integração do EWS auto-hospedado

O aplicativo EWS é entregue como uma imagem do Docker. As seções abaixo explicam como configurar e implantar o dispositivo.

Configuração

O aplicativo espera que um arquivo de configuração JSON esteja presente. Esta seção explica o conteúdo do arquivo. Consulte a seção Implantação para obter instruções sobre como disponibilizar o arquivo de configuração para a solução.

With OAuth 2.0

You can authenticate with client secret or with client certificate.

The token grant flow used is the client credentials flow.

With client secret

{
  "ews_endpoint": "https://outlook.office365.com/EWS/Exchange.asmx",
  "auth_type": "oauth2",
  "auth_oauth_authority": "https://login.microsoftonline.com/<tenant_id>/",
  "auth_oauth_client_id": "<client_id>",
  "auth_oauth_client_secret": "<client_secret>",
  "access_type": "impersonation",
  "mailboxes": {
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    },
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    }
  }
}

With client certificate

{
  "ews_endpoint": "https://outlook.office365.com/EWS/Exchange.asmx",
  "auth_type": "oauth2",
  "auth_oauth_authority": "https://login.microsoftonline.com/<tenant_id>/",
  "auth_oauth_client_id": "<client_id>",
  "auth_oauth_client_credential_private_key": "<private_key>",
  "auth_oauth_client_credential_thumbprint": "<thumbprint>",
  "access_type": "impersonation",
  "mailboxes": {
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    },
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    }
  }
}

With NTLM

{
  "host": "https://exchange-server.example.com",
  "port": 443,
  "auth_type": "ntlm",
  "auth_user": "[e-mail]",
  "access_type": "delegate",
  "mailboxes": {
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    },
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    }
  }
}

First, replace the dummy values in host, port, and auth_user with their real values, and change access_type if required. See the configuration reference for a description of these parameters and their allowed values.

Then, provide the service user password to the appliance as a REINFER_EWS_AUTH_PASS environment variable - see the Deployment section. The full list of environment variables that you can set to override values in the config is:

Nome	Descrição
REINFER_EWS_AUTH_USER	Usuário do Exchange Server
REINFER_EWS_AUTH_PASS	Senha do Exchange Server
REINFER_EWS_ACCESS_TYPE	Tipo de acesso: "delegate" ou "impersonation"
REINFER_EWS_HOST	Host do Exchange Server
REINFER_EWS_PORT	Porta do Exchange Server

Mailbox configuration

You can specify one or more mailboxes in your configuration. For each mailbox, you have to provide the mailbox address and specify the following parameters:

Nome	Descrição
bucket.owner	O projeto do bucket em que a caixa de correio será sincronizada.
bucket.name	Nome do bucket no qual a caixa de correio deve ser sincronizada.
start_from	Se você deve iniciar a partir da última hora sincronizada ("bucket") ou ignorar a última hora sincronizada e sempre começar em start_timestamp ("config"). Deve ser definido como "bucket" para operação normal, mas "config" pode ser útil em alguns casos durante a depuração.
start_timestamp	Carimbo de data/hora a partir do qual a sincronização do email iniciará. Caso não esteja definida, todos os emails serão sincronizados.

A configuração usa os valores padrão para várias configurações, como a frequência de pesquisa ou o tamanho do lote. Para personalizar ainda mais sua configuração, consulte a referência de configuração.

Buckets

A integração do Exchange sincroniza dados brutos de e-mail em buckets do Communications Mining. Assim como outros recursos do Communications Mining, um bucket é criado em um projeto, o que permite que você controle o acesso a ele. Para ler a partir de um bucket, carregar em um bucket ou gerenciar buckets, o usuário precisa das respectivas permissões no projeto em que o bucket está.

Implantação

Você pode implantar o dispositivo EWS com o Kubernetes ou com o Docker.

A implantação com o Kubernetes permite que você execute várias instâncias do dispositivo EWS, com cada instância lidando com um subconjunto de caixas de correio a serem sincronizadas.

Com o Kubernetes

Usar o Kubernetes é uma maneira popular de executar e gerenciar aplicativos em contêiners. Esta seção mostra como implantar o dispositivo EWS usando o Kubernetes. Assume-se que você tenha familiaridade básica com Kubernetes e tenha kubectl instalado. Confira esta documentação se você precisar de ajuda para começar a usar o Kubernetes.

Para implantar no Kubernetes, você precisa criar um arquivo YAML descrevendo seu aplicativo. Para começar, copie o exemplo abaixo.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: reinfer-ews-appliance
  labels:
    app: reinfer-ews-appliance
spec:
  podManagementPolicy: Parallel
  replicas: 1
  selector:
    matchLabels:
      app: reinfer-ews-appliance
  serviceName: reinfer-ews-appliance
  template:
    metadata:
      labels:
        app: reinfer-ews-appliance
      name: reinfer-ews-appliance
    spec:
      containers:
        - args:
            - "reinfer-ews"
            - "--bind"
            - "0.0.0.0:8000"
            - "--reinfer-api-endpoint"
            - "https://<mydomain>.reinfer.io/api/"
            - "--shard-name"
            - "$(POD_NAME)"
            # This value should match `spec.replicas` above
            - "--total-shards"
            - "1"
          env:
            - name: REINFER_EWS_CONFIG
              value: "/mnt/config/example_ews_config"
            - name: REINFER_API_TOKEN
              valueFrom:
                secretKeyRef:
                  key: reinfer-api-token
                  name: reinfer-credentials
            - name: REINFER_EWS_AUTH_PASS
              valueFrom:
                secretKeyRef:
                  key: ews-auth-pass
                  name: reinfer-credentials
            - name: POD_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
          image: "your.private.registry.com/reinfer/ews-appliance:TAG"
          name: reinfer-ews-appliance
          resources:
            requests:
              cpu: 0.05
              memory: 128Mi
          volumeMounts:
            - mountPath: /mnt/config
              name: config-vol
      volumes:
        - configMap:
            name: ews-config
            items:
              - key: example_ews_config
                path: example_ews_config
          name: config-vol

Antes de implantar o dispositivo usando esse arquivo YAML, há algumas etapas adicionais que você precisa realizar.

Primeiro, substitua <mydomain>.reinfer.io pelo endpoint da API do tenant.

Segundo, como queremos evitar o armazenamento de credenciais como texto não criptografado em nosso arquivo YAML, as variáveis de ambiente REINFER_TOKEN e REINFER_EWS_AUTH_PASS são preenchidas a partir de segredos do Kubernetes. Crie os segredos da seguinte forma:

kubectl create secret generic reinfer-credentials \
  --from-literal=reinfer-api-token=<REINFER_TOKEN> \
  --from-literal=ews-auth-pass=<MSEXCHANGE_PASSWORD>

Por fim, como queremos carregar a configuração do dispositivo de um arquivo local, precisamos montar esse arquivo no pod. Fazemos isso armazenando os dados em um ConfigMap do Kubernetes e montando o ConfigMap como um volume. Crie o ConfigMap desta forma:

kubectl create configmap ews-config \
  --from-file=example_ews_config=your-ews-config.json

Observação:

Observação

Como uma alternativa para armazenar o arquivo de configuração localmente, você pode carregá-lo para o Communications Mining e deixar o dispositivo EWS o buscar por meio da API do Communications Mining. Isso é descrito aqui. Se os arquivos de configuração, local e remota, forem especificados, a solução usará o arquivo de configuração local.

Agora, você pode criar sua statefulset e verificar se tudo está sendo executado:

kubectl apply -f reinfer-ews.yaml
kubectl get sts

Com o Docker

Ou então, você pode executar o aplicativo EWS em Docker. O comando abaixo iniciará o dispositivo com os mesmos parâmetros usados na seção Kubernetes .

EWS_CONFIG_DIR=
REINFER_API_TOKEN=
MSEXCHANGE_PASSWORD=
TAG=

sudo docker run \
-v $EWS_CONFIG_DIR:/mnt/config \
--env REINFER_EWS_CONFIG=/mnt/config/your_ews_config.json \
--env REINFER_API_TOKEN=$REINFER_API_TOKEN \
--env REINFER_EWS_AUTH_PASS=$MSEXCHANGE_PASSWORD \
eu.gcr.io/reinfer-gcr/ews:$TAG \
reinfer-ews --reinfer-api-endpoint https://<mydomain>.reinfer.io/api/ &> ews_$(date -Iseconds).log

• Substitua <mydomain>.reinfer.io por seu ponto de extremidade da API do tenant.
• Substitua your_ews_config.json pelo nome do seu arquivo JSON de configuração do EWS.

O aplicativo será executado continuamente sincronizando e-mails na plataforma Communications Mining. Se for interrompida e iniciada novamente, ela retomará o último estado de sincronização do bucket armazenado.

Com o Docker (armazenamento local)

O aplicativo EWS pode salvar e-mails extraídos localmente, em vez de enviá-los para a plataforma Communications Mining.

EWS_LOCAL_DIR=
MSEXCHANGE_PASSWORD=
CONFIG_OWNER=
CONFIG_KEY=
TAG=

sudo docker run \
-v $EWS_LOCAL_DIR:/mnt/ews \
--env REINFER_EWS_AUTH_PASS=$MSEXCHANGE_PASSWORD \
eu.gcr.io/reinfer-gcr/ews:$TAG \
reinfer-ews --local-files-prefix /mnt/ews \
--remote-config-owner $CONFIG_OWNER --remote-config-key $CONFIG_KEY &> ews_$(date -Iseconds).log

• O dispositivo espera encontrar a configuração em $EWS_LOCAL_DIR/config/$CONFIG_OWNER/$CONFIG_KEY.json. Alternativamente, você pode fornecer o caminho para configuração definindo a variável de ambiente $REINFER_EWS_CONFIG .
• O dispositivo salvará o estado de sincronização em $EWS_LOCAL_DIR/state. Se for interrompida e iniciada novamente, ela retomará o último estado de sincronização armazenado.
• O aplicativo salvará os dados em $EWS_LOCAL_DIR/data.

Armazenar configurações no Communications Mining

Em vez de fornecer um arquivo de configuração local ao dispositivo, como faria se estivesse seguindo o guia de implantação do dispositivo EWS, você pode gerenciar o arquivo de configuração no Communications Mining. Observe que, se os arquivos de configuração, local e remota, forem especificados, a solução usará o arquivo de configuração local.

Primeiro, carregue seu arquivo de configuração JSON para o Communications Mining:

curl -H "Authorization: Bearer $REINFER_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F 'file=@your-ews-config.json' \
  -XPUT https://<mydomain>.reinfer.io/api/v1/appliance-configs/<project-name>/<config-name>

Para ver a configuração atual:

curl -H "Authorization: Bearer $REINFER_TOKEN" \
  -XGET https://<mydomain>.reinfer.io/api/v1/appliance-configs/<project-name>/<config-name>

Em seguida, no arquivo YAML do Kubernetes, defina o parâmetro --remote-config-owner para o nome do projeto e o parâmetro --remote-config-key para o nome da configuração.

Referência

Parâmetros do aplicativo

Consulte a tabela abaixo para uma lista de parâmetros de aplicativo disponíveis. Saiba mais sobre como executar o dispositivo EWS aqui.

Parâmetro	Descrição
--reinfer-api-endpoint	Ponto de extremidade para se conectar à API Reinfer. Mutuamente exclusivo com --local-files-prefix.
--local-files-prefix	Caminho para armazenar os e-mails sincronizados e o estado de sincronização do bucket. Mutuamente exclusivo com --reinfer-api-endpoint e REINFER_API_TOKEN.
--remote-config-owner	Projeto proprietário do arquivo de configuração remoto do dispositivo EWS.
--remote-config-key	Nome do arquivo de configuração remoto do dispositivo EWS.
--debug-level	Nível de debug. 0 = Sem depuração, 1 = Depuração de serviço, 2 = Depuração completa. Padrão: 1.
--shard-name	Nome do fragmento, ou seja, ews-N do qual extrair o número de fragmentos. Ao executar em Kubernetes, você pode defini-lo para o nome do pod.
--total-shards	O número total de instâncias no cluster do aplicativo. Ao executar no Kubernetes, deve ser definido com o mesmo valor que o número de instâncias no StatefulSet.
--restart-on-unrecoverable-errors	Se habilitada, falhas irrecuperáveis resultarão em todo o serviço sendo reiniciado sem falhar.

Parâmetros de configuração

Consulte a tabela abaixo para obter uma lista dos parâmetros de configuração disponíveis. Você pode aprender mais sobre como escrever o arquivo de configuração do dispositivo EWS aqui.

Nome	Descrição
host	Host do Exchange Server. Pode ser substituído pela variável de ambiente REINFER_EWS_HOST .
port	Porta do Exchange Server. Padrão: 80. Pode ser substituído pela variável de ambiente REINFER_EWS_PORT .
auth_type	Apenas "ntlm" é permitido.
auth_user	Usuário do servidor do Exchange. Pode ser substituído pela variável de ambiente REINFER_EWS_AUTH_USER .
auth_password	Senha do servidor do Exchange. Pode ser substituído pela variável de ambiente REINFER_EWS_AUTH_PASS .
access_type	Tipo de acesso: "delegado" ou "personificação". Padrão: "delegate". Pode ser substituído pela variável de ambiente REINFER_EWS_ACCESS_TYPE .
ews_ssl_verify	Se definido como "false", não verificará certificados. Padrão: "true".
poll_frequency	Tempo de espera entre lotes, em segundos. Padrão: 15.
poll_message_sleep	Tempo de espera entre emails individuais em um lote, em segundos. Padrão: 0,1.
max_concurrent_uploads	Número de uploads simultâneos para o Communications Mining, entre 0 e 32. Padrão: 8.
emails_per_folder	Número máximo de emails a serem buscados em cada pasta por lote, entre 1 e 100.000. Padrão: 2520. Essa configuração permite que o dispositivo faça progresso em todas as pastas uniformemente, caso haja uma pasta muito grande.
reinfer_batch_size	Quantos emails devem ser buscados por lote, entre 1 e 1.000. Padrão: 80.
mailboxes	Lista de caixas de correio a serem buscadas. Consulte aqui para obter uma explicação de como configurar as caixas de correio.
audit_email	Se você tiver configurado o dispositivo com uma configuração remota, o Communications Mining enviará um e-mail para este endereço sempre que a configuração for atualizada. Padrão: nenhum.
ews_ssl_ciphers	Fazer com que o dispositivo EWS use cifras específicas. As cifras devem ser uma string no formato de lista de cifras do OpenSSL. Padrão: nenhum.