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.

Com OAuth 2.0

Você pode se autenticar com o segredo do cliente ou com o certificado do cliente.

O fluxo de concessão de tokens usado é o fluxo de credenciais do cliente.

Com segredo do cliente

{
  "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"
    }
  }
}

Com certificado de cliente

{
  "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"
    }
  }
}

Com 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"
    }
  }
}

Primeiro, substitua os valores fictícios em host, port e auth_user por seus valores reais, e altere access_type se necessário. Consulte a referência de configuração para obter uma descrição desses parâmetros e seus valores permitidos.

Em seguida, forneça a senha do usuário do serviço para o dispositivo como uma variável de ambiente REINFER_EWS_AUTH_PASS - consulte a seção Implantação . A lista completa de variáveis de ambiente que você pode definir para substituir valores na configuração é:

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

Configuração da caixa de correio

Você pode especificar uma ou mais caixas de correio em sua configuração. Para cada caixa de correio, você deve fornecer o endereço da caixa de correio e especificar os seguintes parâmetros:

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:

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=
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 \
  eu.gcr.io/reinfer-gcr/ews:$TAG \
  --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=
CONFIG_OWNER=
CONFIG_KEY=
TAG=

sudo docker run \
  -v $EWS_LOCAL_DIR:/mnt/ews \
  eu.gcr.io/reinfer-gcr/ews:$TAG \
  --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 a configuração definindo a variável de ambiente $REINFER_EWS_CONFIG como mostrado no exemplo anterior.
• 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.

Com o Docker (Armazenamento de Blobs do Azure)

O dispositivo EWS pode salvar e-mails extraídos no armazenamento de Blob do Azure em vez de enviá-los para a plataforma Communications Mining.

EWS_CONFIG_DIR=
AZ_STORAGE_ACCOUNT_NAME=
AZ_CONTAINER_NAME=
TAG=

sudo docker run \
  -v $EWS_CONFIG_DIR:/mnt/config \
  --env REINFER_EWS_CONFIG=/mnt/config/your_ews_config.json \
  eu.gcr.io/reinfer-gcr/ews:$TAG \
  --private-file-prefix az://$AZ_STORAGE_ACCOUNT_NAME/$AZ_CONTAINER_NAME \
  &> ews_$(date -Iseconds).log

• Você deve fornecer o caminho para o arquivo de configuração definindo a variável de ambiente $REINFER_EWS_CONFIG .

• O dispositivo é autenticado no Armazenamento de Blobs do Azure usando um dos métodos DefaultAzureCredential. Use um método que seja conveniente para você. Independentemente do método que você usar, conceda a função "Storage Blob Data Contributor" ao dispositivo.

• O dispositivo salvará o estado de sincronização em az://$AZ_STORAGE_ACCOUNT_NAME/$AZ_CONTAINER_NAME/state. Se for interrompida e iniciada novamente, ela retomará o último estado de sincronização armazenado.
• O aplicativo salvará os dados em az://$AZ_STORAGE_ACCOUNT_NAME/$AZ_CONTAINER_NAME/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.