Communications Mining - コメント

communications-mining

latest

false

重要 :

このコンテンツの一部は機械翻訳によって処理されており、完全な翻訳を保証するものではありません。新しいコンテンツの翻訳は、およそ 1 ～ 2 週間で公開されます。

Communications Mining 開発者ガイド

最終更新日時 2024年11月26日

Communications Mining の各メッセージは、API 内では 1 つのコメントオブジェクトで表します。したがって、メッセージとコメントオブジェクトは同等のものと見なすことができます。開発者向けドキュメントと API では主に commentsと呼び、ユーザーガイドと Communications Mining UI では主に messages と呼びます。

Communications Mining にデータをアップロードしたり、Communications Mining からデータを取得したりする場合、さまざまな種類のデータ (メール、サポートチケットなど) をどのようにコメントとして表す必要があるかを理解しておくことが重要です。このページでは、データを Communications Mining の comments としてモデル化し、アップロード用に準備する方法と、Communications Mining から取得したデータを理解する方法について説明します。

メールから作成されたコメントの例

レビューから作成された Communications Mining のコメント

「概要」セクションでは、コメントオブジェクトの全体的な構造について説明します。Communications Mining に API 経由でデータをアップロードする方法、または Communications Mining に API 経由でアップロードしたデータを処理する方法について詳しくは、「API 経由で作成されたコメント」セクションをご覧ください。よく使用される種類のコメント (メールまたはサポートチケット) それぞれについて詳しく説明されています。連携を介して Communications Mining にアップロードされたデータを処理する方法について詳しくは、「連携によって作成されたコメント」をご覧ください。最後に、利用可能なすべてのコメントオブジェクトフィールドのリストについては、参照のセクションをご覧ください。

概要

Communications Mining は、メール、アンケートの回答、サポートチケット、カスタマーレビューなど、さまざまな種類のテキストデータを処理できます。これらの種類のデータに共通するのは、すべてがコミュニケーションの単位 (メール、アンケートへの回答、サポートチケット、顧客のレビュー) で構成されているところです。 Communications Mining では、たとえば 1 つのメッセージがコメントとして表されます。

あるコメントがどのようなコミュニケーションの単位の種類を表しているかに関係なく、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 は、そのメッセージが含まれるソース内で一意である必要があります。タイムスタンプは、プラットフォームの UI で日付を条件にしてフィルター処理したり並べ替えたりする場合や、日付ベースの分析を生成する場合に使用します。

コメントの種類によっては、上記の必須フィールド以外に他のフィールドも設定する必要があります。データが連携を介して 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 <alice@example.com>\nDate: Tue, 3 Aug 2021 10:57:42 +0100\nMessage-ID: <e7784b5b@mail.example.com>\nSubject: Figures for today\nTo: Bob <bob@company.com>\nCc: Joe <joe@company.com>"
    }
  },
  "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 <alice@example.com>\nDate: Tue, 3 Aug 2021 10:57:42 +0100\nMessage-ID: <e7784b5b@mail.example.com>\nSubject: Figures for today\nTo: Bob <bob@company.com>\nCc: Joe <joe@company.com>"
    }
  },
  "user_properties": {
    "string:Team": "Team XYZ"
  }
}

処理された電子メール

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

スレッドプロパティ

次のスレッドプロパティを使用できます。

名前	説明
`thread_position`	スレッド内でのコメントの位置です。コメントを `timestamp` 順に並べ替えて計算されます。開始値は `0` です。
`num_messages`	スレッド内のコメントの数。
`num_participants`	スレッド内の一意の参加者 (送信元、宛先、CC、BCC) の総数。
`first_sender`	スレッド内の最初のコメントの送信者。
`duration`	スレッド内の最初のコメントと最後のコメントの `timestamps` の差 (秒単位) です。`num_messages` の場合は `null` に設定されます。は 1 (つまり、スレッドにはコメントが1つしか含まれていません)。手記：コメントの `timestamp` は、対応する生メールの `sent_at` フィールドに対応します。
`response_time`	スレッド内の最初のコメントとスレッド内の最初の応答の差 (秒単位)。スレッドの最初の応答は、送信者が `first_sender`されていない最も古いコメントです。スレッドに応答がない場合(つまり、スレッド内のすべての電子メールが同じ送信者からのものである場合)は `null` に設定されます。

プラットフォームに新しいコメントが追加されるたびに、対応するスレッドのスレッドプロパティが更新されます。

注: thread_position を除き、すべてのプロパティはスレッド内の各コメントで同じです。

サポートチケット

本文に加えて、フォームを介して送信される一般的なサポートチケットには、件名、送信者に関する情報(名前や電子メールアドレスなど)、およびコメントのユーザープロパティの一部としてアップロードできる追加の構造化データ(チケットのトピックなど)が含まれる場合があります。

以下の例は、サポートチケットを Communications Mining のコメントの形式にする方法と、そのコメントがプラットフォームの UI にどのように表示されるかを示しています。実際のユーザープロパティは、収集するデータによって異なる場合があります。

サポートチケットの例

{
  "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": "alice.smith@example.com"
    }
  ],
  "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": "alice.smith@example.com"
    }
  ],
  "user_properties": {
    "string:Customer Name": "Alice Smith",
    "string:Source": "Support Form",
    "string:Topic": "Broadband"
  }
}

統合によって作成されたコメント

Emails (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/CjQSEIExTHEqtdntoxz2WtbZDNEiIIVqcP1Sfx2L4epyRQDasa1RSODvheQ3bvLhj3L-_81G を取得します。

この種類のリクエストについて詳しくは、[API リファレンス](#FIXME) をご覧ください。

添付ファイルオブジェクトに attachment_reference プロパティがない場合は、添付ファイルのコンテンツをダウンロードできません。これは、次の理由が考えられます。

Communications Mining が添付ファイルの内容を受信していませんでした。
添付ファイルの内容が Communications Mining へのアップロードのサイズ制限を超えました。
Communications Mining は、ファイルの内容をサポートする前に添付ファイルを処理していました。

添付ファイルの内容の詳細については、「添付ファイル」ページをご覧ください。

参照

コメント

利用可能なコメントフィールドのリストは、以下の表でご確認ください。Communications Mining のコメントオブジェクトについて詳しくは、「概要」をご覧ください。

名前	型	必須	説明
`id`	string	○	ソース内でコメントを一意に識別します。最大 1024 文字の任意の 16 進文字列が有効です (/[0-9a-f]{1,1024}/ に準拠)。
`timestamp`	string	○	コメントが作成された日時を示す ISO-8601 タイムスタンプ。タイムスタンプにタイムゾーンが指定されていない場合は、UTCが想定されます。タイムスタンプは、1950-01-01T00:00:00Z から 2049-12-31T23:59:59Z の範囲である必要があります。
`messages`	array<Message>	○	0 個または 1 個のメッセージの配列。
`user_properties`	map<string, string \| number>	×	コメントに適用されるユーザー定義メタデータ。 `string` と `number`の 2 種類があります。ユーザープロパティのキーの形式は「タイプ:名前」です。 "string:ドメイン名" または "number:星評価"。ユーザープロパティ名は、文字、数字、スペース、およびアンダースコアで構成でき、最大 32 文字を使用できます (/\w([\w ]{0,30}\w)?/ に準拠)。値は、ユーザープロパティの型に応じて文字列または数値である必要があります。
`thread_id`	string	×	メールスレッドを一意に識別する ID。最大 1024 文字の任意の 16 進文字列が有効です (/[0-9a-f]{1,1024}/ に準拠)。
`uid`	string	Communications Mining によって設定	`source_id.comment_id`の形式で結合されたソースとコメント ID です。このフィールドはアップロードされたコメントに対して Communications Mining によって自動的に生成されるため、直接設定しないでください。
`created_at`	string	Communications Mining によって設定	`timestamp` フィールドと同じ制約を持つ ISO-8601 タイムスタンプ。このフィールドはコメントの作成時に Communications Mining によって自動的に生成されるため、直接設定しないでください。
`updated_at`	string	Communications Mining によって設定	`timestamp` フィールドと同じ制約を持つ ISO-8601 タイムスタンプ。このフィールドは、コメントの更新時に Communications Mining によって自動的に生成されるため、直接設定しないでください。
`attachments`	array<Attachment>	×	0 個以上の添付ファイルの配列。添付ファイルは、コメントに添付されたファイルを表します。

名前	型	必須	説明
`name`	string	○	添付ファイルのファイル名。
`size`	Number	○	添付ファイルのファイルの内容のサイズ (バイト単位)。
`content_type`	string	○	添付ファイルの[メディアの種類](https://en.wikipedia.org/wiki/Media_type) です。使用可能な値の一覧については、[IANA メディアタイプ](https://www.iana.org/assignments/media-types/media-types.xhtml) の一覧を参照してください。
`attachment_reference`	string	×	[添付ファイルAPI](#FIXME)からバイナリファイルの内容を取得するために使用されます

ここで Message の形式は次のとおりです。

名前	型	必須	説明
`body`	コンテンツ	○	メッセージの本文テキストを含むオブジェクト。
`subject`	コンテンツ	×	メッセージの件名を含むオブジェクト。
`signature`	コンテンツ	×	メッセージの署名を格納するオブジェクト。
`from`	string	×	メッセージの送信者。
`to`	array<string>	×	プライマリ受信者の配列。
`cc`	array<string>	×	Cc 受信者の配列。
`bcc`	array<string>	×	Bcc 受信者の配列。
`sent_at`	string	×	メッセージが作成された日時を示す ISO-8601 タイムスタンプ。タイムスタンプにタイムゾーンが指定されていない場合は、UTCが想定されます。
`language`	string	×	メッセージの元の言語。指定すると、[コンテンツ] フィールドに `text` と `translated_from` の両方を指定する必要があります。

ここで Content の形式は次のとおりです。

名前	型	必須	説明
`text`	string	○	`language` (ソースの `language` 以外) が指定されている場合、コンテンツの翻訳されたテキストを指定する必要があります。それ以外の場合は、収集時の元の言語にする必要があります。ソースの `language` ではなく、ソースの `should_translate` が `true` に設定されている場合、翻訳されます。最大 65536 文字です。
`translated_from`	string	×	`language`(ソースの`language`以外)が提供されている場合は、コンテンツの元のテキストによって提供されます。`language`を指定せずにこのフィールドを指定すると、エラーが発生します。最大 65536 文字です。

未加工のメール

利用可能な未加工メールフィールドのリストについては、以下の表をご覧ください。

名前	型	必須	説明
`headers`	ヘッダー	○	メールのヘッダーを含むオブジェクトです。
`body`	本文	○	メールの本文を含むオブジェクトです。

ここで Headers の形式は次のとおりです。

名前	型	必須	説明
`raw`	string	×	`raw`と`parsed`のいずれかが必要です。生の電子メールヘッダーは、単一の文字列として指定され、各ヘッダーは独自の行にあります。
`parsed`	マップ<文字列, 文字列 \|配列<string> >	×	`raw`と`parsed`のいずれかが必要です。解析されたメールヘッダーです。文字列キーと文字列または配列<string> の値を持つオブジェクトとして指定されます。各キーは ASCII である必要があり、1 つの電子メールヘッダーを表します。値文字列は、任意の有効な UTF-8 にすることができます。値のリストは、単一のヘッダー値として設定される前に `,` と連結されます。重複するヘッダーキーが必要な場合は、代わりに `raw` を使用してください。

ここで Body の形式は次のとおりです。

名前	型	必須	説明
`plain`	string	×	`plain`と`html`のうち少なくとも 1 つが必要です。メールのプレーンテキストの内容です。最大 65536 文字です。
`html`	string	×	`plain`と`html`のうち少なくとも 1 つが必要です。メールの HTML コンテンツです。