创建和管理设备

本指南介绍了如何创建、管理和删除设备。正确的设备管理有助于打造流畅的用户体验，并高效使用 Ambient API。

创建设备

用户使用适用于电视和输入受限的设备应用的 OAuth 2.0 流程成功进行身份验证后，请在其 Google 相册账号中创建设备。

当您的应用使用 devices.create 方法成功创建设备时，Ambient API 会返回一个包含 Google 生成的 id 的 AmbientDevice 对象。安全地存储此 id，并将其与您的用户相关联。

使用 OAuth 简化设备创建流程

Ambient API 提供了简化的 OAuth 流程，可在进行用户身份验证的同时创建设备。通过在初始 OAuth 请求中传递额外的 state 参数，您可以将设备创建流程直接关联到用户的登录流程，从而减少用户需要扫描的二维码数量，简化用户体验。

如需了解详情和示例，请参阅 Ambient API 的简化身份验证流程指南。

设备限制

您的应用最多可以为每位用户创建 100 部设备。如果超出此限制，API 将返回 RESOURCE_EXHAUSTED 错误。

管理设备

创建设备并将其关联到用户的 Google 相册账号后，您可能需要管理其生命周期。

检索设备

如需检索特定设备的相关信息，请使用 devices.get 方法及其唯一的 id。这对于检查设备的状态（例如 mediaSourcesSet 是否为 true）非常有用。

更新设备

您可以使用 devices.patch 方法更新现有设备的某些属性，例如其显示名称。这样，用户就可以对自己的设备进行个性化设置，并在 Google 相册中更轻松地识别它们。

删除设备

实现用于删除设备的策略，以便进行适当的清理和用户控制。 您可以使用 devices.delete 方法删除设备。

请考虑以下删除设备的场景：

  • 用户解除关联：如果用户解除您的应用与其 Google 相册账号的关联，您应删除相应的设备。
  • 孤岛设备：如果您丢失了 id，但仍保留了创建时使用的 requestId，则可以将 requestId 与 devices.delete 搭配使用来移除孤岛设备。这有助于防止意外重复，并确保用户的账号保持整洁。

重要注意事项和最佳实践

  • 设备生命周期和用户授权：您需要管理设备和用户授权令牌的生命周期。考虑设备保持活跃状态的时长，以及在设备变为非活跃状态或其令牌过期时，您将如何处理令牌刷新或重新授权。
  • 错误处理：为所有与设备相关的 API 调用实现强大的错误处理机制。请做好以下场景的准备：
    • NOT_FOUND：如果设备不存在或不归用户所有。
    • RESOURCE_EXHAUSTED：如果您超出了设备数量限制。
    • ALREADY_EXISTS：如果您尝试创建具有已存在的 requestId 的设备。

后续步骤