Bỏ qua, tới nội dung
Tài liệu APIv1

Tích hợp lưu trữ

Discovery và capabilities

Đọc /hosting/discovery để lấy urlsrc theo đuôi tệp và /hosting/capabilities để biết khả năng của máy chủ soạn thảo.

Trong trang này

Máy chủ soạn thảo tự mô tả mình qua hai endpoint công khai, đi qua proxy O3O mà không cần xác thực. WOPI host đọc chúng để biết mở mỗi loại tệp bằng URL nào và máy chủ có những khả năng gì.

GET/hosting/discovery

Danh sách hành động theo loại tệp, dạng XML.

Xác thực: không cầnCộng đồngDoanh nghiệp
GET/hosting/capabilities

Khả năng của máy chủ soạn thảo, dạng JSON.

Xác thực: không cầnCộng đồngDoanh nghiệp

Cấu trúc discovery#

Gốc là <wopi-discovery>, bên trong một <net-zone name="external-http">. Mỗi <app> là một nhóm: theo ứng dụng (writer, calc, impress, draw) hoặc theo kiểu MIME. Mỗi <action>ext (đuôi tệp, rỗng với mục theo MIME), name (edit, view, editnew) và urlsrc.

HTTPTrích discovery của bản DEV (rút gọn)
HTTP/1.1 200 OK
Content-Type: text/xml

<wopi-discovery>
    <net-zone name="external-http">
        <app favIconUrl="http://localhost:8080/browser/825c9caa93/images/x-office-document.svg" name="writer">
            <action default="true" ext="odt" name="edit" urlsrc="http://localhost:8080/browser/825c9caa93/cool.html?"/>
            <action ext="odt" name="view" urlsrc="http://localhost:8080/browser/825c9caa93/cool.html?"/>
            <action default="true" ext="docx" name="edit" urlsrc="http://localhost:8080/browser/825c9caa93/cool.html?"/>
            <action ext="docx" name="view" urlsrc="http://localhost:8080/browser/825c9caa93/cool.html?"/>
            <action ext="docx" name="editnew" urlsrc="http://localhost:8080/browser/825c9caa93/cool.html?"/>
            <!-- ... -->
        </app>
        <app name="calc"> <!-- xlsx, xls, ods, csv ... --> </app>
        <app name="impress"> <!-- pptx, ppt, odp ... --> </app>
        <app name="application/vnd.openxmlformats-officedocument.wordprocessingml.document">
            <action default="true" ext="" name="edit" urlsrc="http://localhost:8080/browser/825c9caa93/cool.html?"/>
            <action default="true" ext="" name="view" urlsrc="http://localhost:8080/browser/825c9caa93/cool.html?"/>
        </app>
        <!-- ... -->
        <app name="Capabilities">
            <action ext="" name="getinfo" urlsrc="http://localhost:8080/hosting/capabilities"/>
        </app>
    </net-zone>
</wopi-discovery>
  • urlsrc kết thúc bằng ?. Nối tiếp WOPISrc=<URL đã mã hoá> và tham số tuỳ chọn như lang=vi.
  • Phần gốc của urlsrc lấy từ O3O_ONLINE_SERVER_NAME; lược đồ là https khi O3O_ONLINE_SSL_TERMINATION=true. Nó không phụ thuộc bạn gọi discovery bằng địa chỉ nào.
  • Đoạn /browser/<hash>/ đổi theo phiên bản máy chủ. Luôn đọc lại discovery, đừng ghi cứng. Nhớ đệm vài phút là đủ.
  • Máy chủ soạn thảo hiện mở được các đuôi như docx, doc, odt, rtf, txt, xlsx, xls, ods, csv, pptx, ppt, odp và nhiều đuôi khác; danh sách chính xác là tập extname="edit". Lớp nhúng O3O.Editor chỉ nhận 12 đuôi liệt kê ở tham chiếu cấu hình.
Đọc urlsrc theo đuôi tệp
# Lấy urlsrc theo đuôi tệp từ discovery (chỉ dùng thư viện chuẩn)
import urllib.request
import xml.etree.ElementTree as ET

O3O_URL = "http://localhost:8080"


def load_actions():
    xml = urllib.request.urlopen(O3O_URL + "/hosting/discovery", timeout=10).read()
    actions = {}
    for action in ET.fromstring(xml).iter("action"):
        ext, name = action.get("ext"), action.get("name")
        if ext:  # bỏ các mục theo kiểu MIME (ext rỗng)
            actions.setdefault((ext, name), action.get("urlsrc"))
    return actions


actions = load_actions()
print(actions[("docx", "edit")])   # http://localhost:8080/browser/<hash>/cool.html?
print(actions[("xlsx", "view")])
print(sorted({ext for ext, name in actions if name == "edit"}))
// Node.js 18 trở lên (có sẵn fetch). Nhớ đệm kết quả vài phút thay vì gọi mỗi lần mở tệp.
const O3O_URL = "http://localhost:8080";

async function urlsrcFor(ext, action = "edit") {
  const xml = await (await fetch(`${O3O_URL}/hosting/discovery`)).text();
  for (const tag of xml.match(/<action\b[^>]*>/g) || []) {
    const attr = (n) => (tag.match(new RegExp(`\\b${n}="([^"]*)"`)) || [])[1];
    if (attr("ext") === ext && attr("name") === action) return attr("urlsrc");
  }
  throw new Error(`no ${action} action for .${ext}`);
}

urlsrcFor("docx").then(console.log);   // http://localhost:8080/browser/<hash>/cool.html?

Capabilities#

200GET /hosting/capabilities trên bản DEV (rút gọn)
{
  "convert-to": {
    "available": true,
    "endpoint": "/cool/convert-to"
  },
  "hasMobileSupport": true,
  "hasProxyPrefix": false,
  "hasSettingIframeSupport": true,
  "hasTemplateSource": true,
  "hasWopiAccessCheck": true,
  "productName": "…",
  "productVersion": "26.04.4.1",
  "productVersionHash": "825c9caa93",
  "serverId": "CDF2D4FC"
}
TrườngÝ nghĩa
productName, productVersionTên và phiên bản của máy chủ soạn thảo. Image DEV trả tên của bản thượng nguồn; image O3O dựng từ nguồn (sắp có) sẽ trả tên O3O. Đừng dựa vào giá trị này để bật tắt tính năng.
convert-toMáy chủ soạn thảo tự báo có endpoint chuyển đổi, nhưng với O3O đường này KHÔNG dùng được từ bên ngoài: o3o-proxy trả 404 cho /cool/convert-to/lool/convert-to. Chỉ Nextcloud cùng mạng Docker, gọi thẳng o3o-online:9980, dùng nó để dựng ảnh xem trước. Muốn chuyển đổi tệp, hãy gọi POST /v1/convert của DocBuilder: có xác thực, hạn mức theo gói và không tính kết nối.
hasMobileSupport, hasWopiAccessCheck, …Cờ khả năng; WOPI host có thể đọc để bật tắt giao diện của mình.
Sắp có

Phần tử <proof-key> trong discovery (khoá công khai để kiểm X-WOPI-Proof). Bản v1 chưa có.