Utilizzo dell'API webhook sullo stato del documento

Puoi utilizzare la funzione webhook di stato del documento per inviare un evento webhook alla tua applicazione esterna quando lo stato dei documenti inseriti diventa available o failed. L'evento webhook ti aiuta a eseguire l'azione successiva sui documenti indicizzati, senza dover ottenere lo stato del documento prima tramite l'API Acquisisci dettagli documento.

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 Impostazione di un proxy di HTTP in ambienti isolati.

Per utilizzare la funzione webhook di stato del documento, effettuare le seguenti operazioni:

  1. Configura l'applicazione esterna che può ricevere notifiche webhook da Discovery.

    Per farlo, devi registrare la tua applicazione esterna come un endpoint webhook su una raccolta utilizzando i metodi API create collection o update collection. Per ulteriori informazioni, vedi Crea raccolta o aggiorna raccolta nella guida di riferimento API.

    L'applicazione esterna riceve un evento webhook ping, che notifica che il webhook è stato creato correttamente. L'applicazione esterna deve essere accessibile da IBM Cloud.

  2. Inserire i documenti nella raccolta. Quando lo stato dei documenti inseriti diventa available o failed, l'applicazione esterna riceve l'evento webhook document.status.

    Puoi controllare lo stato dei documenti inseriti nell'oggetto data dell'evento webhook document.status. I parametri document_ids e status mostrano gli ID dei documenti inseriti e il loro stato. Per ulteriori informazioni, vedi Modello di dati dell'evento ping e Modello di dati dell'evento document.status.

La seguente immagine mostra il flusso di configurazione webhook.

Mostra il
di configurazione della funzione webhook di stato del documento*Flusso di configurazione della funzione webhook di stato del

La seguente immagine mostra il flusso del processo della funzione webhook di stato documento.

Mostra il flusso del processo della funzione webhook di stato del
del processo della funzione webhook di stato del

Per ulteriori informazioni sull'API di query, vedi Query di un metodo API del progetto nella guida di riferimento API.

Puoi anche fare riferimento all'applicazione webhook - doc - status - sample per la funzione API webhook dello stato del documento. Per visualizzare l'applicazione di esempio, è necessario avere accesso al repository doc - tutorial - downloads di Discovery.

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.

Ad esempio, di seguito è riportato un evento ping inviato a un webhook:

POST https://example.com/webhook

Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
X-Global-Transaction-ID: 5144bb45-dc81-402c-a045-249fd1318515
Content-Type: application/json
{
  "event": "ping",
  "version": "2023-03-31",
  "instance_id": "1a5d4916-6097-4150-977a-ca897226565c",
  "data": {
    "url": "https://example.com/webhook",
    "events": [
      "document.status"
    ],
    "metadata": {
      "project_id": "02a803f9-c814-4fcb-a764-e01e3d4dd002",
      "collection_id": "f41ae858-0ca9-d0ed-0000-01890118cc5b"
    }
  },
  "created_at": "2023-08-16T08:34:46.000Z"
}

Modello di dati dell'evento document.status

Di seguito sono riportati i parametri dell'evento document.status :

Evento Document.status
Parametro Descrizione
event Il nome evento è document.status.
instance_id L'ID istanza Discovery.
version La versione API Discovery nel formato yyyy-mm-dd.
data Un oggetto con le informazioni specifiche dell'evento: project_id, collection_id e document_ids.
status Lo stato dei documenti.
created_at La data e l'ora in cui l'evento è stato creato.

Ad esempio, di seguito è riportato un evento document.status inviato a un webhook:

POST https://example.com/webhook

Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
X-Global-Transaction-ID: 5144bb45-dc81-402c-a045-249fd1318515
Content-Type: application/json
{
  "event": "document.status",
  "version": "2023-03-31",
  "instance_id": "1a5d4916-6097-4150-977a-ca897226565c",
  "data": {
    "project_id": "02a803f9-c814-4fcb-a764-e01e3d4dd002",
    "collection_id": "f41ae858-0ca9-d0ed-0000-01890118cc5b",
    "document_ids": [
      "1a5d4916-6097-4150-977a-ca897226565b",
      "2a5d4916-6097-4150-977a-ca897226565b"
    ],
    "status": "available"
  },
  "created_at": "2023-08-16T08:34:46.000Z"
}