Verwendung der Webhook-API für den Dokumentstatus

Sie können das Webhook-Feature für Dokumentstatus verwenden, um ein Webhook-Ereignis an Ihre externe Anwendung zu senden, wenn der Status der aufgenommenen Dokumente available oder failed lautet. Das Webhook-Ereignis unterstützt Sie bei der nächsten Aktion für indexierte Dokumente, ohne zuerst den Dokumentstatus über die API zum Abrufen von Dokumentdetailsabrufen zu müssen.

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 Webhook-Funktion für Dokumentstatus zu verwenden:

  1. Richten Sie die externe Anwendung ein, die Webhook-Benachrichtigungen von Discoveryempfangen kann.

    Dazu müssen Sie Ihre externe Anwendung als Webhook-Endpunkt in einer Sammlung mithilfe der API-Methode create collection oder update collection registrieren. Weitere Informationen finden Sie in der API-Referenz unter Sammlung erstellen oder Sammlung aktualisieren.

    Die externe Anwendung empfängt ein Webhook-Ereignis ping, das darüber informiert, dass der Webhook erfolgreich erstellt wurde. Die externe Anwendung muss über IBM Cloudzugänglich sein.

  2. Nehmen Sie die Dokumente in die Objektgruppe auf. Wenn der Status der aufgenommenen Dokumente available oder failed lautet, empfängt die externe Anwendung das Webhook-Ereignis document.status.

    Sie können den Status der aufgenommenen Dokumente im Objekt data des document.status-Webhook-Ereignisses überprüfen. Die Parameter document_ids und status zeigen die IDs der aufgenommenen Dokumente und ihren Status an. Weitere Informationen finden Sie unter Datenmodell des ping-Ereignisses und Datenmodell des document.status-Ereignisses.

Das folgende Bild zeigt den Ablauf der Webhook-Konfiguration.

Zeigt den
der Webhook-Funktion für den

Die folgende Abbildung zeigt den Prozessablauf des Webhook-Features für Dokumentstatus.

Zeigt den Prozessablauf der Webhook-Funktion für den
für den

Weitere Informationen zur Abfrage-API finden Sie unter Projekt-API-Methode abfragen in der API-Referenz.

Sie können auch die Webhook-doc-status-sample-Anwendung für das Webhook-API-Feature für Dokumentstatus verwenden. Um die Beispielanwendung anzuzeigen, benötigen Sie Zugriff auf das Repository doc-tutorial-downloads von Discovery.

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:

Pingereignis
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: url, events und metadata.

  • url : Der konfigurierte Webhook-Endpunkt ( URL ).

  • events : Ein Array von Ereignis-String-Werten. Die Ereignisse in dieser Reihe werden an den Webhook URL gesendet.

  • metadata : Ein Objekt mit Informationen, die spezifisch für den erstellten Webhook sind.
created_at Datum und Uhrzeit der Erstellung des Ereignisses.

Das folgende Beispiel zeigt ein ping-Ereignis, das an einen Webhook gesendet wird:

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"
}

Datenmodell des document.status-Ereignisses

Nachfolgend sind die Ereignisparameter für document.status aufgeführt:

Document.status-Ereignis
Parameter Beschreibung
event Der Ereignisname lautet document.status.
instance_id Die Discovery-Instanz-ID
version Die Discovery-API-Version im Format yyyy-mm-dd.
data Ein Objekt mit den ereignisspezifischen Informationen: project_id, collection_id und document_ids.
status Der Status der Dokumente.
created_at Datum und Uhrzeit der Erstellung des Ereignisses.

Das folgende Beispiel zeigt ein document.status-Ereignis, das an einen Webhook gesendet wird:

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"
}