Server-Modus

Wird der speedata Publisher im Server-Modus gestartet (sp server), erwartet das Programm HTTP-Anfragen auf Port 5266 (konfigurierbar).

Der Servermodus ist ausschließlich in einer privaten Umgebung einzusetzen. Alle Anwender können über die API-Funktionen an alle erzeugen PDF-Dateien heran kommen. Das wird sich in einer anderen API-Version (v1 oder höher) ändern.

/available

Gibt den HTTP-Status 200 zurück.

/v0/publish

Wird die URL mit einem POST-Request aufgerufen, erwartet der speedata Publisher eine JSON-Datei im folgenden Format:

{<dateiname>:<base64 kodierter Inhalt>,
 <dateiname>:<base64 kodierter Inhalt>,
 ...
 }

also z.B.

{"layout.xml":"PD94bWwgdmVyc2lv....",
 "data.xml":"PGRhdGE+CiAgICA8Y29udGVudHM+PCFbQ0RBVEFbPHV..." }

Diese Dateien werden in ein leeres Verzeichnis kopiert und dort wird sp aufgerufen. Die Rückgabe ist in der Form

{"id":"752869708"}

mit einem HTTP-Statuscode 201 (Created).

Falls die JSON-Datei fehlerhaft ist, wird derzeit ein HTTP-Statuscode 400 (Bad Request) zurückgegeben, mit dem textuellen Inhalt der Fehlermeldung, z.B.:

illegal base64 data at input byte 0

Parameter

Ein URL-Parameter kann angegeben werden, um die Ausgabe der PDF-Datei (ohne Dateiendung) anzugeben:

/v0/publish?jobname=meinedatei setzt den Jobname auf "meinedatei", so dass /v0/pdf/<id> die PDF-Datei mit dem Dateinamen meinedatei.pdf zurückgibt. Das wird mithilfe des HTTP-Headers Content-Disposition erreicht. Wird dieser Parameter nicht angegeben, so wird der jobname aus der Datei publisher.cfg entnommen, die übermittelt wird. Ist dort keine Option jobname gesetzt oder wurde die Datei nicht übermittelt, dann wird der jobname 'publisher' genommen.

Ebenso können zusätzliche Variablen angegeben werden: /v0/publish?vars=var1%3Dwert1. Dies entspricht der Angabe auf der Kommandozeile. Die Übergabe erfolgt in der (URL-Kodierten) Form var1=wert1,var2=wert2,var3=wert3....

/v0/delete/<id>

GET: Löscht das Verzeichnis mit dieser ID. Gibt 200 zurück, wenn die ID vorhanden ist, 404 falls nicht.

/v0/publish/<id>

Ein GET-Request mit einer Id aus dem oben beschriebenen POST-Request liefert eine JSON-Datei, mit dem Inhalt:

{"status":"ok","path":"/pfad/zu/publisher.pdf","blob":"<base64 kodiertes PDF>",
  finished:"2015-03-03T13:12:55+01:00"}

oder, im Fehlerfall, falls die Id unbekannt ist:

{"status":"error","path":"","blob":"id unknown"}

Falls die PDF-Datei noch nicht geschrieben wurde:

{"status":"error","path":"","blob":"in progress"}

Das Verzeichnis mit der PDF-Datei wird nach diesem Request gelöscht, es sei denn, die URL enthält die Endung ?delete=false.

/v0/pdf/<id>

Ein GET-Request mit der Id aus dem POST-Request von /v0/publish. Es wird im Erfolgsfall die PDF-Datei mit dem Statuscode 200 und dem Dateinamen publisher.pdf zurückgegeben. Der Request wartet auf die Fertigstellung des Publishing Prozesses. Im Fehlerfall wird nur ein Fehlercode zurück gegeben:

Statuscode Beschreibung
200 OK PDF wurde fehlerfrei generiert
404 Not Found Id ungültig
406 Not Acceptable PDF wurde fehlerhaft generiert

/v0/data/<id>

Liefert die Daten-Datei, die vorab auf den Server kopiert wurde. Das Format kann über den URL-Parameter format angegeben werden:

Format Beschreibung
json oder JSON Liefert eine JSON-Datei im Format {"contents":"<XML Text>"}
base64 Ergibt eine XML Datei, die base64 kodiert ist (PGRhdGE+CiAgICA8....hPgo=)
(keine Angabe) Schreibt eine XML Datei (<data>...</data>)

Beispiel: http://127.0.0.1:5266/v0/data/1347678770?format=base64

/v0/layout/<id>

Liefert das Layout XML, die vorab auf den Server kopiert wurde. Das Format kann über den URL-Parameter format angegeben werden:

Format Beschreibung
json oder JSON Liefert eine JSON-Datei im Format {"contents":"<XML Text>"}
base64 Ergibt eine XML Datei, die base64 kodiert ist (PGRhdGE+CiAgICA8....hPgo=)
(keine Angabe) Schreibt eine XML Datei (<Layout>...</Layout>)

Beispiel: http://127.0.0.1:5266/v0/layout/1347678770?format=base64

/v0/statusfile/<id>

Liefert die Datei publisher.status, die durch den Lauf erzeugt wurde. Das Format kann über den URL-Parameter format angegeben werden:

Format Beschreibung
json oder JSON Liefert eine JSON-Datei im Format {"contents":"<XML Text>"}
base64 Ergibt eine XML Datei, die base64 kodiert ist (PGRhdGE+CiAgICA8....hPgo=)
(keine Angabe) Schreibt eine XML Datei (<Status>...</Status>)

Beispiel: http://127.0.0.1:5266/v0/statusfile/1347678770?format=base64

/v0/status

Liefert den Status aller Publishing-Läufe zurück, die mit /v0/publish gestartet wurden.

Die zurückgegebene JSON-Datei hat folgende Schlüssel:

{
  "1997009134": {
    "errorstatus": "ok",
    "result": "finished",
    "message": "no errors found",
    "finished": "2016-05-23T11:14:14+02:00"
  },
  "1997329145": {
    "errorstatus": "ok",
    "result": "finished",
    "message": "no errors found",
    "finished": "2016-05-23T11:14:14+02:00"
  }
}

Die einzelnen Felder haben dieselbe Bedeutung wie unter /v0/status/<id> beschrieben.

/v0/status/<id>

Ermittelt den Status des Publisher-Laufs, der per POST-Request an /v0/publish gesendet wurde.

Die zurückgegebene JSON Datei hat folgende Schlüssel:

Schlüssel Beschreibung
errorstatus Ist die Anfrage gültig? Mögliche Antworten error und ok. Wenn error, dann enthält der Schlüssel message den Grund für den Fehler, das Feld result ist in dem Fall ohne Bedeutung. Wenn ok, dann enthält das Feld result den Wert not finished, falls die PDF-Datei noch nicht erzeugt wurde.
result Ist eine PDF-Datei erzeugt worden, enthält das Feld result failed, falls bei der PDF-Erzeugung Fehler aufgetreten sind, not finished, falls der Publishing-Prozess noch fortdauert, ansonsten ok.
message Enthält eine informelle Nachricht zum Ergebnis. Bsp. no errors found oder 2 errors occurred during publishing run.
finished Enthält den Zeitstempel, zu dem das PDF fertig gestellt wurde. Format entspricht RFC3339, zum Beispiel 2015-12-25T12:03:04+01:00.

/v0/format

Erzeugt Trennstellen für einen Text, der per POST-Request übergeben wird. Der Text wird mit XML kodiert und kann feste Umbrüche (<br class="keep" />) oder Trennvorschläge (<shy class="keep" />) enthalten.

Die Rückgabe erfolgt in demselben Format wie die Anfrage.

Die XML-Struktur der Anfrage als auch der Rückgabe muss folgendem RelaxNG-Compact-Schema entsprechen:

namespace a = "http://relaxng.org/ns/compatibility/annotations/1.0"
start =
  element root {
    element text {
      (attribute hyphenate-limit-before { xsd:unsignedInt },
       attribute hyphenate-limit-after { xsd:unsignedInt })?,
      mixed {
        element br {
          attribute class { "keep" | "soft" }?,
          empty
        }+,
        element shy {
          attribute class { "keep" | "soft" }?,
          empty
        }+
      }
    }+
  }
Version: 3.1.24 | Startseite | Elementreferenz | Andere Sprache: Englisch