Utilisation de l'API webhook sur l'état des documents

Vous pouvez utiliser la fonction de webhook de statut de document pour envoyer un événement de webhook à votre application externe lorsque le statut des documents ingérés devient available ou failed. L'événement webhook vous aide à effectuer l'action suivante sur les documents indexés, sans avoir à obtenir d'abord le statut du document via l'API d'obtention des détails du document.

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 de webhook de statut de document, procédez comme suit:

  1. Configurez l'application externe qui peut recevoir des notifications de webhook de Discovery.

    Pour ce faire, vous devez enregistrer votre application externe en tant que noeud final de webhook sur une collection à l'aide des méthodes d'API create collection ou update collection. Pour plus d'informations, voir Create collection ou update collection dans la référence d'API.

    L'application externe reçoit un événement ping de webhook, qui indique que la création du webhook a abouti. L'application externe doit être accessible à partir d' IBM Cloud.

  2. Ingérez les documents dans la collection. Lorsque le statut des documents ingérés devient available ou failed, l'application externe reçoit l'événement de webhook document.status.

    Vous pouvez vérifier le statut des documents ingérés dans l'objet data de l'événement de webhook document.status. Les paramètres document_ids et status affichent les ID des documents ingérés et leur statut. Pour plus d'informations, voir Modèle de données de l'événement ping et Modèle de données de l'événement document.status.

L'image suivante montre le flux de configuration du webhook.

Montre le flux{: caption="configuration de la fonctionnalité webhook de l'état du documentFlux " caption-side="bottom"} configuration de la fonctionnalité webhook de l'état du document

L'image suivante montre le flux de processus de la fonction de webhook de statut de document.

Montre le déroulement du processus de la fonction webhook de l'état du
status webhook feature process
(déroulement du processus de la fonction webhook de l'état du document)

Pour plus d'informations sur l'API de requête, voir Query a project API method dans la référence d'API.

Vous pouvez également vous référer à l'application webhook-doc-status-sample pour la fonction d'API webhook de statut de document. Pour afficher l'exemple d'application, vous devez avoir accès au référentiel doc-tutorial-downloads de reconnaissance.

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.

Par exemple, voici un événement ping qui est envoyé à 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"
}

Modèle de données de l'événement document.status

Les paramètres d'événement document.status sont les suivants:

Evénement Document.status
Paramètre Descriptif
event Le nom de l'événement est document.status.
instance_id L'ID d'instance de l' Discovery.
version Version de l'API Discovery au format yyyy-mm-dd.
data Objet avec les informations spécifiques à l'événement: project_id, collection_id et document_ids.
status Le statut des documents.
created_at La date et l'heure de création de l'événement.

Par exemple, voici un événement document.status qui est envoyé à 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"
}