คู่มือระบบอัตโนมัติ 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)
• แบตช์ลดขนาดเพย์โหลดต่อคำขอแต่ไม่ได้ลบการดึงข้อมูลบนอุปกรณ์ คำขอ HealthKit ช้าอาจยังปรากฏเป็นคำเตือนใน บันทึกกิจกรรม ดู คำขอช้าในบันทึกกิจกรรม

การกำหนดค่า

ไปที่หน้าจอการส่งออกอัตโนมัติจากเมนูหลัก แล้วแตะ "ระบบอัตโนมัติใหม่" และเลือก "REST API" เป็นประเภทระบบอัตโนมัติ

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

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

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

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

• Notify on Cache Update — แจ้งเมื่ออัปเดตข้อมูลแคช
• 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 หมดเวลา หรือการอ่าน HealthKit)—ดู ภาพรวมระบบอัตโนมัติ — บันทึกกิจกรรม
4. การอัปโหลด REST ที่สำเร็จมักแสดงสรุปพร้อม รูปแบบ ประเภทข้อมูล ช่วงการส่งออก และ ช่วงวันที่ ในการรัน
5. แชร์ (แถบเครื่องมือ) ส่งออก ZIP การวินิจฉัย บันทึกเหตุการณ์แอป ฉบับเต็มสำหรับฝ่ายสนับสนุน (เหมือน การตั้งค่า → ขั้นสูง)
6. ล้าง ลบเฉพาะประวัติกิจกรรมของระบบอัตโนมัตินี้