Zum Hauptinhalt springen

Dokumente

Bei den REST-Webservices benutzt der webPDF-Server einen "Dokumentenspeicher" (Storage) auf dem Server, um die zu bearbeitenden Dokumente zwischen den einzelnen Webservice-Aufrufen zu speichern.

Dieser Storage wird mittels eines Zugriffstoken (Autorisierung) dem Benutzer zugeordnet und bildet eine Session. Der Zugriffstoken und somit auch die Session, wird über den Webservice "Authentication" initialisiert. Wird eine Session beendet (Logout) oder läuft sie ab (Timeout), so wird der Token ungültig, der Storage entfernt und alle Dokumenten darin auf dem Server gelöscht.

Bei jedem Zugriff auf den Storage muss in dem Request an die REST-API der Zugriffstoken angegeben werden (siehe Autorisierung). Dieser referenziert indirekt die Session und somit die Dokumente in dem Storage.

Um den Storage zu benutzen, stellt der webPDF-Server einen Webservice mit dem URI

/documents/... (API {REST})

zur Verfügung. Mit entsprechenden HTTP-Operation wie z.B. POST oder GET können Dokumente auf den Storage hochgeladen oder von dort herunter geladen werden.

Vorsicht

Bitte beachten Sie, dass bei jedem Webservice-Aufruf der Zugriffstoken, den Sie durch "Authentication" erhalten haben, im HTTP-Header (oder optional als gleichnamiger Query-Parameter) übergeben werden muss (siehe Autorisierung).

Beispiel: Abruf von Informationen über das Dokument "605c045c129a40adb95d7623e279fe8a" aus der Session mit dem Zugriffstoken "eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw" (Zugriffstoken gekürzt).

curl -X GET -i -H 'Accept: application/json' -H 'Authorization: Bearer eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw' http://localhost:8080/webPDF/rest/documents/605c045c129a40adb95d7623e279fe8a/info

Dokumenten-ID

Jedes Dokument, das in dem Storage gespeichert ist, bekommt eine eindeutige ID (Unique "documentId"). Diese ID wird bei einem Upload eines Dokument mit

curl -X POST -i -H 'Content-Type: multipart/form-data' -H 'Authorization: Bearer eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw' -F 'filedata=@sample.jpg' http://localhost:8080/webPDF/rest/documents

erstellt und in der JSON-Antwort des Webservice mitgeliefert (siehe unten). Diese ID wird dann in der URI der Webservices zur Ausführung von PDF-Funktionen zur Auswahl des Dokuments benötigt.

Upload eines Dokuments

Der Upload eines Dokuments in den Storage erfolgt über die URI

POST /documents (API {REST})

als POST in Form eines "multipart/form-data" Dokuments.

curl -X POST -i -H 'Content-Type: multipart/form-data' -H 'Authorization: Bearer eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw' -F 'filedata=@Akquise.docx' http://localhost:8080/webPDF/rest/documents  

HTTP/1.1 100

In dem "request body" wird die Datei übergeben. Wichtig ist die Verwendung des Namens "filedata" in "Content-Disposition":

-----------------------------202131351012485  
Content-Disposition: form-data; name="name"
Akquise.docx
-----------------------------202131351012485
Content-Disposition: form-data; name="filedata"; filename="Akquise.docx"
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
<... binary data follows ...>

Nach dem Upload antwortet der Webservice mit einem HTTP "303 - SEE OTHER" und im Header "Location" mit einer URL.

HTTP/1.1 303  
Location: http://localhost:8080/webPDF/rest/documents/605c045c129a40adb95d7623e279fe8a/info
Cache-Control: no-cache, no-store, no-transform, proxy-revalidate, max-age=0
Content-Length: 0

Unter der URL in "Location" können jetzt die weiteren Informationen über das Dokument abgerufen werden. Wichtig in der URL ist die "documentID" 605c045c129a40adb95d7623e279fe8a unter der das Dokument auf dem Server abgespeichert ist.

Wenn jetzt mit

curl -X GET -i -H 'Accept: application/json' -H 'Authorization: Bearer eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw' http://localhost:8080/webPDF/rest/documents/605c045c129a40adb95d7623e279fe8a/info

die Informationen abgerufen werden, dann antwortet der Server mit einer JSON-Struktur, die alle Informationen zu dem Dokument enthält.

{  
 "documentId": "605c045c129a40adb95d7623e279fe8a",
 "parentDocumentId": "",
 "fileSize": 12703,
 "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
 "fileName": "Akquise",
 "fileExtension": "docx",
 "fileTypeId": 1384,
 "fileTypeGroups": "OFFICE,WORD",
 "fileLastModified": "Mon, 19 Aug 2019 11:01:30 GMT",
 "isFileLocked": false,
 "error": {
   "errorMessage": "No error",
   "errorCode": 0,
   "stackTrace": ""
 }
}

Wichtig in dieser Antwort ist die "documentId". Diese wird für die weiteren Aufrufe benötigt, um die Datei zu referenzieren.

Upload mit automatischen Redirect

Wenn Sie die REST-API mit einem Client verwenden, der ein automatisches "redirect" durchführen kann, dann verkürzen Sie damit die Anzahl der Aufrufe und erhalten direkt als Antwort die entsprechende JSON-Struktur auf das hoch geladene Dokument:

curl -i -L -H 'Content-Type: multipart/form-data' -H 'Authorization: Bearer eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw' -F 'filedata=@sample.jpg' http://localhost:8080/webPDF/rest/documents  

HTTP/1.1 100

HTTP/1.1 303
Location: http://192.168.1.31:8080/webPDF/rest/documents/605c045c129a40adb95d7623e279fe8a/info
...

HTTP/1.1 200
Content-Type: application/json
...
{"documentId":"605c045c129a40adb95d7623e279fe8a","parentDocumentId":"","fileSize":11277,"mimeType":"image/jpeg","fileName":"sample","fileExtension":"jpg","fileTypeId":1535,"fileTypeGroups":"IMAGE","fileLastModified":"Tue, 11 Aug 2020 09:37:44 GMT","isFileLocked":false,"metadata":{},"error":{"errorMessage":"No error","errorCode":0,"stackTrace":""}}

Dokument konvertieren und verwalten

Um dieses Dokument zu konvertieren, wird der Webservice "Converter" mit der "documentId" im URI aufgerufen:

POST /webPDF/rest/converter/67b4e25d3c1a498e9b5a7f8221b2bf0c (API {REST})

Um Informationen über das Dokument im Storage zu erhalten, wird folgendes aufgerufen:

GET /webPDF/rest/documents/67b4e25d3c1a498e9b5a7f8221b2bf0c/info (API {REST})

Um dieses Dokument dann aus dem Storage zu löschen, wird

DELETE /webPDF/rest/documents/67b4e25d3c1a498e9b5a7f8221b2bf0c (API {REST})

aufgerufen.