Selbst gehostete EWS-Integration

Die EWS-Appliance wird als Docker-Image bereitgestellt. In den folgenden Abschnitten wird erläutert, wie Sie die Einheit konfigurieren und bereitstellen.

Konfiguration

Die Anwendung erwartet, dass eine JSON-Konfigurationsdatei vorhanden ist. In diesem Abschnitt wird der Inhalt der Datei erläutert. Anweisungen zum Bereitstellen der Konfigurationsdatei für die Einheit finden Sie im Abschnitt „Bereitstellung“.

Mit OAuth 2.0

Sie können sich mit dem geheimen Clientschlüssel oder dem Clientzertifikat authentifizieren.

Der verwendete Flow für die Gewährung des Tokens ist der Flow der Client-Anmeldeinformationen.

Mit Clientgeheimnis

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

Mit Clientzertifikat

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

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

Ersetzen Sie zuerst die Dummy-Werte in host, port und auth_user durch ihre echten Werte und ändern Sie bei Bedarf access_type . Eine Beschreibung dieser Parameter und deren zulässige Werte finden Sie in der Konfigurationsreferenz .

Geben Sie dann das Dienstbenutzerkennwort für das Gerät als REINFER_EWS_AUTH_PASS -Umgebungsvariable an – siehe Abschnitt Bereitstellung . Die vollständige Liste der Umgebungsvariablen, die Sie zum Überschreiben von Werten in der Konfiguration festlegen können, ist:

Name	BESCHREIBUNG
REINFER_EWS_AUTH_USER	Exchange-Serverbenutzer
REINFER_EWS_AUTH_PASS	Kennwort für Exchange-Server
REINFER_EWS_ACCESS_TYPE	Zugriffstyp: „Delegieren“ oder „Identitätswechsel“
REINFER_EWS_HOST	Exchange-Serverhost
REINFER_EWS_PORT	Exchange-Serverport

Postfachkonfiguration

Sie können ein oder mehrere Postfächer in Ihrer Konfiguration angeben. Für jedes Postfach müssen Sie die Postfachadresse angeben und die folgenden Parameter angeben:

Name	BESCHREIBUNG
bucket.owner	Projekt des Buckets, in dem das Postfach synchronisiert werden soll.
bucket.name	Name des Buckets, in dem das Postfach synchronisiert werden soll.
start_from	Ob ab dem letzten synchronisierten Zeitpunkt („bucket“) gestartet oder die letzte synchronisierte Zeit ignoriert und immer bei start_timestamp gestartet werden soll („config“). Sollte für normalen Betrieb auf „bucket“ festgelegt werden, beim Debuggen kann jedoch in einigen Fällen „config“ nützlich sein.
start_timestamp	Zeitstempel, ab dem die Synchronisierung der E-Mails gestartet werden soll. Wird diese Option nicht festgelegt, werden alle E-Mails synchronisiert.

Die Konfiguration verwendet die Standardwerte für eine Reihe von Einstellungen, z. B. die Abrufhäufigkeit oder Batchgröße. Informationen zum weiteren Anpassen Ihrer Konfiguration finden Sie in der Konfigurationsreferenz.

Buckets

Die Exchange-Integration synchronisiert rohe E-Mail-Daten mit Communications Mining- Buckets. Wie bei anderen Communications Mining-Ressourcen wird ein Bucket in einem Projekt erstellt, mit dem Sie den Zugriff auf den Bucket steuern können. Zum Lesen aus einem Bucket, zum Hochladen in ein Bucket oder zum Verwalten von Buckets benötigt der Benutzer die entsprechenden Berechtigungen in dem Projekt, in dem sich der Bucket befindet.

Bereitstellung

Sie können die EWS-Appliance entweder mit Kubernetes oder mit Docker bereitstellen.

Durch die Bereitstellung mit Kubernetes können Sie mehrere Instanzen der EWS-Appliance ausführen, wobei jede Instanz eine Teilmenge der zu synchronisierenden Postfächer verarbeitet.

Mit Kubernetes

Kubernetes ist eine beliebte Methode zum Ausführen und Verwalten von Containeranwendungen. Dieser Abschnitt zeigt Ihnen, wie Sie die EWS-Appliance mit Kubernetes bereitstellen. Es wird davon ausgegangen, dass Sie mit Kubernetes vertraut sind und kubectl installiert haben. Bitte lesen Sie diese Dokumentation, wenn Sie Hilfe beim Einstieg in Kubernetes benötigen.

Für die Bereitstellung auf Kubernetes müssen Sie eine YAML-Datei erstellen, die Ihre Anwendung beschreibt. Kopieren Sie zum Starten das folgende Beispiel.

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

Bevor Sie die Anwendung mit dieser YAML-Datei bereitstellen können, müssen Sie einige zusätzliche Schritte ausführen.

Ersetzen Sie zuerst <mydomain>.reinfer.io durch Ihren Mandanten-API-Endpunkt.

Zweitens werden die Umgebungsvariablen REINFER_TOKEN und REINFER_EWS_AUTH_PASS mit Kubernetes-Geheimnissen aufgefüllt, da wir vermeiden möchten, Anmeldeinformationen als Klartext in unserer YAML-Datei zu speichern. Erstellen Sie die Geheimnisse wie folgt:

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

Da wir schließlich die Gerätekonfiguration aus einer lokalen Datei laden möchten, müssen wir diese Datei in den Pod einbinden. Dazu speichern wir die Daten in einer Kubernetes ConfigMap und stellen die ConfigMap als Volume bereit. Erstellen Sie die ConfigMap wie folgt:

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

Hinweis:

Als Alternative zum lokalen Speichern der Konfigurationsdatei können Sie sie in Communications Mining hochladen und von der EWS-Appliance über die Communications Mining-API abrufen lassen. Dies wird hier beschrieben. Wenn sowohl lokale als auch Remote-Konfigurationsdateien angegeben sind, verwendet die Einheit die lokale Konfigurationsdatei.

Sie können nun Ihr StatefulSet erstellen und überprüfen, ob alles läuft:

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

Mit Docker

Alternativ können Sie die EWS-Appliance in Docker ausführen. Der folgende Befehl startet die Anwendung mit den gleichen Parametern, die im Abschnitt Kubernetes verwendet werden.

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

• Ersetzen Sie <mydomain>.reinfer.io durch Ihren Mandanten-API-Endpunkt.
• Ersetzen Sie your_ews_config.json durch den Namen Ihrer EWS-Konfigurations-JSON-Datei.

Die Anwendung wird kontinuierlich ausgeführt und synchronisiert E-Mails mit der Communications Mining-Plattform. Wenn er angehalten und erneut gestartet wird, nimmt er den Zustand des zuletzt gespeicherten Bucket-Synchronisierungsstatus wieder auf.

Mit Docker (lokaler Speicher)

Die EWS-Appliance kann extrahierte E-Mails lokal speichern, anstatt sie in die Communications Mining-Plattform zu pushen.

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

• Das Gerät erwartet, die Konfiguration in $EWS_LOCAL_DIR/config/$CONFIG_OWNER/$CONFIG_KEY.json zu finden. Alternativ können Sie den Pfad zur Konfiguration angeben, indem Sie die Umgebungsvariable $REINFER_EWS_CONFIG festlegen, wie im vorherigen Beispiel gezeigt.
• Die Maschine speichert den Synchronisierungsstatus in $EWS_LOCAL_DIR/state. Wenn sie angehalten und erneut gestartet wird, wird der Vorgang ab dem zuletzt gespeicherten Synchronisierungsstatus fortgesetzt.
• Die Anwendung speichert Daten in $EWS_LOCAL_DIR/data.

Mit Docker (Azure Blob Storage)

Das EWS-Gerät kann extrahierte E-Mails in Azure Blob Storage speichern, anstatt sie an die Communications Mining-Plattform zu senden.

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

• Sie müssen den Pfad zur Konfiguration angeben, indem Sie die Umgebungsvariable $REINFER_EWS_CONFIG festlegen.

• Das Gerät authentifiziert sich bei Azure Blob Storage mit einer der DefaultAzureCredential-Methoden. Verwenden Sie eine für Sie geeignete Methode. Gewähren Sie der Maschine unabhängig von der von Ihnen verwendeten Methode die Rolle „Storage Blob Data Contributor“.

• Die Maschine speichert den Synchronisierungsstatus in az://$AZ_STORAGE_ACCOUNT_NAME/$AZ_CONTAINER_NAME/state. Wenn sie angehalten und erneut gestartet wird, wird der Vorgang ab dem zuletzt gespeicherten Synchronisierungsstatus fortgesetzt.
• Die Anwendung speichert Daten in az://$AZ_STORAGE_ACCOUNT_NAME/$AZ_CONTAINER_NAME/data.

Speicherkonfiguration in Communications Mining

Anstatt der App eine lokale Konfigurationsdatei zur Verfügung zu stellen, wie wenn Sie der Anleitung zur Bereitstellung der EWS-Appliance gefolgt sind, können Sie die Konfigurationsdatei stattdessen in Communications Mining verwalten. Beachten Sie, dass, wenn sowohl lokale als auch Remote-Konfigurationsdateien angegeben sind, die Einheit standardmäßig die Verwendung der lokalen Konfigurationsdatei verwendet.

Laden Sie zuerst Ihre JSON-Konfigurationsdatei in Communications Mining hoch:

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>

So zeigen Sie die aktuelle Konfiguration an:

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

Legen Sie dann in der Kubernetes-YAML-Datei den Parameter --remote-config-owner auf den Projektnamen und den Parameter --remote-config-key auf den Konfigurationsnamen fest.

Referenz (Reference)

Anwendungsparameter

Eine Liste der verfügbaren Anwendungsparameter finden Sie in der folgenden Tabelle. Weitere Informationen zum Ausführen der EWS-Appliance finden Sie hier.

Parameter	BESCHREIBUNG
--reinfer-api-endpoint	Endpunkt zum Herstellen einer Verbindung mit der reinfer API. Sich gegenseitig ausschließen mit --local-files-prefix.
--local-files-prefix	Pfad zum Speichern synchronisierter E-Mails und Bucket-Synchronisierungsstatus. Sich gegenseitig ausschließen mit --reinfer-api-endpoint und REINFER_API_TOKEN.
--remote-config-owner	Projekt, das die Remote-Konfigurationsdatei der EWS-Appliance besitzt.
--remote-config-key	Name der Remote-Konfigurationsdatei der EWS-Appliance.
--debug-level	Debug-Stufe. 0 = Kein Debuggen, 1 = Dienst-Debuggen, 2 = Vollständiges Debuggen. Standard: 1.
--shard-name	Shardname, also ews-N , aus dem die Shardnummer extrahiert werden soll. Bei der Ausführung in Kubernetes können Sie ihn auf den Pod-Namen festlegen.
--total-shards	Die Gesamtzahl der Instanzen im Gerätecluster. Muss bei der Ausführung in Kubernetes auf den gleichen Wert wie die Anzahl der Instanzen im StatefulSet festgelegt werden.
--restart-on-unrecoverable-errors	Wenn diese Option aktiviert ist, führen nicht behebbare Fehler dazu, dass der gesamte Dienst neu gestartet wird, ohne abzustürzen.

Konfigurationsparameter

Eine Liste der verfügbaren Konfigurationsparameter finden Sie in der folgenden Tabelle. Weitere Informationen zum Schreiben der EWS-Appliance-Konfigurationsdatei finden Sie hier.

Name	BESCHREIBUNG
host	Exchange-Serverhost. Kann durch die Umgebungsvariable REINFER_EWS_HOST überschrieben werden.
port	Exchange-Serverport. Standard: 80. Kann durch die Umgebungsvariable REINFER_EWS_PORT überschrieben werden.
auth_type	Nur „ntrm“ zulässig.
auth_user	Exchange-Serverbenutzer. Kann durch die Umgebungsvariable REINFER_EWS_AUTH_USER überschrieben werden.
auth_password	Kennwort für Exchange-Server. Kann durch die Umgebungsvariable REINFER_EWS_AUTH_PASS überschrieben werden.
access_type	Zugriffstyp: „Delegieren“ oder „Identitätswechsel“. Standard: „delegate“. Kann durch die Umgebungsvariable REINFER_EWS_ACCESS_TYPE überschrieben werden.
ews_ssl_verify	Wenn „false“ festgelegt ist, werden die Zertifikate nicht überprüft. Standard: „true“.
poll_frequency	Die Wartezeit zwischen den Batches in Sekunden. Standard: 15.
poll_message_sleep	Die Wartezeit zwischen einzelnen E-Mails in einem Batch in Sekunden. Standard: 0.1.
max_concurrent_uploads	Anzahl der gleichzeitigen Uploads in Communications Mining zwischen 0 und 32. Standard: 8.
emails_per_folder	Die maximale Anzahl der E-Mails, die aus jedem Ordner pro Batch abgerufen werden können, liegt zwischen 1 und 100.000. Standard: 2520. Mit dieser Einstellung kann die Anwendung bei allen Ordnern gleichmäßig voranschreiten, auch wenn der Ordner sehr groß ist.
reinfer_batch_size	Die Anzahl der abzurufenden E-Mails pro Batch, zwischen 1 und 1000. Standard: 80.
mailboxes	Liste der abzurufenden Postfächer. Eine Erklärung zum Konfigurieren der Postfächer finden Sie hier .
audit_email	Wenn Sie die Anwendung mit einer Remote -Konfiguration konfiguriert haben, sendet Communications Mining eine E-Mail an diese Adresse, wenn die Konfiguration aktualisiert wird. Standard: Keine.
ews_ssl_ciphers	Stellen Sie sicher, dass die EWS-Appliance bestimmte Verschlüsselungen verwendet. Die Verschlüsselungen müssen eine Zeichenfolge im OpenSSL-Verschlüsselungslistenformat sein. Standard: Keine.