Job-API

Jobs werden gestartet (z.B. um Metadaten zu importieren oder zu exportieren) und laufen im Hintergrund. Jobs ermöglichen es, bestimmte Abläufe asynchron abzuarbeiten, ohne den Aufrufer des Jobs zu blockieren. Das Ergebnis eines Jobs kann abgefragt oder heruntergeladen werden, wenn der Job fertig ist.

Hinweis

In den nachfolgenden Beispielen werden zur Veranschaulichung der Server https://www.myserver.com und die Datenbank test sowie das Modell MyModel verwendet (z.B. im Pfad https://www.myserver.com/api/test/schemes/MyModel). Der Server und die Datenbank sowie das Modell sind in allen echten Aufrufen entsprechend zu ersetzen. Je nach Konfiguration muss die URL gegebenenfalls auch noch um den Context-Path erweitert werden (z.B. https://www.myserver.com/dataspot/api/test/schemes/MyModel).

Das Job-API ist eine Programmierschnittstelle, mit welcher Jobs abgefragt und gesteuert werden können.

Asynchroner Upload und Download

Ein asynchroner Upload startet einen Job und gibt die entsprechende Job-ID zurück. Der Job läuft im Hintergrund und führt den Upload durch. Der Status des Jobs kann mit der Job-ID gepollt werden. Wenn der Job fertig ist können die Statistik und ein gegebenenfalls vorhandenes Protokoll abgefragt werden.

Ein asynchroner Download startet einen Job und gibt die entsprechende Job-ID zurück. Der Job läuft im Hintergrund und führt den Download durch. Der Status des Jobs kann mit der Job-ID gepollt werden. Wenn der Job fertig ist können die Daten heruntergeladen sowie die Statistik und ein gegebenenfalls vorhandenes Protokoll abgefragt werden.

Methoden

Ein Job wird durch eine eindeutige Job-ID identifiziert. Die Job-ID wird beim Starten des Jobs zurückgeliefert und muss in allen darauf folgenden Aufrufen verwendet werden.

Das Job-API unterstützt die nachfolgenden HTTP-Methoden und Endpunkte.

`/statistics`

Der Status und die Statistik eines Jobs mit der Job-ID id können mit GET /jobs/id/statistics abgefragt werden:

GET /api/test/jobs/id/statistics HTTP/1.1
Host: www.myserver.com

Der HTTP-Statuscode gibt an, ob der Job noch läuft oder fertig ist:

HTTP-Statuscode	Beschreibung
`200`	Der Job ist fertig
`202`	Der Job läuft noch

Die HTTP-Nachricht enthält den aktuellen Status des Jobs sowie eine Liste von Statistiken:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "messages": [
        {
            "icon": "solid-circle-check",
            "level": "INFO",
            "message": "*Fachdatenmodell.json erzeugen* erfolgreich (00:00:00)."
        },
        {
            "dateGenerated": 1684997710231,
            "icon": "file-code",
            "level": "INFO",
            "message": "105 Objekte exportiert."
        }
    ],
    "status": "COMPLETED"
}

`/download`

Die bereitgestellten Daten eines fertigen Jobs mit der Job-ID id können mit GET /jobs/id/download heruntergeladen werden:

GET /api/test/jobs/id/download HTTP/1.1
Host: www.myserver.com

Die HTTP-Nachricht enthält die heruntergeladenen Daten. Der Internet Media Type (<media type>) und der Dateiname (<filename>) sind abhängig von den Optionen (Format, Report, Zieldatenbank, usw.), die beim Starten des asynchronen Downloads angegeben wurden.

HTTP/1.1 200 
Content-Type: <media type>
Content-Disposition: filename="<filename>"

`/stop`

Ein Job mit der Job-ID id kann mit PUT /jobs/id/stop angehalten werden:

PUT /api/test/jobs/id/stop HTTP/1.1
Host: www.myserver.com

Die HTTP-Nachricht gibt an, ob der Job erfolgreich angehalten werden konnte:

HTTP-Nachricht	Beschreibung
`true`	Der Job wurde erfolgreich angehalten
`false`	Der Job konnte nicht angehalten werden (Job läuft nicht, unbekannte Job-ID, usw.)

`/logs`

Das Protokoll eines Jobs mit der Job-ID id kann mit GET /jobs/id/logs abgefragt werden:

GET /api/test/jobs/id/logs HTTP/1.1
Host: www.myserver.com

Die HTTP-Nachricht enthält eine Liste von Meldungen:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "totalCount": 1,
    "data": [
        {
            "dateGenerated": 1685213572610,
            "level": "ERROR",
            "message": "BusinessObject.inCollection, line: 209: Asset *Organisationen* konnte in Geschäftsobjektmodell *Fachdatenmodell* nicht gefunden werden!"
        }
    ]
}

Beispiele

Für die nachfolgenden Beispiele wird das Open-Source Tool curl verwendet. Alternativ ist jede beliebige Bibliothek geeignet, die über HTTP kommunizieren kann.

Hinweis

Für die Aufrufe sind Zugangsdaten (z.B. jdoe und s3cr3t) erforderlich. Je nach Authentifizierungsmethode (Benutzerkennung und Passwort, Single Sign-On, Same Sign-In, OpenID Connect) und eingesetzten Tools (z.B. curl) können unterschiedliche Mechanismen (z.B. Basic Authentication, Bearer Token) notwendig sein, um die Zugangsdaten bereitzustellen.

Der Report Metadata_pdf.xsl wird im Modell MyModel asynchron gestartet:

curl -X POST -u jdoe:s3cr3t https://www.myserver.com/api/test/schemes/MyModel/download?xsl=Metadata_pdf.xsl

POST /api/test/schemes/MyModel/download?xsl=Metadata_pdf.xsl HTTP/1.1
Host: www.myserver.com

HTTP/1.1 200 OK
Content-Type: application/json

{ "id":"5373479c-d029-4f01-b1a8-703822138d95" }

Die zurückgegebene Job-ID wird verwendet, um den Status (/statistics) des Jobs zu pollen und auf seine Fertigstellung zu warten:

curl -X GET -u jdoe:s3cr3t https://www.myserver.com/api/test/jobs/5373479c-d029-4f01-b1a8-703822138d95/statistics

GET /api/test/jobs/5373479c-d029-4f01-b1a8-703822138d95/statistics HTTP/1.1
Host: www.myserver.com

Der HTTP-Statuscode 202 (Accepted) gibt an, dass der Job noch nicht fertig ist:

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "messages": [
    {
      "icon": "spin-arrows-spin",
      "level": "WARNING",
      "message": "Metadaten Report erzeugen wird durchgeführt... (00:00:01)"
    }
  ],
  "status": "STARTED"
}

Der HTTP-Statuscode 200 (OK) gibt an, dass der Job fertig ist:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "messages": [
    {
      "icon": "solid-circle-check",
      "level": "INFO",
      "message": "Metadaten Report erzeugen erfolgreich (00:00:02)."
    },
    {
      "dateGenerated": 1685228766258,
      "icon": "file-pdf",
      "level": "INFO",
      "message": "Generiere PDF Report (1 MB)"
    }
  ],
  "status": "COMPLETED"
}

Sobald der Job fertig ist, kann der generierte Report heruntergeladen (/download) und in eine Datei gespeichert werden:

curl -X GET -u jdoe:s3cr3t -o "Metadaten Report_MyModel.pdf" https://www.myserver.com/api/test/jobs/5373479c-d029-4f01-b1a8-703822138d95/download

GET /api/test/jobs/5373479c-d029-4f01-b1a8-703822138d95/download HTTP/1.1
Host: www.myserver.com

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: filename="Metadaten Report_MyModel.pdf"

Alternativ kann der laufende Job angehalten (/stop) werden:

curl -X PUT -u jdoe:s3cr3t https://www.myserver.com/api/test/jobs/5373479c-d029-4f01-b1a8-703822138d95/stop

PUT /api/test/jobs/5373479c-d029-4f01-b1a8-703822138d95/stop HTTP/1.1
Host: www.myserver.com

HTTP/1.1 200 OK
Content-Type: application/json

true

Asynchroner Upload und Download​

Methoden​

/statistics​

/download​

/stop​

/logs​

Beispiele​