セルフホステッド 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 (NT LAN Manager)

{
  "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 Server のユーザー
REINFER_EWS_AUTH_PASS	Exchange サーバーのパスワード
REINFER_EWS_ACCESS_TYPE	アクセスの種類: "委任" または "偽装"
REINFER_EWS_HOST	Exchange サーバーのホスト
REINFER_EWS_PORT	Exchange サーバーのポート

メールボックスの構成

構成で 1 つ以上のメールボックスを指定できます。 メールボックスごとに、メールボックス アドレスを指定し、次のパラメーターを指定する必要があります。

名前	説明
bucket.owner	メールボックスを同期するバケットのプロジェクトです。
bucket.name	メールボックスを同期するバケットの名前です。
start_from	最終同期時刻 ("バケット") から開始するか、最終同期時刻を無視して常に start_timestamp ("config") から開始するかを選択します。通常の操作では「バケット」に設定する必要がありますが、デバッグ時には「config」が役立つ場合があります。
start_timestamp	メールの同期を開始するタイムスタンプです。 設定しない場合、すべてのメールが同期されます。

この構成では、ポーリング頻度やバッチ サイズなど、いくつかの設定に既定値が使用されます。 構成をさらにカスタマイズするには、 構成リファレンスを参照してください。

バケット

Exchange 連携は、メールの生データを Communications Mining バケットに同期 します。 他の Communications Mining リソースと同様に、 バケットはプロジェクト 内に作成され、それによってバケットへのアクセスを制御できます。 バケットからの読み取り、バケットへのアップロード、またはバケットの管理を行うには、バケットが存在するプロジェクト内の それぞれの権限 が必要です。

デプロイ

EWS アプライアンスは、Kubernetes または Docker を使用してデプロイできます。

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>

最後に、ローカルファイルからアプライアンス構成をロードするため、そのファイルをポッドにマウントする必要があります。 そのためには 、データを 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

ドッカーを使用

または、EWS アプライアンスを Docker で実行することもできます。 次のコマンドは、「 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 Storage) を使用する

EWS アプライアンスは、抽出されたメールを、Communications Mining プラットフォームにプッシュする代わりに Azure BLOB Storage に保存できます。

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 環境変数を設定して構成へのパスを指定する必要があります。

• アプライアンスは、DefaultAzureCredential メソッドの 1 つを使用して Azure BLOB Storage に対して認証を行います。都合の良い方法を使用してください。使用する方法に関係なく、アプライアンスに「Storage Blob Data Contributor」ロールを付与してください。

• アプライアンスは同期状態を az://$AZ_STORAGE_ACCOUNT_NAME/$AZ_CONTAINER_NAME/stateに保存します。 停止して再度開始すると、最後に保存された同期状態から取得されます。
• アプライアンスは az://$AZ_STORAGE_ACCOUNT_NAME/$AZ_CONTAINER_NAME/dataにデータを保存します。

Communications Mining でのストアの構成

EWS アプライアンスの展開ガイドに従った場合のようにローカル構成ファイルをアプライアンスに提供する代わりに、Communications Mining で構成ファイルを管理できます。ローカル構成ファイルとリモート構成ファイルの両方が指定されている場合、アプライアンスはデフォルトでローカル構成ファイルを使用することに注意してください。

まず、 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	Reinfer 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 で実行する場合は、ポッド名に設定できます。
--total-shards	アプライアンス クラスター内のインスタンスの合計数。 Kubernetes で実行する場合は、StatefulSet 内のインスタンス数と同じ値に設定する必要があります。
--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	アクセスの種類: "委任" または "偽装"。既定値は "委任" です。 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 暗号リスト形式の文字列である必要があります。 デフォルト: なし。