Verarbeitung von documents mit separaten API-Aufrufen

Ein typisches Szenario für die Verarbeitung von documents mit separaten API-Aufrufen (zum Erstellen eines Vorgangs, Hochladen einer Datei und Starten eines Vorgangs) besteht aus den folgenden Schritten:

Abrufen einer Liste aller verfügbaren Skills
Erstellen eines leeren Vorgangs
Hinzufügen eines Satzes von Dateien, die im Vorgang verarbeitet werden sollen
Starten des Vorgangs
Überwachen des Vorgangsstatus
Herunterladen von Quelldateien und Ergebnisdateien

Jede Anfrage an den Server muss Authentifizierungsinformationen (wie ein Access Token) enthalten. Weitere Informationen finden Sie unter Authentifizierung.

Eine Liste aller verfügbaren Skills abrufen

Senden Sie dazu eine GET-Anfrage an die Ressource skills: Führen Sie den folgenden Befehl aus: Die Antwort enthält eine JSON-Datei, die in etwa wie folgt aussieht:

[
   {
      "id": "Receipt",
      "name": "Receipt",
      "type": "Document"
   },
   {
      "id": "c4b26798-07cb-11eb-adc1-0242ac120002",
      "name": "NewClassifier",
      "type": "Classification"
   },
   {
      "id": "c4b26798-07cb-11eb-adc1-0242ac120002",
      "name": "Invoice",
      "type": "Document"
   }
]

Definieren Sie die Skill-ID, die Sie verwenden möchten. Detaillierte Beschreibungen der Skills finden Sie bei den integrierten Skills.

Einen leeren Vorgang erstellen

Senden Sie dazu die folgende POST-Anfrage an die Ressource transactions: Führen Sie den folgenden Befehl aus: Nachdem ein leerer Vorgang erfolgreich erstellt wurde, erhalten Sie eine Antwort mit der Vorgangs-ID:

{
   "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Hinzufügen eines Dateisatzes, der im Vorgang verarbeitet werden soll

Die maximale Anzahl von Dateien in einem Vorgang beträgt 1000.

Ein Dateisatz kann auf zwei Arten hinzugefügt werden:

Direkt zum Vorgang
Zu einem Document und anschließend dieses Document zum Vorgang hinzufügen

Dateien direkt zum Vorgang hinzufügen

Senden Sie dazu eine POST-Anfrage an die Ressource transactions/<transaction-id>/files: Führen Sie den folgenden Befehl aus: Als Ergebnis erhalten Sie eine Antwort mit einer Liste der hinzugefügten Dateien und deren Identifikatoren. Sie können beliebig viele Dateien hinzufügen, indem Sie diesen Aufruf mehrfach wiederholen. Zusätzliche Optionen zum Hochladen von Dateien:

Dateien zu einem Document hinzufügen

Erstellen Sie zunächst ein Document, indem Sie eine POST-Anfrage an die Ressource transactions/<transaction-id>/documents senden: Als Ergebnis erhalten Sie eine Antwort mit der Document-ID. Fügen Sie anschließend dem Document Dateien hinzu, indem Sie eine POST-Anfrage an die Ressource transactions/<transaction-id>/documents/<document-id>/sourceFiles senden:

Starten des Vorgangs

Um den Vorgang mit dem angegebenen Skill und den Dateien zu starten, senden Sie die folgende POST-Anfrage an die Ressource transactions/<transaction-id>/start:

Überwachung des Vorgangsstatus

Um den Vorgangsstatus zu überwachen, verwenden Sie eine Schleife mit kurzem Timeout (prüfen Sie den Status nicht häufiger als einmal pro Sekunde) und senden Sie eine GET-Anfrage an die Ressource transactions/<transaction_id> mit der Vorgangs-ID in der Anforderungs-URI: Die Antwort sieht in etwa wie folgt aus:

{
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status": "Processing", 
   "manualReviewLink": "https://vantage-us.abbyy.com/api/publicapi/v1/verify?documentIds=9838448d-72ae-4e9a-b071-2bb16f732e46",
   "sourceFiles": [
      {
         "id": "7b2eed6f-3fdd-43b9-a178-7211d0a8d5bb",
         "name": "Invoice07.JPG"
      }
   ]
}

In der Antwort:

Wenn der Wert des Schlüssels status auf Folgendes gesetzt ist:
- New — der Vorgang wurde erstellt, wird aber derzeit nicht verarbeitet.
- Processing — der Vorgang wurde gestartet, aber die Ergebnisse sind noch nicht verfügbar.
- Processed — der Vorgang wurde erfolgreich abgeschlossen, und Sie können die Ergebnisse herunterladen.
- Failed — der Vorgang ist fehlgeschlagen.
- Canceled — der Vorgang wurde abgebrochen.
Der Schlüssel manualReviewLink enthält einen Link zur Weboberfläche des Manual Review-Clients und ein Vantage-Zugriffstoken, falls eine Manuelle Überprüfung erforderlich ist. Dieser Link und das Token können verwendet werden, um die Ergebnisse der Klassifizierung und Feldextraktion für einen bestimmten Vorgang zu überprüfen und zu korrigieren. Bis die Überprüfung abgeschlossen ist, ist der Wert des Schlüssels status auf Processing gesetzt. Der bereitgestellte Link ist 168 Stunden lang gültig. Danach sollte mit derselben Methode ein neuer Link erstellt und für einen weiteren Zeitraum von 168 Stunden abgerufen werden. Weitere Informationen finden Sie unter Integrating manual review.

Benutzer, die über diesen Link autorisiert sind, können keine anderen Documents oder Vorgänge anzeigen oder ändern.

Bei einem Document-Skill sieht die Antwort nun etwa wie folgt aus:

{
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status": "Processed",
   "documents": [
      {
         "id": "9838448d-72ae-4e9a-b071-2bb16f732e46",
         "resultFiles": [
            {
               "fileId": "3a3e6245-48e1-489a-9fef-a10b5ba28515",
               "type": "Json"
            }
         ],
         "businessRulesErrors": []
      }
   ],
   "sourceFiles": [
      {
         "id": "7b2eed6f-3fdd-43b9-a178-7211d0a8d5bb",
         "name": "Invoice07.jpg"
      }
   ]
}

Im Array documents hat jedes Dokument ein Array resultFiles. Verwenden Sie dieses Array, um die fileId-Werte abzurufen. Das Format der Ausgabedateien wird durch den Skill definiert, den Sie verwenden. Derzeit geben alle Skills die extrahierten Felder im JSON-Format zurück. Bei einem Klassifizierungs‑Skill sieht die Antwort nach der Verarbeitung der Documents in etwa wie folgt aus:

{
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status": "Processed",
   "documents": [
      {
         "id": "9838448d-72ae-4e9a-b071-2bb16f732e46",
         "classification": {
            "isResultClassConfident": true,
            "resultClass": "Invoice",
            "classConfidences": [
               {
                  "class": "Invoice",
                  "confidence": 89
               },
               {
                  "class": "PurchaseOrder",
                  "confidence": 32
               }
            ]
         }
      }
   ],
   "sourceFiles": [
      {
         "id": "7b2eed6f-3fdd-43b9-a178-7211d0a8d5bb",
         "name": "Invoice07.jpg"
      }
   ]
}

Entnehmen Sie die Klasse des Dokuments dem Schlüssel resultClass und prüfen Sie den Konfidenzwert jeder wahrscheinlichen Klasse in den Schlüsseln confidence. Bei einem Process-Skill kann die Antwort je nach den im Process-Skill verfügbaren Verarbeitungsstufen alle oder nur einen Teil der Informationen enthalten, die für Dokument- und Klassifizierungs-Skills zurückgegeben werden.

Quelldateien und Ergebnisdateien herunterladen

Nachdem die Verarbeitung abgeschlossen ist, können Sie zwei Arten von Dateien herunterladen:

Quelldateien — die ursprünglich hochgeladenen Dateien, die in ihrem ursprünglichen Binärformat zurückgegeben werden.
Ergebnisdateien — die Verarbeitungsausgabe: die extrahierten Daten, standardmäßig im JSON-Format (das Ausgabeformat wird durch die Skill festgelegt).

Quelldateien und Ergebnisdateien verwenden unterschiedliche Endpoints und unterschiedliche Dateibezeichner:

Quelldatei — GET transactions/<transaction-id>/documents/<document-id>/sourceFiles/<file-id>/download. Die Datei-ID stammt aus der Antwort von GET transactions/<transaction-id>/documents (sourceFiles[].id).
Ergebnisdatei — GET transactions/<transaction-id>/files/<file-id>/download. Die Datei-ID stammt aus dem Array resultFiles in der Antwort zum Vorgangsstatus (documents[].resultFiles[].fileId).

Um eine Liste von documents mit ihren Bezeichnern abzurufen, senden Sie eine GET-Anfrage an die Ressource transactions/<transaction-id>/documents und geben Sie die Vorgangs-ID an: Als Ergebnis erhalten Sie eine Liste aller documents, die innerhalb dieses Vorgangs erstellt wurden. Die Antwort enthält außerdem die Kennungen dieser documents, die benötigt werden können, um detaillierte Informationen zu bestimmten Dokumenten anzufordern.

Quelldateien

Um eine benötigte Quelldatei herunterzuladen, senden Sie eine GET-Anfrage an die Ressource transactions/<transaction-id>/documents/<document-id>/sourceFiles/<file-id>/download und geben Sie die Bezeichner des Vorgangs, des Documents und der Datei an (aus der letzten Antwort): Führen Sie den folgenden Befehl aus: Die Antwort enthält die Datei im Binärformat. Wiederholen Sie diesen Schritt für alle Ihre Quelldateien.

Ergebnisdateien

Um eine Ergebnisdatei herunterzuladen, senden Sie eine GET-Anfrage an die Ressource transactions/<transaction-id>/files/<file-id>/download und geben Sie die Vorgangs-ID sowie die fileId der Ergebnisdatei an. Rufen Sie die fileId aus dem resultFiles-Array ab, das beim Überwachen des Vorgangsstatus zurückgegeben wird (jeder Eintrag hat eine fileId und einen type, z. B. Json): Führen Sie den folgenden Befehl aus:

​Eine Liste aller verfügbaren Skills abrufen

​Einen leeren Vorgang erstellen

​Hinzufügen eines Dateisatzes, der im Vorgang verarbeitet werden soll

​Dateien direkt zum Vorgang hinzufügen

​Dateien zu einem Document hinzufügen

​Starten des Vorgangs

​Überwachung des Vorgangsstatus

​Quelldateien und Ergebnisdateien herunterladen

​Quelldateien

​Ergebnisdateien

Eine Liste aller verfügbaren Skills abrufen

Einen leeren Vorgang erstellen

Hinzufügen eines Dateisatzes, der im Vorgang verarbeitet werden soll

Dateien direkt zum Vorgang hinzufügen

Dateien zu einem Document hinzufügen

Starten des Vorgangs

Überwachung des Vorgangsstatus

Quelldateien und Ergebnisdateien herunterladen

Quelldateien

Ergebnisdateien