Skip to content

wopi.md

Latest commit

 

History

History
123 lines (84 loc) · 13.4 KB

wopi.md

File metadata and controls

123 lines (84 loc) · 13.4 KB
Raw

WOPI integratie

Overzicht

WOPI (Web Application Open Platform Interface) is een protocol waarmee een webtoepassing documenten kan bekijken en bewerken via een externe opslaan-server, zonder de bestanden zelf te downloaden.

De DMF implementeert een WOPI-host zodat een WOPI-client zoals Collabora Online documenten rechtstreeks uit de DRC kan openen en tonen.

WOPI-endpoints

De WOPI-routes zijn beschikbaar onder het basispad /wopi/api/v1.

Token (DMF-specifiek)

Endpoint Method X-WOPI-Override WOPI-operatie Beschrijving Geïmplementeerd
/wopi/api/v1/token/{file_id} POST — IssueToken (DMF-specifiek) Geeft een kortlopend toegangstoken (SLAT) terug voor het opgegeven document. ✅

Host page (DMF-specifiek)

Endpoint Method Beschrijving Geïmplementeerd
/wopi/files/{file_id}?wopiClient={url} GET Retourneert een pagina die automatisch een POST doet naar de opgegeven WOPI-client-URL, met een correct opgebouwde WOPISrc en het toegangstoken. Vereist het SLAT-token als access_token query parameter of Authorization: Bearer-header. ✅

Files

Endpoint Method X-WOPI-Override WOPI-operatie Beschrijving Geïmplementeerd
/wopi/api/v1/files/{file_id} GET — CheckFileInfo Geeft metadata terug (bestandsnaam, grootte, versie, rechten) als JSON. ✅
/wopi/api/v1/files/{file_id} POST LOCK Lock Vergrendelt het document. ✅
/wopi/api/v1/files/{file_id} POST REFRESH_LOCK RefreshLock Vergrendelt het document. Als het bestand al vergrendeld is met hetzelfde token, wordt de vergrendeling vernieuwd. ❌
/wopi/api/v1/files/{file_id} POST LOCK UnlockAndRelock Vervangt een bestaande vergrendeling door een nieuwe. Vereist de X-WOPI-OldLock- en X-WOPI-Lock-request headers. ✅
/wopi/api/v1/files/{file_id} POST UNLOCK Unlock Ontgrendelt het document. ✅
/wopi/api/v1/files/{file_id} POST GET_LOCK GetLock Geeft de huidige vergrendelingswaarde van het document terug. ❌
/wopi/api/v1/files/{file_id} POST RENAME_FILE RenameFile Hernoemt het document via de X-WOPI-RequestedName header. ✅
/wopi/api/v1/files/{file_id} POST DELETE DeleteFile Verwijdert het document, mits het niet vergrendeld is en geen referenties heeft. ✅
/wopi/api/v1/files/{file_id} POST PUT_RELATIVE PutRelativeFile Maakt een nieuwe versie of kopie aan van het document op basis van X-WOPI-RelativeTarget of X-WOPI-SuggestedTarget. ✅
/wopi/api/v1/files/{file_id} POST GET_SHARE_URL GetShareUrl Geeft een deelbare URL terug voor het document (bijv. voor view-only toegang). ❌
/wopi/api/v1/files/{file_id}/contents GET — GetFile Streamt de binaire bestandsinhoud van het document. ✅
/wopi/api/v1/files/{file_id}/contents POST PUT PutFile Slaat nieuwe bestandsinhoud op (vereist een actieve vergrendeling voor bestaande documenten). ✅

Containers

Endpoint Method X-WOPI-Override WOPI-operatie Beschrijving Geïmplementeerd
/wopi/api/v1/containers/{container_id} GET — CheckContainerInfo Geeft metadata en capabilities terug voor de opgegeven container. ❌
/wopi/api/v1/containers/{container_id} POST DELETE DeleteContainer Verwijdert de container en alle inhoud. ❌
/wopi/api/v1/containers/{container_id} POST RENAME_CONTAINER RenameContainer Hernoemt de container. ❌
/wopi/api/v1/containers/{container_id}/children GET — EnumerateChildren Geeft een lijst van bestanden en subcontainers terug. ❌
/wopi/api/v1/containers/{container_id}/children/containers POST — CreateChildContainer Maakt een nieuwe subcontainer aan. ❌
/wopi/api/v1/containers/{container_id}/children/files POST — CreateChildFile Maakt een nieuw bestand aan in de container. ❌

Ecosystem

Endpoint Method X-WOPI-Override WOPI-operatie Beschrijving Geïmplementeerd
/wopi/api/v1/ecosystem GET — CheckEcosystem Geeft de root-URL terug voor de WOPI-host en ondersteunde capabilities. ❌

WOPI-client instellen

Om de WOPI-host implementatie te kunnen testen is het nodig om een WOPI-client te configureren. Er zijn verschillende WOPI-clients beschikbaar, maar een eenvoudig te installeren en veel gebruikte client is Collabora Online. Wij gaan in dit hoofdstuk ook uit van de Collabora Online WOPI-client maar instructies voor andere clients zijn vergelijkbaar.

Vereisten

  • Een draaiende WOPI-client (bijv. Collabora Online via Docker).
  • De DMF moet bereikbaar zijn vanuit de WOPI-client via HTTP(S).

Configuratie

Stel de volgende omgevingsvariabelen in om WOPI te configureren:

Variabele Standaardwaarde Beschrijving
WOPI_ENABLED false Zet op true om de WOPI-routes in te schakelen
WOPI_SLAT_SECRET (geen) Verplicht wanneer WOPI_ENABLED=true. Salt voor het Short-Lived Access Token (SLAT). Minimaal aanbevolen lengte: 32 tekens.
WOPI_SLAT_TTL_SECONDS 3600 Levensduur in seconden van het SLAT-token.

WOPI_HOST_BASE_URL en WOPI_CLIENT_BASE_URL in het voorbeeld hieronder zijn geen omgevingsvariabelen van de DMF — ze worden nergens in de applicatiecode gelezen. Het zijn illustratieve placeholders voor basis-URLs die de frontend/integrator zelf moet kennen:

  • de publieke basis-URL van de DMF, bereikbaar vanuit de WOPI-clientcontainer (bijv. https://dmf.example.com), gebruikt om de WOPISrc-parameter op te bouwen;
  • de publieke URL van de WOPI-clientinstantie (bijv. https://collabora.example.com), gebruikt als doel van het formulier.

Let op: de DMF-basis-URL moet bereikbaar zijn vanuit de WOPI-clientcontainer.

Document openen via een WOPI-client (bijv. Collabora Online)

De eenvoudigste manier om een document te openen is via de WOPI Host pagina van de DMF zelf (GET /wopi/files/{file_id}).

Stappen

  1. Vraag een kortlopend toegangstoken (SLAT) op via POST /wopi/api/v1/token/{file_id}.

  2. Laad (bijv. in een <iframe>, of door de browser te redirecten) de host page van de DMF:

    GET {DMF_BASE_URL}/wopi/files/{file_id}?wopiClient={WOPI_CLIENT_PAGE_URL}&access_token={SLAT}
    • {DMF_BASE_URL} is het adres waarop de DMF voor de gebruiker bereikbaar is.
    • {WOPI_CLIENT_PAGE_URL} is de volledige, URL-encoded pagina-URL van de WOPI-client (bijv. https://collabora.example.com/browser/<hash>/cool.html). Deze is clientspecifiek en meestal op te vragen via de discovery-endpoint van de WOPI-client.
    • {SLAT} mag in plaats van de query parameter ook worden meegegeven via de Authorization: Bearer-header.

    Voorbeeld:

    GET https://dmf.example.com/wopi/files/dd3283aa-04c1-4f37-809c-345606ecddc9?wopiClient=https%3A%2F%2Fcollabora.example.com%2Fbrowser%2F4610258811%2Fcool.html&access_token=eyJ...

  3. De DMF retourneert een HTML-pagina die automatisch een POST doet naar de WOPI-client met de juiste WOPISrc- en access_token-velden. De WOPI-client haalt het document vervolgens zelf op bij de DMF via /wopi/api/v1/files/{file_id}.

Let op: wopi_test.html in de projectroot demonstreert nog de oudere, handmatige formulier-aanpak en is niet bijgewerkt naar de /wopi/files/{file_id}-hostpagina hierboven. Gebruik dit voorbeeld als referentie om zelf een WOPI Host pagina te bouwen.