Google Cloud und OAuth einrichten

Der Zugriff auf die Google Health API erfolgt über Google Cloud. Um die API zu aktivieren und ein Google-Konto zu autorisieren, benötigen Sie ein Google Cloud-Projekt.

Wenn Sie bereits Fitbit API-Entwickler sind oder die Google Health API zum ersten Mal verwenden, müssen Sie diesen Schritt ausführen, um API-Aufrufe zu tätigen.

Projekt und OAuth-Client erstellen

Klicken Sie auf die Schaltfläche API aktivieren und OAuth 2.0-Client-ID abrufen, um die Google Health API zu aktivieren und eine OAuth 2.0-Client-ID abzurufen:

  1. Wenn Sie ein vorhandenes Google Cloud-Projekt verwenden möchten, das Sie für die Google Health API verwenden möchten, müssen Sie sich zuerst im Administratorkonto für dieses Projekt anmelden. Wählen Sie dann das vorhandene Projekt aus der Liste der verfügbaren Projekte aus, nachdem Sie auf den Button geklickt haben. Erstellen Sie andernfalls ein neues Projekt.
  2. Wählen Sie Webserver aus, wenn Sie gefragt werden, woher Sie anrufen.
  3. Geben Sie https://www.google.com als Wert für Autorisierte Weiterleitungs-URIs ein. Eine Weiterleitungs-URI ist erforderlich, um mit OAuth 2.0 einen Autorisierungscode zu erhalten.
  4. Kopieren Sie nach Abschluss der Einrichtung die Werte für die OAuth 2.0-Client-ID und den Clientschlüssel und laden Sie die JSON-Datei mit den Anmeldedaten auf Ihren lokalen Computer herunter.
API aktivieren und OAuth 2.0-Client-ID abrufen

Wenn Sie Ihr Google Cloud-Projekt manuell einrichten oder die Einrichtung überprüfen und Ihre Anmeldedaten noch einmal abrufen möchten, gehen Sie so vor:

  1. Aktivieren Sie die Google Health API auf der Seite API-Aktivierung.
  2. Rufen Sie auf der Seite Anmeldedaten eine OAuth 2.0-Client-ID ab.

Weitere Informationen zum Einrichten von OAuth 2.0 über die Google-Konsole finden Sie unter OAuth 2.0 für den Zugriff auf Google APIs verwenden.

Separate Projekte für Staging und Produktion verwenden

Die Google Health API bietet keine separate Sandbox- oder Staging-Umgebung. In allen Ihren Umgebungen wird die Google Health API in der Produktionsumgebung aufgerufen. Die Trennung der Umgebungen erfolgt also auf Google Cloud-Projektebene.

Beachten Sie beim Einrichten von Umgebungen für Ihre App die folgenden Best Practices:

  • Erstellen Sie separate Google Cloud-Projekte für Ihre Entwicklungs-, Staging- und Produktionsumgebungen. Jedes Projekt verwaltet seinen eigenen OAuth 2.0-Client, Zustimmungsbildschirm und Webhook-Abonnenten.
  • Verwenden Sie für Tests nicht Ihr Google Cloud-Produktionsprojekt oder dessen OAuth 2.0-Client, da sich Änderungen an diesem Projekt direkt auf Ihre Produktions-App auswirken.
  • Entwickeln und testen Sie zuerst in einem Nicht-Produktionsprojekt und wenden Sie die Änderungen dann auf Ihr Produktionsprojekt an, wenn Sie bereit sind.
  • Verwenden Sie Tags in der Google Cloud Console, um Ihre Projekte visuell nach Umgebung zu unterscheiden. Eine Anleitung finden Sie unter Projektumgebungen mit Tags kennzeichnen.

Testnutzer hinzufügen

Standardmäßig haben neu erstellte OAuth-Clients den Status „Nicht bestätigt“ und eine Obergrenze von 100 Nutzern für Test- und Produktionszwecke. Wenn Sie die Autorisierung in diesem Zeitraum aktivieren möchten, müssen Sie die E-Mail-Adresse jedes Nutzers manuell der Liste „Testnutzer“ in Ihrer Projektkonfiguration hinzufügen.

Aktualisieren Sie die Liste der Testnutzer auf der Seite Zielgruppe:

  1. Auf dieser Seite sollte der „Veröffentlichungsstatus“ auf Testen und der „Nutzertyp“ auf Extern festgelegt sein.
  2. Klicken Sie im Bereich „Testnutzer“ auf + Nutzer hinzufügen. Geben Sie die E‑Mail-Adresse aller Testnutzer ein, die Ihrer App die Berechtigung zum Zugriff auf ihre Gesundheitsdaten erteilen dürfen.
  3. Klicken Sie auf Speichern.

Wenn Sie mehr als 100 Nutzer mit der Google Health API unterstützen möchten, müssen Sie eine Sicherheitsüberprüfung durch einen Drittanbieter durchführen lassen. Weitere Informationen finden Sie in der OAuth-App-Überprüfung – Hilfe.

Bereiche hinzufügen

Sie müssen die Bereiche angeben, die Ihr Client auf der Seite Data Access (Datenzugriff) aufrufen darf:

  1. Klicken Sie auf dieser Seite auf Bereiche hinzufügen oder entfernen.
  2. Suchen Sie in der Spalte „API“ nach „Google Health API“. Wählen Sie die Bereiche aus, die Sie für Ihre Anwendung benötigen.
  3. Nachdem Sie alle erforderlichen Bereiche ausgewählt haben, klicken Sie auf Aktualisieren, um zur Seite „Datenzugriff“ zurückzukehren.
  4. Klicken Sie auf Speichern.

Bevor Sie Ihre Bereiche auswählen, sollten Sie sich die Bereichsimplementierung ansehen.

Sie haben die Einrichtung Ihrer Client-ID abgeschlossen und sollten jetzt Aufrufe an die Google Health API senden können.

Bereiche aktualisieren

Sie können den Nutzer auffordern, Ihre App noch einmal zu autorisieren, indem Sie den Parameter „prompt“ in Ihrer Authentifizierungsanfrage auf „consent“ setzen. Wenn prompt=consent enthalten ist, wird der Zustimmungsbildschirm jedes Mal angezeigt, wenn Ihre App die Autorisierung von Zugriffsbereichen anfordert, auch wenn alle Bereiche zuvor für Ihr Google APIs-Projekt gewährt wurden.

So fügen Sie Bereiche mit dem Parameter prompt=consent hinzu oder ändern sie:

  1. Ermitteln Sie die vollständige Liste der Bereiche, die Ihre Anwendung benötigt. Dazu gehören sowohl die vorhandenen als auch alle neuen Bereiche, die Sie hinzufügen müssen.

  2. Ändern Sie den Parameter „scope“ in der Autorisierungs-URL, um die aktualisierte Liste der durch Leerzeichen getrennten Bereichswerte einzufügen.

  3. Hängen Sie prompt=consent an die Parameter Ihres Authentifizierungs-URI an. Dadurch wird der Autorisierungsserver gezwungen, den Nutzer um die Einwilligung zu bitten, bevor Informationen an Ihren Client zurückgegeben werden.

    Das folgende Beispiel zeigt eine HTTPS-GET-Anfrage an den OAuth 2.0-Autorisierungsendpunkt von Google, in der mehrere Bereiche mit angehängtem prompt=consent angefordert werden:

    https://accounts.google.com/o/oauth2/v2/auth?client_id=client-id&redirect_uri=redirect-uri&response_type=code&access_type=offline&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly%20https://www.googleapis.com/auth/googlehealth.sleep.readonly&prompt=consent

  4. Wenn der Nutzer dem aktualisierten Link folgt, wird eine Einwilligungsseite mit allen angeforderten Bereichen angezeigt. Sobald der Nutzer auf „Weiter“ oder „Zulassen“ klickt, erhalten Sie einen neuen Autorisierungscode, der gegen Tokens für alle Bereiche eingetauscht werden kann.

    Fügen Sie prompt=consent nur bei Bedarf ein, z. B. wenn Sie ein neues Aktualisierungstoken benötigen oder sich die angeforderten Bereiche geändert haben.

OAuth2-Clientbibliotheken

Eine Liste der verfügbaren OAuth2-Clientbibliotheken, die für die Integration in gängige Frameworks verwendet werden, finden Sie unter Mit OAuth 2.0 auf Google APIs zugreifen.

Verwenden Sie bei der Implementierung von Google OAuth in Mobil- oder Desktop-Apps immer Systembrowser (z. B. benutzerdefinierte Tabs in Chrome unter Android oder ASWebAuthenticationSession unter iOS) und niemals eingebettete WebViews, da diese Passkeys blockieren und Google OAuth-Abläufe unterbrechen. Best Practices für die Anmeldung mit Google

Bevor ein Nutzer den Google OAuth 2.0-Zustimmungsvorgang in Ihrer App durchläuft, muss er sich in der Google Health App anmelden, um Google Health mit seinem Google-Konto zu verknüpfen. Mit Google OAuth 2.0 wird jedes gültige Google-Konto authentifiziert. Es kann nicht geprüft werden, ob das Konto auf dem Zustimmungsbildschirm ein aktives Google Health-Profil hat.

Weisen Sie Nutzer an, die folgenden Schritte in der Google Health App auszuführen, bevor sie den OAuth-Zustimmungsablauf in Ihrer App starten:

  1. Lade die Google Health App aus dem Google Play Store oder Apple App Store herunter und öffne sie.
  2. Tippen Sie auf Über Google anmelden und wählen Sie das Google-Konto aus, das sie mit Ihrer App verknüpfen möchten.
  3. Folge der Anleitung in der App, um ein neues Google Health-Profil zu erstellen, oder übertrage dein Fitbit-Konto auf dein Google-Konto.

Nachdem Sie den Autorisierungscode gegen OAuth-Tokens eingetauscht haben, rufen Sie den users.getIdentity-Endpunkt (GET https://health.googleapis.com/v4/users/me/identity) auf, um zu prüfen, ob das Google-Konto des Nutzers mit Google Health verknüpft ist, bevor Sie das Konto in Ihrer App als verbunden markieren. Weitere Informationen zum Umgang mit nicht verknüpften Konten (400 ACCOUNT_NOT_LINKED) finden Sie unter Nicht verknüpfte Google-Konten verarbeiten.

Aktualisierungstokens

Wenn Sie langfristig auf Google-APIs zugreifen möchten, ohne dass Nutzer sich ständig neu authentifizieren müssen, muss Ihre Anwendung ein Aktualisierungstoken verwenden. Ausführliche Implementierungsdetails, einschließlich der erforderlichen HTTP-Anfragen und Parameter, finden Sie in der Dokumentation zur Google Identity Platform.

Wenn Sie ein Aktualisierungstoken gegen ein Zugriffstoken eintauschen möchten, senden Sie einen HTTPS-POST-Aufruf an den Google OAuth 2.0-Tokenendpunkt. Das folgende Snippet zeigt ein Beispiel für eine Anfrage und eine Antwort:

Anfrage

curl -L -X POST 'https://oauth2.googleapis.com/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=client-id&client_secret=client-secret&refresh_token=refresh-token&grant_type=refresh_token'

Antwort

{
  "access_token": "access-token",
  "expires_in": 3599,
  "scope": "scope-list",
  "token_type": "Bearer",
  "refresh_token": "refresh-token",
  "refresh_token_expires_in": 112154
}

Wann ein Token aktualisiert werden sollte

Aktualisieren Sie Aktualisierungstokens bei Bedarf im Rahmen des natürlichen Ablaufs einer aktiven Nutzersitzung, wenn Zugriffstokens abgelaufen sind oder bald ablaufen. Vermeiden Sie das Aktualisieren von Tokens in Batches, z. B. mit einem geplanten cron-Job oder -Dienst, um Tokens für alle Nutzer zu einem bestimmten Zeitpunkt zu aktualisieren.

Das Aktualisieren von Tokens in Batches wird aus folgenden Gründen nicht empfohlen:

  • Durch das Aktualisieren im Batchverfahren wird verhindert, dass Token-Aktualisierungen mit Mustern für die Synchronisierung aktiver Nutzer abgeglichen werden. Mit dem Aufruf Get Devices können Sie zwar die letzte Synchronisierungszeit eines Nutzers abrufen, dazu ist jedoch ein zusätzlicher OAuth-Bereich erforderlich, den Nutzer nicht genehmigen müssen.
  • Bei der Batchverarbeitung werden auch Tokens aktualisiert, die nicht aktualisiert werden müssen. Das führt zu unnötigem Verarbeitungsaufwand für Ihre Systeme und die Server von Google.
  • Wenn während einer Batchaktualisierung ein Netzwerkproblem oder Serverausfall auftritt, sind alle betroffenen Nutzer-Tokens gleichzeitig betroffen. Wenn Tokens während des natürlichen Ablaufs von Nutzersynchronisierungen einzeln aktualisiert werden, beschränkt sich die Auswirkung vorübergehender Fehler auf einen einzelnen Nutzer.
  • Die Diagnose von Problemen ist bei Batchjobs schwieriger. Da Batchanfragen seltener erfolgen und eine Flut von Logeinträgen gleichzeitig generieren, ist es schwieriger, den Beginn eines Vorfalls zu ermitteln.
  • Spitzen bei der Anzahl gleichzeitiger Tokenanfragen während Batchläufen erhöhen die Wahrscheinlichkeit, dass Ratenbeschränkungen erreicht werden oder zeitweise Authentifizierungsfehler auftreten.

Tokenverhalten während des Testens

Beachten Sie, wie sich Aktualisierungstokens je nach Veröffentlichungsstatus Ihres Google Cloud-Projekts verhalten:

  • Testmodus:Wenn für Ihren OAuth-Zustimmungsbildschirm der Veröffentlichungsstatus „Test“ konfiguriert ist, sind die ausgegebenen Aktualisierungstokens zeitbasiert und laufen nach 7 Tagen ab. Während dieses Zeitraums erhalten Sie ein einzelnes Aktualisierungstoken, das bis zu seinem Ablaufdatum gültig ist und zum Abrufen neuer Zugriffstokens verwendet werden kann.
  • Veröffentlichungsmodus:Sobald Ihre App den Status „Wird ausgeführt“ hat, laufen Aktualisierungstokens in der Regel nicht ab, es sei denn, sie werden widerrufen oder bleiben über einen längeren Zeitraum (in der Regel sechs Monate) ungenutzt.

Damit die Nutzerfreundlichkeit nicht beeinträchtigt wird, sollten Sie Ihre Anwendung veröffentlichen, bevor sie in eine Produktionsumgebung verschoben wird. So vermeiden Sie, dass das Token nach 7 Tagen abläuft.

Beispieldaten generieren

Google stellt keine vorab ausgefüllten Gesundheitsdaten als Beispiel oder Testdaten zur Verfügung. Zum Testen der Integration müssen Sie eigene Testdaten generieren. Verwenden Sie eine der folgenden Methoden, um Beispieldaten für Ihre Testnutzer zu generieren:

  • Tracker tragen:Trage einen Fitbit-Tracker, eine Pixel Watch oder eine andere Smartwatch, die mit der Google Health App kompatibel ist, und gehe umher, um Daten zu Schritten, Herzfrequenz und Training zu generieren.
  • Mobile Tracking aktivieren:Aktiviere MobileTrack in der Google Health App und gehe mit deinem Mobilgerät spazieren.
  • Daten manuell protokollieren:Du kannst Gesundheitsmesswerte wie Schlaf, Gewicht, Wasser- oder Nahrungsaufnahme über die Google Health App manuell eingeben.
  • Daten mit der API schreiben:Senden Sie Schreibanfragen (z. B. POST oder PATCH) direkt an die REST API-Endpunkte, um Daten programmatisch einzufügen. Weitere Informationen zum Erstellen und Aktualisieren von Datenpunkten finden Sie in der REST-Referenzdokumentation.

Produktübergreifender Kontoschutz (RISC API)

Aktivieren Sie RISC (Risk and Incident Sharing and Coordination), wenn Sie über Änderungen an Ereignistokens oder der Kontoverknüpfung benachrichtigt werden möchten, z. B. über getrennte Konten oder widerrufene Tokens, um gespeicherte Tokens zu bereinigen und den Verbindungsstatus der Benutzeroberfläche zu aktualisieren. Die Aktivierung der RISC API ist optional.

So aktivieren Sie die RISC API für Ihr Google Cloud-Projekt:

  1. Öffnen Sie in der Google Cloud Console die Seite RISC API. Achten Sie darauf, dass das Projekt ausgewählt ist, das Sie für die Google Health API verwenden.
  2. Lesen Sie die RISC-Nutzungsbedingungen und machen Sie sich mit den Anforderungen vertraut.
  3. Klicken Sie auf Aktivieren, wenn Sie den Bedingungen zustimmen.

Nachdem Sie die API aktiviert haben, müssen Sie einen HTTPS-Endpunkt erstellen und registrieren, um die von Google gesendeten Ereignistokens zu empfangen und zu validieren.

Weitere Informationen zum produktübergreifenden Kontoschutz und zu RISC finden Sie unter Nutzerkonten mit dem produktübergreifenden Kontoschutz schützen.