Google Health API'deki verilerle çalışmak, temel olarak buluttaki Google Health API veri deposu ile kendi uygulamanız veya arka uç veri deponuz arasında veri senkronizasyonu döngüsüdür. Ancak bu döngü, çeşitli faktörlere bağlı olarak farklı biçimlerde olabilir:
- Google Health API'ye veri yazıyor musunuz? Yalnızca okuma mı? Yoksa ikisini de mi yapıyorsunuz?
- Veri deponuz uygulama veya cihazda yerel mi? Yoksa kendi bulutunuzda mı?
- Google Health API verilerini kullanıcının uygulaması ile giyilebilir cihaz arasında senkronize etmeniz gerekiyor mu? Cihazları ne sıklıkta senkronize ediyorsunuz?
- Ne tür verilerle çalışıyorsunuz? Temel sayılar Ölçü birimleri Farklı örnekleme oranlarına sahip seriler mi?
- Uygulamanız arka plandayken veri okumayı planlıyor musunuz?
- Uygulamanız kullanıcı izinlerini almadan önce kaydedilen geçmiş verilerle çalışmayı planlıyor musunuz?
Tüm bunların nasıl bir araya geldiğini anlamak için Google Health API senkronizasyon yaşam döngüsüne göz atın. Bu yaşam döngüsünün iki sürümü vardır: standart (okuma ve yazma) ve salt okunur.
Standart senkronizasyon yaşam döngüsü
Google Health API ile entegrasyon, verilerin bir uygulamaya veya arka uç veri deposuna kopyalanması anlamına gelir. Bu dokümanda kolaylık sağlamak için bu veri deposuna geliştirici veri deposu adını vereceğiz.
Buradaki "kopyalama" ifadesi, Google Health API'den okuma (geliştirici veri deposuna kopyalama) veya Google Health API'ye yazma (Google Health API'ye kopyalama) gibi ayrı etkinliklerin yerine kullanılabilir. Bu işlemlerin belirli bir sırayla tekrar tekrar gerçekleştirilmesi, senkronizasyon yaşam döngüsünü oluşturur.
Şekil 1, daha önce bahsedilen faktörlerden bağımsız olarak okuma ve yazma işlemlerini içeren standart senkronizasyon yaşam döngüsünü göstermektedir.
Yazma
- Yazmak için yeni verileri hazırlama: Harici bir cihazdan veya uygulamadan veri aktarın ve veri noktalarını Google Health API veri türleriyle uyumlu JSON temsilleri olarak biçimlendirin. Yazma işlemleri için istemci tarafından atanan özel kimlikler şu anda Health API'de desteklenmemektedir. Bu tür kimlikler
POSTiçinde sağlanabilir ancak yok sayılır. - Kayıtları ekleme/güncelleme: REST uç noktalarını kullanarak veri noktalarını Google Health API'ye gönderin. Kayıt oluşturmak için
POST, mevcut kayıtları eklemek ve güncellemek içinPATCHkullanın.PATCHişlemi için gereken kimlikler, önceki birPOSTişleminden (önceki döngüdeki sonraki adım) gelir. - Döndürülen kaynak kimliklerini işleme: Sunucu tarafından oluşturulan kimlikleri kullanırken, gelecekteki güncellemeleri (
PATCH) veya silme işlemlerini (DELETE) etkinleştirmek için sunucu tarafından döndürülen kaynağınameveya kimliği geliştirici veri deponuza ayıklayın ve saklayın. İki tür hakkında daha fazla bilgi için Tanımlama stratejileri bölümüne bakın.
Okuma
- Kayıtları okuma: REST uç noktalarını (
filtersorgu parametreleri vepageTokensayfalama ileGETveyarollUpvedailyRollUpgibi toplama uç noktaları) kullanarak Google Health API'den yeni verileri ve mevcut verilerdeki değişiklikleri alın ya da Webhook aboneliklerini (projects.subscribers) kullanarak bildirim alın. Bildirimler yalnızca yeni verilerin mevcut olduğunu gösterir, gerçek verilerin ne olduğunu göstermez. - Geliştirici veri deposunu mutabık kılma: Yeni ve güncellenmiş verileri geliştirici veri deponuzla mutabık kılın. Bağlı cihazlar, senkronizasyon sırasında çakışan aralıklar oluşturabilir. Google Health API'nin bu sorunları nasıl çözdüğünü öğrenmek için Aralık zaman damgaları ve bağlı cihaz senkronizasyonu başlıklı makaleyi inceleyin.
Bu döngü, harici cihazların veya uygulamaların özel ihtiyaçlarına göre uygun aralıklarla tekrarlanır. Kendi veri deponuz ile Google Health API arasında veri senkronizasyonu için genellikle bu sırayı öneririz.
Tanımlama stratejileri
Google Health API'ye veri yazmayı planlıyorsanız Google Health API'lerle entegrasyonunuzu oluşturmadan önce, veri noktalarını (temel veri birimi) oluştururken bir kaynak tanımlama stratejisi seçmeniz gerekir.
Yazma işlemleri için istemci tarafından atanan kimlikler şu anda Health API'de desteklenmemektedir.
Bu tür kimlikler POST içinde sağlanabilir ancak yok sayılır. Bu seçenekle ilgili ayrıntılar burada bilgilendirme amacıyla verilmiştir.
- Sunucu Tarafından Oluşturulan Kimlikler (varsayılan seçenek): İstemci, verileri kimlik olmadan gönderir ve Google Health API arka ucu, benzersiz bir sistem tanımlayıcısı oluşturup döndürür.
- İstemci Tarafından Atanan Özel Kimlikler (AIP-133 uyarınca, henüz desteklenmiyor): İstemci uygulaması, benzersiz bir tanımlayıcı (örneğin, UUID veya yerel veritabanı birincil anahtarı) oluşturur ve oluşturma sırasında bunu kaynak yolunda sağlar.
Aşağıdaki tabloda, entegrasyonunuz için doğru yaklaşımı seçmenize yardımcı olmak amacıyla her iki tanımlama stratejisi karşılaştırılmaktadır:
| Özellik | Sunucu Tarafından Oluşturulan Kimlikler | İstemci Tarafından Atanan Özel Kimlikler |
|---|---|---|
| Kimlik oluşturma | Sunucu, POST yürütme sırasında rastgele sistem kimliği oluşturur. |
İstemci, yazma işleminden önce yerel olarak kararlı kimlik (UUID v4/dahili PK) oluşturur. |
| Kaynak yolu | .../dataPoints/{server_id} (yanıtta döndürülür) |
.../dataPoints/{custom_id} |
| Yazma Sonrası Yerel Adım | Zorunlu. Gelecekteki güncellemeleri/silme işlemlerini etkinleştirmek için döndürülen server_id yerel veritabanında depolanmalıdır. |
Yok. Uygulama zaten kimliğe sahip. |
| Kimlik Eşleme Tablosu | Zorunlu. Müşteri, 2 yönlü bir eşleme (local_id ↔ server_id) sürdürmelidir. |
Gerekli değil. İstemci, kendi birincil anahtarını doğrudan kullanır. |
| Yeniden Deneme Davranışı (Zayıf Ağ) | Yinelenen kayıt riski. Zaman aşımına uğrayan bir POST işlemini yeniden denemek, yeni bir sunucu kimliğiyle yinelenen bir kayıt oluşturur. |
Güvenli ve eş güçlü. Aynı custom_id ile POST işlemini yeniden denemek, yinelenen oluşturmayı önler (409
ALREADY_EXISTS döndürür). |
| Çevrimdışı Senkronizasyon Desteği | Sınırlı. Resmi kaynak kimliklerini referans vermeden önce sunucu yanıtını beklemelidir. | Tam. Öğeler, sabit kimliklerle çevrimdışı olarak oluşturulup değiştirilebilir ve yeniden bağlandığında sorunsuz bir şekilde senkronize edilebilir. |
| Biçim kısıtlamaları | Tamamen sunucu tarafından işlenir. | ^[a-z0-9-]{4,63}$ (4-63 küçük harf, alfanümerik karakter ve kısa çizgi) kuralına uymalıdır. |
| Ne Zaman Seçilmeli? |
Aşağıdaki durumlarda sunucu tarafından oluşturulan kimlikleri seçin:
|
Aşağıdaki durumlarda özel kimlikleri seçin:
|
Salt okunur senkronizasyon yaşam döngüsü
Yalnızca Google Health API'den okuma yapmayı amaçlayan bir uygulama, verileri geliştirici veri deposuna kopyalamalı ve yaşam döngüsünün mutabakat bölümünü yönetmelidir.
Okuma bölümünde ele alınan görevler burada da geçerlidir.
Şekil 2'de salt okunur yaşam döngüsü gösterilmektedir.
Aralık zaman damgaları ve bağlı cihaz senkronizasyonu
Aralık verileri, belirli bir süre boyunca toplanan ölçümleri (ör. adım sayısı, nabız veya egzersiz seansları) temsil eder. Buna karşılık, anlık ölçümler, yiyecek günlüğü veya tartı ölçümü gibi manuel girişleri içerir. Aralık verileri genellikle akıllı saatler ve fitness takip cihazları gibi bağlı cihazların senkronizasyonundan elde edilir.
Aralık zaman damgaları (REST JSON yüklerinde startTime ve endTime veya filtre ifadelerinde ve gRPC'de start_time ve end_time), aralık verileriyle çalışırken benzersiz davranışlar sunar. Bu bölümde, çakışan aralıkların neden oluştuğu açıklanmakta ve list ile reconcile uç noktaları karşılaştırılmaktadır.
Bağlı cihazlardan gelen çakışan aralıklar
Fitbit takip cihazları ve Google Pixel Watch gibi bağlı cihazlar, takılıyken sürekli olarak yüksek frekanslı biyometrik ölçümler toplar. Bir cihaz, veri noktalarını Google Health ile senkronize ettikten sonra mevcut kayıtları geriye dönük olarak değiştirmez. Depolanan aralık zaman damgaları değişmez.
Ancak sonraki senkronizasyon döngülerinden önce, cihaz üzerindeki algoritmalar genellikle ham sensör telemetrisini yeniden yorumlar. Cihaz, önceki saatlerde toplanan ölçümleri yeniden gruplandırır. Cihaz tekrar senkronize edildiğinde yeni veri noktalarını yükler. Başlangıç ve bitiş sınırları, daha önce depolanan aralıklarla çakışabilir.
Örneğin, akıllı saat takan bir kullanıcının etkinlik verilerinin art arda iki grup halinde senkronize edildiğini varsayalım:
- İlk senkronizasyon sırasında cihaz,
10:00:00Zile10:14:59Zarasındaki dönemi kapsayan bir veri noktası yükler. - Cihaz üzerinde yeniden hesaplama yapıldıktan sonra, ikinci bir senkronizasyon işlemiyle
10:14:00Zile10:28:59Zarasındaki dönemi kapsayan başka bir veri noktası yüklenir.
Her iki kayıt da Google Health arka ucunda bağımsız olarak depolanır. Sonuç olarak, her iki veri noktası da 10:14:00Z ile 10:14:59Z arasındaki aralığı kapsar.
Bu durum, ham kayıtlar sorgulanırken 59 saniyelik bir çakışmaya neden olur.
Listeyi karşılaştırma ve uç noktaları mutabık kılma
Bu çakışan aralıkları list veya reconcile uç noktasını kullanarak yönetebilirsiniz. Uygulama gereksinimlerinize uygun uç noktayı seçin:
| Özellik | list uç nokta |
reconcile uç nokta |
|---|---|---|
| HTTP yöntemi | GET https://health.googleapis.com/v4/users/me/dataTypes/dataType/dataPoints |
GET https://health.googleapis.com/v4/users/me/dataTypes/dataType/dataPoints:reconcile |
| Çakışma davranışı | Depolanan tüm kayıtları, tekilleştirme olmadan yüklendiği şekilde döndürür. Aralıklar çakıştığında her iki kayıt da döndürülür. | Çakışmaları çözer ve cihazlar ile senkronizasyon oturumları arasında çakışan kayıtları tek bir sürekli akışta birleştirir. |
| Avantajları | Her cihaz ve senkronizasyon grubu tarafından yüklenen her kaydın eksiksiz ve değiştirilmemiş bir denetim kaydını sağlar. | Çakışan aralıkları ve çeşitli cihazlarla ilgili çakışmaları otomatik olarak işleyerek zaman çizelgesi oluşturma ve süre hesaplamalarını basitleştirir. |
| Dezavantajları | Uygulamanız; çakışan aralıkları, çeşitli cihazlar arasındaki çakışmaları ve bileğe takılı olmayan dönemleri algılayıp çözmekten sorumludur. | Alt düzey çakışan kayıtlar yanıttan çıkarılır. Bu nedenle, ayrı cihaz senkronizasyonu grupları tek tek denetlenemez. |
reconcile uç noktası, kullanıcı arayüzleri çizmek, etkinlik zaman çizelgelerini oluşturmak ve çakışmayan süre toplamlarını hesaplamak için tasarlanmıştır. Yeniden gruplandırılmış senkronizasyon oturumlarındaki çakışan aralıkları çözer. Ayrıca, saat ve telefon gibi birden fazla cihazda aynı anda kaydedilen etkinlikleri de mutabık kılar.
Mutabakat, yapay bir zaman birliği oluşturmak yerine yetkili kaydı seçerek çakışan oturumları çözer. Örneğin, 11:00:00Z - 11:30:00Z ve 11:20:00Z - 11:50:00Z aralıklarını 11:00:00Z - 11:50:00Z olarak birleştirmez. Mutabakatlı yanıt, kazanan veri noktasını
orijinal kayıtlı aralığıyla döndürür. Bu sayede, oturumun ölçülen telemetri ve metriklerinin bütünlüğü korunur.
Şekil 3'te, reconcile uç noktasının çakışan oturumları nasıl işlediği gösterilmektedir.
Yapay bir zaman birleşimi oluşturmak yerine yetkili kaydı seçer.
Endpoints kılavuzunda eksiksiz istek ve yanıt örnekleri verilmiştir. Ham list kayıtlarını reconcile çıkışıyla karşılaştırmak için Aralık verilerinin mutabakatı yapılmış bir görünümünü alma başlıklı makaleyi inceleyin.
list uç noktası, Cihaz Sorun Tanılama ve veri denetimleri için tasarlanmıştır. İş akışınız, her cihaz tarafından yüklenen değiştirilmemiş kayıtların incelenmesini gerektirdiğinde bu seçeneği kullanın. list ile sorgulama yaparken istemci mantığınız, ham verilerdeki tüm aralık çakışmalarını işlemelidir.
Zaman damgası değişkenliği ve sahip güncellemeleri
Bağlı cihazlar, normal senkronizasyon döngüleri sırasında depolanan zaman damgalarını geriye dönük olarak değiştirmez. Ancak aralık zaman damgaları (REST JSON yüklerinde startTime ve endTime, filtre ifadelerinde ve gRPC'de start_time ve end_time) tüm veri kaynaklarında evrensel olarak sabit değildir. Bir kaydın alanlarını yalnızca kaydı oluşturan asıl kişi veya kaydın sahibi değiştirebilir. Diğer uygulamalar, oluşturmadıkları veri noktalarını düzenleyemez.
Sahip uygulama, mevcut kayıtlarını güncellemek için patch uç noktasını kullanabilir. Buna, başlangıç veya bitiş zaman damgalarının değiştirilmesi de dahildir. Bu işlem, sunucudaki hem UTC (startTime ve endTime) hem de resmi saat (civilStartTime ve civilEndTime) alanlarını günceller. PATCH ile zaman damgalarını güncelleme örneği için Endpoints kılavuzundaki Mevcut veriler için aralık zaman damgalarını güncelleme bölümüne bakın.
Benzer şekilde, Health Connect veya iş ortağı uygulamaları gibi harici platformlardan senkronize edilen veri noktaları, kaynak platformdan güncellemeleri alır. Health Connect daha sonra orijinal üçüncü taraf uygulamasından senkronize edilmiş bir kayıt için güncelleme alırsa bu değişiklikler yayılır ve mevcut kaydın üzerine yazılır.