Kiểm thử Data Ingestion API

Tài liệu hướng dẫn sử dụng tính năng và tạo ra một Data Record mẫu vào Model trên hệ thống thông qua luồng tích hợp bằng API Ingestion

Mục đích sử dụng

• Tìm hiểm trước khi sử dụng tính năng Data Ingestion API (tạo dữ liệu trên hệ thống PangoCDP bằng phương pháp tích hợp API để truyền).

Nếu bạn đang tìm kiếm tài liệu để thực hiện tích hợp, vui lòng truy cập tại đây

• Kiểm thử một dữ liệu để xem chi tiết cấu trúc Request Payload (chi tiết dữ liệu đẩy), Respond Result (kết quả phản hồi từ Pango),...

• Kiểm tra các lỗi gặp phải trong cấu trúc dữ liệu, hoặc khi tích hợp thất bại

• Khi có nhu cầu tạo một số rất ít dữ liệu vào Pango Model

Hướng dẫn truy cập tính năng

Tính năng Data Ingestion API hiển thị trên các Model cho phép 3rd Party System có thể dùng API để Ingest Data vào, bao gồm: tất cả các loại Custom Model và một số System Model cho phép.

Khi vào chi tiết Model sẽ thấy hiển thị chức năng , thường xuất hiện khi:

• Truy cập Module CDP, chọn Data Model

  • Bất kỳ Model nào thuộc dạng Custom Model

  • Các System Model khi truy cập, nếu Data Ingestion API được hỗ trợ sẽ Enable, nếu không hỗ trợ sẽ hiển thị
• Ấn chọn để mở giao diện Data Ingestion API

Hướng dẫn sử dụng để tạo Data Record

Data Model

Khi đã truy cập vào giao diện Data Ingestion API sẽ mở tab Data Model - giao diện hiển thị Payload, thông tin dữ liệu mẫu được lưu trữ trên hệ thống Pango Model dưới dạng Json View.

• Ấn vào tên Model để mở cấu hình Model trên Module Console

• Copy Payload để sao chép toàn bộ cấu trúc nội dung Payload
• Attention: các thông tin cần lưu ý khi tiến hành tích hợp, bao gồm:

  • User Event: Sử dụng jeConfigId và jeEventKey để tạo sự kiện khi đưa dữ liệu vào Pango. Đầu tiên, thiết lập sự kiện tại: Data Model / [Model Name]/ Data Manipulation / User Event, sau đó sao chép Event Id vào "jeConfigId" và Event Key vào "jeEventKey".

  • ignoreUpdateCfs: Để tránh cập nhật dữ liệu vào các trường tuỳ chỉnh cụ thể, sử dụng "ignoredUpdateCfs". Ví dụ, để loại trừ cập nhật cho customField01 và customFieldLong03, hãy thiết lập như sau: "ignoredUpdateCfs": [ "customField01", "customFieldLong03" ]

• Cấu trúc dữ liệu cơ bản:

  • objectType: model nhận dữ liệu

  • source: nguồn dữ liệu

  • entries:

    • customField: hỗ trợ các custom Field dưới nhiều định dạng

    • systemField: các Field đã được cố định cho Model với định dạng bắt buộc và yêu cầu phải có mới cho ingest data

    

Advanced Config

Hỗ trợ một số tính năng bổ trợ trong luồng Data Ingestion API, bật Enable để sử dụng. Trên giao diện chọn

Callback Result

Sử dụng tính năng để phản hồi cho Server của 3rd Partner System khi ghi nhận dữ liệu thành công vào hệ thống PangoCDP.

GIao diện hiển thị trên Payload

Trước tiên, 3rd Partner cần tích hợp trước luồng nhận dữ liệu Callback từ Pango dựa vào Document này.

• Endpoint: nhập địa chỉ nhận phản hồi từ Callback Result

• API Key: mã xác thực khi gọi qua hệ thống của 3rd System (mã này do đối tác cung cấp).

⇒ Khi Ingest Data vào PangoCDP, sẽ phản hồi kết quả Success/Fail qua cho hệ thống của Đối tác dựa vào Endpoint và API Key xác thực.

User Event

Sử dụng tính năng để tạo ra 01 User Event khi một Data Record được ghi nhận thành công vào Model.

Giao diện hiển thị trên Payload

Lưu ý: chỉ hiển thị Option này để áp dụng trên các Model cho phép. Thực hiện việc tạo User Event trước trên cấu hình Data Model trên Module Console, có thể truy cập nhanh ghi ấn

• User Event Name: chọn ra User Event đã cấu hình để thêm vào cấu trúc Data Ingest - chỉ những Event có trạng thái Active mới được hiển thị.

• User Event ID: mã nhận diện của User Event, được tự động hiển thị khi đã chọn User Event Name

• User Event Key: mã khoá duy nhât, được tự động hiển thị khi đã chọn User Event Name

Pango Webhook

Sử dụng tính năng để tạo lệnh gửi Webhook đã thiết lập sang hệ thống của 3rd Partner.

Giao diện cấu hình trên Payload

Lưu ý: chỉ hiển thị Option này để áp dụng trên các Model cho phép. Để sử dụng tính năng này, Webhook Status phải được Enabled và cấu hình API Trigger chọn Yes, có thể truy cập nhanh tại

• Webhook Connection: chọn cấu hình Webhook đã thiết lập

• Webhook Event: chọn Event cần tạo trên cấu hình Webhook Connection

Test Ingestion

Authentication

Khai báo cơ chế xác thực, khi Ingest Data vào hệ thống Pango, bao gồm:

• App Connect: chọn account đã được tạo - cần có quyền truyền dữ liệu, ấn Manage App để mở giao diện tạo App Connect.

• Get Token: ấn button nhận Token để tạo ra mã xác thực khi thêm dữ liệu vào hệ thống - lưu ý: chỉ có thể tạo khi đã chọn App Connect.

• Your Token: mã Token được tạo sau khi ấn Get Token.

API Information

Thông tin dùng được cung cấp dùng trong việc tích hợp dữ liệu vào hệ thống Pango Model, ấn Extend Document để mở tài liệu API chi tiết:

• Endpoint: địa chỉ nhận dữ liệu

• Method: hình thức thực hiện truyền dữ liệu (Post: đẩy từ hệ thống bên ngoài vào model)

• Request Parameters: thông tin hệ thống - tham số yêu cầu xác định mục đích đẩy dữ liệu

• Content-type: thông tin hệ thống - kiểu dữ liệu sẽ được thêm vào hệ thống

Request Body

Truyền dữ liệu muốn Ingest thử vào trong Model vào trong các trường dữ liệu, bao gồm:

• Custom Field: các field người vận hành tự thêm vào Model

• System Field: các field mặc định hệ thống tạo ra trong Model

Các Model khác nhau sẽ có các System, Custom Field hoàn toàn khác nhau.

Lưu ý: đối với Model khi Ingest cần các trường bắt buộc (momCode, refId...) tuỳ theo đặc thù. Ngoài ra người vận hành cần đảm bảo định dạng dữ liệu phù hợp cho các Field tương ứng (ví dụ: customField - string, customFieldTimestamp - float,...)

Vui lòng hoàn thành các trường bắt buộc và bổ sung thêm thông tin nếu cần để hệ thống có thể ingest dữ liệu. Sau khi hoàn thành việc điền nội dung ⇒ ấn Execute để thực hiện tích hợp thử

Response Result

Kết quả trả về khi Ingest Data vào Model đang thực hiện, giúp bên tích hợp dễ dàng kiểm tra trước các vấn đề xảy ra khi thực hiện tích hợp. Ấn Copy response để sao chép kết quả phản hồi.

Thực hiện tích hợp thành công bằng cách kiểm tra field "success": true

Khi tích hợp vào hệ thống nếu gặp các vấn đề, sẽ phản hồi lỗi trong Response Result. Tuỳ vào ngữ cảnh hay Model thực hiện Ingest Data mà các lỗi gặp phải sẽ khác nhau - các lỗi này được cung cấp chi tiết trong nội dung Response.

Kiểm tra field thông tin "success": true/false để biết kết quả nhanh nhất ⇒ tiếp đến kiểm tra các field khác để tìm hiểu chi tiết.

FAQ/Tips

Mở giao diện Help Center của Pango tổng hợp các câu hỏi thường gặp khi thực hiện Data Ingestion API (nội dung được cập nhật và thêm mới liên tục bởi đội ngũ Pango).

Tổng kết

Tính năng Data Ingestion API cho phép người dùng và hệ thống bên thứ ba đẩy dữ liệu trực tiếp vào các Data Model trên PangoCDP thông qua API. Đây là công cụ thiết yếu để người vận hành tự kiểm thử dữ liệu, xử lý lỗi tích hợp mà không cần sự hỗ trợ của đội ngũ Tech Team từ đơn giản đến phức tạp, bao gồm:

• Xem trước cấu trúc dữ liệu cần truyền (Request Payload).

• Kiểm tra phản hồi từ hệ thống Pango khi ingest.

• Cấu hình nâng cao như tạo sự kiện người dùng (User Event), gọi webhook, phản hồi callback tới hệ thống bên ngoài.

Quy trình sử dụng bao gồm:

1. Truy cập vào tính năng Data Ingestion API tab trong từng Model trong Module CDP

2. Khai báo đúng Request Body, kèm các trường System/Custom Field phù hợp

3. Sử dụng cấu hình App Connect đã thiết lập để tạo Token

4. Thực hiện ingest thử và kiểm tra kết quả trả về (Response) để đảm bảo dữ liệu hợp lệ

5. Tùy chọn cấu hình thêm các hành động phụ trợ (Webhook, Callback, User Event) nếu nằm trong nhu cầu tích hợp.

Đây là công cụ linh hoạt dành cho team vận hành hoặc đối tác tích hợp cần tạo nhanh dữ liệu vào hệ thống, đảm bảo chuẩn dữ liệu ngay từ giai đoạn kiểm tra tính khả thi, truy tìm lỗi xảy ra.