Các phương pháp hay nhất

Áp dụng các mẫu sau để giữ cho tích hợp đối tác dễ dự đoán, dễ quan sát và an toàn cho các cơ sở.

Xác định cơ sở một cách nhất quán

Chọn phương thức liên kết được cấu hình cho tài khoản đối tác của bạn và sử dụng nhất quán:

• Direct Link - sử dụng facility_id của Performance Hub do endpoint cơ sở trả về.
• Linking Identifier - sử dụng mã định danh địa điểm của riêng bạn, chẳng hạn ID chi nhánh, mã địa điểm hoặc số cửa hàng.

Không gửi cả hai mã định danh trong cùng một yêu cầu. Performance Hub xử lý yêu cầu theo phương thức liên kết được cấu hình cho tài khoản đối tác của bạn.

Xem Các phương thức liên kết đối tác để biết hướng dẫn thiết lập.

Ghi theo lô một cách cẩn thận

Partner API chấp nhận nội dung yêu cầu dạng JSON và được thiết kế cho các quy trình đồng bộ theo lô ở những nơi được nêu trong tài liệu. Hãy giữ các lô có kích thước giới hạn và có thể thử lại.

Hướng dẫn mặc định:

• Sử dụng tối đa 1000 mục cho mỗi yêu cầu theo lô để đạt hiệu suất tối ưu.
• Giữ payload dưới 10MB.
• Không vượt quá 5 yêu cầu mỗi giây cho mỗi endpoint.

Giới hạn tốc độ có thể điều chỉnh và được người quản lý tài khoản đối tác Performance Hub của bạn cấu hình theo từng trường hợp. Nếu bạn dự kiến nhập dữ liệu khối lượng lớn, lưu lượng khi ra mắt hoặc bổ sung dữ liệu báo cáo, hãy thống nhất thông lượng cần thiết trước khung thời gian thay đổi.

Nếu bạn cần đồng bộ một tập dữ liệu lớn, hãy chia thành các phần xác định và ghi nhật ký ID của từng phần ở phía bạn. Điều này giúp việc phân tích các lần thử lại thất bại dễ dàng hơn.

Thử lại an toàn

Sử dụng thời gian chờ tăng theo cấp số nhân (exponential backoff) cho các lỗi tạm thời như 429, 500, 502, 503 và 504.

Tránh các vòng lặp thử lại liên tục. Một điểm khởi đầu tốt là:

1. Thử lại sau 1 giây.
2. Thử lại sau 2 giây.
3. Thử lại sau 4 giây.
4. Dừng lại và gửi cảnh báo nếu thao tác vẫn thất bại.

Đối với các lỗi xác thực dữ liệu như 400 hoặc 422, hãy sửa yêu cầu trước khi thử lại.

Sử dụng tính idempotent khi được hỗ trợ

Endpoint mở khóa Door/Gate Controller hỗ trợ idempotency_key không bắt buộc. Dùng lại cùng một khóa cho cùng đối tác, cơ sở và cửa sẽ trả về kết quả hiện có nếu có.

Sử dụng một khóa ổn định cho hành động đang thực hiện, ví dụ ID check-in hoặc ID sự kiện ra vào từ hệ thống của bạn.

Đừng giả định mọi endpoint ghi đều hỗ trợ tính idempotent, trừ khi điều đó được nêu trong tài liệu của endpoint đó.

Giữ dữ liệu nguồn sạch

Gửi các giá trị ổn định, đã chuẩn hóa bất cứ khi nào có thể:

• Sử dụng ID hội viên, gói, cơ sở và check-in nhất quán từ hệ thống nguồn của bạn.
• Sử dụng dấu thời gian ISO 8601 cho ngày và giờ.
• Gửi số điện thoại theo định dạng quốc tế nếu có.
• Gửi đơn vị tiền tệ bằng các trường được nêu trong tài liệu của từng endpoint.
• Tránh nhồi vào các trường văn bản tự do những dữ liệu thuộc về các trường có cấu trúc.

Thiết kế cho cả đồng bộ tăng dần và đồng bộ toàn bộ

Hầu hết các tích hợp đối tác cần cả hai:

• Đồng bộ tăng dần cho các thay đổi hằng ngày.
• Đồng bộ đối soát toàn bộ để khắc phục các sự kiện bị bỏ sót, nhập dữ liệu lịch sử hoặc sai lệch dữ liệu.

Tích hợp của bạn cần có khả năng gửi lại trạng thái hiện tại của một hội viên, gói hội viên hoặc ảnh chụp nhanh báo cáo mà không phụ thuộc vào việc một yêu cầu trước đó đã thành công.

Phát hành Access Time Windows an toàn

Hãy coi giá trị access_time_windows của mỗi hội viên là một ảnh chụp nhanh đầy đủ, có phiên bản độc lập:

• Điều phối một chuỗi access_time_windows_revision tăng đơn điệu duy nhất giữa các worker đồng bộ tăng dần và worker đối soát.
• Thử lại một lần gửi không chắc chắn hoặc lỗi tạm thời với cùng phiên bản và payload đã chuẩn hóa.
• Bỏ qua access_time_windows khi bạn không cập nhật trường này.
• Chỉ gửi [] sau khi một lần truy xuất thành công từ nguồn có thẩm quyền chứng minh rằng không còn khung thời gian nào. Không bao giờ biến một lần hết thời gian chờ từ upstream, kết quả không đầy đủ hoặc lỗi phân tích cú pháp thành việc thu hồi quyền.
• Giữ external_id và scope_key ổn định, và chứng nhận mọi ánh xạ phạm vi trước khi đưa lên production.
• Theo dõi độ cũ của dữ liệu nguồn so với chính sách về độ mới đã thống nhất cho tích hợp đó.

Xem hướng dẫn chính thức dành cho bên tạo dữ liệu Access Time Windows để biết về ảnh chụp nhanh đầy đủ, múi giờ, giờ mùa hè (DST), hủy bỏ và các bộ dữ liệu kiểm thử.

Coi kiểm soát ra vào là yếu tố quan trọng về an toàn

Đối với thao tác mở khóa Door/Gate Controller:

• Hệ thống của bạn phải quyết định người đó có được phép vào hay không trước khi gọi Performance Hub.
• Performance Hub chỉ trả về 200 sau khi bộ điều khiển tại chỗ xác nhận rơ-le đã thực sự mở khóa.
• Hầu hết các xác nhận hoàn tất trong 3-5 giây.
• Hết thời gian chờ là một lần mở khóa thất bại rõ ràng, không phải một thao tác thành công chạy ngầm.
• Chỉ thử lại theo các quy tắc ra vào và an toàn của riêng bạn.

Luôn ghi nhật ký event_id và command_id do endpoint mở khóa trả về.

Giám sát tích hợp của bạn

Sử dụng nhật ký yêu cầu trong Partner Console trong quá trình phát triển và ra mắt. Trên production, hãy duy trì thêm nhật ký của riêng bạn với:

• Dấu thời gian của yêu cầu.
• Endpoint.
• ID bản ghi nguồn.
• Mã định danh cơ sở.
• Mã trạng thái HTTP.
• Nội dung phản hồi hoặc thông báo lỗi từ Performance Hub.

Các trường này giúp việc hỗ trợ và đối soát nhanh hơn nhiều khi khách hàng hỏi điều gì đã xảy ra.