Đồng bộ dữ liệu Apple Health tới REST API

Gửi dữ liệu sức khỏe tới endpoint REST API.

Last updated: June 9, 2026

Trên trang này

Hướng dẫn tự động hóa REST API

Tự động hóa REST API cho phép bạn tự động xuất dữ liệu sức khỏe tới bất kỳ dịch vụ web nào chấp nhận yêu cầu HTTP POST. Phù hợp khi tích hợp backend tùy chỉnh, API bên thứ ba hoặc webhook.

Yêu cầu theo lô và tải trọng lớn

Khi dùng định dạng JSON, bật Yêu cầu theo lô để gửi dữ liệu trong nhiều yêu cầu HTTP thay vì một tải trọng lớn.

BẬT — Phân tán dữ liệu qua nhiều yêu cầu. Dùng khi điểm cuối có giới hạn kích thước, hết thời gian với thân lớn hoặc xử lý dần.
TẮT — Gửi tất cả dữ liệu trong một yêu cầu. Phù hợp xuất nhỏ và webhook đơn giản.

Khi nào bật lô:

Nhiều chỉ số sức khỏe, khoảng ngày dài hoặc nhóm thời gian chi tiết (phút/giây)
Tóm tắt dữ liệu TẮT và bạn xuất chỉ số sức khỏe phân tách
Máy chủ trả lỗi hoặc hết thời gian với thân POST lớn

Ghi chú:

Yêu cầu theo lô chỉ áp dụng cho REST API + JSON (không CSV).
Lô giảm tải trọng mỗi yêu cầu nhưng không bỏ việc lấy dữ liệu trên thiết bị; truy vấn HealthKit chậm vẫn có thể hiện cảnh báo trong nhật ký hoạt động. Xem Truy vấn chậm trong nhật ký hoạt động.

Tổng quan

Tự động hóa REST API gửi dữ liệu sức khỏe của bạn tới URL đã chọn bằng yêu cầu HTTP POST. Có thể gửi dữ liệu dạng JSON hoặc CSV, kèm header tùy chỉnh để xác thực và siêu dữ liệu.

Trường hợp dùng:

Tích hợp với dịch vụ backend tùy chỉnh
Gửi dữ liệu tới webhook
Đồng bộ với API bên thứ ba
Xây bảng điều khiển hoặc nền tảng phân tích tùy chỉnh

Tính năng chính:

Hỗ trợ cả định dạng JSON và CSV
Header HTTP tùy chỉnh cho xác thực
Thời gian chờ yêu cầu có thể cấu hình
Xuất thủ công dữ liệu lịch sử

Hạn chế:

Truy cập dữ liệu sức khỏe: Ứng dụng không được phép truy cập dữ liệu sức khỏe khi iPhone đang khóa. Tự động hóa chỉ chạy khi thiết bị đã mở khóa. Đây là hạn chế của Apple và không thể vượt qua. Thông tin thêm
Xử lý nền: iOS giới hạn xử lý nền để tiết kiệm pin. Tự động hóa phụ thuộc Làm mới ứng dụng nền và có thể không chạy ngay nếu:
- Đã tắt Làm mới ứng dụng nền cho app
- Thiết bị ở Chế độ nguồn thấp
- Thiết bị không hoạt động trong thời gian dài
- Tài nguyên hệ thống bị hạn chế
- Nhiều app tranh thời gian thực thi nền

Hiệu suất

Hãy lưu ý iOS được tối ưu cho các tác vụ chạy ngắn trên thiết bị di động với ràng buộc hiệu suất rất chặt. Tác vụ nền thường phải hoàn thành trong 30 giây và bị giới hạn bộ nhớ. Health Auto Export cho phép linh hoạt và tùy chỉnh cao, vì vậy cần hiểu cách cấu hình ảnh hưởng đến hiệu suất app và kết quả.

Cấu hình: Tự động hóa tạo lượng dữ liệu lớn có thể khiến hệ thống kết thúc tiến trình và tự động hóa không chạy nền. Các cấu hình sau có thể tạo lượng dữ liệu lớn:
- Tự động hóa cấu hình xuất tất cả chỉ số sức khỏe.
  - Khuyến nghị: chỉ chọn chỉ số có dữ liệu đã lưu trong Apple Health và dữ liệu bạn thực sự dùng. Ngay cả loại dữ liệu trống cũng ảnh hưởng hiệu suất. Có thể chia chỉ số đã chọn qua nhiều tự động hóa để hệ thống xử lý dễ hơn.
- Tự động hóa dùng nhóm thời gian theo giây hoặc phút, hoặc tắt tóm tắt dữ liệu. Truy vấn chi tiết như vậy có thể chạy lâu và xung đột giới hạn hệ thống.
  - Khuyến nghị: dù chi tiết tối đa có vẻ lý tưởng, hãy cân nhắc mỗi chỉ số hoặc loại dữ liệu có cần mức đó không. Cân nhắc nhiều tự động hóa với cài đặt khác nhau.
- Khi xuất tập luyện ngoài trời như đạp xe, chạy, leo núi v.v. kèm dữ liệu tuyến đường, GPS và chỉ số liên quan có thể tạo payload lớn.
Kích thước payload: Đặc biệt khi dùng xuất REST API, payload lớn có thể gây lỗi máy chủ. Đảm bảo backend xử lý được payload có thể lên tới vài trăm megabyte.
Tần suất đồng bộ: Thêm widget tự động hóa vào Màn hình chính giúp tự động hóa chạy nền thành công hơn (xem Thiết lập widget cho tự động hóa).

Điều kiện

Một URL hợp lệ chấp nhận yêu cầu HTTP POST
Thông tin xác thực (nếu endpoint yêu cầu)
Kết nối mạng tới được endpoint của bạn

Cấu hình

Từ điều hướng chính, mở màn hình Xuất tự động, chạm Tự động hóa mới và chọn REST API làm Loại tự động hóa.

Tên tự động hóa

Nhập tên mô tả cho tự động hóa (ví dụ: “API backend của tôi”, “Tích hợp webhook”).

Thông báo

Cấu hình khi nào bạn muốn nhận thông báo:

Thông báo khi cập nhật bộ nhớ đệm — Nhận thông báo khi dữ liệu được lưu đệm được cập nhật
Thông báo khi chạy — Nhận thông báo mỗi khi tự động hóa thực thi

Cấu hình URL

Nhập URL đầy đủ nơi bạn muốn gửi dữ liệu sức khỏe. Phải là URL đầy đủ kèm giao thức (http:// hoặc https://).

Ví dụ URL:

https://api.example.com/health-data
https://webhook.site/your-unique-id
http://localhost:3000/api/health

Lưu ý: URL phải hợp lệ và truy cập được từ thiết bị của bạn. URL không hợp lệ sẽ khiến tự động hóa không chạy được.

Thời gian chờ yêu cầu

Chọn khoảng thời gian chờ cho yêu cầu HTTP. Giá trị này quyết định ứng dụng chờ phản hồi bao lâu trước khi coi yêu cầu thất bại.

Header HTTP

Thêm header HTTP tùy cho xác thực hoặc siêu dữ liệu. Cách dùng thường gặp:

Khóa API: X-API-Key: your-api-key
Token ủy quyền: Authorization: Bearer your-token
Ghi đè kiểu nội dung: Content-Type: application/json

Để thêm header:

Chạm Thêm header
Nhập khóa header vào ô bên trái
Nhập giá trị header vào ô bên phải
Lặp lại cho các header khác

Quan trọng: Mỗi khóa header phải có giá trị tương ứng. Header trống sẽ bị bỏ qua.

Cài đặt loại dữ liệu

Loại dữ liệu

Chọn loại dữ liệu sức khỏe cần xuất:

Chỉ số sức khỏe — Bước, nhịp tim, giấc ngủ và các chỉ số đo lường sức khỏe khác
Buổi tập — Hoạt động thể dục và thể hình
Triệu chứng — Triệu chứng và tình trạng sức khỏe
ECG — Kết quả điện tâm đồ
Thông báo nhịp tim — Sự kiện nhịp tim cao/thấp
Trạng thái tinh thần — Mục tâm trạng và trạng thái tinh thần (iOS 18.0+)
Theo dõi chu kỳ — Dữ liệu chu kỳ kinh nguyệt và sức khỏe sinh sản
Thuốc — Nhật ký thuốc và tuân thủ dùng thuốc (iOS 26.0+)

Cấu hình Chỉ số sức khỏe

Khi chọn Chỉ số sức khỏe:

Chọn chỉ số sức khỏe — Chọn chỉ số cụ thể cần gồm. Bạn có thể chọn tất cả chỉ số có sẵn hoặc chỉ một số loại.

Mẹo: Chỉ chọn chỉ số bạn cần có thể rút ngắn thời gian xử lý và giảm dung lượng dữ liệu.

Nguồn ưu tiên — Cấu hình nguồn dữ liệu được ưu tiên khi nhiều nguồn cung cấp cùng một chỉ số.

Cấu hình Buổi tập

Khi chọn Buổi tập:

Đưa dữ liệu lộ trình — Bật để gồm lộ trình cho các buổi tập có dữ liệu vị trí.

Đưa chỉ số buổi tập — Bật để gồm chỉ số sức khỏe thu trong buổi tập (nhịp tim, calo, v.v.).

Gom nhóm thời gian (chỉ số buổi tập) — Khi dùng Phiên bản xuất 2 và đã bật Đưa chỉ số buổi tập:

Phút — Gom chỉ số buổi tập theo phút
Giây — Gom chỉ số buổi tập theo giây

Cài đặt xuất

Định dạng xuất

Chọn định dạng cho dữ liệu xuất:

Định dạng JSON — Cấu trúc dữ liệu chi tiết với đối tượng lồng nhau. Phù hợp API, cơ sở dữ liệu và ứng dụng cần dữ liệu có cấu trúc. JSON có thông tin chi tiết hơn cho kiểu phức tạp như pha ngủ và kết quả AFib.
Định dạng CSV — Dữ liệu dạng bảng, dễ nhập vào bảng tính. Phù hợp phân tích đơn giản hoặc khi endpoint mong đợi CSV.

Lưu ý: Header Content-Type được đặt tự động thành application/json với xuất JSON và multipart/form-data với xuất CSV.

Phiên bản xuất

Chọn một phiên bản xuất. Phiên bản giúp bạn chuyển dần sang bản xuất mới theo tốc độ của mình và giảm thay đổi phá vỡ quy trình.

Phiên bản 1 — Định dạng cũ; dùng nếu quy trình hiện tại phụ thuộc định dạng này
Phiên bản 2 — Định dạng hiện tại với dữ liệu buổi tập mở rộng và tùy chọn siêu dữ liệu chi tiết hơn

Khoảng ngày

Chọn thời điểm dữ liệu được xuất:

Mặc định — Đồng bộ cả ngày hôm trước đầy đủ cộng dữ liệu tới ngày giờ hiện tại
Kể từ lần đồng bộ trước — Mỗi lần đồng bộ, xuất toàn bộ dữ liệu từ lần chạy trước tới ngày giờ hiện tại
Hôm nay — Đồng bộ mọi dữ liệu của ngày hiện tại tới thời điểm hiện tại
Hôm qua — Đồng bộ mọi dữ liệu của cả ngày hôm trước
7 ngày trước — Đồng bộ dữ liệu cho đủ bảy ngày gần nhất

Tóm tắt dữ liệu

Khi dùng định dạng JSON với loại Chỉ số sức khỏe, bật hoặc tắt Tóm tắt dữ liệu.

Bật — Cung cấp bản tóm tắt dữ liệu đã gộp
Tắt — Khi có thể, cung cấp dữ liệu chi tiết từng điểm

Lưu ý: Cài đặt này chỉ áp dụng cho JSON với Chỉ số sức khỏe. Với CSV hoặc khi chọn nhiều chỉ số, dữ liệu luôn được gộp.

Gom nhóm thời gian

Khi dùng JSON và đã bật Tóm tắt dữ liệu, chọn cách gộp dữ liệu.

Lưu ý: CSV luôn gộp dữ liệu. Gom theo phút hoặc giây có thể tăng đáng kể thời gian xử lý và dung lượng dữ liệu.

Yêu cầu theo lô

Khi dùng JSON, bật Yêu cầu theo lô để gửi dữ liệu theo nhiều yêu cầu thay vì một payload duy nhất.

Bật — Chia dữ liệu qua nhiều yêu cầu để tránh payload quá lớn
Tắt — Gửi toàn bộ dữ liệu trong một yêu cầu

Tần suất đồng bộ

Cấu hình tần suất tự động hóa tải dữ liệu lên:

Chọn một số và một khoảng thời gian.

Kiểm thử và xác minh

Kiểm tra định dạng dữ liệu

Ứng dụng tự động gồm các header sau trong mỗi yêu cầu:

Content-Type — Đặt theo định dạng xuất
automation-name — Tên tự động hóa của bạn
automation-id — Định danh duy nhất của tự động hóa
automation-aggregation — Gom nhóm thời gian đã chọn
automation-period — Khoảng ngày đã chọn
session-id — Định danh duy nhất cho mỗi yêu cầu

Khắc phục sự cố

Vấn đề thường gặp

Không nhận được dữ liệu tại endpoint

Xác minh URL endpoint đúng
Kiểm tra endpoint có chấp nhận yêu cầu POST
Xem lại header xác thực
Xem nhật ký endpoint cho yêu cầu đến
Kiểm tra kết nối mạng

Mẹo và thực hành tốt

Đồng bộ tự động:
- Sạc thiết bị và dùng Phản chiếu iPhone
  - Khi đang sạc, iOS hạn chế hiệu năng ít hơn nên dữ liệu có thể đồng bộ thường xuyên hơn
  - Khi dùng Phản chiếu iPhone, thiết bị hoạt động giống như đang mở khóa, giúp Health Auto Export truy cập dữ liệu sức khỏe để chạy hành động tự động
Hiệu năng:
- Dùng gom nhóm thời gian phù hợp để cân bằng độ chi tiết và dung lượng dữ liệu
- Chỉ chọn chỉ số bạn cần
Độ tin cậy:
- Đặt thời gian chờ phù hợp với thời gian phản hồi của endpoint
- Theo dõi Nhật ký hoạt động định kỳ
Định dạng dữ liệu:
- Dùng JSON cho dữ liệu có cấu trúc và API
- Dùng CSV cho phân tích đơn giản hoặc tích hợp bảng tính
- Cân nhắc yêu cầu theo lô với tập dữ liệu lớn hoặc xử lý tách biệt

Xem nhật ký hoạt động

Chạm Xem nhật ký hoạt động trên màn hình cấu hình tự động hóa.
Xem lại lần chạy (nhóm theo lần chạy, mới nhất trước) và mở rộng sự kiện trong mỗi lần chạy.
Phân biệt cảnh báo (ví dụ truy vấn dữ liệu sức khỏe chậm) với lỗi (lỗi HTTP, hết thời gian hoặc lỗi đọc HealthKit)—xem Tổng quan tự động hóa — Nhật ký hoạt động.
Tải lên REST thành công thường hiển thị tóm tắt với định dạng, loại dữ liệu, kỳ xuất và phạm vi ngày trong lần chạy.
Chia sẻ (thanh công cụ) xuất ZIP chẩn đoán đầy đủ Nhật ký sự kiện ứng dụng cho hỗ trợ (giống Cài đặt → Nâng cao).
Xóa chỉ xóa lịch sử hoạt động của tự động hóa này.