mirror of
https://github.com/opencloud-eu/opencloud.git
synced 2026-01-04 11:19:39 -06:00
Merge pull request #2580 from owncloud/app_provider_docs
[docs-only] add app provider docs
This commit is contained in:
Benedikt Kulmann
307
docs/extensions/storage/apps.md
Normal file
307
docs/extensions/storage/apps.md
Normal file
@@ -0,0 +1,307 @@
|
||||
---
|
||||
title: "Apps"
|
||||
date: 2018-05-02T00:00:00+00:00
|
||||
weight: 10
|
||||
geekdocRepo: https://github.com/owncloud/ocis
|
||||
geekdocEditPath: edit/master/docs/extensions/storage
|
||||
geekdocFilePath: apps.md
|
||||
---
|
||||
|
||||
oCIS is all about files. But most of the time you want to do something with files that is beyond the basic upload, download and share behavior. Therefore, oCIS has a concept for apps, that can handle specific file types, so called mime types.
|
||||
|
||||
## App provider capability
|
||||
|
||||
The capabilities endpoint (eg. `https://localhost:9200/ocs/v1.php/cloud/capabilities?format=json`) gives you following capabilities which are relevant for the app provider:
|
||||
|
||||
```json
|
||||
{
|
||||
"ocs": {
|
||||
"data": {
|
||||
"capabilities": {
|
||||
"files": {
|
||||
"app_providers": [
|
||||
{
|
||||
"enabled": true,
|
||||
"version": "1.0.0",
|
||||
"apps_url": "/app/list",
|
||||
"open_url": "/app/open"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
{{< hint info >}}
|
||||
Please note that there might be two or more app providers with different versions. This is not be expected to happen on a regular basis. It was designed for a possible migration period for clients when the app provider needs a breaking change.
|
||||
{{< /hint >}}
|
||||
|
||||
## App registry
|
||||
|
||||
The app registry is the single point where all apps register themselves and their respective supported mime types.
|
||||
|
||||
### Mime type configuration / creation allow list
|
||||
|
||||
The apps will register their supported mime types automatically, so that users can open supported files with them.
|
||||
|
||||
Administrators can set default applications on a per mime type basis and also allow the creation of new files for certain mime types. This per mime type configuration also features a description, file extension option and an icon.
|
||||
|
||||
In order to modify the mime type config you need to set `STORAGE_APP_REGISTRY_MIMETYPES_JSON=.../mimetypes.json` to a valid JSON file with content like this:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"mime_type": "applition/vnd.oasis.opendocument.text",
|
||||
"extension": "odt",
|
||||
"name": "OpenDocument",
|
||||
"description": "OpenDocument text document",
|
||||
"icon": "https://some-website.test/opendocument-text-icon.png",
|
||||
"default_app": "Collabora",
|
||||
"allow_creation": true
|
||||
},
|
||||
{
|
||||
"mime_type": "application/vnd.oasis.opendocument.spreadsheet",
|
||||
"extension": "ods",
|
||||
"name": "OpenSpreadsheet",
|
||||
"description": "OpenDocument spreadsheet document",
|
||||
"icon": "",
|
||||
"default_app": "Collabora",
|
||||
"allow_creation": false
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Fields:
|
||||
|
||||
- `mime_type` is the mime type you want to configure
|
||||
- `extension` is the file extension to be used for new files
|
||||
- `name` is the name of the file / mime type
|
||||
- `description` is a human readable description of the file / mime type
|
||||
- `icon` URL to an icon which should be used for that mime type
|
||||
- `default_app` name of the default app which opens this mime type when the user doesn't specify one
|
||||
- `allow_creation` is wether a user should be able to create new file from that mime type (`true` or `false`)
|
||||
|
||||
### Listing available apps / mime types
|
||||
|
||||
Clients, for example ownCloud Web, need to offer users the available apps to open files and mime types for new file creation. This information can be obtained from this endpoint.
|
||||
|
||||
**Endpoint**: specified in the capabilities in `apps_url`, currently `/app/list`
|
||||
|
||||
**Method**: HTTP GET
|
||||
|
||||
**Authentication**: None
|
||||
|
||||
**Request example**:
|
||||
|
||||
```bash
|
||||
curl 'https://ocis.test/app/list'
|
||||
```
|
||||
|
||||
**Response example**:
|
||||
|
||||
```json
|
||||
{
|
||||
"mime-types": [
|
||||
{
|
||||
"mime_type": "application/pdf",
|
||||
"ext": "pdf",
|
||||
"app_providers": [
|
||||
{
|
||||
"name": "OnlyOffice",
|
||||
"icon": "https://www.pikpng.com/pngl/m/343-3435764_onlyoffice-desktop-editors-onlyoffice-logo-clipart.png"
|
||||
}
|
||||
],
|
||||
"name": "PDF",
|
||||
"description": "PDF document"
|
||||
},
|
||||
{
|
||||
"mime_type": "application/vnd.oasis.opendocument.text",
|
||||
"ext": "odt",
|
||||
"app_providers": [
|
||||
{
|
||||
"name": "Collabora",
|
||||
"icon": "https://www.collaboraoffice.com/wp-content/uploads/2019/01/CP-icon.png"
|
||||
},
|
||||
{
|
||||
"name": "OnlyOffice",
|
||||
"icon": "https://www.pikpng.com/pngl/m/343-3435764_onlyoffice-desktop-editors-onlyoffice-logo-clipart.png"
|
||||
}
|
||||
],
|
||||
"name": "OpenDocument",
|
||||
"icon": "https://some-website.test/opendocument-text-icon.png",
|
||||
"description": "OpenDocument text document",
|
||||
"allow_creation": true
|
||||
},
|
||||
{
|
||||
"mime_type": "text/markdown",
|
||||
"ext": "md",
|
||||
"app_providers": [
|
||||
{
|
||||
"name": "CodiMD",
|
||||
"icon": "https://avatars.githubusercontent.com/u/67865462?v=4"
|
||||
}
|
||||
],
|
||||
"name": "Markdown file",
|
||||
"description": "Markdown file",
|
||||
"allow_creation": true
|
||||
},
|
||||
{
|
||||
"mime_type": "application/vnd.ms-word.document.macroenabled.12",
|
||||
"app_providers": [
|
||||
{
|
||||
"name": "Collabora",
|
||||
"icon": "https://www.collaboraoffice.com/wp-content/uploads/2019/01/CP-icon.png"
|
||||
},
|
||||
{
|
||||
"name": "OnlyOffice",
|
||||
"icon": "https://www.pikpng.com/pngl/m/343-3435764_onlyoffice-desktop-editors-onlyoffice-logo-clipart.png"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"mime_type": "application/vnd.ms-powerpoint.template.macroenabled.12",
|
||||
"app_providers": [
|
||||
{
|
||||
"name": "Collabora",
|
||||
"icon": "https://www.collaboraoffice.com/wp-content/uploads/2019/01/CP-icon.png"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Open a file with the app provider
|
||||
|
||||
**Endpoint**: specified in the capabilities in `open_url`, currently `/app/open`
|
||||
|
||||
**Method**: HTTP POST
|
||||
|
||||
**Authentication** (one of them):
|
||||
|
||||
- `Authorization` header with OIDC Bearer token for authenticated users or basic auth credentials (if enabled in oCIS)
|
||||
- `Public-Token` header with public link token for public links
|
||||
- `X-Access-Token` header with a REVA token for authenticated users
|
||||
|
||||
**Query parameters**:
|
||||
|
||||
- `file_id` (mandatory): id of the file to be opened
|
||||
- `app_name` (optional)
|
||||
- default (not given): default app for mime type
|
||||
- possible values depend on the app providers for a mimetype from the `/app/open` endpoint
|
||||
- `view_mode` (optional)
|
||||
- default (not given): highest possible view mode, depending on the file permissions
|
||||
- possible values:
|
||||
- `write`: user can edit and download in the opening app
|
||||
- `read`: user can view and download from the opening app
|
||||
- `view`: user can view in the opening app (download is not possible)
|
||||
|
||||
**Request examples**:
|
||||
|
||||
```bash
|
||||
curl -X POST 'https://ocis.test/app/open?file_id=ZmlsZTppZAo='
|
||||
|
||||
curl -X POST 'https://ocis.test/app/open?file_id=ZmlsZTppZAo=&app_name=Collabora'
|
||||
|
||||
curl -X POST 'https://ocis.test/app/open?file_id=ZmlsZTppZAo=&view_mode=read'
|
||||
|
||||
curl -X POST 'https://ocis.test/app/open?file_id=ZmlsZTppZAo=&app_name=Collabora&view_mode=write'
|
||||
```
|
||||
|
||||
**Response examples**:
|
||||
|
||||
All apps are expected to be opened in an iframe and the response will give some parameters for that action.
|
||||
|
||||
There are apps, which need to be opened in the iframe with a form post. The form post must include all form parameters included in the response. For these apps the response will look like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"app_url": "https://.....",
|
||||
"method": "POST",
|
||||
"form_parameters": {
|
||||
"access_token": "eyJ0...",
|
||||
"access_token_ttl": "1634300912000",
|
||||
"arbitrary_param": "lorem-ipsum"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
There are apps, which need to be opened in the iframe with a GET request. The GET request must have set all headers included in the response. For these apps the response will look like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"app_url": "https://...",
|
||||
"method": "GET",
|
||||
"headers": {
|
||||
"access_token": "eyJ0e...",
|
||||
"access_token_ttl": "1634300912000",
|
||||
"arbitrary_header": "lorem-ipsum"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Example responses (error case)**:
|
||||
|
||||
- wrong `view_mode`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "SERVER_ERROR",
|
||||
"message": "Missing or invalid viewmode argument"
|
||||
}
|
||||
```
|
||||
|
||||
- unknown `app_name`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "SERVER_ERROR",
|
||||
"message": "error searching for app provider"
|
||||
}
|
||||
```
|
||||
|
||||
- wrong / invalid file id / unauthorized to open the file
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "SERVER_ERROR",
|
||||
"message": "error statting file"
|
||||
}
|
||||
```
|
||||
|
||||
## App drivers
|
||||
|
||||
App drivers represent apps, if the app is not able to register itself. Currently there is only the CS3org WOPI server app driver.
|
||||
|
||||
### CS3org WOPI server app driver
|
||||
|
||||
The CS3org WOPI server app driver is included in oCIS by default. It needs at least one WOPI compliant app (eg. Collabora, OnlyOffice or Microsoft Online Online Server) or a CS3org WOPI bridge supported app (CodiMD or Etherpad) and the CS3org WOPI server.
|
||||
|
||||
Here is a closer look at the configuration of the actual app provider in a docker-compose example (see also [full example](https://github.com/owncloud/ocis/blob/master/deployments/examples/ocis_wopi/docker-compose.yml)):
|
||||
|
||||
```yaml
|
||||
services:
|
||||
ocis:
|
||||
image: owncloud/ocis:latest
|
||||
...
|
||||
environment:
|
||||
...
|
||||
STORAGE_GATEWAY_GRPC_ADDR: 0.0.0.0:9142 # make the REVA gateway accessible to the app drivers
|
||||
|
||||
ocis-appdriver-collabora:
|
||||
image: owncloud/ocis:latest
|
||||
command: storage-app-provider server # start only the app driver
|
||||
environment:
|
||||
STORAGE_GATEWAY_ENDPOINT: ocis:9142 # oCIS gateway endpoint
|
||||
APP_PROVIDER_BASIC_EXTERNAL_ADDR: ocis-appdriver-collabora:9164 # how oCIS can reach this app driver
|
||||
OCIS_JWT_SECRET: ocis-jwt-secret
|
||||
APP_PROVIDER_DRIVER: wopi
|
||||
APP_PROVIDER_WOPI_DRIVER_APP_NAME: Collabora # will be used as name for this app
|
||||
APP_PROVIDER_WOPI_DRIVER_APP_ICON_URI: https://www.collaboraoffice.com/wp-content/uploads/2019/01/CP-icon.png # will be used as icon for this app
|
||||
APP_PROVIDER_WOPI_DRIVER_APP_URL: https://collabora.owncloud.test # endpoint of collabora
|
||||
APP_PROVIDER_WOPI_DRIVER_INSECURE: false
|
||||
APP_PROVIDER_WOPI_DRIVER_IOP_SECRET: wopi-iop-secret
|
||||
APP_PROVIDER_WOPI_DRIVER_WOPI_URL: https://wopiserver.owncloud.test # endpoint of the CS3org WOPI server
|
||||
```
|
||||
Reference in New Issue
Block a user