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-Ereignisenrichment.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 Methodepull 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 Methodepush 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:
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:
|
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:
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
|
created_at |
Datum und Uhrzeit der Erstellung des Ereignisses. |
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:
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:
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:
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:
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:
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:
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:
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. |