Subskrypcje webhooków

Interfejs Google Health API umożliwia aplikacji otrzymywanie powiadomień w czasie rzeczywistym o zmianach danych zdrowotnych użytkownika. Zamiast sondować zmiany, Twój serwer otrzymuje żądanie HTTPS POST (webhook) od razu, gdy dane są dostępne w interfejsie Google Health API.

Obsługiwane typy danych

Powiadomienia webhook są obsługiwane w przypadku tych typów danych:

  • Aktywne minuty w strefie
  • Wysokość
  • Tkanka tłuszczowa
  • Kalorie w strefie tętna
  • Dzienna zmienność rytmu serca
  • Dzienne strefy tętna
  • Dzienne nasycenie tlenem
  • Dzienne tętno spoczynkowe
  • Dzienne pochodne temperatury snu
  • Odległość
  • Ćwiczenia
  • Piętra
  • Tętno
  • Sen
  • Kroki
  • Wszystkie kalorie
  • Waga

Powiadomienia są wysyłane w przypadku tych typów danych tylko wtedy, gdy użytkownik wyraził zgodę na jeden z odpowiednich zakresów:

  • Aktywność, która obejmuje typy danych kroki, wysokość, odległość i piętra:
    • https://www.googleapis.com/auth/googlehealth.activity_and_fitness
    • https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
  • Wskaźniki zdrowotne, które obejmują typ danych waga:
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
  • Sen, który obejmuje typ danych sen:
    • https://www.googleapis.com/auth/googlehealth.sleep
    • https://www.googleapis.com/auth/googlehealth.sleep.readonly

Zarządzanie subskrybentami

Aby otrzymywać powiadomienia, musisz zarejestrować subskrybenta, który reprezentuje punkt końcowy powiadomień aplikacji. Subskrybentami możesz zarządzać za pomocą interfejsu API REST dostępnego pod adresem projects.subscribers.

Punkt końcowy subskrybenta musi używać protokołu HTTPS (TLSv1.2+) i być publicznie dostępny. Podczas tworzenia i aktualizowania subskrybenta interfejs Google Health API przeprowadza weryfikację, aby upewnić się, że jesteś właścicielem identyfikatora URI punktu końcowego. Jeśli weryfikacja się nie powiedzie, operacje tworzenia i aktualizowania subskrybenta zakończą się niepowodzeniem z powodu FailedPreconditionException.

Tworzenie subskrybenta

Aby zarejestrować nowego subskrybenta w projekcie, użyj create punktu końcowego. Musisz podać:

  • project-id: numer projektu, w którym utworzono konto usługi webhook.
  • subscriberId: unikalny identyfikator subskrybenta. Identyfikator musi mieć od 4 do 36 znaków i pasować do wyrażenia regularnego ([a-z]([a-z0-9-]{2,34}[a-z0-9])).
  • endpointUri: docelowy adres URL powiadomień webhook.
  • subscriberConfigs: typy danych, w przypadku których chcesz otrzymywać powiadomienia, oraz zasady subskrypcji dla każdego z nich.
  • endpointAuthorization: mechanizm autoryzacji punktu końcowego. Musi zawierać podany przez Ciebie secret. Wartość secret jest wysyłana w nagłówku Authorization z każdą wiadomością powiadomienia. Za pomocą tego tokena możesz sprawdzić, czy przychodzące żądania pochodzą z interfejsu Google Health API. Możesz na przykład ustawić secret na Bearer R4nd0m5tr1ng123 w przypadku uwierzytelniania za pomocą tokena Bearer lub Basic dXNlcjpwYXNzd29yZA== w przypadku uwierzytelniania podstawowego.

W subscriberConfigs musisz ustawić subscriptionCreatePolicy dla każdego typu danych. Ustaw wartość AUTOMATIC, aby korzystać z automatycznych subskrypcji, lub MANUAL, jeśli chcesz samodzielnie zarządzać subskrypcjami użytkowników. Więcej informacji o każdej opcji znajdziesz w sekcjach Automatyczne subskrypcje i Ręczne subskrypcje.

Żądanie

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"
  }
}

Odpowiedź

{
  "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"
    }
  ]
}

Wyświetlanie listy subskrybentów

Aby pobrać wszystkich subskrybentów zarejestrowanych w projekcie, użyj punktu końcowego list.

Żądanie

GET https://health.googleapis.com/v4/projects/project-id/subscribers

Odpowiedź

{
  "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
}

Aktualizowanie subskrybenta

Aby zaktualizować subskrybenta w projekcie, użyj punktu końcowego patch. Pola, które można zaktualizować, to endpointUri, subscriberConfigs i endpointAuthorization.

Pola aktualizujesz, podając parametr zapytania updateMask i treść żądania. updateMask musi zawierać rozdzieloną przecinkami listę nazw pól, które chcesz zaktualizować. Nazwy pól muszą być zapisane w formacie camel case (np. endpointUri). Treść żądania musi zawierać częściowy obiekt subskrybenta z nowymi wartościami pól, które chcesz zaktualizować. Aktualizowane są tylko pola określone w updateMask. Jeśli w treści żądania podasz pola, których nie ma w updateMask, zostaną one zignorowane.

Jeśli zaktualizujesz endpointUri lub endpointAuthorization, zostanie przeprowadzona weryfikacja punktu końcowego. Więcej informacji znajdziesz w sekcji Weryfikacja punktów końcowych.

Podczas aktualizowania subscriberConfigs pamiętaj, że jest to pełne zastąpienie, a nie scalenie. Jeśli subscriberConfigs jest uwzględniony w updateMask, wszystkie zapisane konfiguracje tego subskrybenta zostaną zastąpione listą podaną w treści żądania. Aby dodać lub usunąć konfigurację, musisz podać pełny zestaw konfiguracji. Jeśli aktualizujesz inne pola i chcesz zachować bieżące konfiguracje, pomiń subscriberConfigs w updateMask.

Żądanie

PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id?updateMask=endpointUri
{
  "endpointUri": "https://myapp.com/new-webhooks/health"
}

Odpowiedź

{
  "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"
    }
  ]
}

Usuwanie subskrybenta

Aby usunąć subskrybenta z projektu, użyj punktu końcowego delete. Po usunięciu subskrybent nie będzie już otrzymywać powiadomień.

Żądanie

DELETE https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id

Odpowiedź

Jeśli usunięcie się powiedzie, zwracana jest pusta treść odpowiedzi z kodem stanu HTTP `200 OK`. 
{}

Weryfikacja punktów końcowych

Aby zapewnić bezpieczeństwo i niezawodność dostarczania powiadomień, interfejs Google Health API przeprowadza obowiązkowe uzgadnianie weryfikacji dwuetapowej za każdym razem, gdy tworzysz subskrybenta lub aktualizujesz jego konfigurację punktu końcowego (endpointUri lub endpointAuthorization). Ten proces jest wykonywany synchronicznie podczas wywołania interfejsu API. Usługa wysyła 2 automatyczne żądania POST do URI punktu końcowego, używając User-Agent Google-Health-API-Webhooks-Verifier, z treścią JSON {"type": "verification"}.

  • Autoryzowane uzgadnianie: pierwsze żądanie jest wysyłane ze skonfigurowanym Authorization nagłówkiem. Twój serwer musi odpowiedzieć kodem stanu 200 OK lub 201 Created.
  • Nieautoryzowane wyzwanie: drugie żądanie jest wysyłane bez danych logowania. Twój serwer musi odpowiedzieć kodem stanu 401 Unauthorized lub 403 Forbidden.

To uzgadnianie potwierdza, że punkt końcowy jest aktywny i prawidłowo egzekwuje zabezpieczenia. Jeśli którykolwiek z tych kroków się nie powiedzie, żądanie do interfejsu API zakończy się niepowodzeniem z powodu błędu FAILED_PRECONDITION. Dopiero po pomyślnym zakończeniu tego uzgadniania subskrybent zostanie zapisany i aktywowany do otrzymywania powiadomień o danych zdrowotnych.

Rotacja kluczy

Jeśli musisz przeprowadzić rotację kluczy dla endpointAuthorization, wykonaj te czynności:

  1. Skonfiguruj punkt końcowy tak, aby akceptował zarówno stare, jak i nowe wartości endpointAuthorization.
  2. Zaktualizuj konfigurację subskrybenta, podając nową wartość endpointAuthorization, za pomocą żądania patch z parametrem ?updateMask=endpointAuthorization.
  3. Po potwierdzeniu, że krok 2 został wykonany pomyślnie, skonfiguruj punkt końcowy tak, aby akceptował tylko nową wartość endpointAuthorization.

Subskrypcje użytkownika

Interfejs Google Health API pomaga efektywnie zarządzać subskrypcjami użytkowników, co zmniejsza potrzebę ręcznej rejestracji podczas wdrażania użytkowników.

Automatyczne subskrypcje

Zalecamy korzystanie z automatycznych subskrypcji. Aby włączyć tę funkcję, ustaw subscriptionCreatePolicy na AUTOMATIC w subscriberConfigs dla określonych typów danych. dataTypes określone za pomocą zasady AUTOMATIC to te same typy danych, w przypadku których interfejs Google Health API wysyła powiadomienia, pod warunkiem że zgoda użytkownika zostanie również udzielona na te typy danych.

Gdy użytkownik wyrazi zgodę na zakresy odpowiadające typom danych z zasadą AUTOMATIC, interfejs Google Health API automatycznie śledzi i wysyła powiadomienia o typach danych wynikających z przecięcia typów danych, na które użytkownik wyraził zgodę, oraz typów danych automatycznej konfiguracji subskrybenta dla tego użytkownika. Powiadomienia są następnie wysyłane do punktu końcowego, gdy użytkownik wygeneruje nowe dane tych typów. Działa to w przypadku użytkowników, którzy wyrażą zgodę przed utworzeniem subskrybenta lub po jego utworzeniu. Powiadomienia nie są uzupełniane w przypadku danych wygenerowanych przed utworzeniem subskrybenta.

Jeśli użytkownik wycofa zgodę, powiadomienia o odpowiednich typach danych przestaną być wysyłane. Automatyczne subskrypcje są zarządzane przez Google i nie można ich wyświetlać ani usuwać pojedynczo. Są one usuwane tylko wtedy, gdy zostanie usunięty subskrybent nadrzędny.

Ręczne subskrypcje

Jeśli wolisz ręcznie zarządzać subskrypcjami każdego użytkownika, ustaw subscriptionCreatePolicy na MANUAL w subscriberConfigs. W przypadku tej zasady subskrypcje użytkowników nie są tworzone automatycznie. Ta funkcja będzie używana w przyszłości, gdy udostępnimy interfejsy API do zarządzania ręcznymi subskrypcjami. Do czasu udostępnienia tych interfejsów API zalecamy korzystanie z subskrypcji AUTOMATIC.

Powiadomienia

Gdy dane użytkownika zmienią się w przypadku subskrybowanego typu danych, interfejs Google Health API wyśle żądanie HTTPS POST na adres URL punktu końcowego subskrybenta.

Format powiadomienia

Ładunek powiadomienia to obiekt JSON zawierający szczegółowe informacje o zmianie danych. Obejmuje to identyfikator użytkownika, typ danych i przedziały czasu, których możesz użyć do wysyłania zapytań o zaktualizowane dane.

{
  "data": {
    "version": "1",
    "clientProvidedSubscriptionName": "subscription-name",
    "healthUserId": "health-user-id",
    "operation": "UPSERT",
    "dataType": "steps",
    "intervals": [
      {
        "physicalTimeInterval": {
          "startTime": "2026-03-0B01: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"
        }
      }
    ]
  }
}

Pole operation wskazuje typ zmiany, która wywołała powiadomienie:

  • UPSERT: wysyłane w przypadku dodania lub modyfikacji danych.
  • DELETE: wysyłane, gdy użytkownik usunie dane lub gdy dane zostaną usunięte z powodu zdarzenia systemowego, np. wycofania uprawnień przez użytkownika lub usunięcia konta.

Zalecamy, aby logika obsługi powiadomień była idempotentna, zwłaszcza w przypadku operacji UPSERT, ponieważ ponawianie może powodować wysyłanie zduplikowanych powiadomień.

Pole clientProvidedSubscriptionName jest unikalnym identyfikatorem. W przypadku subskrypcji z zasadą MANUAL to pole zawiera trwałą nazwę subskrypcji podaną przez dewelopera podczas tworzenia subskrypcji. Zapewnia to stabilny identyfikator do zarządzania ręcznymi subskrypcjami. W przypadku subskrypcji utworzonych za pomocą zasady AUTOMATIC interfejs Google Health API automatycznie generuje i przypisuje unikalny identyfikator (losowy UUID) do tego pola w przypadku każdego powiadomienia. Uwzględnienie clientProvidedSubscriptionName w przypadku zasad ręcznych i automatycznych zapewnia spójny format ładunku powiadomienia we wszystkich typach subskrypcji.

healthUserId to identyfikator interfejsu Google Health API użytkownika, którego dane uległy zmianie. Jeśli Twoja aplikacja obsługuje wielu użytkowników, możesz otrzymywać powiadomienia od każdego użytkownika, który wyraził zgodę na korzystanie z aplikacji. Gdy otrzymasz powiadomienie, użyj healthUserId, aby określić, czyje dane uległy zmianie. Dzięki temu możesz użyć danych logowania OAuth, aby wysłać zapytanie o jego dane.

Aby zmapować dane logowania OAuth użytkownika na jego healthUserId, użyj punktu końcowego getIdentity. Podczas wdrażania użytkownika wywołaj ten punkt końcowy z jego danymi logowania, aby pobrać jego healthUserId, i zapisz to mapowanie. To mapowanie nie zmienia się z upływem czasu, więc można je przechowywać w pamięci podręcznej przez nieograniczony czas. Przykład znajdziesz w sekcji Pobieranie identyfikatora użytkownika. Umożliwia to wybranie prawidłowych danych logowania użytkownika podczas wysyłania zapytań o dane na podstawie healthUserId w powiadomieniu.

Podejmowanie działania w związku z powiadomieniem

Twój serwer musi natychmiast odpowiedzieć na powiadomienia kodem stanu HTTP 204 No Content. Aby uniknąć przekroczenia limitu czasu, przetwórz ładunek powiadomienia asynchronicznie po wysłaniu odpowiedzi. Jeśli interfejs Google Health API otrzyma inny kod stanu lub żądanie przekroczy limit czasu, ponowi wysłanie powiadomienia później.

Przykład w Node.js (Express):

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
    });
});

Stan subskrybenta i odzyskiwanie

Jeśli punkt końcowy subskrybenta stanie się niedostępny lub zwróci kod stanu błędu (inny niż 204), interfejs Google Health API będzie przechowywać oczekujące powiadomienia przez maksymalnie 7 dni i ponawiać ich dostarczanie z wzrastającym czasem do ponowienia.

Gdy punkt końcowy znów będzie dostępny i odpowie kodem 204, interfejs API automatycznie dostarczy zaległe wiadomości. Powiadomienia starsze niż 7 dni są odrzucane i nie można ich odzyskać.

Wstecz
Linki uniwersalne i linki do aplikacji
Dalej
Rozwiązywanie problemów