API チュートリアル

Communications Mining API について、ソースの作成、メッセージのアップロード、予測の取得をステップ バイ ステップで説明します。

これはAPIのチュートリアルスタイルの紹介です - あなたが探しているものを知っているなら、参照に直接ジャンプしてください。

すべてのデータは、メッセージと呼ばれる個別の部分であり、ソースにグループ化されます。ソースは、1 つのメールボックス、特定のフィードバック チャネルなど、データの作成元に対応する必要があります。これらを組み合わせて 1 つ推論モデルを作成できます。そのため、確信が持てない場合は、1 つの巨大なソースを使用するよりも、複数の異なるソースを使用することをお勧めします。

データセットは、ソースと、関連するラベル カテゴリを組み合わせたものです。たとえば、1つのデータセットをWebサイトのフィードバックソースに基づいて構築し、使いやすさや利用可能な情報などのラベルを付けて、別のデータセットを購入後のさまざまなアンケート回答ソースに基づいて、パッケージや配送速度に関するまったく異なるラベルを適用できます。

したがって、コメントを追加する前に、コメントを入れるためのソースを作成する必要があります。

ソースの例を作成する

bash

curl -X PUT 'https://<my_api_endpoint>/api/v1/sources/<project>/example' \
    -H "Authorization: Bearer $REINFER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "source": {
    "description": "An optional long form description.",
    "title": "An Example Source"
  }
}'

ノード

const request = require("request");

request.put(
  {
    url: "https://<my_api_endpoint>/api/v1/sources/<project>/example",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
    json: true,
    body: {
      source: {
        description: "An optional long form description.",
        title: "An Example Source",
      },
    },
  },
  function (error, response, json) {
    // digest response
    console.log(JSON.stringify(json, null, 2));
  }
);

Python

import json
import os

import requests

response = requests.put(
    "https://<my_api_endpoint>/api/v1/sources/<project>/example",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
    json={
        "source": {
            "title": "An Example Source",
            "description": "An optional long form description.",
        }
    },
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

レスポンス

{
  "source": {
    "created_at": "2018-10-16T10:43:56.463000Z",
    "description": "An optional long form description.",
    "id": "22f0f76e82fd8867",
    "language": "en",
    "last_modified": "2018-10-16T10:43:56.463000Z",
    "name": "example",
    "owner": "<project>",
    "sensitive_properties": [],
    "should_translate": false,
    "title": "An Example Source",
    "updated_at": "2018-10-16T10:43:56.463000Z"
  },
  "status": "ok"
}

ソースを作成するには、以下が必要です。

1. プロジェクト - 自身が参加している既存のプロジェクトです。
2. 名前 - 英数字、ハイフン、アンダースコアはすべて OK です (例:「購入後」)。
3. タイトル - ソースがユーザー インターフェイスに表示する、人間が判読できる短いタイトルです (例: 購入後のアンケートへの回答)。
4. 説明 - 必要に応じて、ソースの概要ページに表示するソースの長い形式の説明です。

The first two form the fully qualified name of your source, which is used to refer to it programmatically. The latter two are meant for human consumption in the user interface.

サンプル ソースの作成を続行します。

ソースページを確認してから、戻ってきてください。

リストソースの例

すべてのソースのすべてのメタデータを含むソースページにある同じ情報をプログラムで取得しましょう。 ソースが表示されます。

bash

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

ノード

const request = require("request");

request.get(
  {
    url: "https://<my_api_endpoint>/api/v1/sources",
    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",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

レスポンス

{
  "sources": [
    {
      "created_at": "2018-10-16T10:43:56.463000Z",
      "description": "An optional long form description.",
      "id": "22f0f76e82fd8867",
      "language": "en",
      "last_modified": "2018-10-16T10:43:56.463000Z",
      "name": "example",
      "owner": "<project>",
      "sensitive_properties": [],
      "should_translate": false,
      "title": "An Example Source",
      "updated_at": "2018-10-16T10:43:56.463000Z"
    }
  ],
  "status": "ok"
}

特定のプロジェクトに属するソースのみが必要な場合は、その名前をエンドポイントに追加できます。

ソースを削除する例

ソースを削除すると、すべてのメッセージと、関連付けられたその他の情報は破棄され、元に戻すことはできません。削除したソースを使用しているデータセットでは、削除したソース内のメッセージに追加したラベルで提供したトレーニング データも失われます。したがって、このエンドポイントは注意して使用してください。なお、前のセクションでプロジェクト用に作成したソースは削除しても安全です。

bash

curl -X DELETE 'https://<my_api_endpoint>/api/v1/sources/id:22f0f76e82fd8867' \
    -H "Authorization: Bearer $REINFER_TOKEN"

ノード

const request = require("request");

request.delete(
  {
    url: "https://<my_api_endpoint>/api/v1/sources/id:22f0f76e82fd8867",
    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/id:22f0f76e82fd8867",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

レスポンス

{
  "status": "ok"
}

応答は {"status": "ok"}である必要があります。 それがなくなったことを確認するために、すべてのソースを再度要求できます。

bash

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

ノード

const request = require("request");

request.get(
  {
    url: "https://<my_api_endpoint>/api/v1/sources",
    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",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

レスポンス

{
  "sources": [],
  "status": "ok"
}

コメントの追加の例

情報源は、それらに入るコメントなしでは役に立ちません。Communications Mining™ のコメントは、1 つの個別のテキスト、または会話に結合された複数のテキスト項目のいずれかです。前者の例としては、アンケートへの回答、サポート チケット、カスタマー レビューなどがありますが、後者の例としてはメール チェーンなどがあります。

前のセクションで作成したソースの例に、いくつかのコメントを追加します。

メールの追加

bash

curl -X POST 'https://<my_api_endpoint>/api/v1/sources/<project>/example/sync' \
    -H "Authorization: Bearer $REINFER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "comments": [
    {
      "id": "0123456789abcdef",
      "messages": [
        {
          "body": {
            "text": "Hi Bob,\n\nCould you send me today'"'"'s figures?\n\nThanks,\nAlice"
          },
          "from": "[e-mail]",
          "sent_at": "2011-12-11T11:02:03.000000+00:00",
          "to": [
            "[e-mail]"
          ]
        },
        {
          "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",
          "to": [
            "[e-mail]"
          ]
        },
        {
          "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",
          "to": [
            "[e-mail]"
          ]
        }
      ],
      "timestamp": "2011-12-11T01:02:03.000000+00:00"
    },
    {
      "id": "abcdef0123456789",
      "messages": [
        {
          "body": {
            "text": "All,\n\nJust to let you know that processing is running late today.\n\nRegards,\nBob"
          },
          "from": "[e-mail]",
          "sent_at": "2011-12-12T10:04:30.000000+00:00",
          "to": [
            "[e-mail]",
            "[e-mail]"
          ]
        },
        {
          "body": {
            "text": "Hi Bob,\n\nCould you estimate when you'"'"'ll be finished?\n\nThanks,\nCarol"
          },
          "from": "[e-mail]",
          "sent_at": "2011-12-12T10:06:22.000000+00:00",
          "to": [
            "[e-mail]",
            "[e-mail]"
          ]
        },
        {
          "body": {
            "text": "Carol,\n\nWe should be done by 12pm. Sorry about the delay.\n\nBest,\nBob"
          },
          "from": "[e-mail]",
          "sent_at": "2011-12-11T10:09:40.000000+00:00",
          "to": [
            "[e-mail]",
            "[e-mail]"
          ]
        }
      ],
      "timestamp": "2011-12-11T02:03:04.000000+00:00",
      "user_properties": {
        "number:severity": 3,
        "string:Recipient Domain": "company.com",
        "string:Sender Domain": "organisation.org"
      }
    }
  ]
}'

ノード

const request = require("request");

request.post(
  {
    url: "https://<my_api_endpoint>/api/v1/sources/<project>/example/sync",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
    json: true,
    body: {
      comments: [
        {
          id: "0123456789abcdef",
          messages: [
            {
              body: {
                text: "Hi Bob,\n\nCould you send me today's figures?\n\nThanks,\nAlice",
              },
              from: "[e-mail]",
              sent_at: "2011-12-11T11:02:03.000000+00:00",
              to: ["[e-mail]"],
            },
            {
              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",
              to: ["[e-mail]"],
            },
            {
              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",
              to: ["[e-mail]"],
            },
          ],
          timestamp: "2011-12-11T01:02:03.000000+00:00",
        },
        {
          id: "abcdef0123456789",
          messages: [
            {
              body: {
                text: "All,\n\nJust to let you know that processing is running late today.\n\nRegards,\nBob",
              },
              from: "[e-mail]",
              sent_at: "2011-12-12T10:04:30.000000+00:00",
              to: ["[e-mail]", "[e-mail]"],
            },
            {
              body: {
                text: "Hi Bob,\n\nCould you estimate when you'll be finished?\n\nThanks,\nCarol",
              },
              from: "[e-mail]",
              sent_at: "2011-12-12T10:06:22.000000+00:00",
              to: ["[e-mail]", "[e-mail]"],
            },
            {
              body: {
                text: "Carol,\n\nWe should be done by 12pm. Sorry about the delay.\n\nBest,\nBob",
              },
              from: "[e-mail]",
              sent_at: "2011-12-11T10:09:40.000000+00:00",
              to: ["[e-mail]", "[e-mail]"],
            },
          ],
          timestamp: "2011-12-11T02:03:04.000000+00:00",
          user_properties: {
            "number:severity": 3,
            "string:Recipient Domain": "company.com",
            "string:Sender Domain": "organisation.org",
          },
        },
      ],
    },
  },
  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>/example/sync",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
    json={
        "comments": [
            {
                "id": "0123456789abcdef",
                "timestamp": "2011-12-11T01:02:03.000000+00:00",
                "messages": [
                    {
                        "from": "[e-mail]",
                        "to": ["[e-mail]"],
                        "sent_at": "2011-12-11T11:02:03.000000+00:00",
                        "body": {
                            "text": "Hi Bob,\n\nCould you send me today's figures?\n\nThanks,\nAlice"
                        },
                    },
                    {
                        "from": "[e-mail]",
                        "to": ["[e-mail]"],
                        "sent_at": "2011-12-11T11:05:10.000000+00:00",
                        "body": {
                            "text": "Alice,\n\nHere are the figures for today.\n\nRegards,\nBob"
                        },
                    },
                    {
                        "from": "[e-mail]",
                        "to": ["[e-mail]"],
                        "sent_at": "2011-12-11T11:18:43.000000+00:00",
                        "body": {
                            "text": "Hi Bob,\n\nI think these are the wrong numbers - could you check?\n\nThanks again,\nAlice"
                        },
                    },
                ],
            },
            {
                "id": "abcdef0123456789",
                "timestamp": "2011-12-11T02:03:04.000000+00:00",
                "messages": [
                    {
                        "from": "[e-mail]",
                        "to": ["[e-mail]", "[e-mail]"],
                        "sent_at": "2011-12-12T10:04:30.000000+00:00",
                        "body": {
                            "text": "All,\n\nJust to let you know that processing is running late today.\n\nRegards,\nBob"
                        },
                    },
                    {
                        "from": "[e-mail]",
                        "to": ["[e-mail]", "[e-mail]"],
                        "sent_at": "2011-12-12T10:06:22.000000+00:00",
                        "body": {
                            "text": "Hi Bob,\n\nCould you estimate when you'll be finished?\n\nThanks,\nCarol"
                        },
                    },
                    {
                        "from": "[e-mail]",
                        "to": ["[e-mail]", "[e-mail]"],
                        "sent_at": "2011-12-11T10:09:40.000000+00:00",
                        "body": {
                            "text": "Carol,\n\nWe should be done by 12pm. Sorry about the delay.\n\nBest,\nBob"
                        },
                    },
                ],
                "user_properties": {
                    "string:Sender Domain": "organisation.org",
                    "string:Recipient Domain": "company.com",
                    "number:severity": 3,
                },
            },
        ]
    },
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

レスポンス

null

この例では、複数のメッセージで構成されるコメントを追加する方法を示します。 これは、電子メールを追加するために最も一般的に使用されます。

付随するコードの要求で使用されるフィールドは、一目瞭然である必要があります。必須フィールドは、[ id]、[ timestamp]、および [ messages.body.text] のみです。利用可能なフィールドの詳細については、「 コメントの参照」をご覧ください。

ID フィールドは、コメント間で一意な、最大 256 桁の 16 進数である必要があります。 それ以外の場合は、APIのユーザーが選択できるため、他のシステムとの統合が容易になります。 ID が 16 進数でない場合は、変換できます。 元の ID を追加で保持する場合は、任意のユーザー定義メタデータを保持する user_properties フィールドに元の ID を配置できます。

タイムスタンプは UTC で指定し、コメントが記録された時刻 (たとえば、現在の時刻ではなくアンケートに回答した時刻) を参照する必要があります。

応答では、2 つの新しいコメントが作成されたことを確認する必要があります。

単一メッセージコメントの追加

bash

curl -X POST 'https://<my_api_endpoint>/api/v1/sources/<project>/example/sync' \
    -H "Authorization: Bearer $REINFER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "comments": [
    {
      "id": "fedcba098765",
      "messages": [
        {
          "body": {
            "text": "I was impressed with the speed of your service, but the price is quite high.",
            "translated_from": "J'"'"'ai \u00e9t\u00e9 impressionn\u00e9 par la rapidit\u00e9 de votre service, mais le prix est assez \u00e9lev\u00e9."
          },
          "language": "fr"
        }
      ],
      "timestamp": "2011-12-12T20:00:00.000000+00:00"
    }
  ]
}'

ノード

const request = require("request");

request.post(
  {
    url: "https://<my_api_endpoint>/api/v1/sources/<project>/example/sync",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
    json: true,
    body: {
      comments: [
        {
          id: "fedcba098765",
          messages: [
            {
              body: {
                text: "I was impressed with the speed of your service, but the price is quite high.",
                translated_from:
                  "J'ai \u00e9t\u00e9 impressionn\u00e9 par la rapidit\u00e9 de votre service, mais le prix est assez \u00e9lev\u00e9.",
              },
              language: "fr",
            },
          ],
          timestamp: "2011-12-12T20:00:00.000000+00:00",
        },
      ],
    },
  },
  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>/example/sync",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
    json={
        "comments": [
            {
                "id": "fedcba098765",
                "timestamp": "2011-12-12T20:00:00.000000+00:00",
                "messages": [
                    {
                        "language": "fr",
                        "body": {
                            "text": "I was impressed with the speed of your service, but the price is quite high.",
                            "translated_from": "J'ai été impressionné par la rapidité de votre service, mais le prix est assez élevé.",
                        },
                    }
                ],
            }
        ]
    },
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

レスポンス

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

この例では、1 つのメッセージを含むコメントを追加する方法を説明します。この形式は、アンケートへの回答や顧客のレビューなどのデータに適しています。

The required and available fields are the same as in the emails example, with the only difference that the Messages field should contain a single entry. You can skip email-specific fields that do not fit your data, as they are not required.

応答では、新しいコメントが 1 つ作成されたことを確認する必要があります。

コメントの取得の例

追加後、コメントは ID で取得できます。前のセクションで追加されたコメントに注目してください。

bash

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

ノード

const request = require("request");

request.get(
  {
    url: "https://<my_api_endpoint>/api/v1/sources/<project>/example/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>/example/comments/0123456789abcdef",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

レスポンス

{
  "comment": {
    "context": "0",
    "id": "0123456789abcdef",
    "last_modified": "2018-10-16T10:51:46.247000Z",
    "messages": [
      {
        "body": {
          "text": "Hi Bob,\n\nCould you send me today's figures?\n\nThanks,\nAlice"
        },
        "from": "[e-mail]",
        "sent_at": "2011-12-11T11:02:03.000000+00:00",
        "to": ["[e-mail]"]
      },
      {
        "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",
        "to": ["[e-mail]"]
      },
      {
        "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",
        "to": ["[e-mail]"]
      }
    ],
    "source_id": "22f0f76e82fd8867",
    "text_format": "plain",
    "timestamp": "2011-12-11T01:02:03Z",
    "uid": "22f0f76e82fd8867.0123456789abcdef",
    "user_properties": {}
  },
  "status": "ok"
}

データセットの作成の例

Communications Mining™ に生データが正常に追加されたので、データセットの追加を開始できます。データセットは、ラベルのタクソノミーと、トレーニング データに対応します。このトレーニング データは、選択した一連のソース内のメッセージにそのラベルを適用することで提供されたものです。

同じソースを参照するデータセットを複数作成できます。こうすると、あるデータセットのタクソノミーを使用してメッセージをラベル付けしても、他のデータセットや基になるソースに影響しないので、複数のチームが Communications Mining を使用して個別に分析情報を収集できます。

bash

curl -X PUT 'https://<my_api_endpoint>/api/v1/datasets/<project>/my-dataset' \
    -H "Authorization: Bearer $REINFER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "dataset": {
    "description": "An optional long form description.",
    "source_ids": [
      "22f0f76e82fd8867"
    ],
    "title": "An Example Dataset"
  }
}'

ノード

const request = require("request");

request.put(
  {
    url: "https://<my_api_endpoint>/api/v1/datasets/<project>/my-dataset",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
    json: true,
    body: {
      dataset: {
        description: "An optional long form description.",
        source_ids: ["22f0f76e82fd8867"],
        title: "An Example Dataset",
      },
    },
  },
  function (error, response, json) {
    // digest response
    console.log(JSON.stringify(json, null, 2));
  }
);

Python

import json
import os

import requests

response = requests.put(
    "https://<my_api_endpoint>/api/v1/datasets/<project>/my-dataset",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
    json={
        "dataset": {
            "title": "An Example Dataset",
            "description": "An optional long form description.",
            "source_ids": ["22f0f76e82fd8867"],
        }
    },
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

レスポンス

{
  "dataset": {
    "created": "2018-10-16T10:57:44.667000Z",
    "description": "An optional long form description.",
    "has_sentiment": true,
    "id": "b2ad67f9dfd2e76b",
    "last_modified": "2018-10-16T10:57:44.667000Z",
    "limited_access": false,
    "model_family": "english",
    "name": "my-dataset",
    "owner": "<project>",
    "source_ids": ["22f0f76e82fd8867"],
    "title": "An Example Dataset"
  },
  "status": "ok"
}

ソースが作成されると、適切な権限を持つユーザーは UI でデータセットを作成することもできますが、これはより便利な場合があります。

データセットのリストの例

bash

curl -X GET 'https://<my_api_endpoint>/api/v1/datasets/<project>/my-dataset' \
    -H "Authorization: Bearer $REINFER_TOKEN"

ノード

const request = require("request");

request.get(
  {
    url: "https://<my_api_endpoint>/api/v1/datasets/<project>/my-dataset",
    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/datasets/<project>/my-dataset",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

レスポンス

{
  "dataset": {
    "created": "2018-10-16T10:57:44.667000Z",
    "description": "An optional long form description.",
    "has_sentiment": true,
    "id": "b2ad67f9dfd2e76b",
    "last_modified": "2018-10-16T10:57:44.667000Z",
    "limited_access": false,
    "model_family": "random",
    "name": "my-dataset",
    "owner": "<project>",
    "source_ids": ["22f0f76e82fd8867"],
    "title": "An Example Dataset"
  },
  "status": "ok"
}

ソースと同様に、データセットには以下に対応するいくつかの GET ルートがあります。

• ユーザーがアクセスできるすべてのデータセット
• 指定したプロジェクトに属するデータセット
• プロジェクトと名前で指定された単一のデータセット。

後者の実際の例を示します。

データセットの更新の例

データセットの作成に使用できるフィールドはすべて更新できます。ただし、特定のデータセットに対して固定されている has_sentimentは例外です。

bash

curl -X POST 'https://<my_api_endpoint>/api/v1/datasets/<project>/my-dataset' \
    -H "Authorization: Bearer $REINFER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "dataset": {
    "description": "An updated description."
  }
}'

ノード

const request = require("request");

request.post(
  {
    url: "https://<my_api_endpoint>/api/v1/datasets/<project>/my-dataset",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
    json: true,
    body: { dataset: { description: "An updated description." } },
  },
  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/datasets/<project>/my-dataset",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
    json={"dataset": {"description": "An updated description."}},
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

レスポンス

{
  "dataset": {
    "created": "2018-10-16T10:57:44.667000Z",
    "description": "An updated description.",
    "has_sentiment": true,
    "id": "b2ad67f9dfd2e76b",
    "last_modified": "2018-10-16T10:57:44.667000Z",
    "limited_access": false,
    "model_family": "random",
    "name": "my-dataset",
    "owner": "<project>",
    "source_ids": ["22f0f76e82fd8867"],
    "title": "An Example Dataset"
  },
  "status": "ok"
}

データセットの削除の例

データセットを削除すると、関連するタクソノミーと、そのソースに適用されているすべてのラベルが完全に削除されます。 このタクソノミーに基づく予測は取得できなくなり、この操作を元に戻すにはメッセージの注釈付けのトレーニング プロセスを最初から開始しなければならないため、注意して使用してください。

bash

curl -X DELETE 'https://<my_api_endpoint>/api/v1/datasets/<project>/my-dataset' \
    -H "Authorization: Bearer $REINFER_TOKEN"

ノード

const request = require("request");

request.delete(
  {
    url: "https://<my_api_endpoint>/api/v1/datasets/<project>/my-dataset",
    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/datasets/<project>/my-dataset",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

レスポンス

{
  "status": "ok"
}

パブリッシュ済みのモデルの例から予測を取得する

bash

curl -X POST 'https://<my_api_endpoint>/api/v1/datasets/<project>/<dataset>/labellers/<model_version>/predict' \
    -H "Authorization: Bearer $REINFER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "documents": [
    {
      "messages": [
        {
          "body": {
            "text": "Hi Bob, has my trade settled yet? Thanks, Alice"
          },
          "from": "[e-mail]",
          "sent_at": "2011-12-11T11:02:03.000000+00:00",
          "subject": {
            "text": "Trade Ref: 8726387 Settlement"
          },
          "to": [
            "[e-mail]"
          ]
        }
      ],
      "user_properties": {
        "number:Deal Value": 12000,
        "string:City": "London"
      }
    },
    {
      "messages": [
        {
          "body": {
            "text": "All, just to let you know that processing is running late today. Regards, Bob"
          },
          "from": "[e-mail]",
          "sent_at": "2011-12-12T10:04:30.000000+00:00",
          "subject": {
            "text": "Trade Processing Delay"
          },
          "to": [
            "[e-mail]",
            "[e-mail]"
          ]
        }
      ],
      "user_properties": {
        "number:Deal Value": 4.9,
        "string:City": "Luton"
      }
    }
  ],
  "labels": [
    {
      "name": [
        "Trade",
        "Settlement"
      ],
      "threshold": 0.8
    },
    {
      "name": [
        "Delay"
      ],
      "threshold": 0.75
    }
  ],
  "threshold": 0
}'

ノード

const request = require("request");

request.post(
  {
    url: "https://<my_api_endpoint>/api/v1/datasets/<project>/<dataset>/labellers/<model_version>/predict",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
    json: true,
    body: {
      documents: [
        {
          messages: [
            {
              body: { text: "Hi Bob, has my trade settled yet? Thanks, Alice" },
              from: "[e-mail]",
              sent_at: "2011-12-11T11:02:03.000000+00:00",
              subject: { text: "Trade Ref: 8726387 Settlement" },
              to: ["[e-mail]"],
            },
          ],
          user_properties: {
            "number:Deal Value": 12000,
            "string:City": "London",
          },
        },
        {
          messages: [
            {
              body: {
                text: "All, just to let you know that processing is running late today. Regards, Bob",
              },
              from: "[e-mail]",
              sent_at: "2011-12-12T10:04:30.000000+00:00",
              subject: { text: "Trade Processing Delay" },
              to: ["[e-mail]", "[e-mail]"],
            },
          ],
          user_properties: { "number:Deal Value": 4.9, "string:City": "Luton" },
        },
      ],
      labels: [
        { name: ["Trade", "Settlement"], threshold: 0.8 },
        { name: ["Delay"], threshold: 0.75 },
      ],
      threshold: 0,
    },
  },
  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/datasets/<project>/<dataset>/labellers/<model_version>/predict",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
    json={
        "documents": [
            {
                "messages": [
                    {
                        "body": {
                            "text": "Hi Bob, has my trade settled yet? Thanks, Alice"
                        },
                        "subject": {"text": "Trade Ref: 8726387 Settlement"},
                        "from": "[e-mail]",
                        "sent_at": "2011-12-11T11:02:03.000000+00:00",
                        "to": ["[e-mail]"],
                    }
                ],
                "user_properties": {
                    "number:Deal Value": 12000,
                    "string:City": "London",
                },
            },
            {
                "messages": [
                    {
                        "body": {
                            "text": "All, just to let you know that processing is running late today. Regards, Bob"
                        },
                        "subject": {"text": "Trade Processing Delay"},
                        "from": "[e-mail]",
                        "sent_at": "2011-12-12T10:04:30.000000+00:00",
                        "to": ["[e-mail]", "[e-mail]"],
                    }
                ],
                "user_properties": {
                    "number:Deal Value": 4.9,
                    "string:City": "Luton",
                },
            },
        ],
        "labels": [
            {"name": ["Trade", "Settlement"], "threshold": 0.8},
            {"name": ["Delay"], "threshold": 0.75},
        ],
        "threshold": 0,
    },
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

レスポンス

{
  "entities": [
    [
      {
        "formatted_value": "2019-01-01 00:00 UTC",
        "kind": "date",
        "span": {
          "content_part": "body",
          "message_index": 0,
          "utf16_byte_end": 120,
          "utf16_byte_start": 94
        }
      },
      {
        "formatted_value": "Bob",
        "kind": "person",
        "span": {
          "content_part": "body",
          "message_index": 0,
          "utf16_byte_end": 6,
          "utf16_byte_start": 12
        }
      }
    ],
    []
  ],
  "model": {
    "time": "2018-12-20T15:05:43.906000Z",
    "version": "1"
  },
  "predictions": [
    [
      {
        "name": ["Trade", "Settlement"],
        "probability": 0.8668700814247131
      }
    ],
    [
      {
        "name": ["Delay"],
        "probability": 0.26687008142471313
      }
    ]
  ],
  "status": "ok"
}

トレーニング済みのモデルを作成したら、このモデルを使用して、他のデータに対するラベルを予測できます。 これを行うには、単に以下を提供する必要があります。

1. ドキュメント - モデルがラベルを予測するメッセージ データの配列です。各メッセージ オブジェクトには、1 つのメッセージと任意のプロパティのみを含めることができます。最適なモデル パフォーマンスを得るには、提供するデータが、プラットフォームでアノテーションされたデータおよび形式に一致している必要があります。モデルは、利用可能なデータとメタデータをすべて考慮するためです。たとえば、トレーニング データに件名、送信元、Bcc、Cc フィールドなどが存在する場合、メールにこれらが含まれる必要があります。また、トレーニング データセット内のユーザー プロパティも、API 要求の本文に含める必要があります。
2. ラベル - 提供されたデータ内でモデルが予測する、モデル トレーニング済みのラベルの配列です。さらに、ラベルごとに、ラベルをフィルター処理するための信頼度のしきい値を指定する必要があります。最適なしきい値は、適合率と再現率のトレードオフに基づいて決定できます。しきい値の選択方法について詳しくは、ユーザー ガイドの「検証を使用する」セクションをご覧ください。
3. 既定のしきい値 (任意) - 指定したすべてのラベルに適用される既定のしきい値です。要求で既定のしきい値とラベルごとのしきい値を一緒に指定すると、ラベルごとのしきい値が既定のしきい値よりも優先されることに注意してください。ベスト プラクティスとして、データのテストや探索には既定のしきい値を使用できます。予測を使用して自動意思決定を行う場合に最適な結果を得るには、ラベルごとのしきい値を使用することを強くお勧めします。
   注:

   階層ラベルは、ラベルのリストとして書式設定されます。たとえば、「Trade > Settlements」というラベルは、要求の形式は ["Trade", "Settlements"] になります。

API の URL 内では、次の引数を渡すことが重要です。

1. プロジェクト名 - 自身が参加している既存のプロジェクトです。
2. データセット名 - モデルがトレーニングされたデータセットです。
3. モデル バージョン - モデルのバージョンは、選択したデータセットの [ モデル ] ページに表示される数値です。

応答を理解する

特定のモデル バージョンが使用されているため、モデルをさらにトレーニングしても、同じ要求に対する応答では常に同じ結果が返されます。

新しいモデルの結果を検証した後、新しいモデルに対して要求を送信する場合は、要求のモデル バージョンを更新する必要があります。さらに、ラベルのしきい値も新しいモデルに合わせて更新する必要があります。新しいモデルを作成するたびに、手順をもう一度繰り返す必要があります。

応答では常に既定で、指定したしきい値レベルよりも高い信頼度を持つ各メッセージについて、予測されたラベルのリストが提供されます。

ただし、モデルでエンティティ認識とセンチメントが有効になっている場合、要求の応答は異なる場合があります。

1. 一般フィールド 有効 - 応答では、各ラベルで特定された一般フィールドのリストも提供されます (最初の応答の例)
2. 感情の有効化 - 応答では、信頼度のしきい値より上で分類されたすべてのラベル オブジェクトに対して、-1 (完全に否定的) から 1 (完全に肯定的) の感情スコアも提供されます。(2 番目の応答例)

{
  "model": { "time": "2018-12-20T15:05:43.906000Z", "version": "1" },
  "predictions": [
    [
      {
        "name": ["Trade", "Settlement"],
        "probability": 0.86687008142471313,
        "sentiment": 0.8762539502232571
      }
    ],
    [
      {
        "name": ["Delay"],
        "probability": 0.26687008142471313,
        "sentiment": 0.8762539502232571
      }
    ]
  ],
  "status": "ok"
}