Google Health API'de Veri Yönetimi

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 yapma 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? Sadece okuma mı yapıyorsunuz? Yoksa ikisini de mi yapıyorsunuz?
• Veri deponuz uygulamada veya cihazda yerel olarak mı bulunuyor? 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ı mı? Ölçü birimleri? Farklı örnekleme hızlarına sahip seriler mi var?
• 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 bu işlemlerin nasıl birlikte çalıştığını 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ü

Şekil 1: Google Health API'deki 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 diyeceğiz.

Buradaki "kopyalama", Google Health API'den okuma (geliştirici veri deposuna kopyalama) veya Google Health API'ye yazma (Google Health API'ye kopyalama) gibi ayrı bir etkinliğin yerini alabilir. Bu işlemlerin belirli bir sırada tekrar tekrar yapılmasına senkronizasyon yaşam döngüsü denir.

Ş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österir.

Yazma

1. Yazmak için yeni veriler hazırlama: Verileri harici bir cihazdan veya uygulamadan aktarın ve veri noktalarını Google Health API veri türleriyle uyumlu JSON gösterimlerine biçimlendirin. Yazma işlemleri için özel istemci tarafından atanan kimliklerin şu anda Health API'de desteklenmediğini unutmayın. Bu tür kimlikler POST içinde sağlanabilir ancak yoksayılır.
2. Kayıtları ekleme/güncelleme: REST uç noktalarını kullanarak Google Health API'ye veri noktaları gönderin. Kayıt oluşturmak için POST, mevcut kayıtları eklemek ve güncellemek için PATCH simgesini kullanın. PATCH işlemi için gereken kimlikler, önceki bir POST işleminden (önceki bir döngüdeki sonraki adım) alınmış olmalıdır.
3. 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ğı name veya kimliği geliştirici veri deponuzda ayıklayın ve kalıcı hale getirin. İki tür hakkında daha fazla bilgi için Tanımlama stratejileri bölümüne bakın.

Okuma

1. Kayıtları okuma: REST uç noktalarını (GET ile filter sorgu parametreleri ve pageToken sayfalama veya rollUp ve dailyRollUp gibi toplama uç noktaları) kullanarak Google Health API'deki yeni verileri ve mevcut verilerdeki değişiklikleri getirin ya da Webhook aboneliklerini (projects.subscribers) kullanarak anlık bildirimler alın. Bildirim yalnızca yeni verilerin mevcut olduğunu gösterir, gerçek verilerin ne olduğunu göstermez.
2. Geliştirici veri deposunu mutabakat etme: Yeni ve güncellenmiş verileri geliştirici veri deponuzla mutabakat edin. 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ü daha sonra harici cihazların veya uygulamaların özel ihtiyaçlarına göre uygun aralıklarla tekrarlanır. Bu genellikle kendi veri deponuz ile Google Health API arasında verileri senkronize etmek için önerdiğimiz sıradır.

Tanımlama stratejileri

Google Health API'ye veri yazmayı planlıyorsanız Google Health API'lerle entegrasyonunuzu oluşturmadan önce veri noktaları (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 yoksayılır. Bu seçenekle ilgili ayrıntılar, bilgilendirme amacıyla burada verilmiştir.

1. 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.
2. İstemci Tarafından Atanan Özel Kimlikler (AIP-133 uyarınca, henüz desteklenmemektedir): İstemci uygulaması, benzersiz bir tanımlayıcı (örneğin, UUID veya yerel veritabanı birincil anahtarı) oluşturur ve oluşturma sırasında 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	Müşteri Tarafından Atanan Özel Kimlikler
Kimlik Oluşturma	Sunucu, yürütme sırasında rastgele sistem kimliği oluşturur.POST	İstemci, yazma işleminden önce yerel olarak sabit bir kimlik (UUID v4 / dahili PK) oluşturur.
Kaynak Yolu	.../dataPoints/{server_id} (yanıtta döndürüldü)	.../dataPoints/{custom_id}
Yerel Yazma Sonrası Adımı	Zorunlu. Gelecekteki güncellemeleri/silme işlemlerini etkinleştirmek için döndürülen server_id, yerel veritabanında saklanmalıdır.	Yok. Uygulama zaten kimliğin sahibi.
Kimlik Eşleme Tablosu	Zorunlu. Müşteri, iki yönlü bir eşleme sürdürmelidir (local_id ↔ server_id).	Gerekli değildir. İstemci, kendi birincil anahtarını doğrudan kullanır.
Yeniden Deneme Davranışı (Zayıf Ağ)	Yinelenen Öğeler Riski. Zaman aşımına uğrayan bir POST işlemi yeniden denendiğinde yeni bir sunucu kimliğine sahip yinelenen bir kayıt oluşturulur.	Güvenli ve Idempotent. Aynı custom_id ile POST yeniden deneme, yinelenen oluşturmayı engeller (409 ALREADY_EXISTS döndürür).
Çevrimdışı Senkronizasyon Desteği	Sınırlı. Resmi kaynak kimliklerini almadan önce sunucu yanıtı beklenmelidir.	Tam Öğeler, kararlı kimliklerle çevrimdışı olarak oluşturulabilir ve değiştirilebilir. Ardından, yeniden bağlandığınızda 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 tire) olmalıdır.
Ne zaman seçilir?	Aşağıdaki durumlarda sunucu tarafından oluşturulan kimlikleri seçin: Uygulamanız yalnızca yazma / ekleme işlemine izin veriyor (ör. daha sonra güncellenmeyen veya silinmeyen telemetri ya da adım sayısı gönderme). Uygulamanız, tek tek veri noktalarının yerel ve kalıcı bir veritabanını tutmuyor. Dize doğrulama kısıtlamalarını (ör. 4-63 karakterleri) yönetmeden basitliği tercih ediyorsunuz.	Aşağıdaki durumlarda özel kimlikleri seçin: Cihazlar arasında sağlık kayıtlarını okuyan, yazan ve güncelleyen iki yönlü bir senkronizasyon uygulaması işletiyorsanız. Uygulamanızda, yerel birincil anahtarlara sahip kayıtları depolayan yerel bir veritabanı (ör. Room veya SQLite) var. Kullanıcılarınız verileri çevrimdışı olarak veya güvenli yeniden denemelerin gerekli olduğu aralıklı mobil bağlantılar üzerinden kaydediyor. Arka uç veritabanınız ile API arasındaki kimlik eşleme tablolarını ortadan kaldırmak istiyorsunuz.

Salt okunur senkronizasyon yaşam döngüsü

Şekil 2: Google Health API'de 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 kısmı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ıklı zaman damgaları ve bağlı cihaz senkronizasyonu

Aralık verileri, belirli bir süre boyunca toplanan ölçümleri (ör. adımlar, nabız veya egzersiz seansları) ifade eder. Bunun aksine, belirli bir zamana ait ölçümler arasında yemek günlüğü veya tartı okuması gibi manuel girişler yer alır. Aralık verileri genellikle akıllı saatler ve fitness takip cihazları gibi bağlı cihazların senkronize edilmesinden kaynaklanır.

Aralık zaman damgaları (startTime ve endTime), aralık verileriyle çalışırken benzersiz davranışlar ortaya çıkarır. 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ı cihazlardaki çakışan aralıklar

Fitbit takip cihazları ve Google Pixel Watch gibi bağlı cihazlar, takıldıkları süre boyunca yüksek frekanslı biyometrik ölçümler toplamaya devam eder. Bir cihaz, Google Health ile veri noktalarını senkronize ettikten sonra mevcut kayıtları geriye dönük olarak değiştirmez. Kayıtlı aralık zaman damgaları değişmeden kalır.

Ancak sonraki senkronizasyon döngülerinden önce cihaz üzerindeki algoritmalar genellikle ham sensör telemetrisini yeniden yorumlar. Cihaz, önceki saatlerde toplanan okumaları yeniden gruplandırır. Cihaz tekrar senkronize edildiğinde yeni veri noktaları yüklenir. Başlangıç ve bitiş sınırları, daha önce depolanmış aralıklarla çakışabilir.

Örneğin, etkinlik verileri iki ardışık grup halinde senkronize edilen bir akıllı saat kullanan bir kullanıcıyı ele alalım:

1. İlk senkronizasyon sırasında cihaz, 10:00:00Z ile 10:14:59Z arasındaki verileri kapsayan bir veri noktası yükler.
2. Cihaz üzerinde yeniden hesaplamanın ardından, ikinci bir senkronizasyon 10:14:00Z ile 10:28:59Z arasındaki aralığı kapsayan başka bir veri noktası yükler.

Her iki kayıt da Google Health arka ucunda bağımsız olarak saklanır. Bu nedenle, 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ı uzlaştırma

Bu çakışan aralıkları list veya reconcile uç noktasını kullanarak işleyebilirsiniz. Uygulama gereksinimlerinize uygun uç noktayı seçin:

Özellik	list uç noktası	reconcile uç noktası
HTTP yöntemi	GET https://health.googleapis.com/v4/users/me/dataTypes/<var>dataType</var>/dataPoints	GET https://health.googleapis.com/v4/users/me/dataTypes/<var>dataType</var>/dataPoints:reconcile
Çakışma davranışı	Tüm depolanan kayıtları, yinelenenleri kaldırma işlemi uygulanmadan yüklenmiş olarak döndürür. Aralıklar çakıştığında her iki kayıt da döndürülür.	Cihazlar ve senkronizasyon oturumları arasında çakışmaları giderir ve yinelenen kayıtları tek bir kesintisiz akışta birleştirir.
Avantajları	Her cihaz ve senkronizasyon grubu tarafından yüklenen her kaydın eksiksiz ve değiştirilmemiş bir denetleme izini sağlar.	Çakışan aralıkları ve çeşitli cihazlardaki çakışmaları otomatik olarak ele alarak zaman çizelgesi oluşturma ve süre hesaplamalarını basitleştirir.
Dezavantajları	Çakışan aralıkları, çeşitli cihazlarla ilgili çakışmaları ve bilekte olmayan dönemleri algılamak ve çözmek uygulamanızın sorumluluğundadır.	Alt öğe olan çakışan kayıtlar yanıttan çıkarıldığından, tek tek cihaz senkronizasyonu grupları ayrı olarak 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 uzlaştırır.

Mutabakat, yapay bir zaman birliği sentezlemek yerine yetkili kaydı seçerek çakışan oturumları çözer. Örneğin, 11:00:00Z ile 11:30:00Z ve 11:20:00Z ile 11:50:00Z arasındaki birleştirme işlemi 11:00:00Z ile 11:50:00Z arasında yapılmaz. Uzlaştırılmış yanıt, kazanan veri noktasını orijinal olarak kaydedilmiş aralığıyla birlikte döndürür. Bu, söz konusu oturumun ölçülen telemetri ve metriklerinin bütünlüğünü korur.

Ş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.

Şekil 3: Çakışan oturum uzlaştırması ve yapay zaman birliği birleştirme

Uç noktalar kılavuzunda eksiksiz istek ve yanıt örnekleri verilmektedir. Ham list kayıtlarını reconcile çıkışıyla karşılaştırmak için Aralık verilerinin mutabakatı yapılmış görünümünü elde etme başlıklı makaleyi inceleyin.

list uç noktası, cihaz teşhisleri ve veri denetimleri için tasarlanmıştır. İş akışınızda, her cihaz tarafından yüklenen değiştirilmemiş kayıtların incelenmesi gerektiğinde bu özelliği kullanın. list ile sorgulama yaparken istemci mantığınız, ham verilerdeki 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ı (startTime ve endTime) tüm veri kaynaklarında evrensel olarak değişmez değildir. Bir kaydın alanlarını yalnızca kaydı oluşturan veya kaydın sahibi olan kullanıcı değiştirebilir. Diğer uygulamalar, oluşturmadıkları veri noktalarını düzenleyemez.

Bir sahip uygulaması, mevcut kayıtlarını güncellemek için patch uç noktasını kullanabilir. Başlangıç veya bitiş zaman damgalarını değiştirmek bu kapsamda değerlendirilir. PATCH ile zaman damgalarını güncelleme örneği için Uç Noktalar Kılavuzu'ndaki Mevcut veriler için aralık zaman damgalarını güncelleme başlıklı makaleyi inceleyin.

Benzer şekilde, Health Connect veya iş ortağı uygulamaları gibi harici platformlardan senkronize edilen veri noktaları da kaynak verilerdeki güncellemeleri devralır. Kaynak uygulama mevcut bir kaydı değiştirdiğinde bu güncellemeler Google Health'e aktarılır.

Dikkat: Bir veri noktasının aralık zaman damgalarının kalıcı olarak sabitlendiğini asla varsaymayın. Veri noktalarını yerel olarak önbelleğe alırken senkronizasyon ardışık düzeninizin mevcut kayıtlardaki güncellemeleri ve aralıklarını işlediğinden emin olun.