Tutoriel API

Il s'agit d'une introduction de style tutoriel à l'API. Passez directement à la référence si vous savez ce que vous cherchez.

Toutes les données, dont les éléments individuels sont appelés messages, sont regroupées en sources. Une source doit correspondre à l'origine des données, comme une boîte aux lettres unique ou un canal de commentaires particulier. Ceux-ci peuvent être combinés pour les besoins d'un seul modèle d'inférence, il est donc préférable de se tromper sur plusieurs sources différentes qu'un seul mono résultats en cas de doute.

Un ensemble de données est une combinaison de sources et des catégories de libellés associées. Par exemple, un ensemble de données peut être construit sur une source de commentaires sur un site Web, avec des libellés tels que Facilité d’utilisation ou Informations disponibles, tandis qu’un ensemble de données différent pourrait se baser sur diverses sources de réponses à une enquête post-achat et appliquer des libellés complètement différents concernant le Packaging ou la Vitesse de livraison.

Ainsi, avant d'ajouter des commentaires, vous devez créer une source dans laquelle les intégrer.

Créer un exemple de source

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"
  }
}'

Nœud

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))

Réponse

{
  "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"
}

Pour créer une source, vous avez besoin des éléments suivants :

1. Un projet : un projet existant dont vous faites partie.
2. Un nom : les caractères alphanumériques, les traits d’union et les traits de soulignement sont tous OK (par exemple « post-achat »).
3. Un titre : un titre court et lisible par un humain pour votre source à afficher dans l'interface utilisateur, par exemple, Réponses à l'enquête post-achat.
4. Une description : En option, une description plus longue de la source à afficher sur la page de vue d'ensemble des sources.

Les deux premiers forment le nom complet de votre source, qui est utilisé pour s’y référer par la programmation. Les deux derniers sont destinés à être utilisés par un être humain dans l’interface utilisateur.

Continuez avec la création d'un exemple de source.

Consultez votre page de sources, puis revenez.

Lister des exemples de sources

Récupérons de manière programmatique les mêmes informations disponibles sur la page des sources, avec toutes les métadonnées de toutes les sources. Vous devriez voir votre source.

Bash

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

Nœud

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))

Réponse

{
  "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"
}

Si vous souhaitez uniquement que les sources appartiennent à un projet spécifique, vous pouvez ajouter son nom au point de terminaison.

Supprimer un exemple de source

La suppression d'une source irrécupère tous les messages et toute autre information qui lui est associée. Tous les ensembles de données qui utilisent cette source perdront également les données d'entraînement fournies par les libellés qui ont été ajoutés aux messages de cette source. Par conséquent, ce point de terminaison doit être utilisé avec prudence. Cela dit, vous pouvez supprimer, en toute sécurité, la source que nous avons créée pour votre projet dans la section précédente.

Bash

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

Nœud

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))

Réponse

{
  "status": "ok"
}

La réponse doit être {"status": "ok"}. Pour être sûr, vous pouvez à nouveau demander toutes les sources.

Bash

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

Nœud

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))

Réponse

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

Ajouter un exemple de commentaires

Les sources seraient inutilisables sans les commentaires qui y sont contenus. Un commentaire dans Communications Mining™ est soit un texte individuel, soit plusieurs éléments de texte combinés dans une conversation. Dans le premier cas, il s’agit des réponses aux enquêtes, des tickets d’assistance et des avis sur les clients, tandis que le second comprend des chaînes d’e-mail.

Nous allons ajouter quelques commentaires à l'exemple de source créé dans la section précédente :

Ajout d'e-mails

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"
      }
    }
  ]
}'

Nœud

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))

Réponse

null

Cet exemple montre comment ajouter un commentaire composé de plusieurs messages. Cette fonction est le plus souvent utilisée pour l'ajout d'e-mails.

The fields used in the requests in the accompanying code should be self-explanatory. The only required fields are id, timestamp, and messages.body.text. You can learn more about available fields in the Comment Reference.

Le champ ID doit être un nombre hexadécimal, unique parmi les commentaires, ne dépassant pas 256 chiffres. Sinon, le choix est laissé à l'utilisateur de l'API, ce qui permet une intégration plus facile avec d'autres systèmes. Si vos ID ne sont pas hexadécimaux, vous pouvez les convertir. Si vous souhaitez conserver davantage les ID d'origine, vous pouvez les placer dans le champ user_properties qui contient des métadonnées arbitraires définies par l'utilisateur.

L’horodatage doit être en UTC et faire référence à l’heure où le commentaire a été enregistré, par exemple, l’enquête a été répondue, et non l’heure actuelle.

La réponse doit confirmer que deux nouveaux commentaires ont été créés.

Ajout de commentaires à message unique

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"
    }
  ]
}'

Nœud

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))

Réponse

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

Cet exemple montre comment ajouter un commentaire contenant un seul message. Ce format peut répondre à des données telles que les réponses aux enquêtes, les avis des clients, etc.

Les champs obligatoires et disponibles sont les mêmes que dans l'exemple des e-mails, à la seule différence que le champ Messages doit contenir une seule entrée. Vous pouvez ignorer les champs spécifiques aux e-mails qui ne correspondent pas à vos données, car ils ne sont pas obligatoires.

La réponse doit confirmer qu'un nouveau commentaire a été créé.

Récupérer l'exemple de commentaires

Une fois ajouté, un commentaire peut être récupéré par son ID. Vous devriez remarquer le commentaire ajouté dans la section précédente.

Bash

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

Nœud

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))

Réponse

{
  "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"
}

Créer un exemple d'ensemble de données

Après avoir ajouté avec succès des données brutes à Communications Mining™, nous pouvons commencer à ajouter des ensembles de données. Un ensemble de données correspond à une taxonomie de libellés ainsi qu'aux données d'entraînement fournies en appliquant ces libellés aux messages d'une série de sources sélectionnées. Vous pouvez créer de nombreux ensembles de données se référant à la même source sans l’action de labellisation des messages en utilisant la taxonomie d’un ensemble de données ayant un impact sur les autres ensembles de données, ou les sources sous-jacentes, permettant aux différentes équipes d’utiliser Communications Mining pour recueillir des informations indépendamment.

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"
  }
}'

Nœud

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))

Réponse

{
  "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"
}

Une fois les sources créées, les utilisateurs disposant des autorisations appropriées peuvent également créer des jeux de données dans l'interface utilisateur, ce qui peut être plus pratique.

Lister des exemples de jeux de données

Bash

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

Nœud

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))

Réponse

{
  "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"
}

Comme les sources, les ensembles de données ont plusieurs routages GET correspondant à :

• tous les jeux de données auxquels l’utilisateur a accès ;
• les jeux de données appartenant au projet spécifié ;
• un jeu de données unique spécifié par projet et par nom.

Nous fournissons un exemple de ce dernier en action.

Mettre à jour un exemple d'ensemble de données

Tous les champs autorisés utilisés pour créer un ensemble de données peuvent être mis à jour, à l'exception de has_sentiment, qui est fixe pour un ensemble de données donné.

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."
  }
}'

Nœud

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))

Réponse

{
  "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"
}

Supprimer un exemple de jeu de données

La suppression d'un ensemble de données supprimera complètement la taxonomie associée ainsi que tous les libellés qui ont été appliqués à ses sources. Vous ne pourrez plus obtenir de prédictions basées sur cette taxonomie et devrez démarrer le processus d'apprentissage des messages d'annotation depuis le début afin d'annuler cette opération. Utilisez-la donc avec précaution.

Bash

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

Nœud

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))

Réponse

{
  "status": "ok"
}

Obtenir des prédictions à partir d'un exemple de modèle épinglé

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
}'

Nœud

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))

Réponse

{
  "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"
}

Une fois que vous avez un modèle entraîné, vous pouvez maintenant utiliser ce modèle pour prédire les libellés par rapport à d'autres données. Pour ce faire, il vous suffit de fournir les éléments suivants :

1. Documents : un tableau de données de message pour lesquels le modèle prédit les libellés ; chaque objet de message ne peut contenir qu'un seul message avec des propriétés facultatives. Pour optimiser les performances du modèle, les données fournies doivent être compatibles avec les données et le format qui ont été annotés sur la plate-forme, car le modèle prend en compte toutes les données et métadonnées disponibles. Par exemple, les e-mails doivent inclure les champs Objet, De, Cci, Cc, etc., si ceux-ci étaient présents dans les données d'entraînement. De plus, les propriétés utilisateur de l'ensemble de données d'entraînement doivent également être incluses dans le corps de la requête d'API.
2. Libellés : un tableau des libellés entraînés du modèle que vous souhaitez que le modèle prédit dans les données fournies. De plus, pour chaque libellé, un seuil de confiance permettant de filtrer les libellés doit être fourni. Le seuil optimal peut être déterminé en fonction de votre compromis de précision par rapport au rappel. De plus amples informations sur le choix d'un seuil sont disponibles dans le guide de l'utilisateur, dans la section Utiliser la validation.
3. Seuil par défaut (facultatif) : une valeur de seuil par défaut qui sera appliquée à tous les libellés fournis. Notez que si les seuils par défaut et par libellé sont fournis conjointement dans une requête, les seuils par libellé remplaceront le seuil par défaut. En tant que meilleure pratique, les seuils par défaut peuvent être utilisés pour tester ou explorer les données. Pour des résultats optimaux lorsque vous utilisez des prédictions à des fins de prise de décision automatisée, il est fortement recommandé d'utiliser des seuils par libellé.

Remarque : un libellé hiérarchique sera formaté sous la forme d'une liste de libellés. Par exemple, le libellé « Trade > Settlements » aura le format [« Trade », « Settlements »] dans la requête.

Dans l'URL de l'API, il est important de transmettre les arguments suivants :

1. Nom du projet : un projet existant dont vous faites partie.
2. Nom de l'ensemble de données : un ensemble de données sur lequel le modèle a été entraîné.
3. Version du modèle : la version du modèle est un numéro disponible sur la page Modèles du jeu de données que vous avez choisi.

Comprendre la réponse

Comme une version de modèle spécifique est utilisée, la réponse à la même requête renverra toujours les mêmes résultats, même si le modèle est entraîné davantage. Une fois que vous avez validé les résultats du nouveau modèle et que vous souhaitez soumettre une demande contre le nouveau modèle, vous devez mettre à jour la version du modèle dans votre demande. De plus, vous devez également mettre à jour les seuils de libellé pour qu'ils s'adaptent au nouveau modèle. Pour chaque nouveau modèle, vous devrez à nouveau parcourir les étapes.

Par défaut, la réponse fournira toujours une liste de libellés prédits pour chaque message avec une confiance supérieure aux niveaux de seuil fournis.

Cependant, la réponse à une requête peut varier si la reconnaissance d'entité et les sentiments sont activés pour votre modèle :

1. Champs généraux activés : la réponse fournira également une liste de champs généraux qui ont été identifiés pour chaque libellé (exemple de première réponse)
2. Sentiments activés : la réponse fournira également un score de sentiment compris entre -1 (par défaut négatif) et 1 (par défaut positif) pour chaque objet du libellé classé au-dessus du seuil de confiance. (exemple de deuxième réponse)

{
  "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"
}