自托管 EWS 集成

EWS 设备作为 Docker 映像提供。 以下各节介绍了如何配置和部署设备。

配置

设备需要一个 JSON 配置文件。 本节介绍文件的内容。 有关如何使配置文件可用于设备的说明，请参阅部署部分。

使用 OAuth 2.0

您可以使用客户端密码或客户端证书进行身份验证。

使用的令牌授予流程是客户端凭据流程。

使用客户端密码

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

使用客户端证书

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

使用 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"
    }
  }
}

首先，将host 、 port和auth_user中的虚拟值替换为其实际值，并根据需要更改access_type 。 有关这些参数及其允许值的说明，请参阅配置参考。

然后，将服务用户密码作为REINFER_EWS_AUTH_PASS环境变量提供给设备 - 请参阅部署部分。 您可以设置为覆盖配置中的值的环境变量的完整列表为：

名称	说明
REINFER_EWS_AUTH_USER	Exchange 服务器用户
REINFER_EWS_AUTH_PASS	Exchange 服务器密码
REINFER_EWS_ACCESS_TYPE	访问类型：“委派”或“模拟”
REINFER_EWS_HOST	Exchange 服务器主机
REINFER_EWS_PORT	Exchange 服务器端口

邮箱配置

您可以在配置中指定一个或多个邮箱。 对于每个邮箱，您必须提供邮箱地址并指定以下参数：

名称	说明
bucket.owner	应在其中同步邮箱的存储桶项目。
bucket.name	应在其中同步邮箱的存储桶的名称。
start_from	是从上次同步时间 (“存储桶”) 开始，还是忽略上次同步时间并始终从start_timestamp (“配置”) 开始。应设置为“bucket”以进行正常操作，但在调试时的某些情况下，“config”可能很有用。
start_timestamp	开始同步电子邮件的时间戳。 如果未设置，则系统将同步所有电子邮件。

该配置使用许多设置的默认值，例如轮询频率或批处理大小。 要进一步自定义配置，请参阅配置参考。

存储桶

Exchange 集成将原始电子邮件数据同步到 Communications Mining存储桶中。 与其他 Communications Mining 资源相同，系统会在项目中创建一个存储桶，用于控制对存储桶的访问。 为了从存储桶中读取、上传到存储桶或管理存储桶，用户需要在存储桶所在的项目中拥有相应的权限。

部署

您可以使用Kubernetes或Docker部署 EWS 设备。

通过 Kubernetes 部署，您可以运行 EWS 设备的多个实例，每个实例都处理要同步的一部分邮箱。

使用 Kubernetes

使用 Kubernetes 是运行和管理容器化应用程序的一种流行方法。 本节介绍如何使用 Kubernetes 部署 EWS 设备。 它假定您基本熟悉 Kubernetes 并已安装kubectl 。 如果您在 Kubernetes 入门方面需要帮助，请查看此文档。

为了部署到 Kubernetes，您需要创建一个描述应用程序的 YAML 文件。 首先，复制下面的示例。

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

在使用此 YAML 文件部署设备之前，您需要执行一些其他步骤。

首先，将<mydomain>.reinfer.io替换为您的租户 API 端点。

其次，由于我们希望避免在 YAML 文件中将凭据以明文形式存储，因此REINFER_TOKEN和REINFER_EWS_AUTH_PASS环境变量将使用 Kubernetes 密码填充。 创建密码，如下所示：

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

最后，由于我们想从本地文件加载设备配置，因此需要将该文件装载到 Pod 中。 为此，我们将数据存储在 Kubernetes 配置映射中，并将配置映射安装为卷。 像这样创建配置映射：

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

备注：

除了在本地存储配置文件外，您还可以将其上传到 Communications Mining，并让 EWS 设备通过 Communications Mining API 获取该文件。 此处介绍了这一点。 如果同时指定了本地和远程配置文件，则设备将使用本地配置文件。

您现在可以创建状态副本集并检查一切是否正在运行：

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

使用 Docker

或者，您可以在 Docker 中运行 EWS 设备。 以下命令将使用与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

• 将<mydomain>.reinfer.io替换为您的租户 API 端点。
• 将your_ews_config.json替换为 EWS 配置 JSON 文件的名称。

该设备将持续将电子邮件同步到 Communications Mining 平台中。 如果停止并再次启动，将从上次存储的存储桶同步状态中选取。

使用 Docker（本地存储）

EWS 设备可以在本地保存提取的电子邮件，而不是将其推送到 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

• 设备预期会在$EWS_LOCAL_DIR/config/$CONFIG_OWNER/$CONFIG_KEY.json中找到配置。 您也可以通过设置$REINFER_EWS_CONFIG环境变量来提供配置的路径，如上一个示例所示。
• 设备会将同步状态保存到$EWS_LOCAL_DIR/state 。 如果停止并再次启动，将从上次存储的同步状态中获取。
• 设备会将数据保存到$EWS_LOCAL_DIR/data 。

使用 Docker（Azure Blob 存储）

EWS 设备可以将提取的电子邮件保存到 Azure Blob 存储，而不是将其推送到 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

• 您应该通过设置$REINFER_EWS_CONFIG环境变量来提供配置的路径。

• 设备使用其中一种默认 Azure凭据方法对 Azure Blob 存储进行身份验证。 请使用您方便的方法。 无论使用哪种方法，请向设备授予“存储 Blob 数据参与者”角色。

• 设备会将同步状态保存到az://$AZ_STORAGE_ACCOUNT_NAME/$AZ_CONTAINER_NAME/state 。 如果停止并再次启动，将从上次存储的同步状态中获取。
• 设备会将数据保存到az://$AZ_STORAGE_ACCOUNT_NAME/$AZ_CONTAINER_NAME/data 。

Communications Mining 中的存储配置

您可以在 Communications Mining 中管理配置文件，而不是像按照EWS 设备部署指南那样向设备提供本地配置文件。 请注意，如果同时指定了本地和远程配置文件，则设备将默认使用本地配置文件。

首先，将JSON 配置文件上传到 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" \
  -XGET https://<mydomain>.reinfer.io/api/v1/appliance-configs/<project-name>/<config-name>

然后，在 Kubernetes YAML 文件中，将--remote-config-owner参数设置为项目名称，将--remote-config-key参数设置为配置名称。

参考

应用程序参数

有关可用应用程序参数的列表，请参阅下表。 您可以在此处了解有关运行 EWS 设备的更多信息。

参数	说明
--reinfer-api-endpoint	用于连接到 Reinder API 的端点。 与--local-files-prefix互斥。
--local-files-prefix	用于存储已同步电子邮件和存储桶同步状态的路径。 与--reinfer-api-endpoint和REINFER_API_TOKEN互斥。
--remote-config-owner	拥有远程 EWS 设备配置文件的项目。
--remote-config-key	远程 EWS 设备配置文件的名称。
--debug-level	调试级别。 0 = 无调试，1 = 服务调试，2 = 完全调试。 默认值: 1。
--shard-name	分片名称，即要从中提取分片编号的ews-N 。 在 Kubernetes 中运行时，可以将其设置为 Pod 名称。
--total-shards	设备集群中的实例总数。 在 Kubernetes 中运行时，必须设置为与状态副本集中的实例数量相同的值。
--restart-on-unrecoverable-errors	如果启用，则无法恢复的故障将导致整个服务重新启动而不会崩溃。

配置参数

有关可用配置参数的列表，请参阅下表。 您可以在此处了解有关写入 EWS 设备配置文件的更多信息。

名称	说明
host	Exchange 服务器主机。 可以由REINFER_EWS_HOST环境变量覆盖。
port	Exchange 服务器端口。 默认值：80。可以由REINFER_EWS_PORT环境变量覆盖。
auth_type	仅允许“ntlm”。
auth_user	Exchange 服务器用户。 可以由REINFER_EWS_AUTH_USER环境变量覆盖。
auth_password	Exchange 服务器密码。 可以由REINFER_EWS_AUTH_PASS环境变量覆盖。
access_type	访问类型：“委派”或“模拟”。默认值: "delegate"。可以由REINFER_EWS_ACCESS_TYPE环境变量覆盖。
ews_ssl_verify	如果设置为 "false"，则不会验证证书。 默认值: "true"。
poll_frequency	批次之间的等待时间 (以秒为单位)。 默认值: 15。
poll_message_sleep	批处理中各电子邮件之间的等待时间 (以秒为单位)。 默认值: 0.1。
max_concurrent_uploads	上传到 Communications Mining 的并发数量，介于 0 到 32 之间。 默认值: 8。
emails_per_folder	每批从每个文件夹中获取的最大电子邮件数，介于 1 到 100,000 之间。 默认值: 2520。 如果文件夹非常大，则此设置允许设备在所有文件夹上均匀地处理进度。
reinfer_batch_size	每批要获取的电子邮件数量，介于 1 到 1000 之间。 默认值: 80。
mailboxes	要提取的邮箱列表。 有关如何配置邮箱的说明，请参阅此处。
audit_email	如果已为设备配置远程配置，则每当更新配置时，Communications Mining 都会向该地址发送电子邮件。 默认值: 无。
ews_ssl_ciphers	让 EWS 设备使用特定密码。 密码应为OpenSSL 密码列表格式的字符串。 默认值: 无。