Utiliser l'API d'enrichissement externe

La fonction d'enrichissement externe n'est pas prise en charge dans l'API Analyze.

La fonction d'enrichissement externe vous permet d'annoter des documents avec un modèle de votre choix. Via une interface webhook, vous pouvez utiliser des modèles personnalisés ou des modèles de base avancés, ainsi que d'autres modèles tiers pour enrichir vos documents dans une collection. Les documents sont enrichis par votre application externe, puis fusionnés dans une collection dans un projet Discovery.

IBM Cloud Pak for Data lorsque vous exécutez xml-ph-0000@deepl.internal dans un environnement isolé, vous devez vous connecter à l'application externe via un proxy d'xml-ph-0001@deepl.internal IBM Software Hub Lorsque vous exécutez Discovery dans un environnement isolé, vous devez vous connecter à l'application externe via un proxy d' HTTP. Pour plus d'informations, voir Configuration d'un proxy d' HTTP s dans des environnements isolés.

Pour utiliser la fonction d'enrichissement externe, procédez comme suit:

Configurez l'application externe qui peut recevoir des notifications de webhook à partir de Discovery et annoter des documents.

Pour ce faire, vous devez enregistrer votre application externe en tant que noeud final de webhook sur un projet à l'aide de la méthode create enrichment. Pour plus d'informations, voir Création d'un enrichissement dans la référence d'API.

Une fois l'enrichissement externe configuré pour un projet, il devient disponible pour toutes les collections du projet. L'application externe reçoit également un événement ping de webhook, qui indique qu'un enrichissement externe est créé.
Indiquez la collection dans laquelle vous souhaitez appliquer l'enrichissement externe. Vous pouvez utiliser l'API pour appliquer l'enrichissement externe à une collection. Pour plus d'informations, voir Utilisation de l'API pour gérer les enrichissements.

Vous pouvez également, dans l'interface utilisateur, accéder à la page Gestion des collections et choisir la collection dans laquelle vous souhaitez appliquer l'enrichissement externe. Ouvrez ensuite l'onglet Enrichments et appliquez votre enrichissement externe à une zone de la collection.

Lorsque des documents sont traités ou téléchargés dans cette collection, Discovery crée un lot de documents avec un batch_id unique. L'application externe reçoit également un événement enrichment.batch.created de webhook, qui indique que les lots sont prêts à être extraits. Votre application externe peut ensuite extraire des lots de Discovery pour l'enrichissement externe.

Si l'application externe s'arrête ou redémarre entre les deux, vous pouvez obtenir les éléments suivants à l'aide de la méthode List batch:
- Lots notifiés qui ne sont pas encore extraits par l'application d'enrichissement externe.
- Lots extraits, mais pas encore envoyés à Discovery par l'application d'enrichissement externe.
Pour plus d'informations, voir Liste des lots dans la référence d'API.
Spécifiez le batch_id fourni par Discovery dans la méthode pull batches pour extraire les documents de Discovery en vue de leur enrichissement par votre application externe. Pour plus d'informations, voir Pull batch dans la référence d'API.

La méthode pull batches renvoie un fichier binaire joint à partir de Discovery. Pour plus d'informations sur la pièce jointe binaire, voir Pièce jointe binaire à partir de la méthode des lots d'extraction.
Spécifiez le même batch_id dans la méthode push batches une fois que votre enrichissement externe a annoté les documents du lot. Pour plus d'informations, voir Push batch dans la référence d'API.

Les documents sont envoyés à Discovery sous forme de pièce jointe binaire. Pour plus d'informations, voir Pièce jointe binaire dans la méthode des lots push.
Vérifiez que les documents sont fusionnés et indexés dans la collection. Les documents doivent contenir les annotations qui sont appliquées par votre application externe.

Authentification de la demande pour la sécurité du webhook

Pour authentifier la demande webhook, vérifiez le jeton Web JSON (JWT) qui est envoyé avec la demande. Le micro-service webhook génère automatiquement un JWT et l'envoie dans l'en-tête Authorization avec chaque appel webhook. Il est de votre responsabilité d'ajouter du code au service externe qui vérifie le JWT.

Le système peut générer un jeton JWT en fonction du sample secret que vous spécifiez et, dans l'en-tête Authorization, vous pouvez transmettre ce jeton JWT généré par le système à l'application externe. Si vous spécifiez une valeur dans header, le microservice webhook envoie cette valeur à l'application externe au lieu du jeton JWT.

Par exemple, si vous spécifiez sample secret dans la zone Secret de l'objet Webhooks dans les API Create collection ou update collection, vous pouvez ajouter un exemple de code tel que le suivant dans Node.js:

const jwt = require('jsonwebtoken');
...
const token = request.headers.authentication; // grab the "Authentication" header
try {
  const decoded = jwt.verify(token, 'sample secret');
} catch(err) {
  // error thrown if token is invalid
}

Modèle de données de l'événement `ping`

Les paramètres d'événement ping sont les suivants:

événement ping
Paramètre	Descriptif
`event`	Le nom de l'événement est `ping`.
`instance_id`	L'ID de l'instance Discovery.
`version`	Version de l'API Discovery au format `yyyy-mm-dd`.
`data`	Un objet contenant les informations relatives à l'événement : `url` `events`, et `metadata`. `url` : Le point de terminaison du webhook configuré ( URL ). `events` un tableau de valeurs de chaînes d'événements. Les événements de ce tableau sont envoyés au webhook URL. `metadata` objet : Objet contenant des informations spécifiques au webhook créé.
`created_at`	Date et heure de création de l'événement.

Modèle de données de l'événement `enrichment.batch.created`

Les paramètres d'événement enrichment.batch.created sont les suivants:

Enrichment.batch.created
Paramètre	Descriptif
`event`	Le nom de l'événement est `enrichment.batch.created`.
`instance_id`	Identificateur unique universel de l'instance Discovery, également appelé ID titulaire.
`version`	Date de version de l'événement webhook au format `yyyy-mm-dd`.
`data`	Un objet avec les informations spécifiques à l'événement: `project_id`, `collection_id`, `enrichment_id` et `batch_id`. `project_id`: identificateur unique universel (UUID) d'un projet. `collection_id`: identificateur unique universel (UUID) d'une collection. `enrichment_id`: identificateur unique universel (UUID) d'un enrichissement. `batch_id`: identificateur unique universel (UUID) d'un lot.
`created_at`	La date et l'heure de création de l'événement.

Limites d'enrichissement externe

Limites d'enrichissement externe
Planifier	Quantité maximale d'enrichissement de webhook par collection	Quantité maximale d'enrichissement de webhook par titulaire
Entreprise	1	100
Plus	1	10
Premium	1	100

Pièce jointe binaire à partir de la méthode des lots d'extraction

La méthode pull batches renvoie un fichier de pièce jointe binaire à partir de Discovery.

Le fichier renvoyé est un fichier JSON délimité par des retours à la ligne compressé (NDJSON). Ce fichier contient des données structurées qui représentent les propriétés du document. Par exemple, voici une valeur JSON incluse dans le fichier NDJSON:

{
    "document_id": "3bafc09abfaacd90d66f57181b50d041",
    "location_encoding": "utf-16",
    "language": "en",
    "artifact": "{\"text_positions\":[0,21],\"space_above\":93.07864284515381,\"space_below\":32.53530788421631,\"is_start_of_block\":true,\"image_id\":-1}{\"text_positions\":[22,63],\"space_above\":32.53530788421631,\"space_below\":13.935576438903809,\"is_start_of_block\":true,\"image_id\":-1}{\"parent_document_id\":\"3bafc09abfaacd90d66f57181b50d041\",\"source\":{\"ListId\":\"f0ac1d32-b9e5-41af-b9da-e1e37e965d99\",\"UniqueId\":\"357d7a48-4460-442c-be56-d8bdd40a8c36\",\"ServerRelativeUrl\":\"/Lists/list1/Attachments/1/addattachments.csv\",\"FileNameAsPath\":{\"DecodedUrl\":\"addattachments.csv\"},\"ListItemId\":\"284dcb51-8021-56d0-9213-7f4eb134e083\",\"FileName\":\"addattachments.csv\",\"ServerRelativePath\":{\"DecodedUrl\":\"/Lists/list1/Attachments/1/addattachments.csv\"},\"WebId\":\"ad5bf592-3b4e-4dd1-bd3e-abc0ef179b03\"},\"ingest_datetime\":\"2023-06-26T09:24:02.573Z\",\"application_id\":\"sharepoint\",\"application_sub_type\":\"ListItemAttachmentCollection\"}0.51vanilla ice creamcontamination_tamperingotherchange_of_propertiesI love the ads for the new milk chocolate. Could you tell me the name of the actor in the commercial?{\"metadata\":{\"numPages\":\"54\",\"title\":\"\",\"publicationdate\":\"2010-06-03\"},\"info\":{\"histogram\":{\"mean-char-height\":{},\"mean-char-width\":{},\"number-of-chars\":{}},\"styles\":[]}}1451692800000",
    "features": [
        {
            "type": "field",
            "location": {
                "begin": 0,
                "end": 128
            },
            "properties": {
                "field_name": "multi_nested",
                "field_index": 0,
                "field_type": "json"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 128,
                "end": 258
            },
            "properties": {
                "field_name": "multi_nested",
                "field_index": 1,
                "field_type": "json"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 258,
                "end": 889
            },
            "properties": {
                "field_name": "metadata",
                "field_index": 0,
                "field_type": "json"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 889,
                "end": 892
            },
            "properties": {
                "field_name": "claim_score",
                "field_index": 0,
                "field_type": "double"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 892,
                "end": 893
            },
            "properties": {
                "field_name": "claim_id",
                "field_index": 0,
                "field_type": "long"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 893,
                "end": 910
            },
            "properties": {
                "field_name": "claim_product",
                "field_index": 0,
                "field_type": "string"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 910,
                "end": 933
            },
            "properties": {
                "field_name": "label",
                "field_index": 0,
                "field_type": "string"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 933,
                "end": 938
            },
            "properties": {
                "field_name": "label",
                "field_index": 1,
                "field_type": "string"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 938,
                "end": 958
            },
            "properties": {
                "field_name": "label",
                "field_index": 2,
                "field_type": "string"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 958,
                "end": 1059
            },
            "properties": {
                "field_name": "body",
                "field_index": 0,
                "field_type": "string"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 1059,
                "end": 1230
            },
            "properties": {
                "field_name": "nested",
                "field_index": 0,
                "field_type": "json"
            }
        },
        {
            "type": "field",
            "location": {
                "begin": 1230,
                "end": 1243
            },
            "properties": {
                "field_name": "claim_date",
                "field_index": 0,
                "field_type": "date"
            }
        }
    ]
}

Les propriétés du fichier binaire sont les suivantes:

Propriétés du fichier binaire de la méthode d'extraction
Propriété	Type	Descriptif
`document_id`	`string`	L'identifiant du document.
`location_encoding`	`string`	Type de codage utilisé pour calculer l'emplacement de chaque fonction. Les types pris en charge sont: `utf-8`, `utf-16` et `utf-32`. L'application d'enrichissement externe doit calculer l'emplacement de chaque fonction en fonction du `location_encoding` du document correspondant de Discovery. L'emplacement des fonctions dans une représentation de chaîne de données varie en fonction du type de codage du langage de programmation utilisé pour implémenter l'enrichissement externe. Par exemple, C++ et Go utilisent UTF-8, Java et JavaScript utilisent UTF-16et Python utilise UTF-32.
`language`	`string`	Langue de contenu du document.
`artifact`	`string`	Package de toutes les valeurs de texte.
`features`	`array`	Liste des fonctions d'un document. Pour plus d'informations, voir Types de fonction.

Pièce jointe binaire dans la méthode des lots push

Après l'enrichissement externe, les documents peuvent être envoyés à Discovery en tant que pièce jointe binaire dans la méthode push batches.

Le fichier doit être un fichier NDJSON compressé avec des données structurées qui représentent les propriétés du document. Par exemple, voici un fichier NDJSON:

{
  "document_id": "3bafc09abfaacd90d66f57181b50d041",
  "features": [
    {
      "type": "annotation",
      "location": {
        "begin": 958,
        "end": 1000
      },
      "properties": {
        "type": "element_classes",
        "class_name": "expression",
        "confidence": 0.7905777096748352
      }
    },
    {
      "type": "annotation",
      "location": {
        "begin": 1001,
        "end": 1059
      },
      "properties": {
        "type": "element_classes",
        "class_name": "question",
        "confidence": 0.9507029056549072
      }
    },
    {
      "type": "annotation",
      "location": {
        "begin": 1035,
        "end": 1040
      },
      "properties": {
        "type": "entities",
        "entity_type": "JobTitle",
        "entity_text": "actor",
        "confidence": 0.70953685
      }
    },
    {
      "type": "annotation",
      "properties": {
        "type": "document_classes",
        "class_name": "amount.shortage",
        "confidence": 0.43297016620635986
      }
    },
    {
      "type": "notice",
      "properties": {
        "description": "something wrong happened",
      }
    },
    {
      "type": "notice",
      "properties": {
        "description": "something wrong happened again",
        "created": 1689076276402,
      }
    }
  ]
}

Les propriétés du fichier binaire sont les suivantes:

Propriétés du fichier binaire de la méthode Push
Propriété	Type	Descriptif
`document_id`	`string`	L'identifiant du document.
`features`	`array`	Liste des fonctions d'un document. Pour plus d'informations, voir Types de fonction.

Types de fonction

Une fonction type peut être l'une des suivantes dans un fichier binaire:

Types de fonction
Fonction	Type	Descriptif
`field`	`string`	Représente une valeur de zone spécifique du document.
`annotation`	`string`	Représente une annotation spécifique qui peut enrichir le document.
`notice`	`string`	Représente toute erreur pouvant se produire dans l'application externe lors de l'enrichissement de document. Les informations du `notice` sont utilisées pour générer un message dans l'interface utilisateur de reconnaissance.

Les autres propriétés du fichier binaire sont les suivantes:

Autres propriétés du fichier binaire
Fonction	Type	Descriptif
`location`	`object`	Informations d'emplacement permettant d'obtenir la valeur texte à partir de `artifact` à l'aide des valeurs `begin` et `end`. La valeur `begin` est une valeur de chaîne qui représente l'emplacement de début dans l'artefact. La valeur `end` est une valeur de chaîne qui représente un emplacement de fin exclusif dans l'artefact. Cette propriété est null lorsqu'une fonction représente des informations de niveau document. Par exemple, lorsque `type=annotation` et `properties.type=document_classes`.
`properties`	`object`	Propriétés d'une fonction dans le document. Les propriétés prises en charge varient en fonction de l' `type`. Pour plus d'informations, voir Propriétés de type de zone, Propriétés de type d'annotation et Propriétés de type d'avis.

Propriétés de type de zone

Pour le type field, les propriétés suivantes représentent un certain champ du document qui a été converti par Discovery à partir d'un fichier d'origine:

Propriétés de type de zone
Propriété	Type	Descriptif
`field_name`	`string`	Nom de la zone.
`field_index`	`int`	Index d'une valeur de zone. Cette valeur est `0` pour une zone à valeur unique, mais peut être `> 0` lorsqu'une zone est à valeurs multiples, par exemple, pour un tableau de valeurs.
`field_type`	`string` (enum: `long`, `double`, `date`, `json`)	Le type de données de la fonctionnalité. Cette valeur détermine comment analyser la représentation textuelle de la fonction dans un langage de programmation.

Propriétés de type d'annotation

Pour le type annotation, les propriétés suivantes représentent une annotation pouvant enrichir un document:

Propriétés de type d'annotation
Propriété	Type	Descriptif
`type`	`string` (énumération: `entities`, `element_classes`, `document_classes`)	Type d'annotation enrichie qu'une fonction représente. Les `entities` sont fusionnées en entités de zones enrichies. Les `element_classes` sont fusionnées dans des classes d'élément de zones enrichies. Les `document_classes` sont fusionnées dans des classes de la zone d'enrichissement de niveau document.
`confidence`	`double`	Score de confiance facultatif du modèle externe. Il est compris entre `0` et `1` et est `0` par défaut.
`entity_type`	`string`	Type d'entité qu'un modèle externe affecte à un objet. Obligatoire pour le type `entities`.
`entity_text`	`string`	Texte représentatif d'une entité que l'application externe extrait. Obligatoire pour le type `entities`.
`class_name`	`string`	Nom d'une classe que l'application externe affecte à un objet. Obligatoire pour les types `element_classes` et `document_classes`.

Propriétés de type de notification

Pour le type notice, les propriétés suivantes représentent les erreurs et les exceptions qui se sont produites dans l'application externe lors de l'enrichissement d'un document:

Propriétés de type d'avis
Propriété	Type	Descriptif
`description`	`string`	Message décrivant une erreur qui s'est produite lors de l'enrichissement externe.
`created`	`long`	Temps d'époque Unix en millisecondes lorsqu'une erreur s'est produite lors de l'enrichissement externe.

Utiliser l'API d'enrichissement externe

Utiliser l'API d'enrichissement externe

Authentification de la demande pour la sécurité du webhook

Modèle de données de l'événement ping

Modèle de données de l'événement enrichment.batch.created

Limites d'enrichissement externe

Pièce jointe binaire à partir de la méthode des lots d'extraction

Pièce jointe binaire dans la méthode des lots push

Types de fonction

Propriétés de type de zone

Propriétés de type d'annotation

Propriétés de type de notification

Modèle de données de l'événement `ping`

Modèle de données de l'événement `enrichment.batch.created`