Communications Mining: integración de EWS autohospedado

Configuración

El dispositivo espera que haya un archivo de configuración JSON. Esta sección explica el contenido del archivo. Consulta la sección Implementación para obtener instrucciones sobre cómo hacer que el archivo de configuración esté disponible para el dispositivo.

Con OAuth 2.0

Puedes autenticarte con el secreto del cliente o con el certificado del cliente.

El flujo de concesión de tokens utilizado es el flujo de credenciales de cliente.

Con secreto 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_secret": "<client_secret>",
  "access_type": "impersonation",
  "mailboxes": {
    "abc@example.com": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    },
    "xyz@example.com": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    }
  }
}{
  "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": {
    "abc@example.com": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    },
    "xyz@example.com": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    }
  }
}

Con 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": {
    "abc@example.com": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    },
    "xyz@example.com": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    }
  }
}{
  "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": {
    "abc@example.com": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    },
    "xyz@example.com": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    }
  }
}

Con NTLM

{
  "host": "https://exchange-server.example.com",
  "port": 443,
  "auth_type": "ntlm",
  "auth_user": "ews-service-user@example.com",
  "access_type": "delegate",
  "mailboxes": {
    "abc@example.com": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    },
    "xyz@example.com": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    }
  }
}{
  "host": "https://exchange-server.example.com",
  "port": 443,
  "auth_type": "ntlm",
  "auth_user": "ews-service-user@example.com",
  "access_type": "delegate",
  "mailboxes": {
    "abc@example.com": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    },
    "xyz@example.com": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    }
  }
}

Primero, reemplaza los valores ficticios en host, port y auth_user con sus valores reales, y cambia access_type si es necesario. Consulta la referencia de configuración para obtener una descripción de estos parámetros y sus valores permitidos.

A continuación, proporciona la contraseña de usuario del servicio al dispositivo como una variable de entorno REINFER_EWS_AUTH_PASS ; consulta la sección Implementación . La lista completa de variables de entorno que puedes establecer para anular valores en la configuración es:

Nombre	Descripción
`REINFER_EWS_AUTH_USER`	Usuario del servidor de Exchange
`REINFER_EWS_AUTH_PASS`	Contraseña del servidor de Exchange
`REINFER_EWS_ACCESS_TYPE`	Tipo de acceso: "delegado" o "suplantación"
`REINFER_EWS_HOST`	Host del servidor de Exchange
`REINFER_EWS_PORT`	Puerto del servidor de Exchange

Configuración del buzón

Puedes especificar uno o más buzones en tu configuración. Para cada buzón, debes proporcionar la dirección del buzón y especificar los siguientes parámetros:

Nombre	Descripción
`bucket.owner`	Proyecto del depósito en el que se debe sincronizar el buzón.
`bucket.name`	Nombre del depósito en el que se debe sincronizar el buzón.
`start_from`	Si se debe comenzar desde la última hora sincronizada ("depósito") o ignorar la última hora sincronizada y comenzar siempre desde `start_timestamp` ("config"). Debe establecerse en "depósito" para el funcionamiento normal, pero "config" puede ser útil en algunos casos al depurar.
`start_timestamp`	Marca de tiempo desde la que iniciar la sincronización del correo electrónico. Si no se establece, se sincronizarán todos los correos electrónicos.

La configuración utiliza los valores predeterminados para una serie de ajustes, como la frecuencia de sondeo o el tamaño del lote. Para personalizar aún más tu configuración, consulta la referencia de configuración.

Depósitos

La integración de Exchange sincroniza los datos de correo electrónico sin procesar en depósitos de Communications Mining. Al igual que otros recursos de Communications Mining, se crea un depósito en un proyecto que te permite controlar el acceso al depósito. Para leer desde un depósito, cargar en un depósito o gestionar depósitos, el usuario necesita los permisos respectivos en el proyecto en el que se encuentra el depósito.

Implementación

Puedes implementar el dispositivo EWS con Kubernetes o con Docker.

La implementación con Kubernetes te permite ejecutar varias instancias del dispositivo EWS, y cada instancia gestiona un subconjunto de buzones de correo que se sincronizarán.

Con Kubernetes

El uso de Kubernetes es una forma popular de ejecutar y gestionar aplicaciones en contenedores. Esta sección te muestra cómo implementar el dispositivo EWS utilizando Kubernetes. Se supone que tienes conocimientos básicos de Kubernetes y que tienes kubectl instalado. Consulta esta documentación si necesitas ayuda para empezar a utilizar Kubernetes.

Para implementar en Kubernetes, debes crear un archivo YAML que describa tu aplicación. Para empezar, copia el siguiente ejemplo.

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-volapiVersion: 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 poder implementar el dispositivo utilizando este archivo YAML, hay que realizar algunos pasos adicionales.

En primer lugar, sustituye <mydomain>.reinfer.io por el punto de conexión de la API de tu tenant.

En segundo lugar, dado que nos gustaría evitar almacenar credenciales como texto no cifrado en nuestro archivo YAML, las variables de entorno REINFER_TOKEN y REINFER_EWS_AUTH_PASS se rellenan a partir de los secretos de Kubernetes. Crea los secretos así:

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

Por último, como nos gustaría cargar la configuración del dispositivo desde un archivo local, debemos montar ese archivo en el pod. Para ello, almacenamos los datos en un ConfigMap de Kubernetes y montamos el ConfigMap como un volumen. Crea el ConfigMap así:

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

Nota:

Como alternativa al almacenamiento local del archivo de configuración, puedes cargarlo en Communications Mining y dejar que el dispositivo EWS lo obtenga a través de la API de Communications Mining. Esto se describe aquí. Si se especifican los archivos de configuración locales y remotos, el dispositivo utilizará el archivo de configuración local.

Ahora puedes crear tu statefulset y comprobar que todo se está ejecutando:

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

Con Docker

Como alternativa, puedes ejecutar el dispositivo EWS en Docker. El siguiente comando iniciará el dispositivo con los mismos parámetros que se utilizan en la sección 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).logEWS_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

Sustituye <mydomain>.reinfer.io por el punto de conexión de la API de tu tenant.
Sustituye your_ews_config.json por el nombre de tu archivo JSON de configuración de EWS.

El dispositivo se ejecutará continuamente sincronizando correos electrónicos en la plataforma Communications Mining. Si se detiene y se vuelve a iniciar, se reanudará desde el último estado de sincronización del depósito almacenado.

Con Docker (almacenamiento local)

El dispositivo EWS puede guardar los correos electrónicos extraídos localmente en lugar de enviarlos a la 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).logEWS_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

El dispositivo espera encontrar la configuración en $EWS_LOCAL_DIR/config/$CONFIG_OWNER/$CONFIG_KEY.json. También puedes proporcionar la ruta a la configuración estableciendo la variable de entorno $REINFER_EWS_CONFIG como se muestra en el ejemplo anterior.
El dispositivo guardará el estado de sincronización en $EWS_LOCAL_DIR/state. Si se detiene y se vuelve a iniciar, se reanudará desde el último estado de sincronización almacenado.
El dispositivo guardará los datos en $EWS_LOCAL_DIR/data.

Con Docker (Azure Blob Storage)

El dispositivo EWS puede guardar los correos electrónicos extraídos en Azure Blob Storage en lugar de enviarlos a la 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).logEWS_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

Debes proporcionar la ruta a la configuración estableciendo la variable de entorno $REINFER_EWS_CONFIG .
El dispositivo se autentica en Azure Blob Storage utilizando uno de los métodos DefaultAzureCredential. Utilice un método que sea conveniente para usted. Independientemente del método que utilice, conceda el rol "Contribuidor de datos de blob de almacenamiento" al dispositivo.
El dispositivo guardará el estado de sincronización en az://$AZ_STORAGE_ACCOUNT_NAME/$AZ_CONTAINER_NAME/state. Si se detiene y se vuelve a iniciar, se reanudará desde el último estado de sincronización almacenado.
El dispositivo guardará los datos en az://$AZ_STORAGE_ACCOUNT_NAME/$AZ_CONTAINER_NAME/data.

Almacenar la configuración en Communications Mining

En lugar de proporcionar un archivo de configuración local al dispositivo como lo hacías si seguías la guía de implementación del dispositivo EWS, puedes gestionar el archivo de configuración en Communications Mining. Ten en cuenta que si se especifican los archivos de configuración locales y remotos, el dispositivo utilizará de forma predeterminada el archivo de configuración local.

Primero, sube tu archivo de configuración JSON a 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>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 la configuración actual:

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

A continuación, en el archivo YAML de Kubernetes, establece el parámetro --remote-config-owner en el nombre del proyecto y el parámetro --remote-config-key en el nombre de la configuración.

Referencia

Parámetros de la aplicación

Consulta la siguiente tabla para ver una lista de los parámetros de aplicación disponibles. Puedes obtener más información sobre la ejecución del dispositivo EWS aquí.

Parámetro	Descripción
`--reinfer-api-endpoint`	Punto final para conectarse a la API Reinferir. Mutuamente excluyente con `--local-files-prefix`.
`--local-files-prefix`	Ruta para almacenar los correos electrónicos sincronizados y el estado de sincronización del depósito. Mutuamente excluyente con `--reinfer-api-endpoint` y `REINFER_API_TOKEN`.
`--remote-config-owner`	Proyecto propietario del archivo de configuración del dispositivo EWS remoto.
`--remote-config-key`	Nombre del archivo de configuración del dispositivo EWS remoto.
`--debug-level`	Nivel de depuración. 0 = Sin depuración, 1 = Depuración de servicio, 2 = Depuración completa. Predeterminado: 1.
`--shard-name`	Nombre del fragmento, es decir, `ews-N` del que extraer el número del fragmento. Cuando se ejecuta en Kubernetes, puedes establecerlo en el nombre del pod.
`--total-shards`	El número total de instancias en el clúster de dispositivos. Cuando se ejecuta en Kubernetes, debe establecerse en el mismo valor que el número de instancias en StatefulSet.
`--restart-on-unrecoverable-errors`	Si se habilita, los fallos irrecuperables darán lugar a que todo el servicio se reinicie sin bloquearse.

Parámetros de configuración

Consulta la siguiente tabla para ver una lista de los parámetros de configuración disponibles. Puedes obtener más información sobre cómo escribir el archivo de configuración del dispositivo EWS aquí.

Nombre	Descripción
`host`	Host del servidor de Exchange. Puede ser anulado por la variable de entorno `REINFER_EWS_HOST` .
`port`	Puerto del servidor de Exchange. Valor predeterminado: 80. Puede ser anulado por la variable de entorno `REINFER_EWS_PORT` .
`auth_type`	Solo se permite "ntlm".
`auth_user`	Usuario del servidor de Exchange. Puede ser anulado por la variable de entorno `REINFER_EWS_AUTH_USER` .
`auth_password`	Contraseña del servidor de Exchange. Puede ser anulado por la variable de entorno `REINFER_EWS_AUTH_PASS` .
`access_type`	Tipo de acceso: "delegado" o "suplantación". Predeterminado: "delegado". Puede ser anulado por la variable de entorno `REINFER_EWS_ACCESS_TYPE` .
`ews_ssl_verify`	Si se establece en "falso", no se verificarán los certificados. Predeterminado: "verdadero".
`poll_frequency`	Cuánto tiempo esperar entre lotes, en segundos. Predeterminado: 15.
`poll_message_sleep`	Cuánto tiempo esperar entre correos electrónicos individuales en un lote, en segundos. Predeterminado: 0.1.
`max_concurrent_uploads`	Número de cargas simultáneas en Communications Mining, entre 0 y 32. Predeterminado: 8.
`emails_per_folder`	Número máximo de correos electrónicos para recuperar de cada carpeta por lote, entre 1 y 100 000. Predeterminado: 2520. Esta configuración permite que el dispositivo progrese en todas las carpetas de manera uniforme en caso de que haya una carpeta muy grande.
`reinfer_batch_size`	Cuántos correos electrónicos recuperar por lote, entre 1 y 1000. Predeterminado: 80.
`mailboxes`	Lista de buzones de correo a recuperar. Consulta aquí para obtener una explicación de cómo configurar los buzones de correo.
`audit_email`	Si ha configurado el dispositivo con una configuración remota, Communications Mining enviará un correo electrónico a esta dirección cada vez que se actualice la configuración. Predeterminado: Ninguno.
`ews_ssl_ciphers`	Hacer que el dispositivo EWS utilice cifrados específicos. Los cifrados deben ser una cadena en el formato de lista de cifrado OpenSSL. Predeterminado: Ninguno.

Guía para desarrolladores de Communications Mining

Integración de EWS autohospedado