LumiBaseDocs

Data export

Xuất một collection dạng CSV hoặc JSON từ Studio (Content → collection → Export) hoặc qua API. Bản xuất được truyền theo luồng từng trang, nên kích thước collection không bị giới hạn bởi bộ nhớ. Chính file đó có thể được đọc lại làm dữ liệu import, và một vòng export → import → export giữ nguyên mọi giá trị, kể cả bản dịch.

Endpoint

code
GET /api/v1/items/{collection}/export
QueryGiá trịMặc địnhGhi chú
formatcsv, jsoncsv
fieldstên trường, phân cách bằng dấu phẩymọi trường có lưu giá trịid, status, sort, created_at, updated_at luôn được ghi. Trường không tồn tại trả về 400 UNKNOWN_FIELD.
localescác locale, phân cách bằng dấu phẩyCSV: setting locales của site · JSON: mọi localeÁp dụng cho trường dịch được (interface translatable-text).
relationsid, slug, embedidXem Quan hệ.
filterJSON hoặc filter[field][_op]=valuekhông cóCùng cú pháp với endpoint danh sách.
sortphân cách bằng dấu phẩy, - để giảm dầnid
statustrạng thái itemmọi trạng thái

Phản hồi là một file tải về (Content-Disposition: attachment; filename="<collection>-<date>.<format>", Cache-Control: no-store). Đầu vào sai bị từ chối trước khi gửi byte đầu tiên. Request dùng quyền read của người gọi: luật theo dòng lọc các dòng và luật theo trường che giá trị, y hệt endpoint danh sách. Mỗi lần export ghi một mục items_exported vào audit log (collection, định dạng, các trường, locale, chế độ quan hệ, có dùng filter hay không).

bash
curl -H "Authorization: Bearer $TOKEN" -H "X-Lumi-Site: $SITE" \
  "https://api.example.com/api/v1/items/products/export?format=csv&locales=en,vi" -o products.csv

Với SDK:

ts
const res = await client.items('products').export({ format: 'json', fields: ['title', 'price'] });
const doc = await res.json(); // or pipe res.body to a file

Bố cục CSV

  • UTF-8 có byte-order mark, xuống dòng CRLF, đặt ngoặc kép theo RFC 4180.
  • Các cột: id,status,sort,created_at,updated_at, sau đó mỗi trường một cột.
  • Một trường dịch được tách thành mỗi locale một cột: title.en, title.vi.
  • Object và mảng (trường json, quan hệ được nhúng) được ghi dưới dạng chuỗi JSON.
  • Ô trống là null; "" là chuỗi rỗng.
  • Giá trị văn bản bắt đầu bằng =, +, -, @, tab, ký tự xuống dòng (carriage return) hoặc ' được ghi thêm một dấu ' ở đầu, để ứng dụng bảng tính không chạy nó như công thức. Khi đọc lại file làm dữ liệu import, dấu ' đó được bỏ đi.

Bố cục JSON

json
{
  "collection": "products",
  "format": "lumibase-export@1",
  "exportedAt": "2026-11-12T08:00:00.000Z",
  "fields": ["title", "price"],
  "locales": null,
  "relations": "id",
  "items": [
    {
      "id": "x8Kq…",
      "status": "published",
      "sort": 1,
      "created_at": "2026-11-01T10:00:00.000Z",
      "updated_at": "2026-11-02T10:00:00.000Z",
      "data": { "title": { "en": "Coffee", "vi": "Cà phê" }, "price": 10.5 }
    }
  ]
}

locales là null khi giữ mọi locale. JSON giữ chính xác kiểu giá trị; CSV khôi phục số, boolean và JSON dựa theo kiểu trường của collection.

Quan hệ

Chế độTác dụng
idId khoá ngoại như đã lưu. Dùng chế độ này để import lại.
slugVới trường many-to-one, slug của item liên quan thay cho id (giữ id khi item liên quan không có slug).
embedThêm bản ghi liên quan dưới alias của quan hệ (author cho author_id), dạng JSON. Id khoá ngoại vẫn được giữ.

Hook cho extension

Extension loại hook có thể biến đổi từng dòng bằng items.export.before. Hook nhận { collection, item, itemId, userId, siteId }, trong đó item là bản ghi export ({ id, status, sort, created_at, updated_at, data }). Trả về { item } để thay dòng đó; ném lỗi sẽ dừng export.

ts
export default {
  hooks: {
    'items.export.before': async ({ item }) => ({
      item: { ...item, data: { ...item.data, internal_notes: null } },
    }),
  },
};

Import lại

Upload file dưới dạng job import chạy nền: POST /api/v1/imports?collection=… đọc cả hai định dạng đúng như mô tả ở đây, có báo tiến độ, huỷ và báo cáo lỗi theo từng dòng. Dùng mode=upsert để cập nhật các item có id khớp thay vì tạo bản sao.

Liên quan

Last modified: 15/11/2026