ระบบอัตโนมัติแบบดีพลิงก์

ระบบอัตโนมัติแบบ deep link ให้คุณสร้างระบบอัตโนมัติ REST API แบบโปรแกรมผ่าน URL scheme เหมาะสำหรับสคริปต์อัตโนมัติ การจัดการคอนฟิก หรือการเชื่อมต่อกับระบบภายนอกที่ต้องกำหนดการส่งออกข้อมูลสุขภาพ

ภาพรวม

ระบบอัตโนมัติแบบ deep link ใช้ URL scheme เฉพาะเพื่อสร้างและกำหนดค่าระบบอัตโนมัติ REST API โดยไม่ต้องกรอกการตั้งค่าในแอปด้วยมือ เมื่อคุณเปิด URL แบบ deep link แอปจะสร้างระบบอัตโนมัติใหม่โดยอัตโนมัติตามคอนฟิกที่ระบุ

กรณีใช้งาน:

• ตั้งค่าระบบอัตโนมัติแบบโปรแกรมจากสคริปต์หรือเครื่องมือ
• กำหนดค่าระบบอัตโนมัติจำนวนมาก
• เชื่อมต่อกับระบบจัดการคอนฟิก
• ตั้งค่าอย่างรวดเร็วจากแอปภายนอกหรือเว็บไซต์
• เวิร์กโฟลว์ทดสอบและพัฒนา

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

• สร้างระบบอัตโนมัติผ่าน URL scheme
• กำหนดค่าการตั้งค่าระบบอัตโนมัติ REST API ทั้งหมด
• ตรวจสอบพารามิเตอร์แบบ type-safe
• ข้อความแสดงข้อผิดพลาดครอบคลุม

ข้อจำกัด

• Deep link รองรับเฉพาะระบบอัตโนมัติ REST API (ไม่ใช่ Dropbox, Google Drive ฯลฯ)
• ขีดจำกัดความยาว URL อาจทำให้รายการพารามิเตอร์ที่ยาวมากใช้ไม่ได้
• ข้อจำกัดทั้งหมดของระบบอัตโนมัติ REST API ยังคงใช้ (การประมวลผลในพื้นหลัง การเข้าถึงข้อมูลสุขภาพ ฯลฯ)

รูปแบบ URL

Deep link มีโครงสร้างดังนี้:

com.HealthExport://automation?parameter1=value1&parameter2=value2&...

Base URL: com.HealthExport://automation

พารามิเตอร์: พารามิเตอร์ทั้งหมดเป็นตัวเลือกยกเว้น name และ url ชื่อพารามิเตอร์ไม่สนตัวพิมพ์ใหญ่-เล็ก

อ้างอิงพารามิเตอร์

พารามิเตอร์ที่จำเป็น

url (จำเป็น)

• ประเภท: สตริง (URL ที่ถูกต้อง)
• คำอธิบาย: URL ปลายทางที่จะส่งข้อมูลสุขภาพไป
• ตัวอย่าง: https://api.example.com/health-data
• หมายเหตุ: ต้องเป็น URL HTTP/HTTPS ที่ถูกต้อง

name (จำเป็น)

• ประเภท: สตริง
• คำอธิบาย: ชื่อที่อธิบายได้สำหรับระบบอัตโนมัติ
• ตัวอย่าง: My%20Backend%20API (เข้ารหัส URL สำหรับ "My Backend API")
• หมายเหตุ: ต้องเข้ารหัส URL หากมีช่องว่างหรืออักขระพิเศษ

การกำหนดค่าพื้นฐาน

format

• ประเภท: Enum (json, csv)
• ค่าเริ่มต้น: json
• คำอธิบาย: รูปแบบการส่งออกข้อมูล
• ตัวอย่าง: format=json หรือ format=csv
• หมายเหตุ: รูปแบบ CSV เปิดการรวมข้อมูล (aggregation) โดยอัตโนมัติ

enabled

• ประเภท: Boolean (true, false, 1, 0, yes, no)
• ค่าเริ่มต้น: false
• คำอธิบาย: ว่าระบบอัตโนมัติถูกเปิดใช้งานทันทีหลังสร้างหรือไม่
• ตัวอย่าง: enabled=true

datatype

• ประเภท: Enum (ดูประเภทข้อมูลด้านล่าง)
• ค่าเริ่มต้น: healthMetrics
• คำอธิบาย: ประเภทข้อมูลสุขภาพที่จะส่งออก
• ตัวอย่าง: datatype=workouts
• หมายเหตุ: เลือกได้เพียงหนึ่งประเภท การตั้งค่านี้จะกำหนดแฟล็กการรวมที่เหมาะสมโดยอัตโนมัติ

ประเภทข้อมูลที่ใช้ได้:

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

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

period

• ประเภท: Enum
• ค่าเริ่มต้น: none
• คำอธิบาย: ช่วงวันที่สำหรับการส่งออกข้อมูล
• ตัวอย่าง: period=today

ค่าที่ใช้ได้:

• none — ค่าเริ่มต้น (วันก่อนหน้าเต็มวัน บวกวันปัจจุบัน)
• lastsync — ตั้งแต่ครั้งซิงก์ล่าสุด
• today — วันปัจจุบัน
• yesterday — วันก่อนหน้า
• previous7days — เจ็ดวันก่อนหน้า
• realtime — อัปเดตแบบเรียลไทม์ (ต้องใช้ช่วงซิงก์เป็นวินาที)

interval

• ประเภท: Enum
• ค่าเริ่มต้น: none
• คำอธิบาย: ช่วงการจัดกลุ่ม/รวมตามเวลา (ใช้ได้เฉพาะเมื่อประเภทข้อมูลเป็น healthMetrics)
• ตัวอย่าง: interval=hours

ค่าที่ใช้ได้:

• none — ค่าเริ่มต้น (ไม่รวมข้อมูล)
• minutes — จัดกลุ่มตามนาที
• hours — จัดกลุ่มตามชั่วโมง
• days — จัดกลุ่มตามวัน
• weeks — จัดกลุ่มตามสัปดาห์
• months — จัดกลุ่มตามเดือน
• years — จัดกลุ่มตามปี

หมายเหตุ: พารามิเตอร์นี้ใช้ได้เมื่อ datatype=healthMetrics เท่านั้น รูปแบบ CSV รวมข้อมูลเสมอ

aggregatedata

• ประเภท: Boolean
• ค่าเริ่มต้น: true (สำหรับ CSV), false (สำหรับ JSON)
• คำอธิบาย: ว่าจะรวม/สรุปข้อมูลหรือไม่ (ใช้ได้เฉพาะเมื่อประเภทข้อมูลเป็น healthMetrics และรูปแบบเป็น JSON)
• ตัวอย่าง: aggregatedata=true
• หมายเหตุ: ตั้งเป็น true โดยอัตโนมัติเมื่อ format=csv

aggregatesleep

• ประเภท: Boolean
• ค่าเริ่มต้น: true
• คำอธิบาย: ว่าจะรวมข้อมูลการนอนหรือไม่
• ตัวอย่าง: aggregatesleep=true

exportversion

• ประเภท: Enum (v1, v2, 1, 2)
• ค่าเริ่มต้น: v2
• คำอธิบาย: เวอร์ชันรูปแบบการส่งออก
• ตัวอย่าง: exportversion=v2
• หมายเหตุ: เวอร์ชัน 2 รวมข้อมูลการออกกำลังกายที่ละเอียดขึ้นและเมตาดาต้าละเอียดขึ้น

batchrequests

• ประเภท: Boolean
• ค่าเริ่มต้น: false
• คำอธิบาย: ส่งข้อมูลเป็นชุดหลายคำขอ (ใช้ได้เฉพาะกับ REST API และรูปแบบ JSON)
• ตัวอย่าง: batchrequests=true
• หมายเหตุ: ใช้ได้เมื่อ format=json และ exportDestination=restApi

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

syncinterval

• ประเภท: Enum
• ค่าเริ่มต้น: minutes
• คำอธิบาย: ช่วงเวลาของความถี่การซิงก์
• ตัวอย่าง: syncinterval=hours

ค่าที่ใช้ได้:

• minutes — ซิงก์ทุก N นาที
• hours — ซิงก์ทุก N ชั่วโมง
• days — ซิงก์ทุก N วัน
• weeks — ซิงก์ทุก N สัปดาห์
• seconds — ใช้ได้เมื่อ period=realtime เท่านั้น

หมายเหตุ: สำหรับระบบอัตโนมัติ REST API ใช้ได้เฉพาะ minutes, hours, days, และ weeks เว้นแต่จะใช้การส่งออกแบบเรียลไทม์

syncquantity

• ประเภท: จำนวนเต็มบวก
• ค่าเริ่มต้น: 5
• คำอธิบาย: จำนวนช่วงเวลาระหว่างการซิงก์
• ตัวอย่าง: syncquantity=10 (ซิงก์ทุก 10 นาที หาก syncinterval=minutes)
• หมายเหตุ: ต้องมากกว่า 0

การกำหนดค่า HTTP

headers

• ประเภท: สตริง (คู่คีย์-ค่าคั่นด้วยจุลภาค)
• ค่าเริ่มต้น: ไม่มี
• คำอธิบาย: HTTP headers สำหรับการยืนยันตัวตนหรือเมตาดาต้า
• ตัวอย่าง: headers=Authorization,Bearer%20token123,X-API-Key,abc123
• รูปแบบ: key1,value1,key2,value2,...
• หมายเหตุ: ค่าควรเข้ารหัส URL แต่ละ header ต้องมีทั้งคีย์และค่า

ตัวอย่าง header:

• Authorization, Bearer your-token
• X-API-Key, your-api-key
• Content-Type, application/json

requesttimeout

• ประเภท: จำนวนเต็ม (60–86400)
• ค่าเริ่มต้น: 60
• คำอธิบาย: หมดเวลาคำขอเป็นวินาที
• ตัวอย่าง: requesttimeout=300
• หมายเหตุ: ต้องอยู่ระหว่าง 60 ถึง 86400 วินาที (1 นาที ถึง 24 ชั่วโมง)

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

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

metrics

• ประเภท: สตริง (MetricName rawValues คั่นด้วยจุลภาค)
• ค่าเริ่มต้น: ตัวชี้วัดทั้งหมดที่มี
• คำอธิบาย: ตัวชี้วัดสุขภาพเฉพาะที่จะรวม (ใช้ได้เฉพาะเมื่อประเภทข้อมูลเป็น healthMetrics)
• ตัวอย่าง: metrics=Step%20Count,Heart%20Rate,Active%20Energy
• หมายเหตุ: ต้องใช้ MetricName rawValues ให้ตรงกับในแอป หากไม่ระบุ จะรวมตัวชี้วัดที่มีทั้งหมด

ชื่อตัวชี้วัดที่พบบ่อย:

• Step Count
• Heart Rate
• Active Energy
• Apple Exercise Time
• Sleep Analysis
• Walking + Running Distance

ดูรายการเต็มได้ที่หน้าจอเลือกตัวชี้วัดในแอป

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

includeroutes

• ประเภท: Boolean
• ค่าเริ่มต้น: true
• คำอธิบาย: รวมข้อมูลเส้นทางสำหรับการออกกำลังกาย (ใช้ได้เฉพาะเมื่อประเภทข้อมูลเป็น workouts)
• ตัวอย่าง: includeroutes=true

includeworkoutmetadata

• ประเภท: Boolean
• ค่าเริ่มต้น: true
• คำอธิบาย: รวมตัวชี้วัดการออกกำลังกาย (อัตราการเต้นของหัวใจ แคลอรี ฯลฯ) ที่เก็บระหว่างออกกำลังกาย (ใช้ได้เฉพาะเมื่อประเภทข้อมูลเป็น workouts)
• ตัวอย่าง: includeworkoutmetadata=true

workoutsmetadatainterval

• ประเภท: Enum (minutes, seconds)
• ค่าเริ่มต้น: minutes
• คำอธิบาย: การจัดกลุ่มตามเวลาสำหรับตัวชี้วัดการออกกำลังกาย (ใช้ได้เฉพาะเมื่อประเภทข้อมูลเป็น workouts และ exportVersion เป็น v2)
• ตัวอย่าง: workoutsmetadatainterval=seconds
• หมายเหตุ: ใช้ได้เมื่อ datatype=workouts และ exportversion=v2

workouttypes

• ประเภท: สตริง (ค่า UInt คั่นด้วยจุลภาค)
• ค่าเริ่มต้น: ว่าง (ทุกประเภทการออกกำลังกาย)
• คำอธิบาย: ประเภทการออกกำลังกายเฉพาะที่จะรวม (ใช้ได้เฉพาะเมื่อประเภทข้อมูลเป็น workouts)
• ตัวอย่าง: workouttypes=1,2,3
• หมายเหตุ: ใช้ตัวระบุประเภทการออกกำลังกายของ HealthKit

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

notifyonupdate

• ประเภท: Boolean
• ค่าเริ่มต้น: true
• คำอธิบาย: รับการแจ้งเตือนเมื่ออัปเดตข้อมูลแคช
• ตัวอย่าง: notifyonupdate=true

notifywhenrun

• ประเภท: Boolean
• ค่าเริ่มต้น: true
• คำอธิบาย: รับการแจ้งเตือนทุกครั้งที่ระบบอัตโนมัติทำงาน
• ตัวอย่าง: notifywhenrun=false

ตัวอย่าง

ระบบอัตโนมัติ REST API พื้นฐาน

com.HealthExport://automation?url=https://api.example.com/health&name=My%20Automation&format=json&enabled=true

สร้างระบบอัตโนมัติพื้นฐานที่ส่งข้อมูลรูปแบบ JSON ไปยังปลายทางที่ระบุ

พร้อมส่วนหัวการยืนยันตัวตน

com.HealthExport://automation?url=https://api.example.com/health&name=Authenticated%20API&format=json&headers=Authorization,Bearer%20your-token-here,X-API-Key,abc123&enabled=true

สร้างระบบอัตโนมัติพร้อมส่วนหัวการยืนยันตัวตนแบบกำหนดเอง

ตัวชี้วัดสุขภาพเฉพาะรายการ

com.HealthExport://automation?url=https://api.example.com/metrics&name=Steps%20and%20Heart%20Rate&format=json&datatype=healthMetrics&metrics=Step%20Count,Heart%20Rate&aggregatedata=true&interval=hours&enabled=true

สร้างระบบอัตโนมัติที่ส่งออกเฉพาะก้าวและอัตราการเต้นของหัวใจ โดยรวมตามชั่วโมง

การออกกำลังกายพร้อมข้อมูลเส้นทาง

com.HealthExport://automation?url=https://api.example.com/workouts&name=Workout%20Export&format=json&datatype=workouts&includeroutes=true&includeworkoutmetadata=true&exportversion=v2&workoutsmetadatainterval=minutes&enabled=true

สร้างระบบอัตโนมัติสำหรับการออกกำลังกายพร้อมข้อมูลเส้นทางและตัวชี้วัดการออกกำลังกาย โดยใช้ export version 2

ตัวอย่างการตั้งค่าครบถ้วน

com.HealthExport://automation?url=https://api.example.com/health-data&name=Complete%20Configuration&format=json&datatype=healthMetrics&period=today&interval=hours&aggregatedata=true&aggregatesleep=true&exportversion=v2&syncinterval=hours&syncquantity=2&headers=Authorization,Bearer%20token123&requesttimeout=300&batchrequests=true&notifyonupdate=true&notifywhenrun=false&enabled=true

ตัวอย่างที่ครอบคลุมพารามิเตอร์หลักทั้งหมด

ตัวอย่างรูปแบบ CSV

com.HealthExport://automation?url=https://api.example.com/csv&name=CSV%20Export&format=csv&datatype=healthMetrics&period=yesterday&enabled=true

สร้างระบบอัตโนมัติส่งออก CSV หมายเหตุ: รูปแบบ CSV เปิดการรวมข้อมูลโดยอัตโนมัติ

การเข้ารหัส URL

อักขระพิเศษในค่าพารามิเตอร์ต้องเข้ารหัส URL การเข้ารหัสที่พบบ่อย:

• ช่องว่าง: %20
• จุลภาค: %2C
• โคลอน: %3A
• เซมิโคลอน: %3B
• เท่ากับ: %3D
• แอมเปอร์แซนด์: %26
• บวก: %2B

ตัวอย่าง:

• ต้นฉบับ: My Automation Name
• หลังเข้ารหัส: My%20Automation%20Name

ตัวอย่างส่วนหัว:

• ต้นฉบับ: Authorization, Bearer token123
• หลังเข้ารหัส: Authorization,Bearer%20token123

ภาษาโปรแกรมและเครื่องมือส่วนใหญ่มีฟังก์ชันเข้ารหัส URL:

• Swift: addingPercentEncoding(withAllowedCharacters:)
• JavaScript: encodeURIComponent()
• Python: urllib.parse.quote()

ทดสอบ Deep Link

จาก Safari (iOS)

1. เปิด Safari บนอุปกรณ์ iOS ของคุณ
2. ใส่ URL แบบ deep link ในแถบที่อยู่
3. แตะ Go
4. แอปควรเปิดและสร้างระบบอัตโนมัติ

การแก้ปัญหา

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

"Could not parse the URL"

• ตรวจสอบว่า URL scheme ถูกต้อง: com.HealthExport://automation
• ตรวจสอบว่าค่าพารามิเตอร์ทั้งหมดเข้ารหัส URL อย่างถูกต้อง
• ให้แน่ใจว่าสะกดชื่อพารามิเตอร์ถูกต้อง (ไม่สนตัวพิมพ์ใหญ่-เล็ก)

"Invalid URL parameter value"

• ตรวจสอบว่า URL เป็น HTTP/HTTPS ที่ถูกต้อง
• ตรวจสอบการเข้ารหัส URL
• ให้แน่ใจว่า URL ไม่มีอักขระที่ไม่ถูกต้อง

"Invalid data type"

• ใช้ค่าประเภทข้อมูลให้ตรง: healthMetrics, workouts, symptoms, ecg, heartRateNotification, stateOfMind, cycleTracking, medications
• ตรวจสอบการสะกดและตัวพิมพ์ (แม้จะรองรับการจับคู่แบบไม่สนตัวพิมพ์ใหญ่-เล็ก)

"Invalid sync cadence interval"

• สำหรับ REST API ใช้เฉพาะ: minutes, hours, days, weeks
• ใช้ seconds เฉพาะเมื่อ period=realtime

"Aggregation settings are only valid for healthMetrics data type"

• พารามิเตอร์ aggregatedata และ interval ใช้ได้กับ datatype=healthMetrics เท่านั้น
• ลบพารามิเตอร์เหล่านี้หรือเปลี่ยนประเภทข้อมูล

"Batch requests are only valid for REST API with JSON format"

• batchrequests ใช้ได้เมื่อ format=json เท่านั้น
• เปลี่ยนรูปแบบเป็น JSON หรือลบพารามิเตอร์ batchrequests

"Workout settings are only valid for workouts data type"

• includeroutes, includeworkoutmetadata, และ workoutsmetadatainterval ใช้ได้กับ datatype=workouts เท่านั้น
• เปลี่ยนประเภทข้อมูลเป็น workouts หรือลบพารามิเตอร์เหล่านี้

"Metrics parameter is only valid for healthMetrics data type"

• พารามิเตอร์ metrics ใช้ได้กับ datatype=healthMetrics เท่านั้น
• เปลี่ยนประเภทข้อมูลหรือลบพารามิเตอร์ metrics

"Invalid metric name"

• ใช้ MetricName rawValues ให้ตรง (เช่น "Step Count", "Heart Rate")
• ตรวจสอบการสะกดและตัวพิมพ์ใหญ่-เล็ก
• ดูชื่อที่ใช้ได้ในหน้าจอเลือกตัวชี้วัดของแอป

"Invalid request timeout"

• ต้องอยู่ระหว่าง 60 ถึง 86400 วินาที
• ใช้ค่าภายในช่วงนี้

"A name is required for the automation"

• ให้แน่ใจว่ามีพารามิเตอร์ name
• ตรวจสอบว่าหลังถอดรหัส URL แล้วค่าไม่ว่าง

ข้อจำกัดความยาว URL

URL ที่ยาวมาก (โดยเฉพาะเมื่อมีตัวชี้วัดหรือส่วนหัวจำนวนมาก) อาจเกินขีดจำกัดของระบบ พิจารณา:

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

ลำดับความสำคัญของพารามิเตอร์

เมื่อพารามิเตอร์หลายตัวขัดแย้งกัน:

1. การเลือกประเภทข้อมูล (datatype) จะรีเซ็ตแฟล็กการรวมที่เกี่ยวข้องโดยอัตโนมัติ
2. รูปแบบ CSV (format=csv) จะตั้ง aggregatedata=true โดยอัตโนมัติ
3. ช่วงแบบเรียลไทม์ (period=realtime) ต้องใช้ syncinterval=seconds
4. ชุดค่าที่ไม่เข้ากันจะทำให้เกิดข้อผิดพลาดจากการตรวจสอบ

แนวทางปฏิบัติ

1. การซิงก์อัตโนมัติ (เมื่อเรียกใช้ระบบอัตโนมัติผ่าน deep link):

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

2. เข้ารหัส URL ค่าพารามิเตอร์เสมอ เมื่อมีอักขระพิเศษ

3. ทดสอบด้วย URL แบบง่ายก่อน แล้วค่อยเพิ่มความซับซ้อน

4. ใช้ชื่อที่อธิบายได้ เพื่อระบุได้ง่าย

5. ตรวจสอบความถูกต้องของ URL ก่อนสร้าง deep link แบบโปรแกรม

6. จัดการข้อผิดพลาดอย่างเหมาะสม เมื่อแยกวิเคราะห์ deep link

7. จดเอกสารรูปแบบ deep link ของคุณ หากสร้างเครื่องมือที่สร้างลิงก์

8. พิจารณาความยาว URL เมื่อรวมตัวชี้วัดหรือส่วนหัวจำนวนมาก

9. ทดสอบบนอุปกรณ์จริง รวมถึงบนตัวจำลอง

เอกสารที่เกี่ยวข้อง

• คู่มือระบบอัตโนมัติ REST API — รายละเอียดเกี่ยวกับระบบอัตโนมัติ REST API
• ภาพรวมระบบอัตโนมัติ — แนวคิดทั่วไปเกี่ยวกับระบบอัตโนมัติ
• คู่มือการส่งออกด้วยตนเอง — วิธีส่งออกข้อมูลด้วยตนเอง

การสนับสนุน

หากพบปัญหาที่ไม่ได้ครอบคลุมในคู่มือนี้:

1. ตรวจสอบข้อความแสดงข้อผิดพลาดเพื่อดูปัญหาของพารามิเตอร์เฉพาะ
2. ตรวจสอบว่าการเข้ารหัส URL ของคุณถูกต้อง
3. ทดสอบด้วย URL แบบขั้นต่ำก่อน
4. ใช้ปุ่ม Chat Support ในแอปเพื่อขอความช่วยเหลือ