Integração auto-hospedada do Exchange

O aplicativo de sincronização do Exchange é entregue como uma imagem do Docker. As seções abaixo explicam como configurar e implantar o dispositivo.

Configuração

Como o Aplicativo de Sincronização do Exchange requer a presença de um arquivo de configuração JSON na inicialização, 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 o Aplicativo de Sincronização do Exchange.

OAuth 2.0

Se você estiver usando o tipo de autenticação OAuth 2.0, poderá usar a API do Graph ou a API do EWS. Ambos permitem que você autentique com segredo do cliente ou com certificado de cliente.

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

API do gráfico com segredo do cliente

{
  "microsoft_api": "graph",
  "auth_oauth_authority": "https://login.microsoftonline.com/<tenant_id>/",
  "auth_oauth_client_id": "<client_id>",
  "auth_oauth_client_secret": "<client_secret>",
  "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"
    }
  }
}

API do Graph com certificado de cliente

{
  "microsoft_api": "graph",
  "auth_oauth_authority": "https://login.microsoftonline.com/<tenant_id>/",
  "auth_oauth_client_id": "<client_id>",
  "auth_oauth_client_credential_private_key": "<private_key>",
  "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"
    }
  }
}

API do EWS 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"
    }
  }
}

API do EWS com certificado 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_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

Se você estiver usando a autenticação NTLM, ela só pode ser usada com a API do EWS.

{
  "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. Para obter uma descrição desses parâmetros e seus valores permitidos, consulte a referência de configuração.

Em seguida, forneça a senha do usuário do serviço para o Exchange Sync App como uma variável de ambiente REINFER_EWS_AUTH_PASS . Para obter mais detalhes, consulte a seção Implantação .

A lista completa de variáveis de ambiente que você pode definir para substituir valores na configuração é a seguinte:

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 email nos buckets do Communications Mining™. Assim como outros recursos do Communications Mining, um bucket é criado em um projeto, o que permite controlar o acesso ao bucket.

Observação: para ler de um bucket, carregar em um bucket ou gerenciar buckets, você deve ter atribuído as respectivas permissões no projeto em que o bucket está.

Implantação

Você pode implantar o aplicativo de sincronização do Exchange com o Kubernetes ou com o Docker.

A implantação com o Kubernetes permite que você execute várias instâncias do aplicativo de sincronização do Exchange, 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êineres. Esta seção explica como implantar o aplicativo de sincronização do Exchange usando o Kubernetes.

Requisitos

• conhecimento básico do Kubernetes. Para começar com o Kubernetes, acesse Implantar no Kubernetes.
• ter o kubectl instalado.

kind: StatefulSet
metadata:
  name: uipath-exchange-sync-app
  labels:
    app: uipath-exchange-sync-app
spec:
  podManagementPolicy: Parallel
  replicas: 1
  selector:
    matchLabels:
      app: uipath-exchange-sync-app
  serviceName: uipath-exchange-sync-app
  template:
    metadata:
      labels:
        app: uipath-exchange-sync-app
      name: uipath-exchange-sync-app
    spec:
      containers:
        - args:
            - "uipath-exchange-sync-app"
            - "--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_exchange_sync_config"
            - name: REINFER_API_TOKEN
              valueFrom:
                secretKeyRef:
                  key: reinfer-api-token
                  name: reinfer-credentials
            # Only needed when using EWS API
            - 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:TAG"
          name: uipath-exchange-sync-app
          resources:
            requests:
              cpu: 0.05
              memory: 128Mi
          volumeMounts:
            - mountPath: /mnt/config
              name: config-vol
      volumes:
        - configMap:
            name: exchange-sync-config
            items:
              - key: example_exchange_sync_config
                path: example_exchange_sync_config
          name: config-vol

Antes de poder implantar o Aplicativo de Sincronização do Exchange usando esse arquivo YAML, há algumas etapas adicionais que você precisa realizar:

1. Substitua <mydomain>.reinfer.io por seu ponto de extremidade da API do tenant.
2. 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>

   Observação:

   • Para evitar armazenar 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 dos segredos do Kubernetes.
   • O segredo ews-auth-pass só é necessário ao usar a API EWS.
3. Para carregar a configuração do dispositivo a partir de um arquivo local, monte esse arquivo no pod , armazenando os dados em um ConfigMap do Kubernetes e montando o ConfigMap como um volume.
4. Crie o ConfigMap da seguinte forma:

   kubectl create configmap exchange-sync-config \
     --from-file=example_exchange_sync_config=your-exchange-sync-config.json

   Observação: como alternativa a armazenar o arquivo de configuração localmente, você pode carregá-lo no Communications Mining e deixar o Aplicativo de Sincronização do Exchange o buscar por meio da API do Communications Mining. Isso é descrito Configuração do repositório no Communications Mining. Se os arquivos de configuração local e remota forem especificados, o dispositivo usará o arquivo de configuração local.

Agora você pode criar seu StatefulSet e verificar se tudo está funcionando da seguinte maneira:

kubectl apply -f uipath-exchange-sync.yaml
kubectl get sts

Com o Docker

Como alternativa, você pode executar o Aplicativo de Sincronização do Exchange no Docker. O seguinte comando inicia o dispositivo com os mesmos parâmetros que são usados na seção Kubernetes :

EWS_CONFIG_DIR="location_of_your_self-hosted_appliance_config_directory"
REINFER_API_TOKEN="YOUR API TOKEN"
TAG=latest

sudo docker run \
  -v $EWS_CONFIG_DIR:/mnt/config \
  --env REINFER_EWS_CONFIG=/mnt/config/config.json \
  --env REINFER_API_TOKEN=$REINFER_API_TOKEN \
  eu.gcr.io/reinfer-gcr/ews:$TAG reinfer-ews \
  --reinfer-api-endpoint https://cloud.uipath.com/YourOrganizationName/TenantName/reinfer_/api \
  &> ews_$(date -Iseconds).log

• Substitua <mydomain>.reinfer.io por seu ponto de extremidade da API do tenant.
• Substitua your_exchange_sync_config.json pelo nome do seu arquivo JSON de configuração do Aplicativo de Sincronização do Exchange.

O aplicativo de sincronização do Exchange é executado sincronizando continuamente e-mails na plataforma Communications Mining. Se você parar e iniciá-lo novamente, ele coleta a partir do último estado de sincronização do bucket armazenado.

Com o Docker (armazenamento local)

O aplicativo de sincronização do Exchange pode salvar emails extraídos localmente em vez de enviá-los para a plataforma Communications Mining™ por meio do seguinte:

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

Visão geral

• O Exchange Sync App 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 Aplicativo de Sincronização do Exchange salva o estado de sincronização em $EWS_LOCAL_DIR/state. Se você parar e iniciá-lo novamente, ele retoma o último estado de sincronização armazenado.
• O Aplicativo de Sincronização do Exchange salva dados em $EWS_LOCAL_DIR/data.

Com o Docker (Armazenamento de Blobs do Azure)

O aplicativo de sincronização do Exchange pode salvar emails extraídos no armazenamento de Blobs do Azure em vez de enviá-los para a plataforma Communications Mining™ por meio do seguinte:

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_exchange_sync_config.json \
  eu.gcr.io/reinfer-gcr/ews:$TAG \
  --private-file-prefix az://$AZ_STORAGE_ACCOUNT_NAME/$AZ_CONTAINER_NAME \
  &> ews_$(date -Iseconds).log

Visão geral

• Você deve fornecer o caminho para o arquivo de configuração definindo a variável de ambiente $REINFER_EWS_CONFIG .
• O Aplicativo de sincronização do Exchange é autenticado no Armazenamento de Blobs do Azure usando um dos métodos DefaultAzureCredential. Certifique-se de usar um método que seja conveniente para você. Independentemente do método usado, certifique-se de conceder a função Contribuinte de Dados de Blob de Armazenamento ao Aplicativo de Sincronização do Exchange.
• O Aplicativo de Sincronização do Exchange salva o estado de sincronização em az://$AZ_STORAGE_ACCOUNT_NAME/$AZ_CONTAINER_NAME/state. Se você parar e iniciá-lo novamente, ele retoma o último estado de sincronização armazenado.
• O Aplicativo de Sincronização do Exchange salva 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 você fez se seguiu o guia de implantação do aplicativo de sincronização do Exchange, em vez disso você pode gerenciar o arquivo de configuração no Communications Mining™. Observe que, se os arquivos de configuração local e remota forem especificados, o dispositivo utilizará o arquivo de configuração local por padrão.

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_exchange_sync_config.json' \
  -XPUT https://<mydomain>.reinfer.io/api/v1/appliance-configs/<project-name>/<config-name>

Para visualizar 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

A tabela a seguir contém uma lista de parâmetros de aplicativo disponíveis. Para saber mais sobre como executar o Aplicativo de Sincronização do Exchange, verifique a seção Implantação .

Parâmetro	Description
--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 que tem o arquivo de configuração remoto do Aplicativo de Sincronização do Exchange.
--remote-config-key	Nome do arquivo de configuração remoto do Aplicativo de Sincronização do Exchange.
--debug-level	Nível de depuração, onde: 0 significa que não há depuração. 1 significa depuração do serviço. 2 significa depuração completa. O valor padrão é 1.
--shard-name	Nome do fragmento, que é uipath-exchange-sync-app-N, do qual extrair o número do fragmento. Ao executar no Kubernetes, você pode defini-lo para o nome do pod.
--total-shards	O número total de instâncias no cluster da ferramenta. Ao executar no Kubernetes, o parâmetro deve ser definido com o mesmo valor do número de instâncias no StatefulSet.
--restart-on-unrecoverable-errors	Se habilitadas, as falhas irrecuperáveis farão com que todo o serviço seja reiniciado sem falhar.

Parâmetros de configuração

A tabela a seguir contém uma lista dos parâmetros de configuração disponíveis. Para saber mais sobre como gravar o arquivo de configuração do Aplicativo de sincronização do Exchange, consulte a seção Configuração .

Name	Description
host	Usado apenas com a API EWS. Host do Exchange Server. Pode ser substituído pela variável de ambiente REINFER_EWS_HOST .
port	Usado apenas com a API EWS. Porta do Exchange Server. O padrão é 80. Você pode substituí-la pela variável de ambiente REINFER_EWS_PORT .
auth_type	Usado apenas com a API EWS. Permitido apenas ntlm .
auth_user	Usado apenas com a API EWS. Usuário do Exchange Server. Você pode substituí-la pela variável de ambiente REINFER_EWS_AUTH_USER .
auth_password	Usado apenas com a API EWS. Senha do servidor do Exchange. Você pode substituí-la pela variável de ambiente REINFER_EWS_AUTH_PASS .
access_type	Usado apenas com a API EWS. O tipo de acesso pode ser delegate ou impersonation. O padrão é delegate. Você pode substituí-la pela variável de ambiente REINFER_EWS_ACCESS_TYPE .
ews_ssl_verify	Usado apenas com a API EWS. Se estiver definido como false, não verificará certificados. O padrão é true.
poll_frequency	O tempo de espera entre lotes, em segundos. O padrão é 15.
poll_message_sleep	O tempo de espera entre e-mails individuais em um lote, em segundos. O padrão é 0.1.
max_concurrent_uploads	Número de uploads simultâneos para o Communications Mining, entre 0 e 32. O padrão é 8.
emails_per_folder	Número máximo de emails a serem buscados de cada pasta por lote, entre 1 e 100.000. O padrão é 2520. Essa configuração permite que o Aplicativo de Sincronização do Exchange faça progresso em todas as pastas uniformemente caso haja uma pasta muito grande.
reinfer_batch_size	Quantos emails buscar por lote, entre 1 e 1000. O padrão é 80.
mailboxes	Lista de caixas de correio a serem buscadas. Para obter mais detalhes sobre como configurar as caixas de correio, consulte a seção Configuração .
audit_email	Se você tiver configurado o dispositivo com uma configuração remota, o Communications Mining envia um e-mail para esse endereço sempre que a configuração for atualizada. O padrão é None.
ews_ssl_ciphers	Usado apenas com a API do EWS. Faça com que o Aplicativo de Sincronização do Exchange use cifras específicas. As cifras devem ser uma string no formato de lista de cifras OpenSSL. O padrão é None.