Utilizzo dell'API di arricchimento esterno

La funzione di arricchimento esterno non è supportata nell'API Analyze.

La funzione di arricchimento esterno ti consente di annotare i documenti con un modello a scelta. Tramite un'interfaccia webhook, puoi utilizzare modelli personalizzati o modelli di base avanzati e altri modelli di terze parti per arricchire i documenti in una raccolta. I documenti vengono arricchiti dalla tua applicazione esterna e quindi uniti a una collezione in un progetto Discovery.

IBM Cloud Pak for Data quando si esegue unxml-ph-0000@deepl.internalin un ambiente isolato, è necessario connettersi all'applicazione esterna tramite un proxy di tipo "xml-ph-0001@deepl.internal" IBM Software Hub Quando si esegue Discovery in un ambiente isolato, è necessario connettersi all'applicazione esterna tramite un proxy HTTP. Per ulteriori informazioni, vedere Configurazione di un proxy di HTTP in ambienti isolati.

Per utilizzare la funzione di arricchimento esterno, effettuare le seguenti operazioni:

Configura l'applicazione esterna che può ricevere notifiche webhook dal rilevamento e annotare i documenti.

Per farlo, devi registrare la tua applicazione esterna come un endpoint webhook su un progetto utilizzando il metodo create enrichment. Per ulteriori informazioni, vedi Crea arricchimento nella guida di riferimento API.

Dopo aver impostato l'arricchimento esterno per un progetto, diventa disponibile per tutte le raccolte nel progetto. L'applicazione esterna riceve anche un evento webhook ping, che notifica la creazione di un arricchimento esterno.
Specifica la raccolta in cui vuoi applicare l'arricchimento esterno. Puoi utilizzare l'API per applicare l'arricchimento esterno a una raccolta. Per ulteriori informazioni, vedi Utilizzo dell'API per gestire gli arricchimenti.

In alternativa, nell'interfaccia utente, è possibile passare alla pagina Gestisci raccolte e scegliere la raccolta in cui si desidera applicare l'arricchimento esterno. Apri quindi la scheda Enrichments e applica il tuo arricchimento esterno a un campo nella raccolta.

Quando i documenti vengono elaborati o caricati in questa raccolta, Discovery crea un batch di documenti con un batch_id univoco. L'applicazione esterna riceve anche un evento webhook enrichment.batch.created, che notifica che i batch sono pronti per essere estratti. La tua applicazione esterna può quindi estrarre i batch da Discovery per l'arricchimento esterno.

Se l'applicazione esterna si arresta o si riavvia in mezzo, è possibile ottenere quanto segue utilizzando il metodo Elenca batch:
- Batch notificati che non sono ancora stati estratti dall'applicazione di arricchimento esterna.
- I batch di cui viene eseguito il pull, ma che non sono ancora stati inviati al rilevamento dall'applicazione di arricchimento esterna.
Per ulteriori informazioni, vedi List batches nella guida di riferimento API.
Specifica il batch_id fornito da Discovery nel metodo pull batches per estrarre i documenti da Discovery per l'arricchimento da parte dell'applicazione esterna. Per ulteriori informazioni, vedi Pull batches nella guida di riferimento API.

Il metodo pull batches restituisce un allegato file binario da Discovery. Per ulteriori informazioni sull'allegato binario, consultare Allegato binario dal metodo dei batch pull.
Specifica lo stesso batch_id nel metodo push batches dopo che il tuo arricchimento esterno annota i documenti nel batch. Per ulteriori informazioni, consulta Push batches nella guida di riferimento API.

I documenti vengono inviati a Discovery come allegato binario. Per ulteriori informazioni, consultare Binary attachment in the push batches method.
Verificare che i documenti siano uniti e indicizzati nella raccolta. I documenti devono contenere le annotazioni applicate dalla tua applicazione esterna.

Autenticazione della richiesta per la sicurezza dei webhook

Per autenticare la richiesta webhook, verificare il JWT (JSON Web Token) inviato con la richiesta. Il microservizio webhook genera automaticamente un JWT e lo invia nell'intestazione Authorization con ogni chiamata webhook. È responsabilità dell'utente aggiungere del codice al servizio esterno che verifica il JWT.

Il sistema può generare un JWT basato sul sample secret specificato e nell'intestazione Authorization, è possibile passare questo JWT generato dal sistema all'applicazione esterna. Se specifichi un valore nel header, il microservizio webhook invia tale valore all'applicazione esterna invece che al JWT.

Ad esempio, se specifichi sample secret nel campo Secret dell'oggetto Webhooks nelle API Create collection o update collection, potresti aggiungere il seguente codice di esempio 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
}

Modello di dati dell'evento `ping`

Di seguito sono riportati i parametri dell'evento ping :

Evento Ping
Parametro	Descrizione
`event`	Il nome evento è `ping`.
`instance_id`	L'ID istanza Discovery.
`version`	La versione API Discovery nel formato `yyyy-mm-dd`.
`data`	Un oggetto con le informazioni sull'evento: `url`, `events`, e `metadata`. `url` : L'endpoint webhook configurato ( URL ). `events` un array di valori di stringhe di eventi. Gli eventi in questo array sono inviati al webhook URL. `metadata` un oggetto con informazioni specifiche del webhook creato.
`created_at`	La data e l'ora di creazione dell'evento.

Modello di dati dell'evento `enrichment.batch.created`

Di seguito sono riportati i parametri dell'evento enrichment.batch.created :

Enrichment.batch.created
Parametro	Descrizione
`event`	Il nome evento è `enrichment.batch.created`.
`instance_id`	L'UUID dell'istanza Discovery, noto anche come ID tenant.
`version`	La data della versione dell'evento webhook nel formato `yyyy-mm-dd`.
`data`	Un oggetto con le informazioni specifiche dell'evento: `project_id`, `collection_id`, `enrichment_id` e `batch_id`. `project_id`: l'UUID (Universally Unique Identifier) di un progetto. `collection_id`: l'UUID (Universally Unique Identifier) di una raccolta. `enrichment_id`: l'UUID (Universally Unique Identifier) di un arricchimento. `batch_id`: l'UUID (Universally Unique Identifier) di un batch.
`created_at`	La data e l'ora in cui l'evento è stato creato.

Limiti di arricchimento esterno

Limiti di arricchimento esterno
Pianifica	Quantità massima di arricchimento webhook per raccolta	Quantità massima di arricchimento webhook per tenant
Enterprise	1	100
Segno più	1	10
Premium	1	100

Collegamento binario dal metodo pull batches

Il metodo pull batches restituisce un file allegato binario da Discovery.

Il file restituito è un file JSON delimitato da nuova riga (NDJSON) compresso. Questo file contiene dati strutturati che rappresentano le proprietà del documento. Ad esempio, quanto segue è un valore JSON incluso nel file 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"
            }
        }
    ]
}

Di seguito sono riportate le proprietà del file binario:

Proprietà del file binario del metodo Pull
Proprietà	Tipo	Descrizione
`document_id`	`string`	L'identificatore del documento.
`location_encoding`	`string`	Il tipo di codifica utilizzato per calcolare l'ubicazione di ciascuna funzione. I tipi supportati sono: `utf-8`, `utf-16` e `utf-32`. L'applicazione di arricchimento esterno deve calcolare l'ubicazione di ogni funzione basata su `location_encoding` del documento corrispondente da Discovery. L'ubicazione delle funzioni in una stringa di rappresentazione dei dati varia in base al tipo di codifica del linguaggio di programmazione utilizzato per implementare l'arricchimento esterno. Ad esempio, C++ e Go utilizzano UTF-8, Java e JavaScript utilizzano UTF-16e Python utilizza UTF-32.
`language`	`string`	La lingua del contenuto del documento.
`artifact`	`string`	Il package di tutti i valori di testo.
`features`	`array`	L'elenco di funzioni in un documento. Per ulteriori informazioni, consultare Tipi di funzione.

Collegamento binario nel metodo dei batch push

Dopo l'arricchimento esterno, è possibile eseguire il push dei documenti in Discovery come allegato binario nel metodo push batches.

Il file deve essere un file NDJSON compresso con dati strutturali che rappresentano le proprietà del documento. Ad esempio, il seguente è un file 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,
      }
    }
  ]
}

Di seguito sono riportate le proprietà del file binario:

Proprietà del file binario del metodo Push
Proprietà	Tipo	Descrizione
`document_id`	`string`	L'identificatore del documento.
`features`	`array`	L'elenco di funzioni in un documento. Per ulteriori informazioni, consultare Tipi di funzione.

Tipi di funzione

Una funzione type può essere una delle seguenti in un file binario:

Tipi di feature
Funzione	Tipo	Descrizione
`field`	`string`	Rappresenta un valore campo specifico del documento.
`annotation`	`string`	Rappresenta un'annotazione specifica che può arricchire il documento.
`notice`	`string`	Rappresenta qualsiasi errore che potrebbe verificarsi nell'applicazione esterna durante l'arricchimento del documento. Le informazioni in `notice` sono utilizzate per generare un messaggio nella UI di rilevamento.

Le seguenti sono le altre proprietà nel file binario:

Altre proprietà nel file binario
Funzione	Tipo	Descrizione
`location`	`object`	Informazioni di ubicazione per ottenere il valore di testo da `artifact` utilizzando i valori `begin` e `end`. Il valore `begin` è un valore stringa che rappresenta la posizione iniziale nella risorsa utente. Il valore `end` è un valore stringa che rappresenta un'ubicazione finale esclusiva nella risorsa utente. Questa proprietà è null quando una funzione rappresenta informazioni a livello di documento. Ad esempio, quando `type=annotation` e `properties.type=document_classes`.
`properties`	`object`	Le proprietà di una feature nel documento. Le proprietà supportate variano a seconda del `type` della funzione. Per ulteriori informazioni, consultare Proprietà tipo di campo, Proprietà tipo di annotazione e Proprietà tipo di avviso.

Proprietà del tipo di campo

Per il tipo field, le seguenti proprietà rappresentano un determinato campo del documento convertito dal rilevamento da un file originale:

Proprietà tipo di campo
Proprietà	Tipo	Descrizione
`field_name`	`string`	Il nome del campo.
`field_index`	`int`	L'indice di un valore di campo. Questo valore è `0` per un campo a valore singolo, ma può essere `> 0` quando un campo ha più valori, ad esempio, per un array di valori.
`field_type`	`string` (enumerazione: `long`, `double`, `date`, `json`)	Il tipo di dati della funzione. Questo valore determina come analizzare la rappresentazione del testo della funzione in linguaggio di programmazione.

Proprietà del tipo di annotazione

Per il tipo annotation, le proprietà riportate di seguito rappresentano un'annotazione che può arricchire un documento:

Proprietà del tipo di annotazione
Proprietà	Tipo	Descrizione
`type`	`string` (enumerazione: `entities`, `element_classes`, `document_classes`)	Il tipo di annotazione arricchita che una funzione rappresenta. I `entities` vengono uniti alle entità dei campi arricchiti. I `element_classes` vengono uniti a classi di elementi di campi arricchiti. I `document_classes` vengono uniti alle classi del campo di arricchimento a livello del documento.
`confidence`	`double`	Il punteggio di confidenza facoltativo in base al modello esterno. È compreso tra `0` e `1` ed è `0` per impostazione predefinita.
`entity_type`	`string`	Il tipo di entità che un modello esterno assegna a un oggetto. Obbligatorio per il tipo `entities`.
`entity_text`	`string`	Il testo rappresentativo di un'entità che l'applicazione esterna estrae. Obbligatorio per il tipo `entities`.
`class_name`	`string`	Il nome di una classe che l'applicazione esterna assegna a una cosa. Obbligatorio per i tipi `element_classes` e `document_classes`.

Proprietà del tipo di avviso

Per il tipo notice, le seguenti proprietà rappresentano errori ed eccezioni che si verificano nell'applicazione esterna durante l'arricchimento di un documento:

Proprietà tipo di avviso
Proprietà	Tipo	Descrizione
`description`	`string`	Il messaggio che descrive un errore che si è verificato durante l'arricchimento esterno.
`created`	`long`	Tempo epoch Unix in millisecondi quando si è verificato un errore durante l'arricchimento esterno.