Utilización de la API de webhook sobre el estado de los documentos

Puede utilizar la característica de webhook de estado de documento para enviar un suceso de webhook a la aplicación externa cuando el estado de los documentos ingeridos pasa a ser available o failed. El suceso de webhook le ayuda a realizar la siguiente acción en los documentos indexados, sin tener que obtener primero el estado del documento a través de la API Obtener detalles de documento.

IBM Cloud Pak for Data cuando ejecute xml-ph-0000@deepl.internal en un entorno aislado, debe conectarse a la aplicación externa a través de un proxy de xml-ph-0001@deepl.internal IBM Software Hub Cuando ejecute Discovery en un entorno aislado, debe conectarse a la aplicación externa a través de un proxy de HTTP. Para obtener más información, consulte Configuración de un proxy de HTTP en entornos aislados.

Para utilizar la característica de webhook de estado de documento, haga lo siguiente:

  1. Configure la aplicación externa que puede recibir notificaciones de webhook de Discovery.

    Para ello, debe registrar la aplicación externa como un punto final de webhook en una colección utilizando los métodos de API create collection o update collection. Para obtener más información, consulte Crear colección o actualizar colección en la referencia de API.

    La aplicación externa recibe un suceso de webhook ping, que notifica que el webhook se ha creado correctamente. La aplicación externa debe ser accesible desde IBM Cloud.

  2. Ingiera los documentos en la colección. Cuando el estado de los documentos ingeridos pasa a ser available o failed, la aplicación externa recibe el suceso de webhook document.status.

    Puede verificar el estado de los documentos ingeridos en el objeto data del suceso de webhook document.status. Los parámetros document_ids y status muestran los ID de los documentos ingeridos y su estado. Para obtener más información, consulte Modelo de datos del suceso ping y Modelo de datos del suceso document.status.

La siguiente imagen muestra el flujo de configuración del webhook.

Muestra el flujo de configuración de la función de webhook de estado del documento*Flujo " caption-side="bottom"} configuración de la función de webhook de estado del{: caption="

La imagen siguiente muestra el flujo de proceso de la característica de webhook de estado de documento.

Muestra el flujo del proceso de la función de webhook de estado del " caption-side="bottom"} del proceso de la función de webhook de estado del{: caption="

Para obtener más información sobre la API de consulta, consulte Consultar un método de API de proyecto en la referencia de API.

También puede hacer referencia a la aplicación webhook-doc-status-sample para la característica de API de webhook de estado de documento. Para ver la aplicación de ejemplo, debe tener acceso al repositorio doc-tutorial-downloads de Discovery.

Autentificación de la solicitud para la seguridad del webhook

Para autenticar la solicitud del webhook, verifique la señal web JSON (JWT) que se envía con la solicitud. El microservicio del webhook genera automáticamente una JWT y lo envía en la cabecera Authorization con cada llamada de webhook. Es responsabilidad del usuario añadir código al servicio externo que verifica la JWT.

El sistema puede generar un JWT basado en el sample secret que especifique y, en la cabecera Authorization, puede pasar este JWT generado por el sistema a la aplicación externa. Si especifica un valor en header, el microservicio webhook envía ese valor a la aplicación externa en lugar del JWT.

Por ejemplo, si especifica sample secret en el campo Secret del objeto Webhooks en las API Crear colección o actualizar colección, puede añadir código de ejemplo como el siguiente en 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
}

Modelo de datos del suceso ping

A continuación se muestran los parámetros de suceso ping :

suceso de ping
Parámetro Descripción
event El nombre del suceso es ping.
instance_id El ID de instancia de Discovery.
version La versión de la API Discovery en el formato yyyy-mm-dd.
data

Un objeto con la información del evento: url, events, y metadata.

  • url : El punto final del webhook configurado ( URL ).

  • events : Una matriz de valores de cadena de eventos. Los eventos de esta matriz se envían al webhook URL.

  • metadata : Un objeto con información específica del webhook creado.
created_at La fecha y hora en que se creó el evento.

Por ejemplo, a continuación se muestra un suceso ping que se envía 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"
}

Modelo de datos del suceso document.status

A continuación se muestran los parámetros de suceso document.status :

Suceso Document.status
Parámetro Descripción
event El nombre del suceso es document.status.
instance_id El ID de instancia de Discovery.
version La versión de la API Discovery en el formato yyyy-mm-dd.
data Un objeto con la información específica del suceso: project_id, collection_id y document_ids.
status El estado de los documentos.
created_at La fecha y hora en que se creó el evento.

Por ejemplo, a continuación se muestra un suceso document.status que se envía 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"
}