คู่มือระบบอัตโนมัติ REST API

ระบบอัตโนมัติ REST API ช่วยให้คุณส่งออกข้อมูลสุขภาพไปยังเว็บเซอร์วิสที่รับ HTTP POST โดยอัตโนมัติ เหมาะสำหรับเชื่อมต่อแบ็กเนดที่กำหนดเอง API ของบุคคลที่สาม หรือเว็บฮุก

ภาพรวม

ระบบอัตโนมัติ REST API ส่งข้อมูลสุขภาพไปยัง URL ที่กำหนดด้วยคำขอ HTTP POST สามารถส่งเป็น JSON หรือ CSV พร้อมกำหนดส่วนหัวสำหรับการยืนยันตัวตนและเมทาดาทา

กรณีใช้งาน:

• เชื่อมต่อกับบริการแบ็กเนดที่กำหนดเอง
• ส่งข้อมูลไปยังเว็บฮุก
• ซิงก์กับ API ของบุคคลที่สาม
• สร้างแดชบอร์ดหรือแพลตฟอร์มวิเคราะห์

คุณสมบัติหลัก:

• รองรับทั้ง JSON และ CSV
• กำหนด HTTP headers เองสำหรับการยืนยันตัวตน
• ตั้งค่าหมดเวลาคำขอได้
• ส่งออกข้อมูลย้อนหลังด้วยตนเองได้

ข้อจำกัด:

• การเข้าถึงข้อมูลสุขภาพ: แอปไม่ได้รับอนุญาตให้เข้าถึงข้อมูลสุขภาพขณะ iPhone ถูกล็อก ระบบอัตโนมัติจะทำงานเฉพาะเมื่ออุปกรณ์ปลดล็อก นี่เป็นข้อจำกัดจาก Apple ที่ไม่สามารถหลีกเลี่ยงได้ ข้อมูลเพิ่มเติม

• การประมวลผลในพื้นหลัง: iOS จำกัดการประมวลผลในพื้นหลังเพื่อประหยัดแบตเตอรี่ ระบบอัตโนมัติพึ่งพาการรีเฟรชแอปในพื้นหลัง และอาจไม่ทำงานทันทีหาก:

  • ปิดการรีเฟรชแอปในพื้นหลังสำหรับแอปนี้
  • อุปกรณ์อยู่ในโหมดพลังงานต่ำ
  • อุปกรณ์ไม่ได้ใช้งานเป็นเวลานาน
  • ทรัพยากรระบบจำกัด
  • หลายแอปแย่งเวลาทำงานในพื้นหลัง

ประสิทธิภาพ

โปรดทราบว่า iOS ถูกปรับให้เหมาะกับงานระยะสั้นบนอุปกรณ์มือถือที่มีข้อจำกัดด้านประสิทธิภาพเข้มงวด งานพื้นหลังมักต้องเสร็จภายใน 30 วินาทีและมีหน่วยความจำจำกัด Health Auto Export มีความยืดหยุ่นและปรับแต่งได้สูง จึงควรเข้าใจว่าการตั้งค่าบางอย่างส่งผลต่อประสิทธิภาพแอปและผลลัพธ์อย่างไร

• การตั้งค่า: ระบบอัตโนมัติที่สร้างข้อมูลปริมาณมากอาจทำให้ระบบยุติกระบวนการและระบบไม่ทำงานในพื้นหลัง การตั้งค่าต่อไปนี้อาจสร้างข้อมูลปริมาณมาก:
  • ระบบที่ตั้งให้ส่งออกเมตริกสุขภาพทั้งหมด
    • คำแนะนำ: เลือกเฉพาะเมตริกที่มีข้อมูลใน Apple Health และข้อมูลที่คุณจะใช้จริง แม้ประเภทข้อมูลว่างก็มีผลต่อประสิทธิภาพ อาจแยกเมตริกที่เลือกไปหลายระบบเพื่อให้ระบบจัดการได้ง่ายขึ้น
  • ระบบที่ใช้การจัดกลุ่มเวลาเป็นวินาทีหรือนาที หรือปิดการสรุปข้อมูล การคิวรีละเอียดเช่นนี้อาจใช้เวลานานและชนกับข้อจำกัดของระบบ
    • คำแนะนำ: แม้ข้อมูลละเอียดสูงสุดจะดูเหมาะ ให้พิจารณาว่าแต่ละเมตริกหรือประเภทข้อมูลต้องการระดับนั้นหรือไม่ ลองใช้หลายระบบที่มีการตั้งค่าต่างกัน
  • เมื่อส่งออกการออกกำลังกายกลางแจ้ง เช่น ปั่นจักรยาน วิ่ง เดินป่า พร้อมข้อมูลเส้นทาง GPS และเมตริกที่เกี่ยวข้องอาจสร้าง payload ขนาดใหญ่
• ขนาด payload: โดยเฉพาะเมื่อใช้ส่งออก REST API payload ใหญ่อาจทำให้เซิร์ฟเวอร์ผิดพลาด ตรวจสอบว่า backend รองรับ payload อาจถึงหลายร้อยเมกะไบต์
• ความถี่ซิงค์: เพิ่มวิดเจ็ตระบบอัตโนมัติไปยังหน้าจอหลักเพื่อช่วยให้ระบบทำงานในพื้นหลังสำเร็จ (ดู ตั้งค่าวิดเจ็ตสำหรับการทำงานอัตโนมัติ)

ข้อกำหนดเบื้องต้น

• URL ปลายทางที่ถูกต้องและรับ HTTP POST
• ข้อมูลประจำตัวสำหรับยืนยันตัวตน (หากปลายทางต้องการ)
• การเชื่อมต่อเครือข่ายไปยังปลายทาง

คำขอแบบแบตช์และเพย์โหลดขนาดใหญ่

เมื่อใช้รูปแบบ JSON ให้เปิด คำขอแบบแบตช์ เพื่อส่งข้อมูลในหลายคำขอ HTTP แทนเพย์โหลดเดียวขนาดใหญ่

• เปิด — กระจายข้อมูลไปหลายคำขอ ใช้เมื่อปลายทางมีขีดจำกัดขนาด หมดเวลาบนบอดีใหญ่ หรือประมวลผลทีละส่วน
• ปิด — ส่งข้อมูลทั้งหมดในคำขอเดียว เหมาะกับการส่งออกเล็กและ webhook ง่ายๆ

เมื่อไหร่ควรเปิดแบตช์:

• เลือกเมตริกสุขภาพมาก ช่วงวันที่ยาว หรือจัดกลุ่มเวลาละเอียด (นาที/วินาที)
• สรุปข้อมูลปิดอยู่และคุณส่งออกเมตริกแยกย่อย
• เซิร์ฟเวอร์คืนข้อผิดพลาดหรือหมดเวลาบนบอดี POST ใหญ่

หมายเหตุ:

• คำขอแบบแบตช์ใช้กับ REST API + JSON เท่านั้น (ไม่ใช่ CSV)
• แบตช์ลดขนาดเพย์โหลดต่อคำขอแต่ไม่ได้ลบการดึงข้อมูลบนอุปกรณ์ คำขอข้อมูลสุขภาพช้าอาจยังปรากฏเป็นคำเตือนใน บันทึกกิจกรรม ดู คำขอช้าในบันทึกกิจกรรม

การกำหนดค่า

เปิดแถบด้านข้าง แล้วแตะ ระบบอัตโนมัติ แตะ ระบบอัตโนมัติใหม่ แล้วเลือก "REST API" เป็นประเภท

ชื่อระบบอัตโนมัติ

ตั้งชื่อที่อธิบายได้ (เช่น "My Backend API", "Webhook Integration")

การแจ้งเตือน

กำหนดเมื่อต้องการรับการแจ้งเตือน:

• Notify on Cache Update — แจ้งเมื่ออัปเดตข้อมูลแคช
• Notify When Run — แจ้งทุกครั้งที่ระบบอัตโนมัติรัน
• ตั้งเวลาการเตือน — การเตือนเพิ่มเติมให้ปลดล็อกและเปิดแอป ดู ภาพรวมระบบอัตโนมัติ แยกต่างหากจาก Notify When Run

การตั้งค่า URL

ใส่ URL เต็มที่ต้องการส่งข้อมูลสุขภาพ รวมโปรโตคอล (http:// หรือ https://)

ตัวอย่าง URL:

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

หมายเหตุ: URL ต้องถูกต้องและเข้าถึงได้จากอุปกรณ์ URL ไม่ถูกต้องจะทำให้ระบบอัตโนมัติรันไม่ได้

หมดเวลาคำขอ

เลือกช่วงหมดเวลาสำหรับคำขอ HTTP กำหนดว่าแอปจะรอการตอบกลับนานแค่ไหนก่อนถือว่าล้มเหลว

HTTP Headers

เพิ่มส่วนหัว HTTP สำหรับการยืนยันตัวตนหรือเมทาดาทา ตัวอย่าง:

• API keys: X-API-Key: your-api-key
• Authorization tokens: Authorization: Bearer your-token
• Content type: Content-Type: application/json

วิธีเพิ่ม:

1. แตะ "Add Headers"
2. ใส่ชื่อ header ในช่องซ้าย
3. ใส่ค่า header ในช่องขวา
4. ทำซ้ำสำหรับ header เพิ่มเติม

สำคัญ: แต่ละคีย์ต้องมีค่าคู่กัน header ว่างจะถูกละเว้น

การตั้งค่าประเภทข้อมูล

ประเภทข้อมูล

เลือกประเภทข้อมูลสุขภาพที่จะส่งออก:

• ตัวชี้วัดสุขภาพ — ก้าว อัตราการเต้น การนอน และการวัดอื่น ๆ
• การออกกำลังกาย — กิจกรรมออกกำลังกายและฟิตเนส
• อาการ — อาการและภาวะสุขภาพ
• ECG — การบันทึกคลื่นไฟฟ้าหัวใจ
• การแจ้งเตือนอัตราการเต้น — เหตุการณ์อัตราสูง/ต่ำ
• สภาวะทางจิตใจ — อารมณ์และสภาวะจิตใจ (iOS 18.0+)
• การติดตามรอบเดือน — ข้อมูลรอบเดือนและสืบพันธุ์
• ยา — บันทึกยาและการปฏิบัติตาม (iOS 26.0+)

การตั้งค่าตัวชี้วัดสุขภาพ

เมื่อเลือกตัวชี้วัดสุขภาพ:

เลือกตัวชี้วัดสุขภาพ — เลือกตัวชี้วัดที่รวม ทั้งหมดหรือเฉพาะรายการ

เคล็ดลับ: เลือกเฉพาะที่จำเป็นช่วยลดเวลาประมวลผลและขนาดข้อมูล

แหล่งข้อมูลที่ต้องการ — กำหนดลำดับความสำคัญของแหล่งข้อมูลเมื่อมีหลายแหล่งให้ตัวชี้วัดเดียวกัน

การตั้งค่าการออกกำลังกาย

เมื่อเลือกการออกกำลังกาย:

รวมข้อมูลเส้นทาง — เปิดเพื่อรวมเส้นทางเมื่อมีข้อมูลตำแหน่ง

รวมตัวชี้วัดการออกกำลังกาย — เปิดเพื่อรวมตัวชี้วัดที่เก็บระหว่างออกกำลังกาย (อัตราการเต้น แคลอรี่ ฯลฯ)

การจัดกลุ่มตามเวลา (ตัวชี้วัดการออกกำลังกาย) — เมื่อใช้ Export Version 2 และเปิดรวมตัวชี้วัดการออกกำลังกาย:

• นาที — จัดกลุ่มตามนาที
• วินาที — จัดกลุ่มตามวินาที

การตั้งค่าการส่งออก

รูปแบบการส่งออก

เลือกรูปแบบข้อมูลที่ส่งออก:

• JSON — โครงสร้างละเอียดมีอ็อบเจ็กต์ซ้อน เหมาะกับ API ฐานข้อมูล และแอปที่ต้องการโครงสร้าง JSON มีรายละเอียดมากขึ้นสำหรับข้อมูลซับซ้อน เช่น ระยะการนอนและการอ่าน AFib

• CSV — ข้อมูลตารางนำเข้าสเปรดชีตได้ง่าย เหมาะกับการวิเคราะห์ง่าย ๆ หรือเมื่อปลายทางต้องการ CSV

หมายเหตุ: Content-Type ตั้งเป็น application/json สำหรับ JSON และ multipart/form-data สำหรับ CSV โดยอัตโนมัติ

เวอร์ชันการส่งออก

เลือกเวอร์ชันการส่งออก การมีเวอร์ชันช่วยให้เปลี่ยนรูปแบบใหม่ได้ตามจังหวะและลดการเปลี่ยนที่ทำลายเวิร์กโฟลว์

• เวอร์ชัน 1 — รูปแบบเก่า ใช้หากเวิร์กโฟลว์พึ่งพารูปแบบนี้
• เวอร์ชัน 2 — รูปแบบปัจจุบัน ข้อมูลการออกกำลังกายและเมทาดาทาละเอียดขึ้น

ช่วงวันที่

เลือกว่าควรส่งออกข้อมูลเมื่อใด:

• Default — ซิงก์ข้อมูลวันก่อนหน้าเต็มวัน รวมถึงข้อมูลจนถึงวันเวลาปัจจุบัน
• Since Last Sync — แต่ละครั้งส่งข้อมูลตั้งแต่ครั้งซิงก์ล่าสุดจนถึงปัจจุบัน
• Today — ข้อมูลวันนี้จนถึงเวลาปัจจุบัน
• Yesterday — ข้อมูลวันก่อนเต็มวัน
• Previous 7 Days — ข้อมูลเจ็ดวันก่อนเต็มวัน

สรุปข้อมูล

เมื่อใช้ JSON กับประเภทตัวชี้วัดสุขภาพ เปิดหรือปิดสรุปข้อมูล

• เปิด — ให้สรุปรวม
• ปิด — แยกจุดข้อมูลเมื่อทำได้

หมายเหตุ: ใช้กับ JSON และตัวชี้วัดสุขภาพเท่านั้น ข้อมูลจะรวมเสมอเมื่อใช้ CSV หรือเลือกหลายตัวชี้วัด

การจัดกลุ่มตามเวลา

เมื่อใช้ JSON และเปิดสรุปข้อมูล เลือกวิธีรวมข้อมูล

หมายเหตุ: CSV รวมข้อมูลเสมอ การจัดกลุ่มระดับนาทีหรือวินาทีอาจเพิ่มเวลาประมวลผลและขนาดข้อมูลมาก

คำขอแบบแบตช์

เมื่อใช้ JSON เปิด Batch Requests เพื่อส่งข้อมูลเป็นหลายคำขอแทนครั้งเดียว

• เปิด — แบ่งข้อมูลหลายคำขอเพื่อหลีกเลี่ยง payload ใหญ่เกินไป
• ปิด — ส่งข้อมูลทั้งหมดในคำขอเดียว

ความถี่การซิงก์

กำหนดความบ่อยของการอัปโหลด:

เลือกตัวเลขและช่วงเวลา

การทดสอบและการตรวจสอบ

ตรวจสอบรูปแบบข้อมูล

แอปรวมส่วนหัวต่อไปนี้ในแต่ละคำขอโดยอัตโนมัติ:

• Content-Type — ตามรูปแบบการส่งออก
• automation-name — ชื่อระบบอัตโนมัติ
• automation-id — ตัวระบุเฉพาะ
• automation-aggregation — การจัดกลุ่มตามเวลาที่เลือก
• automation-period — ช่วงวันที่ที่เลือก
• session-id — ตัวระบุเฉพาะของแต่ละคำขอ

การแก้ปัญหา

ปัญหาที่พบบ่อย

ข้อมูลไม่ถึงปลายทาง

• ตรวจสอบ URL ปลายทาง
• ตรวจสอบว่าปลายทางรับ POST
• ทบทวันส่วนหัวการยืนยันตัวตน
• ดูบันทึกปลายทาง
• ตรวจสอบการเชื่อมต่อเครือข่าย

เคล็ดลับและแนวทางปฏิบัติ

1. การซิงค์อัตโนมัติ:

   • ชาร์จอุปกรณ์และใช้การสะท้อนหน้าจอ iPhone
     • ขณะชาร์จ iOS จำกัดประสิทธิภาพน้อยลง ทำให้ซิงค์ข้อมูลได้บ่อยขึ้น
     • เมื่อใช้การสะท้อนหน้าจอ iPhone อุปกรณ์จะทำงานเหมือนปลดล็อก Health Auto Export จึงเข้าถึงข้อมูลสุขภาพเพื่อรันการทำงานอัตโนมัติได้

2. การซิงก์อัตโนมัติ:

   • ชาร์จอุปกรณ์และใช้ iPhone Mirroring
     • เมื่อชาร์จ iOS จำกัดการประมวลผลน้อยลง ข้อมูลจึงซิงก์ได้บ่อยขึ้น
     • การใช้ iPhone Mirroring ทำให้อุปกรณ์ทำงานเหมือนปลดล็อก ข้อมูลสุขภาพจึงเข้าถึงได้เพื่อรันการทำงานอัตโนมัติ

3. ประสิทธิภาพ:

   • ใช้การจัดกลุ่มตามเวลาที่เหมาะสมสมดุลระหว่างรายละเอียดกับขนาด
   • เลือกเฉพาะตัวชี้วัดที่จำเป็น

4. ความน่าเชื่อถือ:

   • ตั้งหมดเวลาให้เหมาะกับเวลาตอบของปลายทาง
   • ตรวจสอบบันทึกกิจกรรมเป็นประจำ

5. รูปแบบข้อมูล:

   • ใช้ JSON สำหรับข้อมูลมีโครงสร้างและ API
   • ใช้ CSV สำหรับการวิเคราะห์ง่ายหรือเชื่อมสเปรดชีต
   • พิจารณา batch สำหรับชุดข้อมูลใหญ่หรือแยกประมวลผล

ดูบันทึกกิจกรรม

1. แตะ ดูบันทึกกิจกรรม ในหน้าจอการตั้งค่าระบบอัตโนมัติ
2. ตรวจสอบ การรัน (จัดกลุ่ม ใหม่สุดก่อน) และขยายเหตุการณ์ในแต่ละการรัน
3. แยก คำเตือน (เช่น การคิวรีข้อมูลสุขภาพช้า) จาก ข้อผิดพลาด (ความล้มเหลวของ HTTP หมดเวลา หรือข้อความเข้ารหัสเช่น “No health data was found in this date range, so nothing was uploaded.” และ “Health data could not be fully read. The device may have locked during the export. Nothing was uploaded.”)—ดู ภาพรวมระบบอัตโนมัติ — บันทึกกิจกรรม
4. การอัปโหลด REST ที่สำเร็จมักแสดงสรุปพร้อม รูปแบบ ประเภทข้อมูล ช่วงการส่งออก และ ช่วงวันที่ ในการรัน
5. แชร์ (แถบเครื่องมือ) ส่งออก ZIP การวินิจฉัย บันทึกเหตุการณ์แอป ฉบับเต็มสำหรับฝ่ายสนับสนุน (เหมือน การตั้งค่า → ขั้นสูง)
6. ล้าง ลบเฉพาะประวัติกิจกรรมของระบบอัตโนมัตินี้