Uç noktalar (Endpoint)

Bu sayfada, REST API kurallarına genel bir bakışın yanı sıra yaygın Google Health API görevlerinin bir dizini ve her birinin örnekleri yer alır.

REST API kuralları

Google Health API, Google API İyileştirme Önerileri (AIP) standartlarına, özellikle de AIP-127 (HTTP ve gRPC Kod Dönüştürme) ve AIP-131 ile AIP-135 (Standart Yöntemler) standartlarına uygundur. Bu standartlar, verilerin bir proto mesajından HTTP isteğine nasıl eşlendiğini tanımlar.

Sorgu parametreleri

Sorgu parametreleri, veriler URL'nin bir parçası olduğunda kullanılır. Bu, öncelikle GET istekleri (kaynak getirme) veya LIST istekleri (filtreleme/sayfalandırma) için kullanılır ancak DELETE işlemleri için de kullanılır.

  • Yerleşim: ? işaretinden sonra URL'ye eklenir.
  • Söz dizimi: & ile ayrılmış anahtar/değer çiftleri.
  • Eşleme: İstek mesajında URL yol şablonunun parçası olmayan her alan bir sorgu parametresiyle eşlenir.
  • En uygun kullanım amacı: Basit türler (dizeler, tam sayılar, enum'lar) ve yinelenen alanlar.

Filtre biçimleri, alan referansları, doğrulama kuralları ve örneklerin ayrıntılı listesi için Verileri filtreleme kılavuzuna bakın.

Örnek söz dizimi:

GET https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints?page_size=10&filter=data_type.interval.start_time >= "2025-10-01T00:00:00Z"

İstek metni

İstek gövdesi, veriler bir kaynağın durumunu değiştirdiğinde veya URL için çok büyük olduğunda kullanılır. Gövde genellikle kaynağın JSON gösterimidir. Genellikle POST, PATCH ve PUT işlemleri için kullanılır.

  • Yerleşim: HTTP yükünün içinde (URL'de görünmez).
  • Söz dizimi: JSON nesnesi olarak biçimlendirilir.
  • Eşleme: google.api.http ek açıklamasında tanımlanır.
    • body: "*", tüm mesajın gövde olduğu anlamına gelir.
    • body: "resource_name", gövdenin yalnızca proto'daki belirli bir alan olduğu anlamına gelir.
  • En uygun kullanım alanları: Karmaşık nesneler, iç içe yerleştirilmiş mesajlar ve hassas veriler.

Toplama penceresi boyutları, gruplandırma kuralları ve toplama örnekleri hakkında ayrıntılı yönergeler için Birleştirilmiş veri kılavuzunu inceleyin.

Örnek söz dizimi:

POST https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints:rollUp
Content-Type: application/json

{
  "range": {
    "startTime": "2025-11-05T00:00:00Z",
    "endTime": "2025-11-13T00:00:00Z"
  },
  "windowSize": "3600s"
}

Karma durum

AIP-134 uyumlu bir Update yönteminde veya PATCH işleminde her ikisi de kullanılır. URL, kaynak adını içerir. İstek gövdesi, güncellenen kaynak verilerini içerir. Bir sorgu parametresi (genellikle update_mask) ise hangi alanların değiştirileceğini belirtir.

PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id
Content-Type: application/json

{
  "endpointUri": "https://myapp.com/new-webhooks/health"
}

Bir bakışta temel farklar

Özellik Sorgu Parametreleri İstek Metni
AIP Rehberi Arama, filtreleme ve okuma işlemleri için kullanılır. Yazma işlemleri için kullanılır.
Görünürlük Tarayıcı geçmişinde ve sunucu günlüklerinde görünür. URL'den gizlenir.
Karmaşıklık Düz veya tekrarlanan yapılarla sınırlıdır. İç içe yerleştirilmiş JSON nesnelerini destekler.
Kodlama URL kodlamalı olmalıdır (örneğin, boşluklar %20 olur). Standart JSON kodlaması.

Tarihler

Google Health API'deki tüm tarihler YYYY-MM-DD biçiminde gösterilir. Nutrition API, tarih değerleri için ISO-8601 standardını aşağıdaki koşullarla destekler:

  • 4 haneli yıl YYYY
  • 0000-9999 aralığındaki yıl değerleri
  • ISO-8601 standardı veya başka bir dönem tarafından ima edilen başlangıç tarihi kısıtlamaları uygulanmaz.

Üst bilgiler

Google Health API uç noktalarını yürütmek için uygun üstbilgilerin ve erişim jetonunun kullanılması gerekir. Hem GET hem de POST istekleri için aşağıdaki üstbilgi önerilir:

Authorization: Bearer access-token
Accept: application/json

API görev dizini

Bu bölümde, yaygın Google Health API görevlerinin bir dizini ve her birinin örnekleri verilmiştir.

Fitbit veya Google kullanıcı kimliğini alma

Kullanıcı, Google OAuth 2.0 üzerinden izin verdikten sonra jeton yanıtı, Fitbit veya Google kullanıcı kimliğini içermez. Hem legacyUserId hem de healthUserId değerlerini almak ve kullanıcının Google Hesabı'nın Google Health'e bağlı olduğunu doğrulamak için yetkilendirme kodunu değiştirdikten hemen sonra getIdentity uç noktasını çağırın. Hesap henüz bağlanmadıysa getIdentity, ACCOUNT_NOT_LINKED nedeniyle 400 Bad Request döndürür (Bağlı olmayan Google Hesaplarını işleme bölümüne bakın).

Örneğin:

İstek

GET https://health.googleapis.com/v4/users/me/identity
Authorization: Bearer access-token
Accept: application/json

Yanıt (200 OK)

{
  "name": "users/me/identity",
  "legacyUserId": "A1B2C3",
  "healthUserId": "111111256096816351"
}

Yanıt (400 ACCOUNT_NOT_LINKED)

{
  "error": {
    "code": 400,
    "message": "The account is not linked to Google Health.",
    "status": "FAILED_PRECONDITION",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "ACCOUNT_NOT_LINKED",
        "domain": "health.googleapis.com",
        "metadata": {
          "redirect_uri": "https://fitbit.google.com/auth/signup"
        }
      }
    ]
  }
}

Gün içinde veya gün boyunca toplanan ayrıntılı verileri alma

Belirli bir veri türü için gün içinde veya gün boyunca toplanan ayrıntılı verileri, o veri türü için desteklenen aralıklarla almak üzere list uç noktasını kullanın.

Örneğin:

İstek

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints
Authorization: Bearer access-token
Accept: application/json

Yanıt

{
  "dataPoints": [
    {
      "dataSource": {
        "recordingMethod": "PASSIVELY_MEASURED",
        "device": {
          "manufacturer": "",
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "steps": {
        "interval": {
          "startTime": "2026-03-04T07:05:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T07:06:00Z",
          "endUtcOffset": "0s",
          "civilStartTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 5
            }
          },
          "civilEndTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 6
            }
          }
        },
        "count": "40"
      }
    },
...
  ],
  "nextPageToken": "Xm5h-6L0viZxIlRuWjx5bmvy98zj85uG34tuMn16mu2pntsnZI32iqhq"
}

Aralık verilerinin mutabakatlı görünümünü alma

Çakışan kayıtlar veya çeşitli cihaz çakışmaları olmadan aralık verilerini almak için reconcile uç noktasını çağırın. Mutabakat uç noktası, senkronizasyon grupları ve birden fazla kayıt cihazı genelinde çakışan aralıkları otomatik olarak tekilleştirir. Böylece, etkinlik zaman çizelgelerini oluşturmaya ve süreleri hesaplamaya uygun, yetkili ve kesintisiz bir akış döndürür.

Bağlı cihazların neden çakışan aralıklar oluşturduğu ve list ile reconcile arasındaki operasyonel karşılaştırma hakkında bilgi edinmek için Veri yönetimi kılavuzunu inceleyin.

Aşağıdaki örnekte, çakışan iki egzersiz oturumu olan bir kullanıcı için list (çakışan her iki kaydı da döndürür) ile reconcile (yetkili kaydı döndürerek çakışmayı çözer) yanıtları karşılaştırılmaktadır:

Ham liste

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
Authorization: Bearer access-token
Accept: application/json
 
{
  "dataPoints": [
    {
      "name": "users/111111256096816351/dataTypes/exercise/dataPoints/7797422996486764704",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:20:00Z",
          "endTime": "2026-09-03T11:50:00Z"
        },
        "exerciseType": "RUNNING"
      }
    },
    {
      "name": "users/111111256096816351/dataTypes/exercise/dataPoints/4389052750481144696",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:00:00Z",
          "endTime": "2026-09-03T11:30:00Z"
        },
        "exerciseType": "RUNNING"
      }
    }
  ]
}

Mutabakat yapıldı

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints:reconcile
Authorization: Bearer access-token
Accept: application/json
 
{
  "dataPoints": [
    {
      "dataPointName": "users/111111256096816351/dataTypes/exercise/dataPoints/7797422996486764704",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:20:00Z",
          "endTime": "2026-09-03T11:50:00Z"
        },
        "exerciseType": "RUNNING"
      }
    }
  ]
}

Mutabakat, yapay bir zaman birliği (ör. 11:00:00Z - 11:50:00Z) oluşturmak yerine yetkili kaydı tekilleştirip seçerek çakışan oturumları çözer. Mutabakatlı yanıt, kazanan veri noktasını (7797422996486764704) orijinal kayıtlı aralığıyla (11:20:00Z - 11:50:00Z) döndürerek bu oturumun ölçülen telemetrisinin ve metriklerinin bütünlüğünü korur.

Verileri filtrele

Zaman aralığı, tarih veya gözlem zamanı gibi ölçütlerle eşleşen veri noktası kayıtlarının belirli alt kümelerini almak için filter parametresiyle list veya reconcile uç noktasını kullanın.

Ayrıntılı yönergeler, biçimlendirme kuralları, doğrulama hataları ve sorgu örnekleri için Verileri filtreleme kılavuzunu inceleyin.

Veri kaynağı ailesine göre filtreleme

Belirli kaynak türlerinden (ör. fiziksel giyilebilir cihazlar ve manuel girişler) gelen verileri ayırmak veya birleştirmek için dataSourceFamily parametresini kullanın.

reconcile, rollUp ve dailyRollUp için ayrıntılı yönergeler, desteklenen aileler, istek ve yanıt örneklerini Verileri filtreleme kılavuzundaki Veri kaynağı ailesine göre filtreleme bölümünde bulabilirsiniz.

Verileri sivil başlangıç zamanı aralığına göre filtreleme

Verileri sivil saate veya bir aralığa göre filtrelemek için filter parametresiyle list uç noktasını kullanın.

Örneğin:

İstek

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints?filter=steps.interval.civil_start_time >= "2026-03-04T00:00:00"
Authorization: Bearer access-token
Accept: application/json

Yanıt

{
  "dataPoints": [
    {
      "dataSource": {
        "recordingMethod": "PASSIVELY_MEASURED",
        "device": {
          "manufacturer": "",
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "steps": {
        "interval": {
          "startTime": "2026-03-04T07:05:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T07:06:00Z",
          "endUtcOffset": "0s",
          "civilStartTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 5
            }
          },
          "civilEndTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 6
            }
          }
        },
        "count": "40"
      }
...
  ],
  "nextPageToken": "Xm5h-6L0viZxIlRuQjp5bml1bZ4ve2dhNmZvMnt4Yn7qIGQhbHN3YQ"
}

Verileri örnek gözlem fiziksel zamanına göre filtreleme

Verileri örnek gözlem fiziksel zamanına göre filtrelemek için filter parametresiyle list uç noktasını kullanın.

Örneğin:

İstek

GET https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints?filter=body_fat.sample_time.physical_time >= "2026-03-01T00:00:00Z"
Authorization: Bearer access-token
Accept: application/json

Yanıt

{
  "dataPoints": [
    {
      "name": "users/123456789/dataTypes/body-fat/dataPoints/1234567890",
      "dataSource": {
        "recordingMethod": "UNKNOWN",
        "application": {
          "packageName": "",
          "webClientId": "",
          "googleWebClientId": "google-web-client-id"
        },
        "platform": "GOOGLE_WEB_API"
      },
      "bodyFat": {
        "sampleTime": {
          "physicalTime": "2026-03-10T10:00:00Z",
          "utcOffset": "0s",
          "civilTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 10
            },
            "time": {
              "hours": 10
            }
          }
        },
        "percentage": 20
      }
    }
  "nextPageToken": ""
}

Veri kaynağı ailesine göre filtreleme ve toplama

Veri kaynağı ailesi, veri kaynaklarının (ör. akıllı saatler, mobil uygulamalar veya manuel girişler) mantıksal bir gruplandırmasıdır. Belirli kaynak türlerinden (ör. fiziksel giyilebilir cihazlar ve manuel girişler) gelen verileri ayırmanıza veya birleştirmenize olanak tanır.

reconcile, rollUp ve dailyRollUp uç noktalarının tümü dataSourceFamily parametresini destekler. Geçiş mekanizması uç noktaya bağlıdır:

Uç nokta (HTTP yöntemi) Sistem
reconcile (GET) dataSourceFamily parametresini URL sorgu parametresi olarak iletin.
rollUp (POST) JSON istek gövdesinde dataSourceFamily değerini alan olarak iletin.
dailyRollUp (POST) JSON istek gövdesinde dataSourceFamily değerini alan olarak iletin.

Desteklenen Veri Kaynağı Aileleri

Aşağıdaki tabloda, desteklenen dataSourceFamily değerleri açıklanmaktadır:

Seçenek Açıklama
users/me/dataSourceFamilies/all-sources Varsayılan değer. Kayıtlı tüm birinci taraf (1P) ve üçüncü taraf (3P) veri kaynaklarında mutabakatı sağlanan veri noktalarını döndürür. Bu seçenek belirlendiğinde üçüncü taraf uygulama verileri (ör. akıllı saat adımları + üçüncü taraf uygulama adımları + cep telefonu adımları + manuel adımlar) döndürülür.
users/me/dataSourceFamilies/google-wearables Google ve Fitbit takip cihazları (ör. Fitbit giyilebilir takip cihazları ve Pixel Watch) tarafından kaydedilen verileri içerir. Manuel olarak kaydedilen veriler ve telefon tarafından tahmin edilen veriler hariç tutulur. Entegrasyonunuz için doğrudan giyilebilir donanım tarafından kaydedilen ham sensör telemetrisi gerektiğinde bu seçeneği kullanın.
users/me/dataSourceFamilies/google-sources Birinci taraf Google ve Fitbit kaynaklarını içerir. Buna fiziksel takip cihazı kayıtları, Health Connect'ten alınan veriler ve birinci taraf uygulamaları (ör. Fitbit uygulaması veya Google Fit) üzerinden kaydedilen manuel girişler dahildir.

Belirli bir veri kaynağı ailesinden mutabakatı yapılmış bir veri akışı almak için dataSourceFamily sorgu parametresiyle reconcile uç noktasını çağırın.

Örneğin, aşağıdaki GET isteği, 2026-03-03'ten sonraki gün için takip cihazı tarafından kaydedilen uykuyu getirir:

İstek

GET https://health.googleapis.com/v4/users/me/dataTypes/sleep/dataPoints:reconcile?dataSourceFamily=users/me/dataSourceFamilies/google-wearables&filter=sleep.interval.civil_end_time >= "2026-03-03"
Authorization: Bearer access-token
Accept: application/json

Yanıt

{
  "dataPoints": [
    {
      "name": "users/2515055256096816351/dataTypes/sleep/dataPoints/2724123844716220216",
      "dataSource": {
        "recordingMethod": "DERIVED",
        "device": {
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "sleep": {
        "interval": {
          "startTime": "2026-03-03T20:57:30Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T04:41:30Z",
          "endUtcOffset": "0s"
        },
        "type": "STAGES",
        "stages": [
          {
            "startTime": "2026-03-03T20:57:30Z",
            "startUtcOffset": "0s",
            "endTime": "2026-03-03T20:59:30Z",
            "endUtcOffset": "0s",
            "type": "AWAKE",
            "createTime": "2026-03-04T04:43:40.937183Z",
            "updateTime": "2026-03-04T04:43:40.937183Z"
          },
          {
            "startTime": "2026-03-04T04:07:30Z",
            "startUtcOffset": "0s",
            "endTime": "2026-03-04T04:41:30Z",
            "endUtcOffset": "0s",
            "type": "AWAKE",
            "createTime": "2026-03-04T04:43:40.937183Z",
            "updateTime": "2026-03-04T04:43:40.937183Z"
          }
        ],
        "metadata": {
          "stagesStatus": "SUCCEEDED",
          "processed": true,
          "main": true
        },
        "summary": {
          "minutesInSleepPeriod": "464",
          "minutesAfterWakeUp": "0",
          "minutesToFallAsleep": "0",
          "minutesAsleep": "407",
          "minutesAwake": "57",
          "stagesSummary": [
            {
              "type": "AWAKE",
              "minutes": "56",
              "count": "12"
            },
            {
              "type": "LIGHT",
              "minutes": "198",
              "count": "19"
            },
            {
              "type": "DEEP",
              "minutes": "114",
              "count": "10"
            },
            {
              "type": "REM",
              "minutes": "94",
              "count": "4"
            }
          ]
        },
        "createTime": "2026-03-04T04:43:40.337983Z",
        "updateTime": "2026-03-04T04:43:40.937183Z"
      }
    }
  ],
  "nextPageToken": ""
}

Veri noktalarını belirli bir veri kaynağı ailesiyle kısıtlanmış belirli bir pencere boyutunda birleştirmek için rollUp uç noktasını çağırın ve JSON istek gövdesinde dataSourceFamily alanını iletin.

Aşağıdaki POST isteği, yalnızca giyilebilir cihazlardan toplanan gün içi yürüme adım sayılarını saatlik aralıklarla (3600s) sorgular:

İstek

POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:rollUp
Authorization: Bearer access-token
Accept: application/json

{
  "range": {
    "startTime": "2026-07-29T00:00:00Z",
    "endTime": "2026-07-29T23:59:59Z"
  },
  "windowSize": "3600s",
  "dataSourceFamily": "users/me/dataSourceFamilies/google-wearables"
}

Yanıt

{
  "rollupDataPoints": [
    {
      "startTime": "2026-07-29T08:00:00Z",
      "endTime": "2026-07-29T09:00:00Z",
      "steps": {
        "countSum": "1200"
      }
    },
    {
      "startTime": "2026-07-29T09:00:00Z",
      "endTime": "2026-07-29T10:00:00Z",
      "steps": {
        "countSum": "3450"
      }
    }
  ]
}

Belirli bir kaynak ailesi için günlük veri noktalarını toplamak istiyorsanız dailyRollUp uç noktasını çağırın ve istek gövdesinde dataSourceFamily alanını iletin.

Örneğin, aşağıdaki istek, kullanıcının adımları için günlük toplamları hesaplar. Bu hesaplamaya tüm birinci taraf Google ve Fitbit kaynakları (giyilebilir cihazlar + manuel girişler) dahildir:

İstek

POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:dailyRollUp
Authorization: Bearer access-token
Accept: application/json

{
  "range": {
    "start": {
      "date": {
        "year": 2026,
        "month": 7,
        "day": 28
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    },
    "end": {
      "date": {
        "year": 2026,
        "month": 7,
        "day": 30
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    }
  },
  "windowSizeDays": 1,
  "dataSourceFamily": "users/me/dataSourceFamilies/google-sources"
}

Yanıt

{
  "rollupDataPoints": [
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 28
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 28
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "8430"
      }
    },
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 29
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 29
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "11245"
      }
    }
  ]
}

Belirli bir zaman aralığındaki veri noktalarını birleştirme

Kullanıcının fiziksel zamanındaki (UTC olarak) datetime aralığında, saniye cinsinden bir pencereye (windowSize) dayalı veri noktalarının toplamını döndürmek için rollUp uç noktasını kullanın.

rollUp uç noktasını çağırırken gerekli kapalı-açık zamanı range ve windowSize (en az "1s") temsil eden istek gövdesini sağlayın. windowSize gereksinimleri, depolama çözünürlüğü hizalaması, gruplandırma kuralları ve istek ve yanıt örnekleri hakkında ayrıntılı yönergeler için Birleştirilmiş veri kılavuzundaki Fiziksel zaman aralıklarında birleştirme bölümüne bakın.

Tek bir güne veya birden fazla güne ait verileri birleştirme

Verileri tek bir gün veya birden fazla gün (windowSizeDays) boyunca toplamak için dailyRollUp uç noktasını kullanın. İstek gövdesinde gerekli aralık için kapalı-açık sivil zamanı range belirtin. Veri türüne bağlı olarak uç nokta, her penceredeki toplamı veya ortalamayı döndürür.

Günlük toplama davranışı, sivil zaman işleme, istek başına aralık sınırları ve istek ile yanıt örnekleri hakkında ayrıntılı bilgi için Birleştirilmiş veri kılavuzundaki Takvim günleri arasında birleştirme bölümüne bakın.

Kullanıcının sağlık verilerini güncelleme

Kullanıcının sağlık verilerini güncellemek için patch uç noktasını kullanın.

patch uç noktası, istek URL'sinde belirtilen tanımlayıcıya göre mevcut bir kaydı günceller. Daha önce eklenen bir veri noktasının tanımlayıcısını sağlayın. API, mevcut kaydın üzerine yazar.

Bir veri noktasının aralık zaman damgaları (startTime ve endTime), kaydın sahibi tarafından güncellenebilir veya Health Connect gibi üst platformlardan yayılabilir. Zaman damgası değişkenliği hakkında ayrıntılı bilgi için Veri yönetimi kılavuzuna bakın. Aralık zaman damgalarını güncelleme örneği için Mevcut veriler için aralık zaman damgalarını güncelleme başlıklı makaleyi inceleyin.

Veri noktası tanımlayıcı ne zaman kullanılır?

Veri noktası tanımlayıcısı aşağıdaki senaryolarda gereklidir:

  • Hedeflenen güncellemeler: Belirli bir ölçümü güncellemek için patch isteğinde tanımlayıcısını sağlayın.
  • Silme işlemleri: Tanımlayıcıyı saklamak, uygulamanızın daha sonra batchDelete uç noktasını kullanarak kaydı silmesine olanak tanır.

Aşağıda, bir kullanıcının "Scales R Us" şirketinin "HumanScale" adlı tartısında vücut yağ yüzdesi ölçümünü güncellediği bir örnek verilmiştir. Kullanıcının 10.03.2026 tarihli yeni vücut yağ yüzdesi ölçümü %20:

İstek

PATCH https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints/1234567890
Authorization: Bearer access-token
Content-Type: application/json

{
  "name": "users/me/dataTypes/body-fat/dataPoints/1234567890",
  "dataSource": {
    "recordingMethod": "ACTIVELY_MEASURED",
    "device": {
      "formFactor": "SCALE",
      "manufacturer": "Scales R Us",
      "displayName": "HumanScale"
    }
  },
  "bodyFat": {
    "sampleTime": {
      "physicalTime": "2026-03-10T10:00:00Z"
    },
    "percentage": 20
  }
}

Yanıt

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.DataPoint",
    "name": "users/123456789/dataTypes/body-fat/dataPoints/1234567890",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "device": {
        "formFactor": "SCALE",
        "manufacturer": "Scales R Us",
        "displayName": "HumanScale"
      },
      "application": {
        "googleWebClientId": "618308034039.apps.googleusercontent.com"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "bodyFat": {
      "sampleTime": {
        "physicalTime": "2026-03-10T10:00:00Z"
      },
      "percentage": 20
    }
  }
}

Mevcut veriler için aralık zaman damgalarını güncelleme

Mevcut bir veri noktasının aralık zaman damgalarını (REST JSON yüklerinde startTime ve endTime, gRPC'de start_time ve end_time) güncellemek için veri noktasının kaynak URI'sine bir PATCH isteği gönderin. Bir kaydın alanlarını yalnızca kaydı oluşturan asıl kişi veya kaydın sahibi değiştirebilir. Uygulamalar, oluşturmadıkları veri noktalarını düzenleyemez.

Zaman damgası değişkenliği, Health Connect'ten gelen güncellemeler ve önbelleğe alma ile ilgili bilgiler için Veri yönetimi kılavuzunu inceleyin.

Aşağıdaki örnekte, sahip uygulamanın patch uç noktasını kullanarak mevcut bir sıvı tüketimi günlüğünün aralık zaman damgalarını nasıl güncellediği gösterilmektedir:

İstek

PATCH https://health.googleapis.com/v4/users/me/dataTypes/hydration-log/dataPoints/4093039283164890826
Authorization: Bearer access-token
Content-Type: application/json

{
  "hydrationLog": {
    "interval": {
      "startTime": "2026-09-03T10:05:00Z",
      "endTime": "2026-09-03T10:19:59Z"
    },
    "amountConsumed": {
      "milliliters": 350
    }
  }
}

Yanıt

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/111111256096816351/dataTypes/hydration-log/dataPoints/4093039283164890826",
    "hydrationLog": {
      "interval": {
        "startTime": "2026-09-03T10:05:00Z",
        "endTime": "2026-09-03T10:19:59Z",
        "civilStartTime": {
          "date": {
            "year": 2026,
            "month": 9,
            "day": 3
          },
          "time": {
            "hours": 10,
            "minutes": 5
          }
        },
        "civilEndTime": {
          "date": {
            "year": 2026,
            "month": 9,
            "day": 3
          },
          "time": {
            "hours": 10,
            "minutes": 19,
            "seconds": 59
          }
        }
      },
      "amountConsumed": {
        "milliliters": 350
      }
    }
  }
}

Yiyecek kaydetme

Bir yiyecek öğesini kaydetmek için nutrition-log dataPoints uç noktasına bir POST isteği gönderin. İstek gövdesinde nutritionLog nesnesi içeren bir DataPoint bulunur. Daha fazla bilgi için Beslenme kılavuzuna bakın.

Örneğin:

İstek

POST https://health.googleapis.com/v4/users/me/dataTypes/nutrition-log/dataPoints
Authorization: Bearer access-token
Content-Type: application/json

{
  "nutritionLog": {
    "interval": {
      "startTime": "2026-06-16T12:00:00Z",
      "endTime": "2026-06-16T12:30:00Z"
    },
    "foodDisplayName": "Banana",
    "mealType": "LUNCH",
    "energy": {
      "kcal": 105
    },
    "totalCarbohydrate": {
      "grams": 27
    },
    "totalFat": {
      "grams": 0.3
    }
  }
}

Yanıt

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/123456789/dataTypes/nutrition-log/dataPoints/567890",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "platform": "GOOGLE_WEB_API"
    },
    "nutritionLog": {
      "interval": {
        "startTime": "2026-06-16T12:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-06-16T12:30:00Z",
        "endUtcOffset": "0s"
      },
      "energy": {
        "kcal": 105
      },
      "totalCarbohydrate": {
        "grams": 27
      },
      "totalFat": {
        "grams": 0.3
      },
      "mealType": "LUNCH",
      "foodDisplayName": "Banana"
    }
  }
}

Kullanıcı sağlık verilerini silme

Kullanıcının Fitbit uygulama verileri dizisini silmek için batchDelete yöntemini kullanın.

Aşağıdaki örnekte, daha önce tartıda vücut yağ yüzdesini kaydeden bir kullanıcının bu kaydı silmek istediği gösterilmektedir. Orijinal ekleme işlemindeki user-id ve data-point-id kullanılarak:

İstek

POST https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints:batchDelete
Authorization: Bearer access-token
Accept: application/json
content-length: 93

{
  "names": [
    "users/123456789/dataTypes/body-fat/dataPoints/1234567890"
  ]
}

Yanıt

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.BatchDeleteDataPointsResponse"
  }
}

Cihaz bilgilerini bulma

Bir kullanıcının hesabıyla eşlenen cihazların listesini almak için list uç noktasını kullanın. Buna cihazın model bilgileri (deviceVersion) ve Google Health mobil uygulamasıyla en son senkronize edildiği zaman (lastSyncTime) dahildir.

Liste yapılandırması ve senkronizasyon bilgileri, senkronizasyon sorunlarını gidermek veya son senkronizasyon zamanından bu yana geçmiş verileri almak için kullanışlıdır.

Örneğin:

İstek

GET https://health.googleapis.com/v4/users/me/pairedDevices
Authorization: Bearer access-token
Accept: application/json

Yanıt

{
  "pairedDevices": [
    {
      "name": "users/me/pairedDevices/123456",
      "deviceType": "TRACKER",
      "batteryStatus": "High",
      "batteryLevel": 88,
      "lastSyncTime": "2026-03-04T07:05:00Z",
      "deviceVersion": "Charge 6",
      "macAddress": "00:11:22:33:44:55",
      "features": [
        "STEPS",
        "HEART_RATE"
      ]
    }
  ]
}

Geçmiş verileri sorgulama

Google Health API'nin temel avantajlarından biri, kullanıcının performansını ve sağlık verilerini uzun süre boyunca izleyebilmesidir. Bir kullanıcının verilerini, kaydedildiği tarihe kadar sorgulayabilirsiniz. API, uygulamanızın kullanabileceği geçmiş verilerin miktarı konusunda herhangi bir sınırlama veya kısıtlama getirmez.

Ancak geçmiş verileri sorgulama işlemi, standart sıklık sınırlamalarına tabidir. Google Health API, sistem kararlılığını yönetmek ve aşırı yükleri önlemek için uç noktaya özel sayfa boyutlarıyla otomatik sayfalama kullanır. Aşağıdaki sınırları ve davranışları göz önünde bulundurun:

  • Otomatik sayfalama: Uzun bir veri aralığını sorgularsanız API, yalnızca ilgili uç noktanın sayfa boyutu sınırına kadar olan ilk sonuç sayfasını ve nextPageToken değerini döndürür. Sonraki sayfaları istemek için nextPageToken kullanmanız gerekir.
  • Değişken sayfa boyutları: Sınırlandırma limitleri, uç noktaya ve veri türüne bağlıdır. Çoğu veri türü için sayfa boyutları maksimum 10.000 ile sınırlıdır. Ancak exercise ve sleep gibi belirli veri türleri için varsayılan ve maksimum sayfa boyutu 25 ile sınırlıdır. Örneğin, bir istemci son 10 yıla ait tüm uyku verilerini isterse API, ilk sayfada yalnızca 25 uyku seansı döndürür.
  • Toplama tarih aralığı kısıtlamaları: Veri toplama ve birleştirme uç noktaları (ör. rollUp ve dailyRollUp) için sorgu tarih aralıkları, veri türüne göre kısıtlanır:
    • calories-in-heart-rate-zone, heart-rate, active-minutes ve total-calories için maksimum 14 günlük bir aralık.
    • Diğer tüm toplayıcı veri türleri için maksimum 90 günlük bir aralık.

Uygulamanızın ihtiyaç duyduğu geçmiş verilerin hacmine bağlı olarak, tüm veri kümesini almak için sayfalar arasında sırayla gezinmeniz gerekir. Uygulamanızın veri senkronizasyonu sürecini tasarlarken bunu göz önünde bulundurun.

En iyi performansı elde etmek ve API hatalarını önlemek için geçmiş verileri sorgularken aşağıdaki yönergeleri uygulayın:

Aşamalı veri senkronizasyonu (sıcak yükleme ve sıfırdan yükleme)

  • İlk "sıcak" yükleme: Birincil yükleme sırası sırasında yalnızca en son 7-14 günlük verileri getirip oluşturun. Bu sayede kullanıcılar, uzun süren sorguları beklemeden verileri hemen görür.
  • Arka planda "soğuk" yükleme: Birincil kullanıcı arayüzü oluşturulduktan sonra daha eski geçmiş verilerin alınmasını eşzamansız, daha düşük öncelikli bir sıraya veya arka plan işlemine devredin.

Toplama için sorgu parçalama

  • Toplama ve günlük toplama uç noktaları maksimum tarih aralığı sınırı (veri türüne bağlı olarak 14 veya 90 gün) uyguladığından, büyük geçmiş toplama sorgularını bu sınırlar dahilinde daha küçük, sıralı aralıklara bölmeniz gerekir.
  • Eşzamanlılık sınırlarına uymak ve kullanıcı arayüzü ilerleme göstergelerinin istikrarlı bir şekilde çalışmasını sağlamak için bu alt sorguları güvenli bir şekilde gruplandırın veya sıralayın.

Önceden toplanmış toplayıcıları kullanma

Genel bakış kontrol panellerini ve trend grafiklerini, önceden toplanmış özet uç noktaları (ör. DailyRollUpDataPoints) kullanacak şekilde yeniden yapılandırın. Bu sayede, arka uçtaki işlem yükü ve istemciye ağ aktarım süresi önemli ölçüde azalır.

Esnek hata işleme (akıllı yeniden denemeler)

  • Sıklık sınırları (429 Too Many Requests) ve sunucu ağ geçidi zaman aşımları (504 Gateway Timeout) ile karşılaşıldığında katı eksponansiyel geri yükleme işleme uygulayın. Başarısız olan büyük yükleri hiçbir zaman hemen yeniden denemeyin. Anında yeniden denemeler, arka uçtaki yoğunluğu artırır ve sistemin daha da kötüleşmesine neden olur.
Önceki
İstemci Kitaplıkları
Sonraki
Filtreler