Panduan otomatisasi REST API

Automatisasi REST API memungkinkan Anda mengekspor data kesehatan secara otomatis ke layanan web apa pun yang menerima permintaan HTTP POST. Ini ideal untuk integrasi dengan backend kustom, API pihak ketiga, atau webhook.

Ringkasan

Automatisasi REST API mengirim data kesehatan Anda ke endpoint URL yang ditentukan menggunakan permintaan HTTP POST. Otomatisasi dapat mengirim data dalam format JSON atau CSV, dengan header yang dapat dikonfigurasi untuk autentikasi dan metadata kustom.

Contoh penggunaan:

• Integrasi dengan layanan backend kustom
• Mengirim data ke webhook
• Sinkronisasi dengan API pihak ketiga
• Membangun dashboard kustom atau platform analitik

Fitur utama:

• Mendukung format JSON dan CSV
• Header HTTP kustom untuk autentikasi
• Batas waktu permintaan yang dapat dikonfigurasi
• Ekspor manual data historis

Batasan:

• Akses data kesehatan: Aplikasi tidak diizinkan mengakses data kesehatan saat iPhone terkunci. Otomatisasi hanya berjalan saat perangkat Anda tidak terkunci. Ini adalah batasan Apple yang tidak dapat diatasi. Informasi selengkapnya

• Pemrosesan latar belakang: iOS membatasi pemrosesan latar belakang untuk menghemat baterai. Otomatisasi bergantung pada Penyegaran Aplikasi Latar Belakang dan mungkin tidak langsung berjalan jika:

  • Penyegaran Aplikasi Latar Belakang dinonaktifkan untuk aplikasi
  • perangkat dalam Mode Daya Rendah
  • perangkat tidak aktif dalam waktu lama
  • sumber daya sistem terbatas
  • beberapa aplikasi bersaing untuk waktu eksekusi latar belakang

Kinerja

Perlu diingat bahwa iOS dioptimalkan untuk tugas berjalan singkat di perangkat seluler dengan batasan kinerja yang ketat. Tugas latar belakang biasanya harus selesai dalam 30 detik dan dibatasi memori yang dapat digunakan. Health Auto Export menawarkan fleksibilitas dan kustomisasi tinggi, sehingga penting memahami bagaimana konfigurasi tertentu memengaruhi kinerja aplikasi dan hasilnya.

• Konfigurasi: Otomatisasi yang menghasilkan data dalam jumlah besar dapat menyebabkan sistem menghentikan proses sehingga otomatisasi tidak berjalan di latar belakang. Konfigurasi berikut dapat menghasilkan data dalam jumlah besar:
  • Otomatisasi yang dikonfigurasi untuk mengekspor semua metrik kesehatan.
    • Rekomendasi: pilih hanya metrik kesehatan yang memiliki data tersimpan di Apple Health dan data yang benar-benar akan Anda gunakan. Bahkan tipe data kosong memengaruhi kinerja. Pertimbangkan juga membagi metrik yang dipilih ke beberapa otomatisasi agar sistem lebih mudah menanganinya.
  • Otomatisasi dengan pengelompokan waktu dalam detik atau menit, atau dengan ringkasan data nonaktif. Kueri sehalus ini dapat berjalan lama dan bentrok dengan batasan sistem.
    • Rekomendasi: meskipun data sedetail mungkin tampak ideal, pertimbangkan apakah tingkat detail itu diperlukan untuk setiap metrik atau tipe data. Pertimbangkan beberapa otomatisasi dengan pengaturan berbeda.
  • Saat mengekspor latihan luar ruangan seperti bersepeda, lari, hiking, dll. dengan data rute, GPS dan metrik kesehatan terkait dapat menghasilkan payload besar.
• Ukuran payload: Terutama saat menggunakan ekspor REST API, payload besar dapat menyebabkan kesalahan server. Pastikan backend Anda dikonfigurasi untuk menangani payload yang mungkin mencapai beberapa ratus megabyte.
• Frekuensi sinkronisasi: Tambahkan widget Otomatisasi ke Layar Utama untuk membantu memastikan otomatisasi berjalan berhasil di latar belakang (lihat Siapkan widget untuk otomatisasi).

Prasyarat

• Endpoint URL valid yang menerima permintaan HTTP POST
• Kredensial autentikasi (jika diperlukan oleh endpoint Anda)
• Konektivitas jaringan untuk menjangkau endpoint Anda

Konfigurasi

Buka layar Automated Exports dari navigasi utama, lalu ketuk "New Automation" dan pilih "REST API" sebagai Automation Type.

Nama Otomatisasi

Masukkan nama deskriptif untuk otomatisasi Anda (misalnya "My Backend API", "Webhook Integration").

Notifikasi

Konfigurasikan kapan Anda ingin menerima notifikasi:

• Notify on Cache Update – Terima notifikasi saat data cache diperbarui
• Notify When Run – Terima notifikasi setiap kali otomatisasi dijalankan

Konfigurasi URL

Masukkan URL lengkap tempat Anda ingin mengirim data kesehatan. Ini harus berupa 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

Catatan: URL harus valid dan dapat diakses dari perangkat Anda. URL tidak valid akan mencegah otomatisasi berjalan.

Request Timeout

Pilih interval batas waktu untuk permintaan HTTP. Ini menentukan berapa lama aplikasi akan menunggu respons sebelum menganggap permintaan gagal.

Header HTTP

Tambahkan header HTTP kustom untuk autentikasi atau metadata. Kasus penggunaan umum meliputi:

• Kunci API: X-API-Key: your-api-key
• Token otorisasi: Authorization: Bearer your-token
• Penggantian tipe konten: Content-Type: application/json

Untuk menambahkan header:

1. Ketuk "Add Headers"
2. Masukkan kunci header di kolom kiri
3. Masukkan nilai header di kolom kanan
4. Ulangi untuk header tambahan

Penting: Setiap kunci header harus memiliki nilai yang sesuai. Header kosong akan diabaikan.

Pengaturan jenis data

Data Type

Pilih tipe data kesehatan mana yang akan diekspor:

• Health Metrics – Langkah, detak jantung, tidur, dan pengukuran kesehatan lainnya
• Workouts – Aktivitas olahraga dan kebugaran
• Symptoms – Gejala dan kondisi kesehatan
• ECG – Pembacaan elektrokardiogram
• Heart Rate Notifications – Event detak jantung tinggi/rendah
• State of Mind – Entri suasana hati dan mental (iOS 18.0+)
• Cycle Tracking – Data siklus menstruasi dan kesehatan reproduksi
• Medications – Log obat dan kepatuhan (iOS 26.0+)

Health Metrics Configuration

Saat Health Metrics dipilih:

Select Health Metrics – Pilih metrik spesifik mana yang akan disertakan. Anda dapat memilih semua metrik yang tersedia atau hanya sebagian.

Tips: Memilih hanya metrik yang Anda perlukan dapat mempercepat pemrosesan dan mengurangi ukuran data.

Preferred Sources – Konfigurasikan sumber data mana yang diprioritaskan saat beberapa sumber menyediakan metrik yang sama.

Workout Configuration

Saat Workouts dipilih:

Include Route Data – Alihkan ON untuk menyertakan rute untuk workout yang memiliki data lokasi.

Include Workout Metrics – Alihkan ON untuk menyertakan metrik kesehatan yang dikumpulkan selama workout (detak jantung, kalori, dll.).

Time Grouping (Workout Metrics) – Saat menggunakan Export Version 2 dan Include Workout Metrics aktif:

• Minutes – Mengelompokkan metrik workout per menit
• Seconds – Mengelompokkan metrik workout per detik

Pengaturan ekspor

Export Format

Pilih format untuk data yang diekspor:

• JSON format – Menyediakan struktur data detail dengan objek bersarang. Terbaik untuk API, basis data, dan aplikasi yang memerlukan data terstruktur. Format JSON menyertakan informasi lebih detail untuk tipe data kompleks seperti fase tidur dan pembacaan AFib.

• CSV format – Menyediakan data tabular yang mudah diimpor ke aplikasi spreadsheet. Terbaik untuk analisis data sederhana atau saat endpoint Anda mengharapkan data CSV.

Catatan: Header Content-Type secara otomatis diset ke application/json untuk ekspor JSON dan multipart/form-data untuk ekspor CSV.

Export Version

Pilih Export Version. Pemversionan memungkinkan transisi antar versi ekspor yang diperbarui sesuai kecepatan Anda sendiri dan meminimalkan perubahan yang merusak alur kerja.

• Version 1 – Format lama; gunakan jika Anda memiliki alur kerja yang bergantung pada format ini
• Version 2 – Format saat ini dengan data workout yang ditingkatkan dan opsi metadata lebih detail

Date Range

Pilih kapan data harus diekspor:

• Default – Menyinkronkan data untuk hari sebelumnya penuh ditambah data hingga tanggal dan waktu saat ini
• Since Last Sync – Pada setiap sinkronisasi, mengekspor semua data sejak ekspor terakhir berjalan hingga tanggal dan waktu saat ini
• Today – Menyinkronkan semua data untuk tanggal saat ini hingga waktu saat ini
• Yesterday – Menyinkronkan semua data untuk hari sebelumnya penuh
• Previous 7 Days – Menyinkronkan data untuk tujuh hari sebelumnya penuh

Summarize Data

Saat menggunakan format JSON dengan tipe data Health Metrics, alihkan Summarize Data ON atau OFF.

• ON – Menyediakan ringkasan data agregat
• OFF – Menyediakan data tidak teragregasi jika memungkinkan, menampilkan titik data individual

Catatan: Pengaturan ini hanya berlaku untuk format JSON dengan Health Metrics. Data selalu diagregasi saat menggunakan format CSV atau saat beberapa metrik dipilih.

Time Grouping

Saat menggunakan format JSON dengan Summarize Data diaktifkan, pilih cara data diagregasi.

Catatan: Format CSV selalu mengagregasi data. Agregasi tingkat menit dan detik dapat secara signifikan meningkatkan waktu pemrosesan dan ukuran data.

Permintaan batch dan muatan besar

Saat menggunakan format JSON, aktifkan Permintaan Batch untuk mengirim data dalam beberapa permintaan HTTP, bukan satu muatan besar.

• AKTIF — Menyebarkan data ke beberapa permintaan. Gunakan saat endpoint memiliki batas ukuran, timeout pada body besar, atau memproses data secara bertahap.
• NONAKTIF — Mengirim semua data dalam satu permintaan. Cocok untuk ekspor kecil dan webhook sederhana.

Kapan mengaktifkan batch:

• Banyak metrik kesehatan dipilih, rentang tanggal panjang, atau pengelompokan waktu halus (menit/detik)
• Ringkas Data NONAKTIF dan Anda mengekspor metrik kesehatan terpisah
• Server mengembalikan error atau timeout pada body POST besar

Catatan:

• Permintaan batch hanya berlaku untuk REST API + JSON (bukan CSV).
• Batching mengurangi ukuran muatan per permintaan tetapi tidak menghilangkan kebutuhan mengambil data di perangkat; kueri HealthKit lambat masih dapat muncul sebagai peringatan di log aktivitas. Lihat Kueri lambat di log aktivitas.

Frekuensi sinkronisasi

Konfigurasikan seberapa sering otomatisasi harus mengunggah data:

Pilih angka dan interval.

Pengujian dan verifikasi

Memverifikasi format data

Aplikasi secara otomatis menyertakan header berikut di setiap permintaan:

• Content-Type – Diset berdasarkan format ekspor
• automation-name – Nama otomatisasi Anda
• automation-id – Pengidentifikasi unik untuk otomatisasi
• automation-aggregation – Pengelompokan waktu yang dipilih
• automation-period – Rentang tanggal yang dipilih
• session-id – Pengidentifikasi unik untuk setiap permintaan

Pemecahan masalah

Masalah umum

Data tidak diterima di endpoint

• Verifikasi URL endpoint benar
• Periksa bahwa endpoint Anda menerima permintaan POST
• Tinjau header autentikasi
• Periksa log endpoint untuk permintaan masuk
• Verifikasi konektivitas jaringan

Tips dan praktik terbaik

1. Sinkronisasi otomatis:

   • Isi daya perangkat Anda dan gunakan iPhone Mirroring
     • Saat perangkat sedang diisi daya, iOS memberi pembatasan lebih sedikit pada performa perangkat, sehingga data dapat disinkronkan lebih sering
     • Dengan iPhone Mirroring, perangkat Anda berperilaku seperti saat tidak terkunci. Ini berarti data kesehatan dapat diakses oleh Health Auto Export untuk menjalankan tindakan otomatis

2. Performa:

   • Gunakan pengelompokan waktu yang sesuai untuk menyeimbangkan detail vs. ukuran data
   • Pilih hanya metrik yang Anda perlukan

3. Keandalan:

   • Setel nilai batas waktu yang sesuai berdasarkan waktu respons endpoint Anda
   • Pantau Activity Logs secara rutin

4. Format data:

   • Gunakan JSON untuk data terstruktur dan API
   • Gunakan CSV untuk analisis data sederhana atau integrasi spreadsheet
   • Pertimbangkan permintaan batch untuk dataset besar atau pemrosesan terpisah

Melihat log aktivitas

1. Ketuk Lihat log aktivitas di layar konfigurasi otomatisasi.
2. Tinjau jalankan (dikelompokkan, terbaru di atas) dan luaskan peristiwa dalam setiap jalankan.
3. Bedakan peringatan (misalnya, kueri data kesehatan lambat) dari kesalahan (kegagalan HTTP, waktu habis, atau kegagalan membaca HealthKit)—lihat Ikhtisar Otomatisasi — Log aktivitas.
4. Unggahan REST yang berhasil sering menampilkan ringkasan dengan format, jenis data, periode ekspor, dan rentang tanggal dalam run.
5. Bagikan (bilah alat) mengekspor ZIP diagnostik lengkap Log peristiwa aplikasi untuk dukungan (sama seperti Pengaturan → Lanjutan).
6. Hapus hanya menghapus riwayat aktivitas otomatisasi ini.