Geräte erstellen und verwalten

In diesem Leitfaden erfahren Sie, 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 über den OAuth 2.0-Vorgang für TV- und Geräteanwendungen mit begrenzter Eingabe authentifiziert hat, erstellen Sie ein Gerät in seinem Google Fotos-Konto.

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

Wichtig: Speichern Sie die id. Wenn Sie die von Google generierte id nicht speichern, können Sie das Gerät später nicht mehr 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, mit dem ein Gerät gleichzeitig mit der Nutzerauthentifizierung erstellt werden kann. Wenn Sie den zusätzlichen Parameter state in Ihrer ersten OAuth-Anfrage übergeben, können Sie den Prozess zur Geräteerstellung direkt mit dem Anmeldevorgang des Nutzers verknüpfen. Dadurch wird die Nutzerfreundlichkeit verbessert, da die Anzahl der zu scannenden QR-Codes reduziert wird.

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

Gerätelimits

Ihre Anwendung kann bis zu 100 Geräte pro Nutzer erstellen. Wird dieses Limit überschritten, 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, 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 wahr 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 vor dem Erstellen zu benennen. So können Nutzer ihr Gerät viel leichter erkennen, wenn sie Medienelemente in ihrem Google Fotos-Konto auswählen.

Geräte löschen

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

Betrachten Sie die folgenden Szenarien für das Löschen von Geräten:

• Trennung der Nutzerverbindung: Wenn ein Nutzer die Verknüpfung Ihrer App mit seinem Google Fotos-Konto aufhebt, sollten Sie das entsprechende Gerät löschen.
• Verwaiste Geräte: Wenn Sie den Überblick über eine id verlieren, 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 sauber.

Wichtige Hinweise 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 mit der Tokenaktualisierung oder erneuten Autorisierung umgehen, 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 bereits vorhandenen requestId zu erstellen.

Nächste Schritte

• Beispielanwendung:Unsere Beispielanwendung enthält ein Beispiel zum Erstellen eines Geräts und zum Arbeiten mit den Antwortdaten. Weitere Informationen finden Sie in der Hilfe unter createDevice-Funktion.
• Referenzdokumentation:In den umfassenden Referenzdokumenten zu Geräten finden Sie detaillierte Informationen zu allen verfügbaren Methoden, Anfrage- und Antwortparametern sowie Fehlercodes.
• Medienelemente auflisten und abrufen:Nachdem Sie Ihre Geräte erstellt und verwaltet haben, erfahren Sie hier, wie Sie Medienelemente auflisten und abrufen, die auf den Geräten angezeigt werden sollen.