Panduan automasi REST API

Automasi REST API membolehkan anda mengeksport data kesihatan secara automatik ke mana-mana perkhidmatan web yang menerima permintaan HTTP POST. Ini sesuai untuk penyepaduan dengan backend tersuai, API pihak ketiga atau webhook.

Gambaran keseluruhan

Automasi REST API menghantar data kesihatan anda ke URL endpoint yang ditetapkan menggunakan permintaan HTTP POST. Automasi boleh menghantar data dalam format JSON atau CSV, dengan pengepala boleh konfigurasikan untuk pengesahan dan metadata tersuai.

Kes penggunaan:

• Menyepadukan dengan perkhidmatan backend tersuai
• Menghantar data ke webhook
• Menyegerak dengan API pihak ketiga
• Membina papan pemuka atau platform analitis tersuai

Ciri utama:

• Menyokong format JSON dan CSV
• Pengepala HTTP tersuai untuk pengesahan
• Tamat masa permintaan boleh konfigurasikan
• Eksport data sejarah secara manual

Had:

• Akses data kesihatan: Aplikasi tidak dibenarkan mengakses data kesihatan semasa iPhone dikunci. Automasi hanya berjalan apabila peranti anda tidak dikunci. Ini ialah had Apple yang tidak boleh dipintas. Maklumat lanjut

• Pemprosesan latar belakang: iOS mengehadkan pemprosesan latar belakang untuk menjimatkan bateri. Automasi bergantung pada Muat Semula Apl Latar Belakang dan mungkin tidak berjalan serta-merta jika:

  • Muat Semula Apl Latar Belakang dimatikan untuk aplikasi
  • peranti dalam Mod Kuasa Rendah
  • peranti tidak aktif untuk tempoh yang lama
  • sumber sistem terhad
  • beberapa aplikasi bersaing untuk masa pelaksanaan latar belakang

Prestasi

Ingat bahawa iOS dioptimumkan untuk tugas jangka pendek pada peranti mudah alih dengan kekangan prestasi yang ketat. Tugas latar belakang biasanya perlu disiapkan dalam 30 saat dan terhad dari segi memori. Health Auto Export menawarkan fleksibiliti dan penyesuaian tinggi, jadi penting untuk memahami bagaimana konfigurasi tertentu menjejaskan prestasi apl dan hasilnya.

• Konfigurasi: Automasi yang menghasilkan data dalam jumlah besar boleh menyebabkan sistem menamatkan proses dan automasi tidak berjalan di latar belakang. Konfigurasi berikut boleh menghasilkan data dalam jumlah besar:
  • Automasi yang dikonfigurasi untuk mengeksport semua metrik kesihatan.
    • Cadangan: pilih hanya metrik kesihatan yang mempunyai data disimpan dalam Apple Health dan data yang anda benar-benar akan gunakan. Walaupun jenis data kosong memberi kesan prestasi. Pertimbangkan juga membahagikan metrik terpilih merentas beberapa automasi, yang memudahkan sistem mengendalikannya.
  • Automasi menggunakan pengumpulan masa dalam saat atau minit, atau dengan ringkasan data dimatikan. Pertanyaan sehalus ini boleh mengambil masa lama dan bertembung dengan had sistem.
    • Cadangan: walaupun data sepantas mungkin kelihatan ideal, pertimbangkan sama ada tahap butiran itu diperlukan untuk setiap metrik atau jenis data. Pertimbangkan beberapa automasi dengan tetapan berbeza.
  • Semasa mengeksport senaman luar, seperti berbasikal, berlari, mendaki, dll. dengan data laluan, GPS dan metrik kesihatan berkaitan boleh menghasilkan muatan besar.
• Saiz muatan: Terutamanya apabila menggunakan eksport REST API, muatan besar boleh menyebabkan ralat pelayan. Pastikan backend anda dikonfigurasi untuk mengendalikan muatan yang mungkin beberapa ratus megabyte.
• Kekerapan penyegerakan: Tambahkan Widget Automasi ke Skrin Utama untuk membantu memastikan automasi berjalan berjaya di latar belakang (lihat Sediakan widget untuk Automasi).

Prasyarat

• Endpoint URL sah yang menerima permintaan HTTP POST
• Kelayakan pengesahan (jika diperlukan oleh endpoint anda)
• Sambungan rangkaian untuk mencapai endpoint anda

Permintaan kelompok dan muatan besar

Apabila menggunakan format JSON, hidupkan Permintaan Kelompok untuk menghantar data dalam beberapa permintaan HTTP dan bukannya satu muatan besar.

• HIDUP — Menyebarkan data ke beberapa permintaan. Gunakan apabila endpoint mempunyai had saiz, tamat masa pada badan besar atau memproses data secara berperingkat.
• MATI — Menghantar semua data dalam satu permintaan. Sesuai untuk eksport kecil dan webhook mudah.

Bila mendayakan kelompok:

• Banyak metrik kesihatan dipilih, julat tarikh panjang atau pengelompokan masa halus (minit/saat)
• Ringkaskan Data MATI dan anda mengeksport metrik kesihatan terpisah
• Pelayan mengembalikan ralat atau tamat masa pada badan POST besar

Nota:

• Permintaan kelompok hanya terpakai untuk REST API + JSON (bukan CSV).
• Kelompok mengurangkan saiz muatan setiap permintaan tetapi tidak menghapuskan keperluan mengambil data pada peranti; pertanyaan HealthKit perlahan masih boleh muncul sebagai amaran dalam log aktiviti. Lihat Pertanyaan perlahan dalam log aktiviti.

Konfigurasi

Navigasi ke skrin Eksport Automatik daripada navigasi utama, kemudian ketik "Automasi Baharu" dan pilih "REST API" sebagai Jenis Automasi.

Nama automasi

Masukkan nama deskriptif untuk automasi anda (cth. "API Backend Saya", "Penyepaduan Webhook").

Pemberitahuan

Konfigurasikan bila anda ingin menerima pemberitahuan:

• Beritahu pada kemas kini cache — Terima pemberitahuan apabila data cache dikemas kini
• Beritahu semasa dijalankan — Terima pemberitahuan setiap kali automasi dilaksanakan

Konfigurasi URL

Masukkan URL penuh di mana anda ingin menghantar data kesihatan. Ini patut menjadi URL lengkap termasuk protokol (http:// atau https://).

Contoh URL:

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

Nota: URL mesti sah dan boleh diakses daripada peranti anda. URL tidak sah akan menghalang automasi daripada berjalan.

Tamat masa permintaan

Pilih selang tamat masa untuk permintaan HTTP. Ini menentukan berapa lama apl akan menunggu respons sebelum menganggap permintaan gagal.

Pengepala HTTP

Tambah pengepala HTTP tersuai untuk pengesahan atau metadata. Kes penggunaan biasa termasuk:

• Kunci API: X-API-Key: your-api-key
• Token pengesahan: Authorization: Bearer your-token
• Ganti kandungan: Content-Type: application/json

Untuk menambah pengepala:

1. Ketik "Tambah Pengepala"
2. Masukkan kunci pengepala dalam medan kiri
3. Masukkan nilai pengepala dalam medan kanan
4. Ulangi untuk pengepala tambahan

Penting: Setiap kunci pengepala mesti mempunyai nilai sepadan. Pengepala kosong akan diabaikan.

Tetapan jenis data

Jenis data

Pilih jenis data kesihatan untuk dieksport:

• Metrik kesihatan — Langkah, kadar denyutan jantung, tidur dan ukuran kesihatan lain
• Latihan — Aktiviti senaman dan kecergasan
• Gejala — Gejala dan keadaan kesihatan
• ECG — Bacaan elektrokardiogram
• Pemberitahuan kadar denyutan jantung — Peristiwa kadar tinggi/rendah
• Keadaan minda — Entri mood dan keadaan mental (iOS 18.0+)
• Penjejakan kitaran — Data kitaran haid dan kesihatan reproduktif
• Ubat-ubatan — Log ubat dan pematuhan (iOS 26.0+)

Konfigurasi metrik kesihatan

Apabila Metrik kesihatan dipilih:

Pilih Metrik kesihatan — Pilih metrik tertentu untuk disertakan. Anda boleh memilih semua metrik tersedia atau metrik tertentu.

Petua: Memilih hanya metrik yang anda perlukan boleh meningkatkan masa pemprosesan dan mengurangkan saiz data.

Sumber pilihan — Konfigurasikan sumber data mana mengambil keutamaan apabila berbilang sumber menyediakan metrik yang sama.

Konfigurasi latihan

Apabila Latihan dipilih:

Sertakan data laluan — Togol HIDUP untuk menyertakan laluan bagi latihan yang mempunyai data lokasi.

Sertakan metrik latihan — Togol HIDUP untuk menyertakan metrik kesihatan dikumpul semasa latihan (kadar denyutan jantung, kalori, dll.).

Pengumpulan masa (metrik latihan) — Apabila menggunakan Versi eksport 2 dan Sertakan metrik latihan didayakan:

• Minit — Mengumpulkan metrik latihan mengikut minit
• Saat — Mengumpulkan metrik latihan mengikut saat

Tetapan eksport

Format eksport

Pilih format untuk data dieksport:

• Format JSON — Menyediakan struktur data terperinci dengan objek bersarang. Terbaik untuk API, pangkalan data dan aplikasi yang memerlukan data berstruktur. Format JSON merangkumi maklumat lebih terperinci untuk jenis data kompleks seperti fasa tidur dan bacaan AFib.

• Format CSV — Menyediakan data jadual yang mudah diimport ke apl hamparan. Terbaik untuk analisis data mudah atau apabila endpoint anda menjangka data CSV.

Nota: Pengepala Content-Type ditetapkan secara automatik kepada application/json untuk eksport JSON dan multipart/form-data untuk eksport CSV.

Versi eksport

Pilih Versi eksport. Pembentukan versi membolehkan peralihan antara versi eksport yang dikemas kini mengikut rentak anda sendiri dan mengurangkan perubahan putus pada aliran kerja.

• Versi 1 — Format legasi, gunakan jika anda mempunyai aliran kerja sedia ada yang bergantung pada format ini
• Versi 2 — Format semasa dengan data latihan dipertingkatkan dan lebih pilihan metadata terperinci

Julat tarikh

Pilih bila data patut dieksport:

• Lalai — Menyegerak data untuk hari penuh sebelumnya tambah data sehingga tarikh dan masa semasa
• Sejak penyegerakan terakhir — Pada setiap penyegerakan, mengeksport semua data sejak eksport terakhir berjalan sehingga tarikh dan masa semasa
• Hari ini — Menyegerak semua data untuk tarikh semasa sehingga masa semasa
• Semalam — Menyegerak semua data untuk hari penuh sebelumnya
• 7 hari sebelumnya — Menyegerak data untuk tujuh hari penuh sebelumnya

Ringkaskan data

Apabila menggunakan format JSON dengan jenis data Metrik kesihatan, togol Ringkaskan data HIDUP atau MATI.

• HIDUP — Menyediakan ringkasan data diagregat
• MATI — Menyediakan data tidak diagregat di mana boleh, menunjukkan titik data individu

Nota: Tetapan ini hanya terpakai kepada format JSON dengan Metrik kesihatan. Data sentiasa diagregat apabila menggunakan format CSV atau apabila berbilang metrik dipilih.

Pengumpulan masa

Apabila menggunakan format JSON dengan Ringkaskan data didayakan, pilih cara data diagregat.

Nota: Format CSV sentiasa mengagregat data. Pengumpulan peringkat minit dan saat boleh meningkatkan masa pemprosesan dan saiz data dengan ketara.

Permintaan kelompok

Apabila menggunakan format JSON, togol Permintaan kelompok HIDUP untuk menghantar data dalam kelompok merentas berbilang permintaan berbanding satu muatan.

• HIDUP — Menyebarkan data merentas berbilang permintaan untuk mengelakkan muatan terlalu besar
• MATI — Menghantar semua data dalam satu permintaan

Kaden penyegerakan

Konfigurasikan kerap automasi patut memuat naik data:

Pilih nombor dan selang.

Ujian & pengesahan

Mengesahkan format data

Apl secara automatik menyertakan pengepala ini dalam setiap permintaan:

• Content-Type — Ditetapkan berdasarkan format eksport
• automation-name — Nama automasi anda
• automation-id — Pengecam unik untuk automasi
• automation-aggregation — Pengumpulan masa dipilih
• automation-period — Julat tarikh dipilih
• session-id — Pengecam unik untuk setiap permintaan

Penyelesaian masalah

Isu biasa

Data tidak diterima di endpoint

• Sahkan URL endpoint betul
• Semak bahawa endpoint anda menerima permintaan POST
• Semak pengepala pengesahan
• Semak log endpoint untuk permintaan masuk
• Sahkan sambungan rangkaian

Petua dan amalan terbaik

1. Penyegerakan automatik:

   • Cas peranti anda dan gunakan Cerminan iPhone
     • Apabila peranti dicas iOS meletakkan kurang sekatan pada prestasi peranti, jadi data boleh disegerakkan lebih kerap
     • Dengan menggunakan Cerminan iPhone, peranti anda berkelakuan sama seperti dibuka kunci. Ini bermakna data kesihatan boleh diakses oleh Health Auto Export untuk menjalankan tindakan automatik

2. Prestasi:

   • Gunakan pengumpulan masa yang sesuai untuk mengimbangi terperinci lwn saiz data
   • Pilih hanya metrik yang anda perlukan

3. Kebolehpercayaan:

   • Tetapkan nilai tamat masa sesuai berdasarkan masa respons endpoint anda
   • Pantau Log Aktiviti secara berkala

4. Format data:

   • Gunakan JSON untuk data berstruktur dan API
   • Gunakan CSV untuk analisis data mudah atau penyepaduan hamparan
   • Pertimbangkan permintaan kelompok untuk set data besar atau pemprosesan berasingan

Melihat log aktiviti

1. Ketik Lihat log aktiviti pada skrin konfigurasi automasi.
2. Semak larian (dikumpulkan, terbaharu dahulu) dan kembangkan peristiwa dalam setiap larian.
3. Bezakan amaran (cth. pertanyaan data kesihatan perlahan) daripada ralat (kegagalan HTTP, tamat masa atau kegagalan bacaan HealthKit)—lihat Gambaran Automasi — Log aktiviti.
4. Muat naik REST yang berjaya sering menunjukkan ringkasan dengan format, jenis data, tempoh eksport, dan julat tarikh dalam larian.
5. Kongsi (bar alat) mengeksport ZIP diagnostik penuh Log peristiwa apl untuk sokongan (sama seperti Tetapan → Lanjutan).
6. Kosongkan membuang hanya sejarah aktiviti automasi ini.