注释

Communications Mining API 中的注释对象及其与用户界面中的消息的关系。

Each message in Communications Mining™ is represented by a single comment object in the API. As a result, they can be considered equivalent. The developer documentation and API will refer primarily to comments, whilst the user guide and the Communications Mining UI refer primarily to 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": { ... },
}

As shown in the previous code snippet, in addition to the actual piece of text, a comment always has an ID and a timestamp. The ID needs to be unique within the containing message. The timestamp is used in the platform UI to filter and sort by date, and to generate date-based analytics.

除了这些必填字段外，还应根据注释的类型设置其他字段。如果已通过集成将数据上传到 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 <[e-mail]>\nDate: Tue, 3 Aug 2021 10:57:42 +0100\nMessage-ID: <[e-mail]>\nSubject: Figures for today\nTo: Bob <[e-mail]>\nCc: Joe <[e-mail]>"
    }
  },
  "user_properties": {
    "string:Team": "Team XYZ"
  }
}

已处理的电子邮件

{
  "comment": {
    "id": "3c6537373834623562406d61696c2e6578616d706c652e636f6d3e",
    "timestamp": "2021-08-03T09:57:42Z",
    "user_properties": {
      "string:Has Signature": "Yes",
      "string:Sender": "[e-mail]",
      "string:Thread": "<[e-mail]>",
      "string:Message ID": "<[e-mail]>",
      "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\" <[e-mail]>"],
        "cc": ["\"Joe\" <[e-mail]>"],
        "sent_at": "2021-08-03T09:57:42Z",
        "from": "\"Alice Smith\" <[e-mail]>"
      }
    ],
    "thread_id": "3c6537373834623562406d61696c2e6578616d706c652e636f6d3e"
  },
  "thread_properties": {
    "duration": null,
    "response_time": null,
    "num_messages": 1,
    "num_participants": 3,
    "first_sender": "[e-mail]",
    "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": "[e-mail]"
    }
  ],
  "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 ... },

此外，您还可以下载附件的内容。 下载附件内容后将返回attachment_reference字段：

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 检索二进制文件内容。对于之前的示例，您可获取以下 URL： https://cloud.uipath.com/ / /reinfer_/api/v1/attachments/CjQSEIExTHEqtdntoxz2WtbZDNEiIIVqcP1Sfx2L4epyRQDasa1RSODvheQ3bvLhj3L-_81G。

有关此类请求的更多详细信息，请查看 API 参考。

如果附件对象没有attachment_reference属性，您将无法下载附件的内容。 这可能是因为：

• Communications Mining™ 未收到附件的内容。
• 附件内容超过了上传到 Communications Mining 的大小限制。
• Communications Mining 在支持文件内容之前处理了附件。

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

参考

注释

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

名称	类型	必填	说明
id	字符串	是	在源中唯一标识注释。任何不超过 1024 个字符的十六进制字符串都是有效的（符合/[0-9a-f]{1,1024}/ ）。
timestamp	字符串	是	An ISO-8601 timestamp indicating when the comment was created. If the timestamp does not specify a timezone, UTC will be assumed. The timestamp must be in the range 1950-01-01T00:00:00Z to 2049-12-31T23:59:59Z inclusive.
messages	array<Message>	是	包含零条或一条消息的数组。
user_properties	map<string, string | number>	否	Any user-defined metadata that applies to the comment. There are two possible types: string and number. The key of a user property has the format "type:name", eg. "string:Domain Name" or "number:Star Rating". The user property name may consist of letters, numbers, spaces, and underscores, and may contain up to 32 characters (conforms to /\w([\w ]{0,30}\w)?/). The value must be a string or a number depending on the type of the user property.
thread_id	字符串	否	唯一标识电子邮件会话的 ID。任何不超过 1024 个字符的十六进制字符串都是有效的（符合/[0-9a-f]{1,1024}/ ）。
uid	字符串	由 Communications Mining™ 设置	合并的来源和注释 ID，格式为source_id.comment_id 。 您不应直接设置此字段，因为它是 Communications Mining 为上传的注释自动生成的。
created_at	字符串	由 Communications Mining 设置	An ISO-8601 timestamp with the same constraints as the timestamp field. You should not be setting this field directly as it's automatically generated by Communications Mining when the comment is created.
updated_at	字符串	由 Communications Mining 设置	An ISO-8601 timestamp with the same constraints as the timestamp field. You should not be setting this field directly as it's automatically generated by Communications Mining when the comment is updated.
attachments	array<Attachment>	否	由零个或多个附件组成的数组。 附件表示附加到注释的文件。

名称	类型	必填	说明
name	字符串	是	附件的文件名。
size	数字	是	附件文件内容的大小 (以字节为单位)。
content_type	字符串	是	附件的媒体文件类型。有关可能值的列表，请查看IANA 媒体类型列表。
attachment_reference	字符串	否	用于从附件 API 检索二进制文件内容

其中Message具有以下格式：

名称	类型	必填	说明
body	内容	是	包含消息主体文本的对象。
subject	内容	否	包含消息主题的对象。
signature	内容	否	包含消息签名的对象。
from	字符串	否	消息发件人。
to	array<string>	否	主要收件人数组。
cc	array<string>	否	副本收件人数组。
bcc	array<string>	否	密件副本收件人数组。
sent_at	字符串	否	An ISO-8601 timestamp indicating when the message was created. If the timestamp does not specify a timezone, UTC will be assumed.
language	字符串	否	消息的原始语言。如果提供了此项，则应为“内容”字段同时提供text和translated_from 。

其中Content具有以下格式：

名称	类型	必填	说明
text	字符串	是	If language (other than the source's language) has been supplied, this should be the translated text of the content. Otherwise, it should be in the original language it was collected; it will be translated if not in the source's language and the source has should_translate set to true. Maximum 65536 characters.
translated_from	字符串	否	If language (other than the source's language) has been supplied, this should be the original text of the content. Supplying this field without having supplied a language will result in an error. At most 65536 characters.

原始电子邮件

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

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

其中Headers具有以下格式：

名称	类型	必填	说明
raw	字符串	否	需要raw和parsed 。 原始电子邮件标头，以单个字符串形式提供，每个标头占自己的行。
parsed	map<string, string | array<string>>	否	One of raw and parsed is required. The parsed email headers, given as an object with string keys and string or array<string> values. Each key must be ASCII, and represents one email header. Value strings may be any valid UTF-8. Lists of values will be concatenated with , before being set as a single header value. If you require duplicate header keys, please use raw instead.

其中Body具有以下格式：

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