OCR-App

OCR-App

 Basisinformationen

In diesem Thema findest du allgemeine Informationen zur OCR-API.

 Über die OCR-API

In dieser Dokumentation erfährst du, wie du die Programmierschnittstelle der OCR-App für eigene Entwicklungen nutzen kannst. Die OCR-App stellt Funktionalitäten rund um die Texterkennung von digitalen Seiten bereit.

 Funktionsumfang der OCR-App

Die OCR-App umfasst Schnittstellen für die Erkennung von Text aus Dokumenten. Folgende Funktionen sind enthalten:

  • Erkennung des Volltextes
  • Erkennung von hOCR-Informationen

 Verwenden der API-Funktionen

Im Folgenden lernst du die unterschiedlichen Möglichkeiten kennen, die Schnittstellen der OCR-App für deine Anforderungen zu verwenden.

 Allgemeines

In diesem Kapitel findest du allgemeine Informationen zur Verwendung der API.

 Voraussetzungen

Für die Nutzung der bereitgestellten Schnittstellen benötigst du einen sogenannten App-Schlüssel. Um diesen zu erhalten, melde dich bitte beim d.velop-Support.

 Einschränkungen

Pro Anfrage kann die OCR-App eine maximale Anzahl von 500 Seiten verarbeiten. Wenn das bereitgestellte Dokument mehr als 500 Seiten umfasst, wird die OCR-Erkennung nicht ausgeführt und der zugehörige Job wird als fehlerhaft gekennzeichnet.

Bei der OCR-App erstellte Jobs sind temporär und werden maximal einen Tag gespeichert. Vorsignierte URLs, die von der OCR-App bereitgestellt werden, sind maximal 5 Minuten gültig.

 Unterstützte Formate

Die OCR-App unterstützt eine Reihe von Eingangsformaten:

  • application/pdf
  • image/png
  • image/jpeg
  • image/tiff
  • image/bmp

Die folgenden Zielformate werden unterstützt:

  • text/plain
  • text/html;format=hocr

 Ermitteln der verfügbaren Schnittstellen und Formate

Um die Schnittstellen der OCR-App nutzen zu können, musst du zunächst ermitteln, welche Schnittstellen bereitgestellt werden. Führe dazu eine HTTP GET-Anforderung auf die Rootressource der App aus:

Request


GET /ocr
Accept: application/hal+json

Response


{
    _links: {
        converter: {
            href: "/ocr/convert/features"
        }
    }
}

Folge der angegebenen converter-Linkrelation, um die verfügbaren Schnittstellen zu ermitteln:


GET /ocr/convert/features
Accept: application/hal+json

Response


{
    async: [
        {
            _links: {
                convert: {
                    href: "/ocr/recognition/"
                }
            },
            sourceMimeType: "application/pdf",
            destinationMimeType: "text/plain"
        },
        {
            _links: {
                convert: {
                    "href": "/ocr/recognition/"
                }
            },
            sourceMimeType: "application/pdf",
            destinationMimeType: "text/html;format=hocr"
        },
        {
            _links: {
                convert: {
                    href: "/ocr/recognition/"
                }
            },
            sourceMimeType: "image/png",
            destinationMimeType: "text/plain"
        },
         .....
    ]
}

 Ausführen der OCR-Erkennung

Wenn du die benötigte Schnittstelle ermittelt hast, wie in Kapitel Ermitteln der verfügbaren Schnittstellen und Formate beschrieben, kannst du eine OCR-Erkennung starten.

Erstelle dazu zunächst einen Job bei der OCR-App, indem du eine HTTP POST-Anforderung auf die ermittelte Schnittstelle ausführst. Das gewünschte Zielformat kannst du im Accept-Header angeben.

Request


POST /ocr/recognition
Accept: text/plain
{
   sourceMimeType: "application/pdf",
   callbackUri: "/my-app/callback",
   languageCodes: [
      "deu",
      "eng"
   ],
   appKey: "my-custom-app-key"
}

Hinweise zu den Eigenschaften

EigenschaftTypBeschreibungPflicht
sourceMimeTypestringMime-Typ der zu verarbeitenden Datei. Die unterstützten Formate findest du im Abschnitt Unterstützte Formate.Ja
callbackUristringAngabe einer URI, die beim Abschluss der OCR-Erkennung aufgerufen wird. Nein
languageCodesstring[]Angabe der Sprachen, die vom OCR-Modul zur Erkennung verwendet werden sollen. Zurzeit werden Deutsch (deu) und Englisch (eng) unterstützt. Wenn du für den Parameter keine Angabe machst, werden beide Sprachen verwendet.Nein
appKeystringBenötigter Schlüssel zur Nutzung der Schnittstelle. Wenn du noch keinen App-Schlüssel besitzt, melde dich beim d.velop-Support.Ja

Nach dem Ausführen der zuvor dargestellten Anfrage erhältst du folgende Antwort.

Response


{
    "_links": {
        "self": {
            "href": "/ocr/recognition/my-job-id/"
        },
        "upload": {
            "href": "https://presigned-upload-url"
        }
    },
    "jobId": "my-job-id",
    "sourceMimeType": "application/pdf",
    "status": 0,
}

Hinweise zu den Eigenschaften

EigenschaftBeschreibung
_links.uploadUpload-URL für den Upload der Datei, für die eine OCR-Erkennung ausgeführt werden soll.
jobIdEindeutiger Bezeichner des erstellten Jobs.
statusStatus des Jobs. Eine Aufschlüsselung der möglichen Zustände ist im Abschnitt Beschreibung der möglichen Jobstatus und Seitenstatus dargestellt.

Nach dem erfolgreichen Erstellen eines Jobs musst du anschließend deine Quelldatei bei der OCR-App hochladen, indem du eine HTTP PUT-Anforderung auf die bereitgestellte Route unter der Linkrelation upload durchführst:

Request


PUT https://presigned-upload-url
Content-Type application/pdf

<Binary-Content>

Nach dem erfolgreichen Upload der Datei startet die OCR-Erkennung. Deine App wird über die eingetragene callbackUri benachrichtigt, sobald die Erkennung abgeschlossen wurde. Wenn du keine Callback-URL beim Erstellen des Jobs mitgegeben hast, kannst du den Job mit der in der self-Linkrelation bereitgestellten URL abrufen. In beiden Fällen erhältst du folgendes JSON:

Response


{
    _links: {
        self: {
            href: "/ocr/recognition/my-job-id"
        }
    },
    jobId: "my-job-id",
    sourceMimeType: "application/pdf",
    status: 2,
    message: "",
    pageResults: [
        {
            _links: {
                outputfile: {
                    "href": "https://presigned-outputfile-url"
                }
            },
            index: 0,
            status: 2,
            message: ""
        }
    ]
}

Hinweise zu den Eigenschaften

EigenschaftBeschreibung
jobIdEindeutiger Bezeichner des Jobs.
statusStatus des Jobs. Alle möglichen Zustände sind im Abschnitt Beschreibung der möglichen Jobstatus und Seitenstatus beschrieben.
pageResultsListe der Ergebnisse pro Seite.
pageResults._links.outputfileURL zum Download des Ergebnisses der jeweiligen Seite.
pageResults.indexIndex der Seite.
pageResults.statusStatus der Verarbeitung der Seite. Alle möglichen Zustände sind im Abschnitt Beschreibung der möglichen Jobstatus und Seitenstatus beschrieben.
pageResults.messageFehlermeldung für den Fall, dass bei der Erkennung ein Fehler aufgetreten ist.

 Beschreibung der möglichen Jobstatus und Seitenstatus

Jobstatus

StatusBezeichnungBeschreibung
0WaitingForFileDer Job wurde erfolgreich erstellt. Es wird auf einen Upload der Quelldatei gewartet, um mit der Erkennung starten zu können.
1InProgressDie Verarbeitung ist in Arbeit.
2FinishedDie Verarbeitung wurde erfolgreich ausgeführt.
3ErrorBei der Verarbeitung ist ein Fehler aufgetreten.
4PartialSuccessEs konnte nur eine Teilmenge der in der Quelldatei bereitgestellten Seiten erfolgreich verarbeitet werden.

Seitenstatus

StatusBezeichnungBeschreibung
2FinishedDie Seitenerkennung wurde erfolgreich ausgeführt.
3ErrorEs ist ein Fehler bei der Erkennung der Seite aufgetreten.