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

Bắt đầu

Bắt đầu nhanh trong 5 phút Beta

Dựng bản Docker DEV gồm proxy, máy chủ soạn thảo, o3o-gate và DocBuilder, kiểm tra từng dịch vụ, mở trình soạn thảo nhúng và chuyển một tệp .docx sang PDF.

Trang này mô tả tính năng đang ở giai đoạn beta: đã chạy được nhưng có thể còn thay đổi.

Trong trang này

Trang này đưa bạn từ con số không tới một bản O3O Office Online chạy trên máy mình. Năm phút là thời gian khi image đã có sẵn trên máy; lần đầu còn phụ thuộc tốc độ tải image (chưa đo).

Cần chuẩn bị#

  • Docker Engine hoặc Docker Desktop (engine Linux) có Docker Compose v2.
  • Cổng 8080 còn trống; thêm cổng 8081 nếu thử Nextcloud.
  • curl để kiểm tra dịch vụ; một tệp .docx bất kỳ để thử chuyển đổi.
  • Thư mục online/ của mã nguồn O3O Office Online. Chưa có thì liên hệ office@o3o.vn.
  • Cấu hình phần cứng tối thiểu: chưa đo. Bộ đặc tả v1 được kiểm chứng trên Docker Desktop, engine Linux.

Bước 1. Tạo tệp cấu hình .env#

Mọi lệnh trên trang này chạy trong thư mục online/. Tạo .env bằng script sinh bí mật với tuỳ chọn DEV: script chép .env.example thành .env, thay mọi giá trị CHANGE_ME bằng chuỗi ngẫu nhiên 32 ký tự và sinh mã O3O_GATE_INSTANCE_ID. Bước này bắt buộc, vì hồ sơ nextcloud không khởi động được khi còn CHANGE_ME. Script dùng cú pháp bash nên phải gọi bằng bash, không gọi bằng sh.

Tạo .env
cd online
bash scripts/gen-secrets.sh --dev
cd online
powershell -ExecutionPolicy Bypass -File scripts\gen-secrets.ps1 -Dev

Bước 2. Dựng image và khởi động#

Lần đầu, dựng hai image của O3O là o3o/gate:dev và o3o/docbuilder:dev (ngữ cảnh dựng luôn là thư mục online/), rồi khởi động cả bộ:

BashDựng và khởi động
docker build -f gate/Dockerfile -t o3o/gate:dev .
docker build -f docbuilder/Dockerfile -t o3o/docbuilder:dev .
docker compose --env-file .env -f docker/compose.dev.yml up -d
docker compose --env-file .env -f docker/compose.dev.yml ps

Bốn dịch vụ chạy lên: o3o-proxy, o3o-online, o3o-gate, o3o-docbuilder. Chỉ proxy mở cổng ra máy chủ; các dịch vụ còn lại nói chuyện với nhau trong mạng o3o-net. Máy chủ soạn thảo cần thêm một lúc sau khi container chạy mới sẵn sàng; dùng bước 3 để biết khi nào xong.

Bước 3. Kiểm tra từng dịch vụ#

BashBốn lệnh kiểm tra
curl -s http://localhost:8080/o3o/healthz
curl -s http://localhost:8080/o3o/status
curl -s http://localhost:8080/v1/status
curl -s http://localhost:8080/hosting/discovery | head -c 400
LệnhKết quả mong đợi
/o3o/healthz{"ok": true}: tiến trình o3o-gate đang sống.
/o3o/statusedition là community, connections.limit là 50, upstream.coolwsd là ok khi máy chủ soạn thảo đã sẵn sàng, dev_image là true.
/v1/statusservice là o3o-docbuilder; trường core cho biết phiên bản LibreOffice đang chạy trong container; workers.total ít nhất là 1.
/hosting/discoveryXML có các urlsrc dạng http://localhost:8080/browser/<mã>/cool.html?. Sai cổng hoặc sai tên máy thì sửa O3O_ONLINE_SERVER_NAME.
200Ví dụ rút gọn của GET /o3o/status trên máy DEV (máy chủ trả câu thông báo bằng tiếng Việt).
{
  "service": "o3o-gate",
  "version": "1.0.0",
  "api": "v1",
  "edition": "community",
  "dev_mode": true,
  "dev_image": true,
  "license": {
    "state": "none",
    "message": "Không có token bản quyền. Đang chạy bản cộng đồng."
  },
  "connections": {
    "limit": 50,
    "current": 0,
    "pending": 0,
    "peak_5m": 0,
    "readonly": 0,
    "limit_reached": false,
    "source": "adminws",
    "enforcing": true
  },
  "upstream": {
    "coolwsd": "ok"
  },
  "embed": {
    "enabled": true,
    "jwt_required": false,
    "callback_signing": true
  }
}

Bước 4. Mở trình soạn thảo nhúng#

Với O3O_DEV_MODE=1, mở http://localhost:8080/o3o/demo: trang thử mở tệp mẫu sample.docx ở chế độ sửa, in mọi sự kiện ra khung nhật ký và có nút gọi save(), setReadOnly(), close(), getInfo().

Để nhúng vào trang của bạn chỉ cần một phần tử chứa và một thẻ script. Lưu đoạn dưới thành tệp HTML rồi mở qua một máy chủ web bất kỳ trên localhost:

HTMLTrang nhúng tối thiểu
<!doctype html>
<html lang="vi">
<body style="margin:0">
  <div id="editor" style="height:100vh"></div>
  <script src="http://localhost:8080/o3o/api.js"></script>
  <script>
    new O3O.Editor("editor", {
      document: {
        url: "http://localhost:8080/o3o/demo/sample.docx",
        title: "Tài liệu thử.docx",
        fileType: "docx",
        key: "quickstart-1"
      },
      editor: { mode: "edit", lang: "vi", user: { id: "dev-01", name: "Lập trình viên" } },
      events: {
        onDocumentLoaded: function () { console.log("Đã mở tài liệu"); },
        onError: function (e) { console.error(e.code, e.message); }
      }
    });
  </script>
</body>
</html>

Bước 5. Chuyển một tệp sang PDF#

DocBuilder nhận khoá API trong header Authorization: Bearer. Đặt khoá đầu tiên của O3O_DOCBUILDER_API_KEYS trong .env vào biến môi trường O3O_DEMO_KEY:

Nạp khoá mẫu
# Lấy khoá đầu tiên trong O3O_DOCBUILDER_API_KEYS của .env (bỏ phần "ten:" nếu có)
export O3O_DEMO_KEY="$(grep '^O3O_DOCBUILDER_API_KEYS=' .env | cut -d= -f2- | cut -d, -f1 | sed 's/^[^:]*://')"
# In độ dài khoá để chắc đã đọc được (khoá hợp lệ dài 24 tới 128 ký tự)
echo "${#O3O_DEMO_KEY} ký tự"
# Lấy khoá đầu tiên trong O3O_DOCBUILDER_API_KEYS của .env (bỏ phần "ten:" nếu có)
$line = (Select-String -Path .env -Pattern '^O3O_DOCBUILDER_API_KEYS=').Line
$env:O3O_DEMO_KEY = (($line -split '=', 2)[1] -split ',')[0] -replace '^[^:]*:', ''
# In độ dài khoá để chắc đã đọc được (khoá hợp lệ dài 24 tới 128 ký tự)
$env:O3O_DEMO_KEY.Length
POST/v1/convert

Chuyển đổi định dạng trong cùng một họ tài liệu (văn bản, bảng tính, trình chiếu). Gửi tệp bằng multipart/form-data hoặc gửi url bằng JSON.

Xác thực: BearerCộng đồngDoanh nghiệp
Chuyển .docx sang PDF
curl -s -X POST http://localhost:8080/v1/convert \
  -H "Authorization: Bearer $O3O_DEMO_KEY" \
  -F "file=@hop-dong.docx" \
  -F "to=pdf" \
  -o hop-dong.pdf
curl.exe -s -X POST http://localhost:8080/v1/convert `
  -H "Authorization: Bearer $env:O3O_DEMO_KEY" `
  -F "file=@hop-dong.docx" `
  -F "to=pdf" `
  -o hop-dong.pdf
// Node.js 18 trở lên (fetch, FormData, Blob có sẵn)
import { readFile, writeFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("hop-dong.docx")]), "hop-dong.docx");
form.append("to", "pdf");

const res = await fetch("http://localhost:8080/v1/convert", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.O3O_DEMO_KEY },
  body: form
});
if (!res.ok) throw new Error((await res.json()).error.code);
await writeFile("hop-dong.pdf", Buffer.from(await res.arrayBuffer()));
import os
import requests

with open("hop-dong.docx", "rb") as f:
    r = requests.post(
        "http://localhost:8080/v1/convert",
        headers={"Authorization": "Bearer " + os.environ["O3O_DEMO_KEY"]},
        files={"file": ("hop-dong.docx", f)},
        data={"to": "pdf"},
        timeout=120,
    )
r.raise_for_status()
with open("hop-dong.pdf", "wb") as f:
    f.write(r.content)
<?php
$ch = curl_init("http://localhost:8080/v1/convert");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("O3O_DEMO_KEY")],
    CURLOPT_POSTFIELDS => ["file" => new CURLFile("hop-dong.docx"), "to" => "pdf"],
    CURLOPT_RETURNTRANSFER => true,
]);
$pdf = curl_exec($ch);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200) {
    exit($pdf);
}
file_put_contents("hop-dong.pdf", $pdf);
using System.Net.Http.Headers;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("O3O_DEMO_KEY"));

using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(File.ReadAllBytes("hop-dong.docx")), "file", "hop-dong.docx");
form.Add(new StringContent("pdf"), "to");

var res = await http.PostAsync("http://localhost:8080/v1/convert", form);
res.EnsureSuccessStatusCode();
File.WriteAllBytes("hop-dong.pdf", await res.Content.ReadAsByteArrayAsync());
200Chế độ đồng bộ trả thẳng tệp PDF. Header X-O3O-Job-Id và X-O3O-File-Id cho biết mã job và mã tệp.
401Thiếu hoặc sai khoá. detail.reason là missing, invalid hoặc no_keys_configured; câu message dưới đây chỉ là ví dụ.
{
  "error": {
    "code": "unauthorized",
    "message": "Khoá API không hợp lệ.",
    "detail": {
      "reason": "invalid"
    },
    "request_id": "req_0123456789abcdef"
  }
}

Bản cộng đồng nhận tệp tối đa 10 MB, 10 yêu cầu xử lý mỗi phút và 200 yêu cầu mỗi ngày. Hạn mức đầy đủ ở trang Các gói và khác biệt tính năng.

Bước 6 (tuỳ chọn). Thử với Nextcloud#

Hồ sơ nextcloud thêm Nextcloud 30, MariaDB 11 và Redis 7; Nextcloud mở ở http://localhost:8081. Bật hồ sơ rồi chạy script setup-nextcloud: script chờ Nextcloud cài xong, cài ứng dụng kết nối richdocuments, chạy richdocuments:activate-config với cả địa chỉ máy chủ soạn thảo trong mạng nội bộ (-w http://o3o-online:9980) lẫn địa chỉ để máy chủ soạn thảo gọi ngược về Nextcloud (-c http://o3o-nextcloud), đọc lại cấu hình, rồi tạo người dùng thử kèm ba tệp mẫu. Tên và mật khẩu người dùng thử được in ra ở cuối.

Bật hồ sơ nextcloud và đấu nối
docker compose --env-file .env -f docker/compose.dev.yml --profile nextcloud up -d
bash scripts/setup-nextcloud.sh
docker compose --env-file .env -f docker/compose.dev.yml --profile nextcloud up -d
powershell -ExecutionPolicy Bypass -File scripts\setup-nextcloud.ps1

Muốn làm tay thì chờ http://localhost:8081/status.php báo "installed":true, rồi chạy hai lệnh occ dưới. Lệnh thứ hai phải có đủ -w và -c:

BashLàm tay bằng occ
docker compose --env-file .env -f docker/compose.dev.yml --profile nextcloud exec -u www-data o3o-nextcloud php occ app:install richdocuments
docker compose --env-file .env -f docker/compose.dev.yml --profile nextcloud exec -u www-data o3o-nextcloud php occ richdocuments:activate-config -w http://o3o-online:9980 -c http://o3o-nextcloud

Khi mọi thứ đã chạy#

  • /o3o/status báo upstream.coolwsd = ok và connections.enforcing = true.
  • Trang /o3o/demo phát onReady rồi onDocumentLoaded; gõ chữ và bấm lưu thì có sự kiện onSaved.
  • Lệnh chuyển đổi tạo ra tệp PDF mở được.
  • Mở cùng một tài liệu ở chế độ sửa trong hai tab thì connections.current tăng thêm 2; mở ở chế độ chỉ đọc thì không đổi.

Dọn dẹp#

BashDừng và xoá
docker compose --env-file .env -f docker/compose.dev.yml --profile nextcloud down -v

Tiếp theo#

Kiến trúc và thành phầnĐịnh tuyến, luồng dữ liệu, cổng và biến môi trường.Chọn cách tích hợpNextcloud, WOPI tự viết, O3O.Editor hay chỉ DocBuilder.Các góiHạn mức của bản cộng đồng và bảng giá bản doanh nghiệp.

Báo lỗi hoặc góp ý cho trang nàyO3O Office Online · API v1 · Phiên bản trang 26.8.6