Geräte erstellen und verwalten

In diesem Leitfaden wird beschrieben, wie Sie Geräte erstellen, verwalten und löschen. Eine ordnungsgemäße Geräteverwaltung trägt zu einer reibungslosen Nutzererfahrung und einer effizienten Nutzung der Ambient API bei.

Geräte erstellen

Nachdem sich ein Nutzer mit dem OAuth 2.0-Vorgang für TV- und Geräteanwendungen mit eingeschränkter Eingabe erfolgreich authentifiziert hat, erstellen Sie ein Gerät in seinem Google Fotos-Konto.

Wenn Ihre App mit der Methode devices.create erfolgreich ein Gerät erstellt, gibt die Ambient API ein AmbientDevice-Objekt zurück, das eine von Google generierte id enthält. Speichern Sie diese id sicher und verknüpfen Sie sie mit Ihren Nutzern.

Wichtig: Speichern Sie die id. Wenn Sie die von Google generierte id nicht speichern, können Sie ein Gerät später nicht abrufen oder verwalten. Dies kann zu verwaisten Geräten in den Google Fotos-Konten Ihrer Nutzer führen, auf die Ihre Anwendung nicht zugreifen oder die sie nicht bereinigen kann.

Optimierte Geräteerstellung mit OAuth

Die Ambient API bietet einen optimierten OAuth-Vorgang. Wenn Sie den zusätzlichen Parameter state in Ihre erste OAuth-Anfrage einfügen und devices.create mit der entsprechenden requestId aufrufen, können Sie den Geräteerstellungsprozess direkt mit dem Anmeldevorgang des Nutzers verknüpfen. So wird die Nutzererfahrung verbessert, da weniger QR-Codes gescannt werden müssen.

Weitere Informationen und ein Beispiel finden Sie im Leitfaden Optimierter Authentifizierungsvorgang für die Ambient API.

Gerätelimits

Ihre Anwendung kann bis zu 100 Geräte pro Nutzer erstellen. Wenn dieses Limit überschritten wird, gibt die API den Fehler RESOURCE_EXHAUSTED zurück.

Geräte verwalten

Nachdem ein Gerät erstellt und mit dem Google Fotos-Konto eines Nutzers verknüpft wurde, müssen Sie möglicherweise seinen Lebenszyklus verwalten.

Geräte abrufen

Verwenden Sie die Methode devices.get mit der eindeutigen id des Geräts, um Informationen zu einem bestimmten Gerät abzurufen. Das ist nützlich, um den Status des Geräts zu prüfen, z. B. ob mediaSourcesSet auf „true“ gesetzt ist.

Geräte aktualisieren

Mit der Methode devices.patch können Sie bestimmte Eigenschaften eines vorhandenen Geräts aktualisieren, z. B. den Anzeigenamen. So können Nutzer ihre Geräte personalisieren und sie in Google Fotos leichter identifizieren.

Hinweis: Es empfiehlt sich, dem Nutzer die Möglichkeit zu geben, sein Gerät zu benennen, bevor er es erstellt. So kann der Nutzer sein Gerät viel leichter erkennen, wenn er in seinem Google Fotos-Konto Mediendateien auswählt.

Geräte löschen

Implementieren Sie eine Strategie zum Löschen von Geräten, um eine ordnungsgemäße Bereinigung und Nutzerkontrolle zu gewährleisten. Sie können ein Gerät mit der Methode devices.delete löschen.

Berücksichtigen Sie die folgenden Szenarien zum Löschen von Geräten:

• Verbindung durch Nutzer getrennt: Wenn ein Nutzer die Verbindung Ihrer Anwendung zu seinem Google Fotos-Konto trennt, sollten Sie das entsprechende Gerät löschen.
• Verwaiste Geräte: Wenn Sie eine id nicht mehr finden, aber noch die requestId haben, die bei der Erstellung verwendet wurde, können Sie die requestId mit devices.delete verwenden, um ein verwaistes Gerät zu entfernen. So lassen sich versehentliche Duplikate vermeiden und das Konto des Nutzers bleibt übersichtlich.

Wichtige Überlegungen und Best Practices

• Gerätelebenszyklus und Nutzerautorisierung:Sie müssen den Lebenszyklus von Geräten und Nutzerautorisierungstokens verwalten. Überlegen Sie, wie lange Geräte aktiv bleiben und wie Sie Tokenaktualisierungen oder eine erneute Autorisierung handhaben, wenn ein Gerät inaktiv wird oder sein Token abläuft.
• Fehlerbehandlung:Implementieren Sie eine robuste Fehlerbehandlung für alle gerätebezogenen API-Aufrufe. Seien Sie auf folgende Szenarien vorbereitet:
  • NOT_FOUND: Wenn ein Gerät nicht vorhanden ist oder nicht dem Nutzer gehört.
  • RESOURCE_EXHAUSTED: Wenn Sie das Gerätelimit überschreiten.
  • ALREADY_EXISTS: Wenn Sie versuchen, ein Gerät mit einer requestId zu erstellen, die bereits vorhanden ist.

Nächste Schritte

• Beispielanwendung: Unsere Beispielanwendung enthält ein Beispiel für das Erstellen eines Geräts und das Arbeiten mit den Antwortdaten. Weitere Informationen finden Sie in der Funktion createDevice.
• Referenzdokumentation: In der umfassenden Referenzdokumentation zu Geräten finden Sie detaillierte Informationen zu allen verfügbaren Methoden, Anfrage- und Antwort parametern sowie Fehlercodes.
• Mediendateien auflisten und abrufen: Nachdem Sie Ihre Geräte erstellt und verwaltet haben, erfahren Sie, wie Sie Mediendateien auflisten und abrufen, um sie auf den Geräten anzuzeigen.