ixp
latest
false
UiPath logo, featuring letters U and I in white

Communications Mining 用户指南

上次更新日期 2025年10月20日

注释

Communications Mining™ 中的每条消息都由 API 中的单个注释对象表示。因此，可以将它们视为等效。开发者文档和 API 将主要引用comments ，而用户指南和 Communications Mining 用户界面主要引用messages 。
将数据上传到 Communications Mining 或从 Communications Mining 获取数据时，了解如何将不同类型的数据（例如电子邮件或支持工单）表示为注释非常重要。 本页说明如何将数据建模为 Communications Mining comments ，以准备上传，以及如何理解从 Communications Mining 中获取的数据。
根据电子邮件创建的注释示例

根据审核创建的 Communications Mining™ 注释

“概述”部分描述注释对象的整体结构。如果要通过 API 将数据上传到 Communications Mining™，或了解如何处理通过 API 上传到 Communications Mining 的数据，请查看“通过 API 创建的注释”部分。您可以找到每种常用注释类型（电子邮件或支持工单）的详细说明。如果想更好地了解如何处理通过集成上传到 Communications Mining 的数据，请查看“集成创建的注释”部分。最后，有关可用注释对象字段的完整列表，请查看参考部分。

概述

Communications Mining™ 可处理各种类型的文本数据，例如电子邮件、调查响应、支持工单或客户评论。这些类型的数据的共同点是，它们都由通信单元（电子邮件、调查回复、支持工单、客户评论）组成。例如，在 Communications Mining 中，单个消息表示为注释。

无论注释代表哪种通信单位，它都会始终保持以下基本结构：

{
  "id": <UNIQUE ID>,
  "timestamp": <TIMESTAMP>,
  "messages": [
    {
      "body": { "text": <TEXT> },
      ...
    }
  ],
  "user_properties": { ... },
}{
  "id": <UNIQUE ID>,
  "timestamp": <TIMESTAMP>,
  "messages": [
    {
      "body": { "text": <TEXT> },
      ...
    }
  ],
  "user_properties": { ... },
}

如前面的代码片段所示，除了实际的文本段，注释还总是有一个 ID 和一个时间戳。在包含消息的页面中，该 ID 必须唯一。时间戳用于在平台用户界面中按日期进行筛选和排序，并生成基于日期的分析。

除了这些必填字段外，还应根据注释的类型设置其他字段。如果已通过集成将数据上传到 Communications Mining™，则 Communications Mining 会自动填充所有必填字段。请查看以下部分以获取更详细的说明。

通过 API 创建的注释

电子邮件

虽然将电子邮件同步到 Communications Mining™ 的最简单方法是通过Exchange 集成，但如果您自己提取电子邮件，则可以通过 API 同步电子邮件。对于原始电子邮件，请使用sync-raw-emails端点，对于经过处理的电子邮件，请使用sync端点。

同步原始电子邮件时，请按原样提供提取的 MIME 电子邮件标头和电子邮件正文（有关原始电子邮件格式的说明，请查看参考资料）。 Communications Mining 解析标头并清理电子邮件正文。

注意：为简洁起见，以下原始电子邮件示例显示了极少量的标头。将所有提取的标头发送到 Communications Mining，这可能比示例中的标头长得多。
重要提示：

Communications Mining 如何处理原始电子邮件？

  • 在消息对象messages[0]中设置特定于电子邮件的字段
  • 设置thread_id字段和thread_properties对象
  • 通过去除带引号的电子邮件并将签名放入单独的signature字段中，来清理电子邮件正文
  • 使用从电子邮件标头中提取的元数据填充user_properties对象。
如果电子邮件中不存在某个字段，则根本不会在注释中设置该字段（而不是设置为 null 或空值）。 例如，以下示例中的注释不包含BCC:字段。

如果在上传到 Communications Mining 之前使用其他数据丰富电子邮件，则可以在注释的用户属性中提供这些附加数据。

处理后的原始电子邮件如以下处理后的电子邮件示例所示。检查 Communications Mining 创建的其他字段数量。如果要上传已处理的电子邮件，请按照已处理的电子邮件示例中的方式构建这些电子邮件。
电子邮件示例

原始电子邮件
{
  "raw_email": {
    "body": {
      "plain": "Hi Bob,\n\nCould you send me the figures for today?\n\nThanks,\nAlice"
    },
    "headers": {
      "raw": "From: Alice Smith <[email protected]>\nDate: Tue, 3 Aug 2021 10:57:42 +0100\nMessage-ID: <[email protected]>\nSubject: Figures for today\nTo: Bob <[email protected]>\nCc: Joe <[email protected]>"
    }
  },
  "user_properties": {
    "string:Team": "Team XYZ"
  }
}{
  "raw_email": {
    "body": {
      "plain": "Hi Bob,\n\nCould you send me the figures for today?\n\nThanks,\nAlice"
    },
    "headers": {
      "raw": "From: Alice Smith <[email protected]>\nDate: Tue, 3 Aug 2021 10:57:42 +0100\nMessage-ID: <[email protected]>\nSubject: Figures for today\nTo: Bob <[email protected]>\nCc: Joe <[email protected]>"
    }
  },
  "user_properties": {
    "string:Team": "Team XYZ"
  }
}
已处理的电子邮件
{
  "comment": {
    "id": "3c6537373834623562406d61696c2e6578616d706c652e636f6d3e",
    "timestamp": "2021-08-03T09:57:42Z",
    "user_properties": {
      "string:Has Signature": "Yes",
      "string:Sender": "[email protected]",
      "string:Thread": "<[email protected]>",
      "string:Message ID": "<[email protected]>",
      "number:Recipient Count": 2,
      "number:Participant Count": 3,
      "number:Position in Thread": 1,
      "string:Sender Domain": "example.com",
      "string:Team": "Team XYZ"
    },
    "messages": [
      {
        "body": {
          "text": "Hi Bob,\n\nCould you send me the figures for today?"
        },
        "signature": {
          "text": "Thanks,\nAlice"
        },
        "subject": {
          "text": "Figures for today"
        },
        "to": ["\"Bob\" <[email protected]>"],
        "cc": ["\"Joe\" <[email protected]>"],
        "sent_at": "2021-08-03T09:57:42Z",
        "from": "\"Alice Smith\" <[email protected]>"
      }
    ],
    "thread_id": "3c6537373834623562406d61696c2e6578616d706c652e636f6d3e"
  },
  "thread_properties": {
    "duration": null,
    "response_time": null,
    "num_messages": 1,
    "num_participants": 3,
    "first_sender": "[email protected]",
    "thread_position": 0
  }
}{
  "comment": {
    "id": "3c6537373834623562406d61696c2e6578616d706c652e636f6d3e",
    "timestamp": "2021-08-03T09:57:42Z",
    "user_properties": {
      "string:Has Signature": "Yes",
      "string:Sender": "[email protected]",
      "string:Thread": "<[email protected]>",
      "string:Message ID": "<[email protected]>",
      "number:Recipient Count": 2,
      "number:Participant Count": 3,
      "number:Position in Thread": 1,
      "string:Sender Domain": "example.com",
      "string:Team": "Team XYZ"
    },
    "messages": [
      {
        "body": {
          "text": "Hi Bob,\n\nCould you send me the figures for today?"
        },
        "signature": {
          "text": "Thanks,\nAlice"
        },
        "subject": {
          "text": "Figures for today"
        },
        "to": ["\"Bob\" <[email protected]>"],
        "cc": ["\"Joe\" <[email protected]>"],
        "sent_at": "2021-08-03T09:57:42Z",
        "from": "\"Alice Smith\" <[email protected]>"
      }
    ],
    "thread_id": "3c6537373834623562406d61696c2e6578616d706c652e636f6d3e"
  },
  "thread_properties": {
    "duration": null,
    "response_time": null,
    "num_messages": 1,
    "num_participants": 3,
    "first_sender": "[email protected]",
    "thread_position": 0
  }
}

线程属性

以下线程属性可用。

名称说明
thread_position注释在会话中的位置，通过按timestamp对注释进行排序来计算。 从0开始。
num_messages会话中的注释数量。
num_participants会话中唯一参与者（发件人、收件人、抄送、密件抄送）总数。
first_sender会话中第一个注释的发件人。
duration会话中第一个注释与最后一个注释的timestamps之间的差异 (以秒为单位)。 如果 ，则系统会设置为nullnum_messages

是 1（即 线程仅包含 1 个注释）。

注意：注释的timestamp对应于相应原始电子邮件的sent_at字段。
response_time会话中第一个注释与会话中第一个响应之间的差异 (以秒为单位)。 会话中的第一个响应是发件人不是first_sender的最早注释。 如果会话中没有任何响应（即会话中的所有电子邮件都来自同一发件人），则设置为null 。

每次将新注释添加到平台时，都会更新相应线程的线程属性。

注意：除了thread_position之外，会话中每条注释的所有属性都相同。

支持票证

除正文外，通过表单提交的典型支持工单还可能包含主题、发件人信息（例如姓名或电子邮件地址）以及其他可以上传的结构化数据（例如工单主题）。作为注释的用户属性的一部分。

以下示例显示了如何将支持工单格式化为 Communications Mining™ 注释，以及该注释在平台的用户界面中的显示方式。您的用户属性可能会因您收集的数据而异。
支持工单示例

{
  "id": "dbcb03ad",
  "timestamp": "2020-02-26T16:09:00Z",
  "messages": [
    {
      "body": {
        "text": "Hi Support Team\n\nPlease could you look into my broadband service network status. I don't have any signal."
      },
      "subject": {
        "text": "Network Outage for over 24 hours - Customer account number 1234567"
      },
      "from": "[email protected]"
    }
  ],
  "user_properties": {
    "string:Customer Name": "Alice Smith",
    "string:Source": "Support Form",
    "string:Topic": "Broadband"
  }
}{
  "id": "dbcb03ad",
  "timestamp": "2020-02-26T16:09:00Z",
  "messages": [
    {
      "body": {
        "text": "Hi Support Team\n\nPlease could you look into my broadband service network status. I don't have any signal."
      },
      "subject": {
        "text": "Network Outage for over 24 hours - Customer account number 1234567"
      },
      "from": "[email protected]"
    }
  ],
  "user_properties": {
    "string:Customer Name": "Alice Smith",
    "string:Source": "Support Form",
    "string:Topic": "Broadband"
  }
}

集成创建的注释

电子邮件 (Microsoft Exchange)

通过Exchange 集成提取到 Communications Mining 的 Microsoft Exchange 电子邮件，会像原始电子邮件一样自动转换为注释对象。

附件和附件内容

注释可能已附加文件。 如果注释包含附件，则attachments字段包含有关附件的元数据：
```json
{
    "id": "3c484531505230324d423",
    "attachments": [
        {
            "name": "account-statement.pdf",
            "size": 49078,
            "content_type": "application/pdf",
        }
    ],
    // other comment fields omitted
    ...
},
``````json
{
    "id": "3c484531505230324d423",
    "attachments": [
        {
            "name": "account-statement.pdf",
            "size": 49078,
            "content_type": "application/pdf",
        }
    ],
    // other comment fields omitted
    ...
},
```
此外，您还可以下载附件的内容。 下载附件内容后将返回attachment_reference字段： 
```json
{
    "id": "3c484531505230324d423",
    "attachments": [
        {
            "name": "account-statement.pdf",
            "size": 49078,
            "content_type": "application/pdf",
            "attachment_reference": "CjQSEIExTHEqtdntoxz2WtbZDNEiIIVqcP1Sfx2L4epyRQDasa1RSODvheQ3bvLhj3L-_81G"
        }
    ],
    // other comment fields omitted
    ...
},
``````json
{
    "id": "3c484531505230324d423",
    "attachments": [
        {
            "name": "account-statement.pdf",
            "size": 49078,
            "content_type": "application/pdf",
            "attachment_reference": "CjQSEIExTHEqtdntoxz2WtbZDNEiIIVqcP1Sfx2L4epyRQDasa1RSODvheQ3bvLhj3L-_81G"
        }
    ],
    // other comment fields omitted
    ...
},
```
使用attachment_reference从[附件 API](#FIXME) 中检索二进制文件内容。对于上一个示例，您获取以下 URL：https://cloud.uipath.com/<organisation>/<tenant>/reinfer_/api/v1/attachments/CjQSEIExTHEqtdntoxz2WtbZDNEiIIIVqcP1Sfx2L4epyRQDasa1RSODvheQ3bvLhj3L-_81G。

查看 [API 参考](#FIXME)，详细了解此类请求。

如果附件对象没有attachment_reference属性，您将无法下载附件的内容。 这可能是因为：
  • Communications Mining™ 未收到附件的内容。
  • 附件内容超过了上传到 Communications Mining 的大小限制。
  • Communications Mining 在支持文件内容之前处理了附件。

在附件页面了解有关附件内容的更多信息。

参考

注释

查看下表中可用注释字段的列表。如果您不熟悉 Communications Mining™ 注释对象，请查看概述。

名称类型必填说明
id字符串是在源中唯一标识注释。 不超过 1024 个字符的任何十六进制字符串都有效（符合 /[0-9a-f]{1,1024}/）。
timestamp字符串是指明注释创建时间的 ISO-8601 时间戳。 如果时间戳未指定时区，则采用 UTC。 时间戳必须在 1950-01-01T00:00:00Z 到 2049-12-31T23:59:59Z（含）范围内。
messagesarray<Message>是包含零条或一条消息的数组。
user_propertiesmap<string, string | number>否适用于注释的任何用户定义的元数据。 有两种可能的类型： string和number 。 用户属性键的格式为“类型:名称”，例如 “字符串：域名”或“数字：星级”。 用户属性名称可由字母、数字、空格和下划线组成，最多可包含 32 个字符 (符合 /\w([\w ]{0,30}\w)?/)。 该值必须是字符串或数字，具体取决于用户属性的类型。
thread_id字符串否唯一标识电子邮件会话的 ID。 不超过 1024 个字符的任何十六进制字符串都有效（符合 /[0-9a-f]{1,1024}/）。
uid字符串由 Communications Mining™ 设置合并的来源和注释 ID，格式为source_id.comment_id 。 您不应直接设置此字段，因为它是 Communications Mining 为上传的注释自动生成的。
created_at字符串由 Communications Mining 设置ISO-8601 时间戳，其约束与timestamp字段相同。 您不应直接设置此字段，因为它是创建注释时由 Communications Mining 自动生成的。
updated_at字符串由 Communications Mining 设置ISO-8601 时间戳，其约束与timestamp字段相同。 您不应直接设置此字段，因为它是在更新注释时由 Communications Mining 自动生成的。
attachmentsarray<Attachment>否由零个或多个附件组成的数组。 附件表示附加到注释的文件。
名称类型必填说明
name字符串是附件的文件名。
size数字是附件文件内容的大小 (以字节为单位)。
content_type字符串是附件的[媒体类型](https://en.wikipedia.org/wiki/Media_type)。有关可能值的列表，请查看 [IANA 媒体类型](https://www.iana.org/assignments/Media-types/Media-types.xhtml) 列表。
attachment_reference字符串否用于从 [附件 API] 检索二进制文件内容 (#FIXME)

其中Message具有以下格式：

名称类型必填说明
body内容是包含消息主体文本的对象。
subject内容否包含消息主题的对象。
signature内容否包含消息签名的对象。
from字符串否消息发件人。
toarray<string>否主要收件人数组。
ccarray<string>否副本收件人数组。
bccarray<string>否密件副本收件人数组。
sent_at字符串否指示消息创建时间的 ISO-8601 时间戳。 如果时间戳未指定时区，则采用 UTC。
language字符串否消息的原始语言。 如果提供了此项，则应为“内容” 字段同时提供text和translated_from 。

其中Content具有以下格式：

名称类型必填说明
text字符串是如果已提供language （而非来源的language ），则这应是内容的翻译文本。 否则，应使用收集时的原始语言；如果源的language中没有该内容，并且源已将should_translate设置为true ，则对其进行翻译。 最多支持 65536 个字符。
translated_from字符串否如果提供了language （而非来源的language ），则应提供内容的原始文本。 在未提供language的情况下提供此字段将导致发生错误。 最多 65536 个字符。

原始电子邮件

查看下表以获取可用的原始电子邮件字段列表。

名称类型必填说明
headers标头是包含电子邮件标头的对象。
body正文是包含电子邮件正文的对象。

其中Headers具有以下格式：

名称类型必填说明
raw字符串否需要raw和parsed 。 原始电子邮件标头，以单个字符串形式提供，每个标头占自己的行。
parsed映射<字符串，字符串|数组 <string>>否
需要raw和parsed 。 已解析的电子邮件标头，作为具有字符串键和字符串或数组<string>值的对象提供。

每个密钥必须是 ASCII，并代表一个电子邮件标头。 值字符串可以是任何有效的 UTF-8 字符串。

值列表将使用,连接，然后再设置为单个标头值。 如果您需要重复的标头键，请改用raw 。

其中Body具有以下格式：

名称类型必填说明
plain字符串否至少需要plain和html 。 电子邮件的明文内容。 最多 65536 个字符。
html字符串否至少需要plain和html 。 电子邮件的 HTML 内容。

此页面有帮助吗？

支持与服务
获取您需要的帮助
UiPath Academy
了解 RPA - 自动化课程
UiPath 论坛
UiPath Community 论坛
Uipath Logo
信任与安全
使用条款
隐私策略
Cookie 政策
© 2005-2025 UiPath。保留所有权利。