API チュートリアル

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

すべてのデータは、メッセージと呼ばれる個別の部分であり、ソースにグループ化されます。ソースは、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"
  }

ソースを作成するには、次の 4 つが必要です。

1. プロジェクト。これは、ユーザーが参加している既存のプロジェクトです。
2. 名前。英数字、ハイフン、アンダースコアはすべてOKです(例: '購入後')。
3. タイトル。ソースをUIに表示するための、人間が読める短い素敵なタイトル(例: 「購入後のアンケート回答」)。
4. 説明。必要に応じて、ソースの概要ページに表示するソースの長いフォームの説明。

最初の2つは、ソースの「完全修飾」名を形成し、プログラムで参照するために使用されます。 後者の 2 つは、UI での人間による使用を目的としています。

先に進み、 example ソースを作成します。

これで、ソースの誇り高い所有者になるはずです。 ソースページをチェックしてから、戻ってきてください。

リストソースの例

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

• 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 の コメント は、個別のテキスト、または会話に結合された複数のテキスト アイテムのいずれかです。 前者の例としては、調査の回答、サポート チケット、カスタマー レビューなどがあり、後者の例としては、電子メール チェーンなどがあります。

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

メールの追加

• 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 つのメッセージを含むコメントを追加する方法を示します。 この形式は、調査の回答、カスタマーレビューなどのデータに適しています。

必須フィールドと使用可能なフィールドはメールの例と同じですが、唯一の違いは messages フィールドに 1 つのエントリを含める必要があることです。 データに合わないメール固有のフィールドは必須ではないため、スキップできます。

応答では、新しいコメントが 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 つのメッセージのみを含めることができます。 モデルでは使用可能なすべてのデータとメタデータが考慮されるため、モデルのパフォーマンスを最適化するには、提供されるデータが、プラットフォームで注釈が付けられたデータと形式と一致している必要があります。 たとえば、電子メールには件名、from/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"
}