Đồ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: April 1, 2026

Trên trang này

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.

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. Điều này có thể ảnh hưởng độ “mới” của dữ liệu. Xem hướng dẫn đồng bộ thủ công để giữ dữ liệu cập nhật.
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 trong nền và có thể không chạy ngay nếu:
- Làm mới ứng dụng trong nền bị tắt cho ứng dụng
- Thiết bị ở chế độ Năng lượng 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 ứng dụng cùng tranh thời gian chạy nền

Đ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

Thử thủ công

Chạm Xuất thủ công trên màn hình cấu hình tự động hóa
Chọn khoảng ngày
Chạm Xuất để gửi yêu cầu thử
Kiểm tra endpoint để xác nhận dữ liệu đã nhận

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 các lần chạy gần đây
Kiểm tra lỗi hoặc cảnh báo
Xác minh thời điểm yêu cầu và trạng thái phản hồi

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