Derin bağlantı otomasyonu

Derin bağlantı otomasyonları, URL şemaları kullanarak REST API otomasyonlarını programatik olarak oluşturmanıza olanak tanır. Bu özellik otomasyon betikleri, yapılandırma yönetimi veya sağlık verisi dışa aktarımını yapılandırması gereken harici sistemlerle entegrasyon için idealdir.

Genel bakış

Derin bağlantı otomasyonları, uygulamada ayarları elle girmeden REST API otomasyonlarını oluşturmak ve yapılandırmak için özel bir URL şeması kullanır. Bir derin bağlantı URL’sini açtığınızda uygulama, belirtilen yapılandırmayla yeni bir otomasyon oluşturur.

Kullanım alanları:

• Betikler veya araçlarla programatik otomasyon kurulumu
• Toplu otomasyon yapılandırması
• Yapılandırma yönetim sistemleriyle entegrasyon
• Harici uygulamalardan veya web sitelerinden hızlı kurulum
• Test ve geliştirme iş akışları

Öne çıkan özellikler:

• URL şemasıyla otomasyon oluşturma
• Tüm REST API otomasyon ayarlarını yapılandırma
• Tür güvenli parametre doğrulaması
• Ayrıntılı hata iletileri

Sınırlamalar

• Derin bağlantılar yalnızca REST API otomasyonlarını destekler (Dropbox, Google Drive vb. değil)
• URL uzunluk sınırları çok uzun parametre listelerini kısıtlayabilir
• REST API otomasyonlarından gelen tüm sınırlamalar geçerlidir (arka planda işlem, sağlık verisine erişim vb.)

URL biçimi

Derin bağlantı URL’si şu yapıyı izler:

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

Temel URL: com.HealthExport://automation

Parametreler: name ve url dışında tüm parametreler isteğe bağlıdır. Parametre adları büyük/küçük harfe duyarlı değildir.

Parametre referansı

Zorunlu parametreler

url (zorunlu)

• Tür: Dize (geçerli URL)
• Açıklama: Sağlık verisinin gönderileceği uç nokta URL’si
• Örnek: https://api.example.com/health-data
• Not: Geçerli bir HTTP/HTTPS URL’si olmalıdır

name (zorunlu)

• Tür: Dize
• Açıklama: Otomasyon için açıklayıcı bir ad
• Örnek: My%20Backend%20API (URL kodlu: «My Backend API»)
• Not: Boşluk veya özel karakter içeriyorsa URL kodlanmalıdır

Temel yapılandırma

format

• Tür: Enum (json, csv)
• Varsayılan: json
• Açıklama: Veri için dışa aktarma biçimi
• Örnek: format=json veya format=csv
• Not: CSV biçimi veri birleştirmeyi otomatik etkinleştirir

enabled

• Tür: Boolean (true, false, 1, 0, yes, no)
• Varsayılan: false
• Açıklama: Oluşturma sonrası otomasyonun hemen etkin olup olmayacağı
• Örnek: enabled=true

datatype

• Tür: Enum (aşağıdaki veri türlerine bakın)
• Varsayılan: healthMetrics
• Açıklama: Dışa aktarılacak sağlık verisi türü
• Örnek: datatype=workouts
• Not: Yalnızca bir veri türü seçilebilir. Bu, uygun dahil etme bayraklarını otomatik ayarlar.

Geçerli veri türleri:

• healthMetrics – Sağlık ölçümleri (adım, kalp atışı, uyku vb.)
• workouts – Egzersiz ve fitness aktiviteleri
• symptoms – Sağlık belirtileri ve durumlar
• ecg – Elektrokardiyogram kayıtları
• heartRateNotification – Yüksek/düşük kalp atışı olayları
• stateOfMind – Ruh hali ve zihinsel durum kayıtları (iOS 18.0+)
• cycleTracking – Adet döngüsü ve üreme sağlığı verileri
• medications – İlaç kayıtları ve uyum (iOS 26.0+)

Dışa aktarma ayarları

period

• Tür: Enum
• Varsayılan: none
• Açıklama: Veri dışa aktarma için tarih aralığı
• Örnek: period=today

Geçerli değerler:

• none – Varsayılan (önceki günün tamamı artı geçerli gün)
• lastsync – Son eşitlemeden beri
• today – Bugün
• yesterday – Dün
• previous7days – Son 7 gün
• realtime – Gerçek zamanlı güncellemeler (saniye eşitleme aralığı gerekir)

interval

• Tür: Enum
• Varsayılan: none
• Açıklama: Zaman gruplama/birleştirme aralığı (yalnızca healthMetrics veri türü için geçerli)
• Örnek: interval=hours

Geçerli değerler:

• none – Varsayılan (birleştirme yok)
• minutes – Dakikaya göre grupla
• hours – Saate göre grupla
• days – Güne göre grupla
• weeks – Haftaya göre grupla
• months – Aya göre grupla
• years – Yıla göre grupla

Not: Bu parametre yalnızca datatype=healthMetrics iken geçerlidir. CSV biçimi her zaman veriyi birleştirir.

aggregatedata

• Tür: Boolean
• Varsayılan: true (CSV için), false (JSON için)
• Açıklama: Verinin birleştirilip özetlenip özetlenmeyeceği (yalnızca JSON ile healthMetrics için geçerli)
• Örnek: aggregatedata=true
• Not: format=csv iken otomatik olarak true olur

aggregatesleep

• Tür: Boolean
• Varsayılan: true
• Açıklama: Uyku verisinin birleştirilip birleştirilmeyeceği
• Örnek: aggregatesleep=true

exportversion

• Tür: Enum (v1, v2, 1, 2)
• Varsayılan: v2
• Açıklama: Dışa aktarma biçimi sürümü
• Örnek: exportversion=v2
• Not: Sürüm 2, gelişmiş antrenman verisi ve daha ayrıntılı üst veri içerir

batchrequests

• Tür: Boolean
• Varsayılan: false
• Açıklama: Veriyi birden çok istekte toplu gönderme (yalnızca JSON ile REST API için geçerli)
• Örnek: batchrequests=true
• Not: Yalnızca format=json ve exportDestination=restApi iken geçerlidir

Eşitleme sıklığı

syncinterval

• Tür: Enum
• Varsayılan: minutes
• Açıklama: Eşitleme sıklığı için aralık
• Örnek: syncinterval=hours

Geçerli değerler:

• minutes – Her N dakikada bir eşitle
• hours – Her N saatte bir eşitle
• days – Her N günde bir eşitle
• weeks – Her N haftada bir eşitle
• seconds – Yalnızca period=realtime iken geçerlidir

Not: REST API otomasyonlarında gerçek zamanlı dışa aktarma kullanılmadığı sürece yalnızca minutes, hours, days ve weeks geçerlidir.

syncquantity

• Tür: Pozitif tam sayı
• Varsayılan: 5
• Açıklama: Eşitlemeler arasındaki aralık sayısı
• Örnek: syncquantity=10 (syncinterval=minutes ise her 10 dakikada bir)
• Not: 0’dan büyük olmalıdır

HTTP yapılandırması

headers

• Tür: Dize (virgülle ayrılmış anahtar-değer çiftleri)
• Varsayılan: Yok
• Açıklama: Kimlik doğrulama veya üst veri için HTTP başlıkları
• Örnek: headers=Authorization,Bearer%20token123,X-API-Key,abc123
• Biçim: key1,value1,key2,value2,...
• Not: Değerler URL kodlanmalıdır. Her başlık hem anahtar hem değer gerektirir.

Başlık örnekleri:

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

requesttimeout

• Tür: Tam sayı (60–86400)
• Varsayılan: 60
• Açıklama: İstek zaman aşımı (saniye)
• Örnek: requesttimeout=300
• Not: 60 ile 86400 saniye arasında olmalıdır (1 dakika ile 24 saat)

Veri türüne özel ayarlar

Sağlık ölçümleri ayarları

metrics

• Tür: Dize (virgülle ayrılmış MetricName rawValues)
• Varsayılan: Tüm kullanılabilir ölçümler
• Açıklama: Dahil edilecek belirli sağlık ölçümleri (yalnızca healthMetrics için)
• Örnek: metrics=Step%20Count,Heart%20Rate,Active%20Energy
• Not: Tam MetricName rawValues kullanılmalıdır. Belirtilmezse tüm kullanılabilir ölçümler dahil edilir.

Yaygın ölçüm adları:

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

Tam liste için uygulamadaki ölçüm seçim ekranına bakın.

Antrenman ayarları

includeroutes

• Tür: Boolean
• Varsayılan: true
• Açıklama: Antrenmanlar için rota verisini dahil et (yalnızca workouts)
• Örnek: includeroutes=true

includeworkoutmetadata

• Tür: Boolean
• Varsayılan: true
• Açıklama: Antrenman sırasında toplanan ölçümleri dahil et (kalp atışı, kalori vb.; yalnızca workouts)
• Örnek: includeworkoutmetadata=true

workoutsmetadatainterval

• Tür: Enum (minutes, seconds)
• Varsayılan: minutes
• Açıklama: Antrenman ölçümleri için zaman gruplaması (yalnızca workouts ve dışa aktarma sürümü v2)
• Örnek: workoutsmetadatainterval=seconds
• Not: Yalnızca datatype=workouts ve exportversion=v2 iken geçerlidir

workouttypes

• Tür: Dize (virgülle ayrılmış UInt değerleri)
• Varsayılan: Boş (tüm antrenman türleri)
• Açıklama: Dahil edilecek belirli antrenman türleri (yalnızca workouts)
• Örnek: workouttypes=1,2,3
• Not: HealthKit antrenman türü tanımlayıcılarını kullanır

Bildirimler

notifyonupdate

• Tür: Boolean
• Varsayılan: true
• Açıklama: Önbelleğe alınan veri güncellendiğinde bildirim al
• Örnek: notifyonupdate=true

notifywhenrun

• Tür: Boolean
• Varsayılan: true
• Açıklama: Otomasyon her çalıştığında bildirim al
• Örnek: notifywhenrun=false

Örnekler

Temel REST API otomasyonu

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

Belirtilen uç noktaya JSON verisi gönderen basit bir otomasyon oluşturur.

Kimlik doğrulama başlıklarıyla

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

Özel kimlik doğrulama başlıkları olan bir otomasyon oluşturur.

Belirli ölçümlerle sağlık ölçümleri

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

Yalnızca adım ve kalp atışını saatlik birleştirerek dışa aktaran bir otomasyon oluşturur.

Rota verisiyle antrenmanlar

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

Rota verisi ve antrenman ölçümleriyle, dışa aktarma sürümü 2 kullanan bir antrenman otomasyonu oluşturur.

Tam yapılandırma örneği

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

Tüm ana parametrelerin ayarlandığı kapsamlı bir örnek.

CSV biçimi örneği

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

CSV dışa aktarma otomasyonu oluşturur. CSV biçimi veri birleştirmeyi otomatik etkinleştirir.

URL kodlama

Parametre değerlerindeki özel karakterler URL kodlanmalıdır. Yaygın kodlamalar:

• Boşluk: %20
• Virgül: %2C
• İki nokta: %3A
• Noktalı virgül: %3B
• Eşittir: %3D
• Ve işareti: %26
• Artı: %2B

Örnek:

• Orijinal: My Automation Name
• Kodlanmış: My%20Automation%20Name

Başlık örneği:

• Orijinal: Authorization, Bearer token123
• Kodlanmış: Authorization,Bearer%20token123

Çoğu programlama dili ve araç URL kodlama işlevleri sunar:

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

Derin bağlantıları test etme

Safari’den (iOS)

1. iOS cihazınızda Safari’yi açın
2. Adres çubuğuna derin bağlantı URL’sini yazın
3. Git’e dokunun
4. Uygulama açılmalı ve otomasyon oluşturulmalıdır

Terminalden (macOS/iOS Simulator)

xcrun simctl openurl booted "com.HealthExport://automation?url=https://api.example.com/health&name=Test&enabled=true"

Xcode’dan

Kesme noktası ekleyin veya hata ayıklayıcı konsolunu kullanın:

let url = URL(string: "com.HealthExport://automation?url=https://api.example.com/health&name=Test&enabled=true")!
try DataModel.shared.handleAPIDeepLink(url)

Kısayollar uygulamasından

1. Yeni bir kısayol oluşturun
2. «URL’leri Aç» eylemini ekleyin
3. Derin bağlantı URL’nizi girin
4. Kısayolu çalıştırın

Sorun giderme

Yaygın sorunlar

"Could not parse the URL"

• URL şemasının doğru olduğunu doğrulayın: com.HealthExport://automation
• Tüm parametre değerlerinin düzgün URL kodlandığını kontrol edin
• Parametre adlarının doğru yazıldığından emin olun (büyük/küçük harf duyarsız)

"Invalid URL parameter value"

• URL’nin geçerli bir HTTP/HTTPS URL’si olduğunu doğrulayın
• URL kodlamasını kontrol edin
• URL’nin geçersiz karakter içermediğinden emin olun

"Invalid data type"

• Tam veri türü değerlerini kullanın: healthMetrics, workouts, symptoms, ecg, heartRateNotification, stateOfMind, cycleTracking, medications
• Yazımı kontrol edin (büyük/küçük harf eşleşmesi desteklenir)

"Invalid sync cadence interval"

• REST API için yalnızca şunları kullanın: minutes, hours, days, weeks
• seconds yalnızca period=realtime iken kullanın

"Aggregation settings are only valid for healthMetrics data type"

• aggregatedata ve interval parametreleri yalnızca datatype=healthMetrics ile çalışır
• Bu parametreleri kaldırın veya veri türünü değiştirin

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

• batchrequests yalnızca format=json iken çalışır
• Biçimi JSON yapın veya batchrequests parametresini kaldırın

"Workout settings are only valid for workouts data type"

• includeroutes, includeworkoutmetadata ve workoutsmetadatainterval yalnızca datatype=workouts ile çalışır
• Veri türünü workouts yapın veya bu parametreleri kaldırın

"Metrics parameter is only valid for healthMetrics data type"

• metrics parametresi yalnızca datatype=healthMetrics ile çalışır
• Veri türünü değiştirin veya metrics parametresini kaldırın

"Invalid metric name"

• Tam MetricName rawValues kullanın (ör. «Step Count», «Heart Rate»)
• Yazımı ve büyük/küçük harfi kontrol edin
• Geçerli adlar için uygulamadaki ölçüm seçim ekranına bakın

"Invalid request timeout"

• 60 ile 86400 saniye arasında olmalıdır
• Bu aralıkta bir değer kullanın

"A name is required for the automation"

• name parametresinin eklendiğinden emin olun
• URL kod çözümünden sonra değerin boş olmadığını kontrol edin

URL uzunluğu sınırlamaları

Çok uzun URL’ler (özellikle çok sayıda ölçüm veya başlıkla) sistem sınırlarını aşabilir. Şunları düşünün:

• metrics parametresinde daha az ölçüm
• Daha az başlık
• Mümkün olduğunda daha kısa parametre değerleri
• Karmaşık yapılandırmaları birden çok daha basit otomasyona bölme

Parametre önceliği

Birden çok parametre çakıştığında:

1. Veri türü seçimi (datatype) dahil etme bayraklarını otomatik sıfırlar
2. CSV biçimi (format=csv) otomatik olarak aggregatedata=true yapar
3. Gerçek zamanlı dönem (period=realtime) syncinterval=seconds gerektirir
4. Uyumsuz kombinasyonlar için doğrulama hataları oluşur

En iyi uygulamalar

1. Otomatik eşitleme (otomasyonlar derin bağlantıyla tetiklendiğinde):

   • Cihazınızı şarj edin ve iPhone Yansıtma kullanın
     • Cihaz şarj olurken iOS performans kısıtlarını azaltır, böylece veri daha sık eşitlenebilir
     • iPhone Yansıtma ile cihaz kilidi açıkmış gibi davranır; böylece Health Auto Export otomatik eylemler için sağlık verisine erişebilir

2. Özel karakter içeren parametre değerlerini her zaman URL kodlayın

3. Önce basit URL’lerle test edin, sonra karmaşıklığı artırın

4. Kolay tanımlama için açıklayıcı adlar kullanın

5. Derin bağlantıları programatik oluşturmadan önce URL’leri doğrulayın

6. Derin bağlantıları ayrıştırırken hataları düzgün şekilde işleyin

7. Üreten araçlar oluşturuyorsanız derin bağlantı biçimlerinizi belgeleyin

8. Çok sayıda ölçüm veya başlık eklerken URL uzunluğunu göz önünde bulundurun

9. Simülatörlerin yanı sıra gerçek cihazlarda da test edin

İlgili belgeler

• REST API otomasyonu kılavuzu – REST API otomasyonları hakkında ayrıntılar
• Otomasyonlara genel bakış – Genel otomasyon kavramları
• Manuel dışa aktarma kılavuzu – Veriyi manuel dışa aktarma

Destek

Bu kılavuzda ele alınmayan sorunlarla karşılaşırsanız:

1. Belirli parametre sorunları için hata iletisini okuyun
2. URL kodlamasının doğru olduğunu doğrulayın
3. Önce minimal bir URL ile test edin
4. Yardım için uygulamadaki Sohbet Desteği düğmesini kullanın