注释

添加或更新注释

/api/v1/sources/<project>/<source_name>/sync

所需权限：编辑消息

重要提示：

可计费操作

对于每个创建的评论或每个更新的评论 (依据其唯一 ID)，如果其文本已被修改，您需支付 1 个 AI Unit 的费用。

• 重击

  curl -X POST 'https://<my_api_endpoint>/api/v1/sources/<project>/<source>/sync' \
      -H "Authorization: Bearer $REINFER_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
    "comments": [
      {
        "id": "0123456789abcdef",
        "messages": [
          {
            "body": {
              "text": "Alice,\n\nHere are the figures for today.\n\nRegards,\nBob"
            },
            "from": "[e-mail]",
            "sent_at": "2011-12-11T11:05:10.000000+00:00",
            "subject": {
              "text": "Today'"'"'s figures"
            },
            "to": [
              "[e-mail]"
            ]
          }
        ],
        "timestamp": "2011-12-11T11:05:10.000000+00:00",
        "user_properties": {
          "string:Recipient Domain": "company.com",
          "string:Sender Domain": "organisation.org"
        }
      },
      {
        "id": "abcdef0123456789",
        "messages": [
          {
            "body": {
              "text": "Hi Bob,\n\nI think these are the wrong numbers - could you check?\n\nThanks again,\nAlice"
            },
            "from": "[e-mail]",
            "sent_at": "2011-12-11T11:18:43.000000+00:00",
            "subject": {
              "text": "Today'"'"'s figures"
            },
            "to": [
              "[e-mail]"
            ]
          }
        ],
        "timestamp": "2011-12-11T11:18:43.000000+00:00",
        "user_properties": {
          "string:Recipient Domain": "organisation.org",
          "string:Sender Domain": "company.com"
        }
      }
    ]
  }'

• 节点

  const request = require("request");
  
  request.post(
    {
      url: "https://<my_api_endpoint>/api/v1/sources/<project>/<source>/sync",
      headers: {
        Authorization: "Bearer " + process.env.REINFER_TOKEN,
      },
      json: true,
      body: {
        comments: [
          {
            id: "0123456789abcdef",
            messages: [
              {
                body: {
                  text: "Alice,\n\nHere are the figures for today.\n\nRegards,\nBob",
                },
                from: "[e-mail]",
                sent_at: "2011-12-11T11:05:10.000000+00:00",
                subject: { text: "Today's figures" },
                to: ["[e-mail]"],
              },
            ],
            timestamp: "2011-12-11T11:05:10.000000+00:00",
            user_properties: {
              "string:Recipient Domain": "company.com",
              "string:Sender Domain": "organisation.org",
            },
          },
          {
            id: "abcdef0123456789",
            messages: [
              {
                body: {
                  text: "Hi Bob,\n\nI think these are the wrong numbers - could you check?\n\nThanks again,\nAlice",
                },
                from: "[e-mail]",
                sent_at: "2011-12-11T11:18:43.000000+00:00",
                subject: { text: "Today's figures" },
                to: ["[e-mail]"],
              },
            ],
            timestamp: "2011-12-11T11:18:43.000000+00:00",
            user_properties: {
              "string:Recipient Domain": "organisation.org",
              "string:Sender Domain": "company.com",
            },
          },
        ],
      },
    },
    function (error, response, json) {
      // digest response
      console.log(JSON.stringify(json, null, 2));
    }
  );

• Python

  import json
  import os
  
  import requests
  
  response = requests.post(
      "https://<my_api_endpoint>/api/v1/sources/<project>/<source>/sync",
      headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
      json={
          "comments": [
              {
                  "id": "0123456789abcdef",
                  "timestamp": "2011-12-11T11:05:10.000000+00:00",
                  "messages": [
                      {
                          "from": "[e-mail]",
                          "to": ["[e-mail]"],
                          "sent_at": "2011-12-11T11:05:10.000000+00:00",
                          "subject": {"text": "Today's figures"},
                          "body": {
                              "text": "Alice,\n\nHere are the figures for today.\n\nRegards,\nBob"
                          },
                      }
                  ],
                  "user_properties": {
                      "string:Sender Domain": "organisation.org",
                      "string:Recipient Domain": "company.com",
                  },
              },
              {
                  "id": "abcdef0123456789",
                  "timestamp": "2011-12-11T11:18:43.000000+00:00",
                  "messages": [
                      {
                          "from": "[e-mail]",
                          "to": ["[e-mail]"],
                          "sent_at": "2011-12-11T11:18:43.000000+00:00",
                          "subject": {"text": "Today's figures"},
                          "body": {
                              "text": "Hi Bob,\n\nI think these are the wrong numbers - could you check?\n\nThanks again,\nAlice"
                          },
                      }
                  ],
                  "user_properties": {
                      "string:Sender Domain": "company.com",
                      "string:Recipient Domain": "organisation.org",
                  },
              },
          ]
      },
  )
  
  print(json.dumps(response.json(), indent=2, sort_keys=True))

• 响应

  {
    "new": 2,
    "status": "ok",
    "unchanged": 0,
    "updated": 0
  }

注释的 ID 在来源中唯一标识该注释。 如果提供的注释 ID 在来源中不存在，则会创建新注释。 否则，系统将更新现有注释。

名称	类型	必填	说明
comments	array<Cmment>	是	最多包含 16384 条注释的批处理，其格式请参阅注释参考。 每个注释的批处理比较大的批处理速度更快。

已分配的常规字段

除非文本发生了重大变化，否则分配的常规字段将保留。 分配的标签永远不会被丢弃。

大型请求

对于大型请求，此端点可能需要更长时间才能响应。 您应该增加客户端超时时间。

添加或更新原始电子邮件中的注释

/api/v1/sources/<project>/<source_name>/sync-raw-emails

所需权限：编辑消息

重要提示：

可计费操作

如果注释的文本已被修改，您将按创建的注释或更新的注释（基于电子邮件的消息 ID）支付 1 个 AI Unit。

• 重击

  curl -X POST 'https://<my_api_endpoint>/api/v1/sources/<project>/<source>/sync-raw-emails' \
      -H "Authorization: Bearer $REINFER_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
    "documents": [
      {
        "raw_email": {
          "body": {
            "plain": "Hi Bob,\n\nCould you send me today'"'"'s figures?\n\nThanks,\nAlice"
          },
          "headers": {
            "parsed": {
              "Date": "Thu, 09 Jan 2020 16:34:45 +0000",
              "From": "[e-mail]",
              "Message-ID": "[e-mail]",
              "References": "<[e-mail]> <[e-mail]>",
              "Subject": "Figures Request",
              "To": "[e-mail]"
            }
          }
        },
        "user_properties": {
          "number:Deal Value": 12000,
          "string:City": "London"
        }
      }
    ],
    "include_comments": true,
    "transform_tag": "name.0.ABCD1234"
  }'

• 节点

  const request = require("request");
  
  request.post(
    {
      url: "https://<my_api_endpoint>/api/v1/sources/<project>/<source>/sync-raw-emails",
      headers: {
        Authorization: "Bearer " + process.env.REINFER_TOKEN,
      },
      json: true,
      body: {
        documents: [
          {
            raw_email: {
              body: {
                plain:
                  "Hi Bob,\n\nCould you send me today's figures?\n\nThanks,\nAlice",
              },
              headers: {
                parsed: {
                  Date: "Thu, 09 Jan 2020 16:34:45 +0000",
                  From: "[e-mail]",
                  "Message-ID": "[e-mail]",
                  References: "<[e-mail]> <[e-mail]>",
                  Subject: "Figures Request",
                  To: "[e-mail]",
                },
              },
            },
            user_properties: {
              "number:Deal Value": 12000,
              "string:City": "London",
            },
          },
        ],
        include_messages: true,
        transform_tag: "name.0.ABCD1234",
      },
    },
    function (error, response, json) {
      // digest response
      console.log(JSON.stringify(json, null, 2));
    }
  );

• Python

  import json
  import os
  
  import requests
  
  response = requests.post(
      "https://<my_api_endpoint>/api/v1/sources/<project>/<source>/sync-raw-emails",
      headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
      json={
          "transform_tag": "name.0.ABCD1234",
          "documents": [
              {
                  "raw_email": {
                      "headers": {
                          "parsed": {
                              "Message-ID": "[e-mail]",
                              "Date": "Thu, 09 Jan 2020 16:34:45 +0000",
                              "Subject": "Figures Request",
                              "From": "[e-mail]",
                              "To": "[e-mail]",
                              "References": "<[e-mail]> <[e-mail]>",
                          }
                      },
                      "body": {
                          "plain": "Hi Bob,\n\nCould you send me today's figures?\n\nThanks,\nAlice"
                      },
                  },
                  "user_properties": {
                      "string:City": "London",
                      "number:Deal Value": 12000,
                  },
              }
          ],
          "include_comments": True,
      },
  )
  
  print(json.dumps(response.json(), indent=2, sort_keys=True))

• 响应

  {
    "comments": [
      {
        "attachments": [],
        "id": "61626364656640636f6d70616e792e636f6d",
        "messages": [
          {
            "body": {
              "text": "Hi Bob,\n\nCould you send me today's figures?"
            },
            "from": "[e-mail]",
            "sent_at": "2020-01-09T16:34:45Z",
            "signature": {
              "text": "Thanks,\nAlice"
            },
            "subject": {
              "text": "Figures Request"
            },
            "to": ["[e-mail]"]
          }
        ],
        "source_id": "c1fb849b855841de",
        "text_format": "plain",
        "thread_id": "3c303132333440636f6d70616e792e636f6d3e",
        "timestamp": "2020-01-09T16:34:45Z",
        "uid": "c1fb849b855841de.61626364656640636f6d70616e792e636f6d",
        "user_properties": {
          "number:Deal Value": 12000,
          "number:Participant Count": 2,
          "number:Position in Thread": 3,
          "number:Recipient Count": 1,
          "string:City": "London",
          "string:Has Signature": "Yes",
          "string:Message ID": "[e-mail]",
          "string:Sender": "[e-mail]",
          "string:Sender Domain": "company.com",
          "string:Thread": "<[e-mail]>"
        }
      }
    ],
    "new": 1,
    "status": "ok",
    "unchanged": 0,
    "updated": 0
  }

每封原始电子邮件都将转换为 Communications Mining 注释。 Communications Mining 将根据电子邮件的“Message-ID”标头生成注释的 ID。 如果来源中不存在具有此注释 ID 的注释，则系统会创建新注释。 否则，系统将更新现有注释。

将原始电子邮件转换为注释时，Communications Mining 将清理电子邮件正文，并从电子邮件标头生成元数据。 您可以将include_comments设置为true ，以在响应中包含生成的注释。 注释将以注释参考中描述的格式返回。

名称	类型	必填	说明
transform_tag	字符串	是	标识发送数据的电子邮件集成的标签。 您应该在集成配置设置期间收到此标签。
documents	array<Document>	是	一批最多包含 16384 个文档，其格式如下所述。 对于每个文档，较大批处理比较小批处理速度更快。
include_comments	boolean	否	如果设置为true ，则从电子邮件中解析的注释将在响应正文中返回。
override_user_properties	array<string>	否	如果documents中提供的用户属性的名称出现在此列表中，将覆盖自动生成的用户属性。 此列表中的用户属性名称不应指定类型前缀，例如My Property而不是string:My Property 。

其中Document具有以下格式：

名称	类型	必填	说明
raw_email	RawEmail	是	通过电子邮件发送数据，格式如注释参考中所述。
comment_id	字符串	否	唯一标识注释。 如果未提供注释 ID，Communications Mining 将根据电子邮件的消息 ID 生成注释 ID。 注释参考文档中对该格式进行了说明。
user_properties	map<string, string | number>	否	适用于注释的任何用户定义的元数据。 注释参考中对该格式进行了说明。 注意：某些用户属性是根据电子邮件内容生成的。 如果这些属性与上传的用户属性冲突，则请求将失败，并422 Unprocessable Entity 。

警告：

已分配的常规字段

Communications Mining 将从原始电子邮件正文和原始电子邮件标头的子集生成注释“消息”的内容，同时考虑到指定的转换标签。 除非文本发生了重大变化，否则分配的常规字段将保留。 分配的标签永远不会被丢弃。

重要提示：

大型请求

对于大型请求，此端点可能需要更长时间才能响应。 您应该增加客户端超时时间。

删除注释

/api/v1/sources/<project>/<source_name>/comments?id=<comment_id0>[&id=<comment_id1>...]

所需权限：编辑消息

• 重击

  curl -X DELETE 'https://<my_api_endpoint>/api/v1/sources/<project>/<source_name>/comments?id=abcdef0123456789' \
      -H "Authorization: Bearer $REINFER_TOKEN"

• 节点

  const request = require("request");
  
  request.delete(
    {
      url: "https://<my_api_endpoint>/api/v1/sources/<project>/<source_name>/comments?id=abcdef0123456789",
      headers: {
        Authorization: "Bearer " + process.env.REINFER_TOKEN,
      },
    },
    function (error, response, json) {
      // digest response
      console.log(JSON.stringify(json, null, 2));
    }
  );

• Python

  import json
  import os
  
  import requests
  
  response = requests.delete(
      "https://<my_api_endpoint>/api/v1/sources/<project>/<source_name>/comments?id=abcdef0123456789",
      headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
  )
  
  print(json.dumps(response.json(), indent=2, sort_keys=True))

• 响应

  {
    "status": "ok"
  }

使用添加注释时提供的 ID，可以从来源中删除单个注释。

系统将永久删除与此注释关联的所有数据。

按 ID 获取注释

/api/v1/sources/<project>/<source_name>/comments/<comment_id>

所需权限：查看来源

• 重击

  curl -X GET 'https://<my_api_endpoint>/api/v1/sources/<project>/<source>/comments/0123456789abcdef' \
      -H "Authorization: Bearer $REINFER_TOKEN"

• 节点

  const request = require("request");
  
  request.get(
    {
      url: "https://<my_api_endpoint>/api/v1/sources/<project>/<source>/comments/0123456789abcdef",
      headers: {
        Authorization: "Bearer " + process.env.REINFER_TOKEN,
      },
    },
    function (error, response, json) {
      // digest response
      console.log(JSON.stringify(json, null, 2));
    }
  );

• Python

  import json
  import os
  
  import requests
  
  response = requests.get(
      "https://<my_api_endpoint>/api/v1/sources/<project>/<source>/comments/0123456789abcdef",
      headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
  )
  
  print(json.dumps(response.json(), indent=2, sort_keys=True))

• 响应

  {
    "comment": {
      "context": "1596721237668",
      "created_at": "2020-08-06T13:20:28.531000Z",
      "id": "0123456789abcdef",
      "last_modified": "2020-08-06T13:40:37.668000Z",
      "messages": [
        {
          "body": {
            "text": "Alice,\n\nHere are the figures for today.\n\nRegards,\nBob"
          },
          "from": "[e-mail]",
          "sent_at": "2011-12-11T11:05:10Z",
          "subject": {
            "text": "Today's figures"
          },
          "to": ["[e-mail]"]
        }
      ],
      "source_id": "47194279497e141e",
      "text_format": "plain",
      "timestamp": "2011-12-11T11:05:10Z",
      "uid": "47194279497e141e.0123456789abcdef",
      "user_properties": {
        "string:Recipient Domain": "company.com",
        "string:Sender Domain": "organisation.org"
      }
    },
    "status": "ok"
  }

注释将以注释参考中描述的格式返回。

按会话 ID 获取注释

/api/v1/sources/<project>/<source_name>/threads?id=<thread_id0>[&id=<thread_id1>...]

所需权限：查看来源

• 重击

  curl -X GET 'https://<my_api_endpoint>/api/v1/sources/<project>/<source>/threads?id=185521538102&id=81745162' \
      -H "Authorization: Bearer $REINFER_TOKEN"

• 节点

  const request = require("request");
  
  request.get(
    {
      url: "https://<my_api_endpoint>/api/v1/sources/<project>/<source>/threads?id=185521538102&id=81745162",
      headers: {
        Authorization: "Bearer " + process.env.REINFER_TOKEN,
      },
    },
    function (error, response, json) {
      // digest response
      console.log(JSON.stringify(json, null, 2));
    }
  );

• Python

  import json
  import os
  
  import requests
  
  response = requests.get(
      "https://<my_api_endpoint>/api/v1/sources/<project>/<source>/threads?id=185521538102&id=81745162",
      headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
  )
  
  print(json.dumps(response.json(), indent=2, sort_keys=True))

• 响应

  {
    "status": "ok",
    "threads": [
      {
        "messages": ["4321dcba.1234", "4321dcba.2345", "4321dcba.3456"],
        "thread_id": "185521538102"
      },
      {
        "messages": [],
        "thread_id": "81745162"
      }
    ]
  }

对于每个指定的线程 ID，响应将包含属于该线程的注释 UID 列表（格式为source_id.comment_id ）。 请注意，如果提供的线程 ID 不存在，则不会收到错误消息；相反，响应中的相应注释列表将为空。