Verwendung der externen Anreicherungs-API

Die externe Aufbereitungsfunktion wird in der Analyse-API nicht unterstützt.

Mit der externen Aufbereitungsfunktion können Sie Dokumente mit einem Modell Ihrer Wahl annotieren. Über eine Webhook-Schnittstelle können Sie angepasste Modelle oder erweiterte Basismodelle und andere Modelle anderer Anbieter zum Aufbereiten Ihrer Dokumente in einer Sammlung verwenden. Die Dokumente werden von Ihrer externen Anwendung aufbereitet und anschließend mit einer Sammlung in einem Discovery-Projekt zusammengeführt.

IBM Cloud Pak for DataIBM Software Hub Wenn Sie Discovery in einer Air-Gapped-Umgebung ausführen, müssen Sie über einen HTTP-Proxy eine Verbindung zur externen Anwendung herstellen. Weitere Informationen finden Sie unter Einrichten des HTTP-Proxys in Umgebungen mit Luftschnittstelle.

Gehen Sie wie folgt vor, um die externe Aufbereitung zu verwenden:

Richten Sie die externe Anwendung ein, die Webhook-Benachrichtigungen von Discovery empfangen und Dokumente annotieren kann.

Dazu müssen Sie Ihre externe App als Webhook-Endpunkt in einem Projekt mit der Methode create enrichment registrieren. Weitere Informationen finden Sie unter Aufbereitung erstellen in der API-Referenz.

Nachdem die externe Aufbereitung für ein Projekt eingerichtet wurde, wird sie für alle Objektgruppen im Projekt verfügbar. Die externe Anwendung empfängt auch ein Webhook-Ereignis ping, das benachrichtigt, dass eine externe Aufbereitung erstellt wird.
Geben Sie die Objektgruppe an, in der die externe Aufbereitung angewendet werden soll. Sie können die API verwenden, um die externe Aufbereitung auf eine Objektgruppe anzuwenden. Weitere Informationen finden Sie unter API zum Verwalten von Aufbereitungen verwenden.

Alternativ können Sie in der Benutzerschnittstelle zur Seite Sammlungen verwalten navigieren und die Sammlung auswählen, auf die Sie die externe Aufbereitung anwenden möchten. Öffnen Sie anschließend die Registerkarte Aufbereitungen und wenden Sie Ihre externe Aufbereitung auf ein Feld in der Objektgruppe an.

Wenn Dokumente verarbeitet oder in diese Objektgruppe hochgeladen werden, erstellt Discovery einen Stapel von Dokumenten mit einem eindeutigen batch_id. Die externe Anwendung empfängt auch ein Webhook-Ereignis enrichment.batch.created, das benachrichtigt, dass Batches für die Pull-Operation bereit sind. Ihre externe Anwendung kann dann Batches zur externen Aufbereitung aus Discovery extrahieren.

Wenn die externe Anwendung beendet oder neu gestartet wird, können Sie mit der Methode "Batches auflisten" Folgendes abrufen:
- Benachrichtigte Batches, die noch nicht von der externen Aufbereitungsanwendung extrahiert wurden.
- Batches, die extrahiert, aber von der externen Aufbereitungsanwendung noch nicht mit Push-Operation an Discovery übertragen wurden.
Weitere Informationen finden Sie unter Batches auflisten in der API-Referenz.
Geben Sie die von der Erkennung bereitgestellte batch_id in der Methode pull batches an, um die Dokumente zur Aufbereitung durch Ihre externe Anwendung aus der Erkennung zu extrahieren. Weitere Informationen finden Sie unter Pull-Batches in der API-Referenz.

Die Methode pull batches gibt einen binären Dateianhang von Discovery zurück. Weitere Informationen zum binären Anhang finden Sie unter Binärer Anhang aus der Pull-Stapelmethode.
Geben Sie dieselbe batch_id in der Methode push batches an, nachdem Ihre externe Aufbereitung die Dokumente im Batch annotiert hat. Weitere Informationen finden Sie unter Push-Stapel in der API-Referenz.

Die Dokumente werden als binäre Anlage an Discovery übertragen. Weitere Informationen finden Sie unter Binary attachment in the push batches method.
Überprüfen Sie, ob die Dokumente in der Objektgruppe zusammengeführt und indexiert wurden. Die Dokumente müssen die Annotationen enthalten, die von Ihrer externen Anwendung angewendet werden.

Authentifizierung der Anfrage für Webhook-Sicherheit

Um die Webhook-Anforderung zu authentifizieren, überprüfen Sie das JSON Web Token (JWT), das mit der Anforderung gesendet wird. Der Webhook-Mikroservice generiert automatisch ein JWT und sendet es mit jedem Webhook-Aufruf im Authorization-Header. Es liegt in Ihrer Verantwortung, Code zum externen Service hinzuzufügen, der das JWT überprüft.

Das System kann ein JWT basierend auf dem von Ihnen angegebenen sample secret generieren und Sie können dieses vom System generierte JWT im Header Authorization an die externe Anwendung übergeben. Wenn Sie einen Wert in header angeben, sendet der Webhook-Mikroservice diesen Wert an die externe Anwendung anstelle des JWT.

Wenn Sie beispielsweise sample secret im Feld Secret des Webhooks-Objekts in den APIs Create collection oder update collection angeben, können Sie Beispielcode wie den folgenden in 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
}

Datenmodell des `ping`-Ereignisses

Nachfolgend sind die Ereignisparameter für ping aufgeführt:

Pingereignis
Parameter	Beschreibung
`event`	Der Ereignisname lautet `ping`.
`instance_id`	Die Discovery-Instanz-ID
`version`	Die Discovery-API-Version im Format `yyyy-mm-dd`.
`data`	Ein Objekt mit den Ereignisinformationen: `url`, `events` und `metadata`. `url` : Der konfigurierte Webhook-Endpunkt ( URL ). `events` : Ein Array von Ereignis-String-Werten. Die Ereignisse in dieser Reihe werden an den Webhook URL gesendet. `metadata` : Ein Objekt mit Informationen, die spezifisch für den erstellten Webhook sind.
`created_at`	Datum und Uhrzeit der Erstellung des Ereignisses.

Datenmodell des `enrichment.batch.created`-Ereignisses

Nachfolgend sind die Ereignisparameter für enrichment.batch.created aufgeführt:

Enrichment.batch.created
Parameter	Beschreibung
`event`	Der Ereignisname lautet `enrichment.batch.created`.
`instance_id`	Die UUID der Discovery-Instanz, die auch als Tenant-ID bezeichnet wird
`version`	Das Versionsdatum des Webhook-Ereignisses im Format `yyyy-mm-dd`.
`data`	Ein Objekt mit den ereignisspezifischen Informationen `project_id`, `collection_id`, `enrichment_id` und `batch_id`. `project_id`: Die UUID (Universally Unique Identifier) eines Projekts. `collection_id`: Die UUID (Universally Unique Identifier) einer Sammlung. `enrichment_id`: Die UUID (Universally Unique Identifier) einer Aufbereitung. `batch_id`: Die UUID (Universally Unique Identifier) eines Batch.
`created_at`	Datum und Uhrzeit der Erstellung des Ereignisses.

Grenzwerte für externe Aufbereitung

Grenzwerte für externe Aufbereitung
Planen	Maximale Menge der Webhook-Aufbereitung pro Objektgruppe	Maximale Webhook-Aufbereitung pro Tenant
Enterprise	1	100
Und	1	10
Premium	1	100

Binäre Zuordnung aus der Methode für Pull-Batches

Die Methode pull batches gibt eine binäre Anhangsdatei aus Discovery zurück.

Die zurückgegebene Datei ist eine komprimierte JSON-Datei mit Zeilenumbrüchen (NDJSON). Diese Datei enthält strukturierte Daten, die die Dokumenteigenschaften darstellen. Das folgende Beispiel zeigt einen JSON-Wert, der in der NDJSON-Datei enthalten ist:

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

Es folgen die Eigenschaften der Binärdatei:

Eigenschaften der Binärdatei der Pull-Methode
Eigenschaft	Typ	Beschreibung
`document_id`	`string`	Die Kennung des Dokuments.
`location_encoding`	`string`	Der Codierungstyp, der zur Berechnung der Position der einzelnen Features verwendet wird. Die unterstützten Typen sind `utf-8`, `utf-16` und `utf-32`. Die externe Aufbereitungsanwendung muss die Position jedes Features basierend auf der `location_encoding` des entsprechenden Dokuments aus Discovery berechnen. Die Position von Features in einer Zeichenfolgedarstellung von Daten variiert abhängig vom Codierungstyp der Programmiersprache, die für die Implementierung der externen Aufbereitung verwendet wird. C++ und Go verwenden beispielsweise UTF-8, Java und JavaScript verwenden UTF-16und Python verwendet UTF-32.
`language`	`string`	Die Inhaltssprache des Dokuments.
`artifact`	`string`	Das Paket aller Textwerte.
`features`	`array`	Die Liste der Features in einem Dokument Weitere Informationen finden Sie unter "Feature-Typen ".

Binärer Anhang in der Push-Stapelmethode

Nach der externen Aufbereitung können die Dokumente als binäre Anlage in der Methode push batches mit Push-Operation an Discovery übertragen werden.

Die Datei muss eine komprimierte NDJSON-Datei mit strukturierten Daten sein, die die Dokumenteigenschaften darstellen. Das folgende Beispiel zeigt eine NDJSON-Datei:

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

Es folgen die Eigenschaften der Binärdatei:

Eigenschaften der Binärdatei der Push-Methode
Eigenschaft	Typ	Beschreibung
`document_id`	`string`	Die Kennung des Dokuments.
`features`	`array`	Die Liste der Features in einem Dokument Weitere Informationen finden Sie unter "Feature-Typen ".

Featuretypen

Ein Feature type kann eines der folgenden Elemente in einer Binärdatei sein:

Komponententypen
Funktion	Typ	Beschreibung
`field`	`string`	Stellt einen bestimmten Feldwert des Dokuments dar.
`annotation`	`string`	Stellt eine bestimmte Anmerkung dar, die das Dokument aufbereiten kann.
`notice`	`string`	Stellt jeden Fehler dar, der in der externen Anwendung während der Dokumentaufbereitung auftreten kann Die Informationen in `notice` werden zum Generieren einer Nachricht in der Erkennungsbenutzerschnittstelle verwendet.

Im Folgenden sind die anderen Eigenschaften in der Binärdatei aufgeführt:

Weitere Eigenschaften in der Binärdatei
Funktion	Typ	Beschreibung
`location`	`object`	Positionsinformationen zum Abrufen des Textwerts aus `artifact` unter Verwendung der Werte `begin` und `end`. Der Wert `begin` ist ein Zeichenfolgewert, der die Anfangsposition im Artefakt darstellt. Der Wert `end` ist ein Zeichenfolgewert, der eine exklusive Endposition im Artefakt darstellt. Diese Eigenschaft ist null, wenn ein Feature Informationen auf Dokumentebene darstellt. Beispiel: `type=annotation` und `properties.type=document_classes`.
`properties`	`object`	Die Eigenschaften eines Features im Dokument. Die unterstützten Eigenschaften variieren je nach `type` der Funktion. Weitere Informationen finden Sie unter Feldtypeigenschaften, Anmerkungstypeigenschaften und Bekanntmachungstypeigenschaften.

Feldtypeigenschaften

Beim Typ field stellen die folgenden Eigenschaften ein bestimmtes Feld des Dokuments dar, das von Discovery aus einer Originaldatei konvertiert wurde:

Feldtypeigenschaften
Eigenschaft	Typ	Beschreibung
`field_name`	`string`	Der Name des Feldes.
`field_index`	`int`	Der Index eines Feldwerts. Dieser Wert ist `0` für ein Feld mit einem einzelnen Wert, kann aber `> 0` sein, wenn ein Feld mehrere Werte hat, z. B. für ein Array von Werten.
`field_type`	`string` (Aufzählung: `long`, `double`, `date`, `json`)	Der Datentyp des Merkmals. Dieser Wert legt fest, wie die Textdarstellung des Features in einer Programmiersprache geparst wird.

Anmerkungstypeigenschaften

Für den Typ annotation stellen die folgenden Eigenschaften eine Annotation dar, die ein Dokument aufbereiten kann:

Eigenschaften des Anmerkungstyps
Eigenschaft	Typ	Beschreibung
`type`	`string` (Aufzählung: `entities`, `element_classes`, `document_classes`)	Der Typ der angereicherten Anmerkung, die ein Merkmal darstellt. Die `entities` werden mit Entitäten angereicherter Felder zusammengeführt. Die `element_classes` werden mit Elementklassen angereicherter Felder zusammengeführt. Die `document_classes` werden mit Klassen des Aufbereitungsfelds auf Dokumentebene zusammengeführt.
`confidence`	`double`	Der optionale Verlässlichkeitsscore des externen Modells. Sie liegt zwischen `0` und `1` und ist standardmäßig `0`.
`entity_type`	`string`	Der Entitätstyp, den ein externes Modell einem Ding zuordnet. Erforderlich für den Typ `entities`.
`entity_text`	`string`	Der repräsentative Text einer Entität, die die externe Anwendung extrahiert. Erforderlich für den Typ `entities`.
`class_name`	`string`	Der Name einer Klasse, die die externe Anwendung einem Ding zuordnet. Erforderlich für den Typ `element_classes` und `document_classes`.

Eigenschaften des Hinweistyps

Beim Typ notice stellen die folgenden Eigenschaften Fehler und Ausnahmen dar, die in der externen Anwendung beim Aufbereiten eines Dokuments aufgetreten sind:

Eigenschaften des Bekanntmachungstyps
Eigenschaft	Typ	Beschreibung
`description`	`string`	Die Nachricht, die einen Fehler beschreibt, der während der externen Aufbereitung aufgetreten ist
`created`	`long`	UNIX-Epochenzeit in Millisekunden, wenn während der externen Aufbereitung ein Fehler aufgetreten ist.