Google Health API, uygulamanızın kullanıcıların sağlık verileri değiştiğinde anlık bildirimler almasına olanak tanır. Sunucunuz, değişiklikleri yoklamak yerine Google Health API'de veriler kullanıma sunulur sunulmaz bir HTTPS POST isteği (webhook) alır.{:target="_blank" class="external"}
Desteklenen veri türleri
Webhook bildirimleri aşağıdaki veri türleri için desteklenir:
- Aktif Bölge Dakikası
- Etkinlik Düzeyi
- Rakım
- Kan Şekeri
- Vücut Yağ Yüzdesi
- Nabız bölgesindeki kalori
- Günlük nabız değişkenliği
- Günlük nabız bölgeleri
- Günlük oksijen doygunluğu
- Günlük solunum hızı
- Günlük dinlenme nabzı
- Günlük Uyku Sıcaklığı Türevleri
- Mesafe
- Egzersiz
- Döşeme
- Nabız
- Nabız değişkenliği
- Yükseklik
- Sıvı alımı günlüğü
- Beslenme Günlüğü
- Solunum Hızı Uyku Özeti
- Maksimum oksijen tüketimi koşusu
- Hareketsiz Kalma Süresi
- Uyku
- Adımlar
- Nabız bölgesinde geçirilen süre
- Toplam Kalori
- Ağırlık
Bu veri türleri için bildirimler yalnızca kullanıcı, ilgili kapsamların birine izin verdiğinde gönderilir:
- Adım, yükseklik, mesafe ve kat veri türlerini kapsayan aktivite:
https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonlyhttps://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
- Kilo veri türünü kapsayan Sağlık Metrikleri:
https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonlyhttps://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.writeonly
- Uyku veri türünü kapsayan Uyku:
https://www.googleapis.com/auth/googlehealth.sleep.readonlyhttps://www.googleapis.com/auth/googlehealth.sleep.writeonly
IAM hizmet hesapları
Zorunlu olmasa da Google Health API için aboneleri yapılandırırken IAM hizmet hesabı kullanmanızı öneririz. Hizmet hesapları, aşağıdaki özellikler sayesinde uygulama iş yükleri için standart kullanıcı hesaplarına kıyasla daha iyi güvenlik sağlar:
- Otomatik olarak oluşturulan kısa ömürlü kimlik bilgileri: Hizmet hesapları, Google Cloud yürütme ortamına (ör. Compute Engine, Cloud Run veya Google Kubernetes Engine) eklendiğinde otomatik olarak güvenli ve kısa ömürlü kimlik bilgileri alır ve bunları döndürür. Bu, kalıcı statik anahtarları yönetme ve depolama risklerini ortadan kaldırır.
- En az ayrıcalık ilkesi: Hizmet hesapları, iş yükleri için özel kimlikler sağlar. Bu kullanıcılara yalnızca abone uç noktalarını yönetmek için gereken belirli izinleri verebilir, böylece Google Cloud kaynaklarınıza daha geniş kapsamlı erişimi önleyebilirsiniz.
- Yaşam döngüsü bağımsızlığı: Hizmet hesapları, herhangi bir kullanıcının hesabından bağımsız olarak çalışır. Bu sayede, personel değişikliklerinin uzun vadeli kimlik doğrulama kararlılığını etkilememesi sağlanır.
Hizmet hesabı oluşturma
Abone uygulamanızı bir hizmet hesabı kullanarak kimlik doğrulayacak şekilde yapılandırmak için:
- Hizmet hesabı oluşturun: Google Cloud Console'da projenizin IAM ve Yönetici sayfasına giderek kullanıcı tarafından yönetilen yeni bir hizmet hesabı oluşturun.
- Gerekli IAM rollerini verin: Google Cloud projenizde aboneleri yönetmek için hizmet hesabına uygun rolleri atayın.
- Hizmet hesabını iş yükünüze ekleyin: Abone mantığınızı barındıran ortamı yeni hizmet hesabı olarak çalışacak şekilde yapılandırın.
Bu sayede, uygulama kodunuz (ör. Google API istemci kitaplıkları)
projects.subscribersREST API'sini çağırırken hizmet hesabının kısa ömürlü kimlik bilgilerini otomatik olarak algılayıp kullanabilir.
ETBM rolleri
Google Health API abonelerini veya aboneliklerini yönetmek için API çağrılarını yapan kimliğe bürünülmüş hizmet hesabına uygun rolü vermeniz gerekir. Gerekli erişim düzeyine bağlı olarak aşağıdaki rollerden birini atayın:
- Google Health API Read
- Google Health API Düzenleyicisi
- Google Health API Admin
Google Health API IAM rolleri ve izinleri hakkında daha fazla bilgi edinin.
Aboneleri yönetme
Bildirimleri alabilmeniz için uygulamanızın bildirim uç noktasını temsil eden bir abone kaydetmeniz gerekir. Aboneleri projects.subscribers adresinde bulunan REST API'yi kullanarak yönetebilirsiniz.
Abone uç noktanız HTTPS (TLSv1.2+) kullanmalı ve herkese açık olmalıdır.
Google Health API, abone oluşturma ve güncelleme sırasında uç nokta URI'sinin size ait olduğunu doğrulamak için doğrulama işlemi yapar. Doğrulama başarısız olursa abone oluşturma ve güncelleme işlemleri FailedPreconditionException ile başarısız olur.
Abone oluşturma
Projenize yeni bir abone kaydetmek için
create
uç noktasını kullanın. Şu bilgileri sağlamanız gerekir:
project-id: Web kancası hizmet hesabının oluşturulduğu proje numarası.subscriberId: Abone için sağladığınız benzersiz tanımlayıcı. Bu kimlik 4 ile 36 karakter arasında olmalı ve normal ifadeyle ([a-z]([a-z0-9-]{2,34}[a-z0-9])) eşleşmelidir.endpointUri: Webhook bildirimlerinin hedef URL'si.subscriberConfigs: Bildirim almak istediğiniz veri türleri ve her biri için geçerli olan abonelik politikası.endpointAuthorization: Uç noktanızın yetkilendirme mekanizması. Bu, sizin sağladığınız birsecretiçermelidir.secretdeğeri, her bildirim iletisindeAuthorizationüstbilgisiyle birlikte gönderilir. Gelen isteklerin Google Health API'den geldiğini doğrulamak için bu jetonu kullanabilirsiniz. Örneğin, Taşıyıcı kimlik doğrulaması içinsecretdeğeriniBearer R4nd0m5tr1ng123, Temel kimlik doğrulaması için iseBasic dXNlcjpwYXNzd29yZA==olarak ayarlayabilirsiniz.
subscriberConfigs içinde her veri türü için subscriptionCreatePolicy ayarlamanız gerekir. Otomatik abonelikleri kullanmak için AUTOMATIC, kullanıcı aboneliklerini kendiniz yönetmek için MANUAL olarak ayarlayın. Her seçenek hakkında daha fazla bilgi için otomatik abonelikler ve manuel abonelikler başlıklı makaleleri inceleyin.
İstek
POST https://health.googleapis.com/v4/projects/project-id/subscribers?subscriberId=subscriber-id
{
"endpointUri": "https://myapp.com/webhooks/health",
"subscriberConfigs": [
{
"dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
"subscriptionCreatePolicy": "AUTOMATIC"
},
{
"dataTypes": ["sleep"],
"subscriptionCreatePolicy": "MANUAL"
}
],
"endpointAuthorization": {
"secret": "Bearer example-secret-token"
}
}Yanıt
{
"name": "projects/project-id/subscribers/subscriber-id",
"endpointUri": "https://myapp.com/webhooks/health",
"subscriberConfigs": [
{
"dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
"subscriptionCreatePolicy": "AUTOMATIC"
},
{
"dataTypes": ["sleep"],
"subscriptionCreatePolicy": "MANUAL"
}
]
}Aboneleri listeleme
Projenize kayıtlı tüm aboneleri almak için list uç noktasını kullanın.
İstek
GET https://health.googleapis.com/v4/projects/project-id/subscribers
Yanıt
{
"subscribers": [
{
"name": "projects/project-id/subscribers/subscriber-id",
"endpointUri": "https://myapp.com/webhooks/health",
"subscriberConfigs": [
{
"dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
"subscriptionCreatePolicy": "AUTOMATIC"
},
{
"dataTypes": ["sleep"],
"subscriptionCreatePolicy": "MANUAL"
}
],
"endpointAuthorization": {
"authorizationTokenSet": true
}
}
],
"totalSize": 1
}Abone güncelleme
Projenizdeki bir aboneyi güncellemek için patch uç noktasını kullanın. Güncellenebilecek alanlar şunlardır: endpointUri, subscriberConfigs ve endpointAuthorization.
Alanları, updateMask sorgu parametresi ve istek gövdesi sağlayarak güncellersiniz. updateMask, güncellemek istediğiniz alan adlarının virgülle ayrılmış bir listesini içermelidir. Alan adları için camel case kullanılmalıdır (örneğin, endpointUri). İstek gövdesi, güncellemek istediğiniz alanların yeni değerlerini içeren kısmi bir Abone nesnesi içermelidir. Yalnızca updateMask içinde belirtilen alanlar güncellenir. İstek gövdesinde updateMask'da bulunmayan alanlar sağlarsanız bu alanlar yoksayılır.
endpointUri veya endpointAuthorization güncellerseniz uç nokta doğrulaması gerçekleştirilir. Ayrıntılar için Uç nokta doğrulaması başlıklı makaleyi inceleyin.
subscriberConfigs güncellenirken bunun bir birleştirme değil, tam değiştirme olduğunu unutmayın. subscriberConfigs, updateMask içinde yer alıyorsa bu abone için depolanan tüm yapılandırmaların üzerine istek gövdesinde sağlanan liste yazılır. Yapılandırma eklemek veya kaldırmak için yapılandırmaların tamamını sağlamanız gerekir. Diğer alanları güncelliyorsanız ve mevcut yapılandırmalarınızı korumak istiyorsanız subscriberConfigs öğesini updateMask öğesinden çıkarın.
İstek
PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id?updateMask=endpointUri
{
"endpointUri": "https://myapp.com/new-webhooks/health"
}Yanıt
{
"name": "projects/project-id/subscribers/subscriber-id",
"endpointUri": "https://myapp.com/new-webhooks/health",
"subscriberConfigs": [
{
"dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
"subscriptionCreatePolicy": "AUTOMATIC"
},
{
"dataTypes": ["sleep"],
"subscriptionCreatePolicy": "MANUAL"
}
]
}Abone silme
Bir aboneyi projenizden kaldırmak için delete uç noktasını kullanın. Silindikten sonra abone artık bildirim almaz.
İstek
DELETE https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id
Yanıt
Silme işlemi başarılı olursa HTTP durumu "200 OK" olan boş bir yanıt gövdesi döndürülür.{}Uç nokta doğrulaması
Google Health API, bildirim teslimatınızın güvenliğini ve güvenilirliğini sağlamak için abone oluşturduğunuzda veya uç nokta yapılandırmasını güncellediğinizde (endpointUri veya endpointAuthorization) zorunlu iki adımlı doğrulama el sıkışması gerçekleştirir. Bu işlem, API çağrısı sırasında eşzamanlı olarak gerçekleştirilir. Hizmet, uç nokta URI'nize iki otomatik POST isteği gönderir. Bu isteklerde, JSON gövdesi {"type": "verification"} ile birlikte User-Agent Google-Health-API-Webhooks-Verifier kullanılır.
- Yetkilendirilmiş el sıkışma: İlk istek, yapılandırılmış
Authorizationbaşlığınızla birlikte gönderilir. Sunucunuz200 OKveya201 Createddurumuyla yanıt vermelidir. - Yetkisiz sorgu: İkinci istek kimlik bilgileri olmadan gönderilir.
Sunucunuz
401 Unauthorizedveya403 Forbiddendurumuyla yanıt vermelidir.
Bu el sıkışma, uç noktanızın etkin olduğunu ve güvenliği doğru şekilde uyguladığını onaylar. Adımlardan biri başarısız olursa API isteği FAILED_PRECONDITION hatasıyla başarısız olur. Yalnızca bu el sıkışma başarılı olduktan sonra aboneniz kaydedilir ve sağlık verileri bildirimleri alacak şekilde etkinleştirilir.
Anahtar rotasyonu
endpointAuthorization için anahtarları döndürmeniz gerekiyorsa şu adımları uygulayın:
- Uç noktanızı hem eski hem de yeni
endpointAuthorizationdeğerleri kabul edecek şekilde yapılandırın. endpointAuthorizationdeğerini kullanarak abone yapılandırmasını yeniendpointAuthorizationdeğeriyle güncelleyin?updateMask=endpointAuthorizationilepatchisteği göndererek.- 2. adımın başarılı olduğunu onayladıktan sonra uç noktanızı yalnızca yeni
endpointAuthorizationdeğerini kabul edecek şekilde yapılandırın.
Kullanıcı abonelikleri
Google Health API, kullanıcı aboneliklerini verimli bir şekilde yönetmenize yardımcı olur ve kullanıcı oryantasyonu sırasında manuel kayıt ihtiyacını azaltır.
Otomatik abonelikler
Otomatik abonelikleri kullanmanızı öneririz. Bu özelliği etkinleştirmek için belirli veri türleri için subscriberConfigs öğenizde subscriptionCreatePolicy değerini AUTOMATIC olarak ayarlayın. AUTOMATIC politikasıyla belirttiğiniz dataTypes, Google Health API'nin bildirim gönderdiği veri türleriyle aynıdır. Ancak bu veri türleri için kullanıcı izni de verilmiş olmalıdır.
Kullanıcı, AUTOMATIC politikasına sahip veri türlerine karşılık gelen kapsamlar için uygulama izni verdiğinde Google Health API, kullanıcı tarafından izin verilen veri türleri ile söz konusu kullanıcı için otomatik abone yapılandırması veri türleri arasındaki kesişimden kaynaklanan veri türlerini otomatik olarak izler ve bu veri türleriyle ilgili bildirimler gönderir. Bu kullanıcının bu türler için yeni veriler oluşturduğu her seferde uç noktanıza bildirim gönderilir. Bu özellik, abone oluşturmadan önce veya sonra izin veren kullanıcılar için geçerlidir. Bildirimler, abone oluşturulmadan önce oluşturulan veriler için doldurulmaz.
Kullanıcı izni iptal ederse ilgili veri türleriyle ilgili bildirimler durdurulur. Otomatik abonelikler Google tarafından yönetilir ve tek tek listelenemez veya silinemez. Yalnızca üst abone silindiğinde kaldırılırlar.
Manuel abonelikler
Aboneniz belirli veri türleri için MANUAL olarak yapılandırılmışsa subscription_create_policy
her kullanıcı için abonelikleri açıkça oluşturup yönetmeniz gerekir. Abonelik, belirli bir kullanıcıyı tanımlanmış bir veri türü grubu için abone uç noktanıza bağlar. Geliştiriciler, belirli API'leri kullanarak şunları yapabilir:
healthUserIdbaşına abonelik oluşturma (manuel): Belirli bir kullanıcı için yeni bir abonelik oluşturur. Bu yöntemde, abonenin istenen veri türleri içinSubscriptionCreatePolicyayarınıMANUALolarak belirlemesi gerekir.- Aboneliği güncelleme (manuel): Mevcut bir kullanıcı aboneliğinin veri türlerini günceller.
- Aboneliği silme (manuel): Belirli bir kullanıcı aboneliğini siler. Silindikten sonra, abone uç noktanız artık bu kullanıcı için ilişkili veri türleriyle ilgili bildirim almaz.
- List (manual) subscriptions: Belirli bir abone için tüm etkin abonelikleri listeler. Sonuçları kullanıcıya veya veri türüne göre filtreleyebilirsiniz.
Bildirimler
Bir kullanıcının verileri, abone olunan bir veri türü için değiştiğinde Google Health API, abone uç noktası URL'sine bir HTTPS POST isteği gönderir.
Bildirim biçimi
Bildirim yükü, veri değişikliğiyle ilgili ayrıntıları içeren bir JSON nesnesidir. Güncellenen verileri sorgulamak için kullanabileceğiniz kullanıcı kimliği, veri türü ve zaman aralıkları bu kapsamdadır.
{
"data": {
"version": "1",
"clientProvidedSubscriptionName": "subscription-name",
"healthUserId": "health-user-id",
"operation": "UPSERT",
"dataType": "steps",
"intervals": [
{
"physicalTimeInterval": {
"startTime": "2026-03-08T01:29:00Z",
"endTime": "2026-03-08T01:34:00Z"
},
"civilDateTimeInterval": {
"startDateTime": {
"date": {
"year": 2026,
"month": 3,
"day": 7
},
"time": {
"hours": 17,
"minutes": 29
}
},
"endDateTime": {
"date": {
"year": 2026,
"month": 3,
"day": 7
},
"time": {
"hours": 17,
"minutes": 34
}
}
},
"civilIso8601TimeInterval": {
"startTime": "2026-03-07T17:29:00",
"endTime": "2026-03-07T17:34:00"
}
}
]
}
}
operation alanı, bildirimi tetikleyen değişiklik türünü gösterir:
UPSERT: Herhangi bir veri ekleme veya değiştirme işlemi için gönderilir.DELETE: Kullanıcı verileri sildiğinde gönderilir.
Yeniden denemeler, bildirimlerin yinelenmesine neden olabileceğinden, özellikle UPSERT işlemleri için bildirim işleme mantığınızı idempotent yapmanızı öneririz.
clientProvidedSubscriptionName alanı benzersiz bir tanımlayıcıdır. MANUAL politikası olan aboneliklerde bu alan, abonelik oluşturulurken belirtilen, geliştirici tarafından sağlanan kalıcı abonelik adını içerir.
Bu, manuel abonelikleri yönetmek için sabit bir kimlik sağlar. AUTOMATIC politikasıyla oluşturulan abonelikler için Google Health API, her bildirimde bu alan için otomatik olarak benzersiz bir tanımlayıcı (rastgele bir UUID) oluşturur ve atar. Hem manuel hem de otomatik politikalar için clientProvidedSubscriptionName eklenmesi, tüm abonelik türlerinde tutarlı bir bildirim yükü biçimi sağlar.
healthUserId, verileri değişen kullanıcının Google Health API tanımlayıcısıdır. Uygulamanız birden fazla kullanıcıyı destekliyorsa uygulamanıza izin veren tüm kullanıcılar için bildirim alabilirsiniz. Bildirim aldığınızda, hangi kullanıcının verilerinin değiştiğini belirlemek için healthUserId simgesini kullanın. Böylece, verilerini sorgulamak için kullanıcının OAuth kimlik bilgilerini kullanabilirsiniz.
Bir kullanıcının OAuth kimlik bilgilerini healthUserId ile eşlemek için getIdentity uç noktasını kullanın. Kullanıcı oryantasyonu sırasında kullanıcının kimlik bilgileriyle bu uç noktayı çağırarak healthUserId değerini alın ve bu eşlemeyi saklayın. Bu eşleme zaman içinde değişmediği için süresiz olarak önbelleğe alınabilir. Örnek için Kullanıcı kimliğini alma başlıklı makaleyi inceleyin. Bu sayede, bir bildirimdeki healthUserId temel alınarak veri sorgulanırken doğru kullanıcı kimlik bilgilerini seçebilirsiniz.
Bir bildirimi yanıtlama
Sunucunuz, bildirimlere HTTP 204 No Content durum koduyla hemen yanıt vermelidir. Zaman aşımlarını önlemek için yanıtı gönderdikten sonra bildirim yükünü eşzamansız olarak işleyin. Google Health API başka bir durum kodu alırsa veya isteğin zaman aşımı olursa bildirim daha sonra tekrar gönderilir.
Node.js (Express) örneği:
app.post('/webhook-receiver', (req, res) => {
// 1. Immediately acknowledge the notification
res.status(204).send();
// 2. Process the data asynchronously in the background
const notification = req.body;
setImmediate(() => {
console.log(`Update for user ${notification.data.healthUserId} of type ${notification.data.dataType}`);
// Trigger your data retrieval logic here
});
});
İmza doğrulama
Webhook bildirimlerinin gerçekliğini sağlamak için her giden webhook bildiriminin ham JSON yükü, Tink'in PublicKeySign kullanılarak özel bir anahtarla imzalanır. Bu işlem, istekteki GOOGLE-HEALTH-API-SIGNATURE HTTP üstbilgisinde Base64 kodlu imzayı sağlar. Bu imzalama anahtarları 30 günde bir otomatik olarak döndürülür ve ilgili resmi genel anahtar kümesi, kalıcı URL olan https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json adresinde bir JSON dosyası olarak dağıtılır.
İmza nasıl doğrulanır?
Tink'i kullanma (önerilir): Geliştiriciler, Tink'in PublicKeyVerify temel öğesini kullanarak imzayı doğrulayabilir. Herkese açık anahtar kümesini kalıcı URL'den getirin, anahtar kümesiyle PublicKeyVerify öğesini oluşturun ve kod çözümü yapılmış GOOGLE-HEALTH-API-SIGNATURE üst bilgisini ham webhook JSON yüküne göre doğrulayın.
Manuel Doğrulama (Tink Olmadan): Geliştiriciler Tink'i kullanmamayı tercih ederse aşağıdaki adımları uygulayarak imzayı manuel olarak doğrulayabilir:
- 5 baytlık Tink önekini (1 baytlık sürüm öneki ve 4 baytlık keyId içerir) gerçek DER kodlu imzadan ayırmak için
GOOGLE-HEALTH-API-SIGNATUREbaşlığının Base64 kodunu çözer. - JSON anahtar kümesini https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json adresinden getirin.
- Ayrıştırılan keyId ile eşleşen anahtarı bulun ve değer alanını Base64 kodunu çözün. Bu alan, seri hale getirilmiş bir EcdsaPublicKey Protocol Buffer içerir.
- Bu ikili yükten büyük endian x ve y koordinatlarını (Protobuf etiketleri 3 ve 4) ayıklayın.
- Ayıklanan x ve y koordinatlarını kullanarak yerleşik bir kriptografi kitaplığında standart bir ECDSA P-256 ortak anahtarı oluşturun.
- SHA-256 algoritmasını kullanarak, çıkarılan DER imzasına karşı ham webhook JSON yükünü doğrulayın.
Abone durumu ve kurtarma
Abone uç noktanız kullanılamaz hale gelirse veya hata durum kodu (204 dışında herhangi bir kod) döndürürse Google Health API, bekleyen bildirimleri 7 güne kadar saklar ve eksponansiyel geri yükleme ile teslimatı yeniden dener.
Uç noktanız tekrar çevrimiçi olup 204 ile yanıt verdiğinde API, depolanan iletilerin birikimini otomatik olarak teslim eder. 7 günden eski bildirimler silinir ve kurtarılamaz.
Sık karşılaşılan hatalar
| Hata kodu | Mesaj | Açıklama | Öneri |
|---|---|---|---|
| 400 Hatalı İstek | Kaynak adında geçersiz proje numarası | İstek URL'sinde proje numarası yerine Google Cloud proje kimliğinizi kullanarak bir aboneyi silerken veya güncellerken. Bu, projects.subscribers uç noktasını kullanan webhook abonelikleri için geçerlidir. |
İstek URL'sinde proje kimliğini değil, Google Cloud proje numaranızı kullanın. |
| 403 Yasak | Arayan kullanıcının izni yok | İstek URL'sinde proje numarası yerine Google Cloud proje kimliğinizi kullanarak abone oluştururken veya listelerken. Bu, projects.subscribers uç noktasını kullanan webhook abonelikleri için geçerlidir. |
İstek URL'sinde proje kimliğini değil, Google Cloud proje numaranızı kullanın. |