Chuyển đến nội dung chính

Giới thiệu

Mô-đun IntegrationCollections lưu trữ dữ liệu được sử dụng để tích hợp các dịch vụ và hệ thống khác nhau.

Để tích hợp các dịch vụ bên thứ ba, trước tiên bạn cần tạo và cấu hình các bộ sưu tập.

Thông tin thêm về giao diện người dùng của mô-đun https://doc.oneentry.cloud/docs/category/integration-collections

🎯 Mô-đun này làm gì?​

Mô-đun IntegrationCollections cho phép bạn đọc và quản lý các bộ sưu tập — các bảng có cấu trúc của các bản ghi được sử dụng để tích hợp OneEntry với các dịch vụ và hệ thống bên ngoài. Mỗi bộ sưu tập được định nghĩa bởi một biểu mẫu (lược đồ của nó); mỗi bản ghi (hàng) giữ formData đã được gửi.

Định nghĩa một bộ sưu tập và biểu mẫu của nó trong bảng điều khiển quản trị, sau đó lấy, tạo, cập nhật và xóa các hàng của nó từ ứng dụng của bạn.

🚀 Bắt đầu nhanh​

Khởi tạo mô-đun từ defineOneEntry:


const { IntegrationCollections } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Lấy tất cả các bộ sưu tập và đọc các trường của chúng:

// Returns an array of collections (langCode defaults to the configured language).
const collections = await IntegrationCollections.getICollections("en_US");

collections.forEach((collection) => {
  console.log(collection.id, collection.identifier, collection.formId);
});

✨ Khái niệm chính​

Bộ sưu tập vs. Hàng​

  • Bộ sưu tập (ICollectionEntity) — bộ chứa/lược đồ. Nó tham chiếu đến một biểu mẫu (formId) và một tập hợp thuộc tính, và mang thông tin địa phương hóa.
  • Hàng (ICollectionRow) — một bản ghi đơn lẻ bên trong một bộ sưu tập, giữ formData (một mảng của { marker, type, value }), dấu thời gian, và một thực thể liên kết tùy chọn (entityType / entityId).

Cấu trúc Bộ sưu tập​

{
  id: 1,
  identifier: 'collection1',
  formId: 1234,
  localizeInfos: { title: 'Admins text' },
  attributeSetId: 1234,
  selectedAttributeMarkers: 'collection_marker'
}

Cấu trúc Hàng​

{
  id: 1,
  createdDate: '2025-06-06T19:08:54.616Z',
  updatedDate: '2025-06-06T19:08:54.616Z',
  collectionId: 1,
  formData: [
    { marker: 'name_1', type: 'string', value: 'Value' }
  ],
  entityType: null,
  entityId: null,
  attributeSetIdentifier: null
}

Tạo hoặc cập nhật hàng​

Truyền một đối tượng biểu mẫu (ICollectionFormObject) với định danh biểu mẫu và các giá trị trường:

const body = {
  formIdentifier: 'collection-form',
  formData: [
    { marker: 'collection_marker', type: 'string', value: 'Collection marker' }
  ]
};

await IntegrationCollections.createICollectionRow('collection1', body);

📋 Những điều bạn cần biết​

Các bộ sưu tập được định nghĩa trong bảng điều khiển quản trị​

Các bộ sưu tập và biểu mẫu của chúng được tạo và cấu hình trong bảng điều khiển quản trị OneEntry. SDK được sử dụng để đọc các bộ sưu tập và quản lý các hàng của chúng (tạo / cập nhật / xóa).

Xóa hàng yêu cầu quyền​

deleteICollectionRowByMarkerAndId() yêu cầu quyền collections.row.delete; nếu không có quyền này, việc xóa sẽ thất bại.

📊 Bảng tham khảo nhanh​

Phương thứcMô tả
getICollections()Lấy tất cả các bộ sưu tập.
getICollectionById()Lấy một bộ sưu tập đơn lẻ theo id.
getICollectionRowsById()Lấy tất cả các hàng của một bộ sưu tập theo id bộ sưu tập.
getICollectionRowsByMarker()Lấy tất cả các hàng của một bộ sưu tập theo marker.
getICollectionRowByMarkerAndId()Lấy một hàng đơn lẻ theo marker bộ sưu tập và id hàng.
validateICollectionMarker()Kiểm tra xem một marker bộ sưu tập có tồn tại hay không.
createICollectionRow()Tạo một hàng trong một bộ sưu tập.
updateICollectionRow()Cập nhật một hàng trong một bộ sưu tập.
deleteICollectionRowByMarkerAndId()Xóa một hàng bộ sưu tập (cần quyền collections.row.delete).

❓ Câu hỏi thường gặp (FAQ)​

Các bộ sưu tập được tạo ở đâu?​

Các bộ sưu tập và biểu mẫu của chúng được tạo và cấu hình trong bảng điều khiển quản trị OneEntry. SDK được sử dụng để đọc các bộ sưu tập và quản lý các hàng của chúng (tạo / cập nhật / xóa).

Sự khác biệt giữa một bộ sưu tập và một hàng bộ sưu tập là gì?​

Một bộ sưu tập là định nghĩa bảng (lược đồ biểu mẫu và siêu dữ liệu của nó). Một hàng bộ sưu tập là một bản ghi đơn lẻ được lưu trữ trong bộ sưu tập đó, mang các giá trị formData của nó.

🎓 Thực hành tốt nhất​

  • Định nghĩa các bộ sưu tập trong bảng điều khiển quản trị - SDK đọc các bộ sưu tập và quản lý các hàng của chúng, không phải lược đồ.
  • Xác thực các marker trước khi sử dụng - Sử dụng validateICollectionMarker() để xác nhận một marker bộ sưu tập tồn tại.
  • Khớp các trường biểu mẫu với lược đồ - Các marker/type của formData phải khớp với biểu mẫu của bộ sưu tập.
  • Đảm bảo quyền xóa - deleteICollectionRowByMarkerAndId() cần quyền collections.row.delete.

🔗 Tài liệu liên quan​