Ambient API 使用入门

借助 Ambient API，您的应用可以将环境设备连接到用户的 Google 相册账号，并显示用户选择的照片。

Ambient API 流程

下面详细介绍了 Ambient API 如何连接设备，然后检索和显示媒体项：

  1. 检查现有设备（推荐）：在创建新设备之前，建议先检查当前用户是否已有设备。您的应用应维护内部用户与 Google 提供的 deviceId 之间的映射，以用于用户通过您的应用创建的任何设备。如果找到用户的 deviceId，您可以继续刷新其授权令牌（如果需要）。

  2. 启动 OAuth 2.0 授权（并可选择创建设备）：通过请求授权代码来开始 OAuth 2.0 for TV and Limited Input Devices 流程。

  3. 创建新设备：您的应用通过调用 CreateDevice 并提供有效的 v4 UUID，在用户的 Google 相册账号中创建设备。

    成功创建设备后，API 将返回一个包含 Google 分配的 deviceId 的 AmbientDevice 对象。对于您的应用来说，存储此 deviceId 并将其与用户相关联至关重要。

  4. 显示 settingsUri：AmbientDevice 对象包含 settingsUri。向用户显示此 URI（通常以二维码的形式），用户可以使用移动设备扫描该 URI。此 URI 会将用户定向到 Google 相册应用，用户可以在其中配置要在氛围设备上显示的媒体来源（例如相册）。

  5. 轮询 mediaSourcesSet：您的应用应定期调用 GetDevice 方法（提供 deviceId），以检查环境设备的状况。监控 AmbientDevice 响应中的 mediaSourcesSet 字段。最初为 false。

    当用户在 Google 相册应用中成功选择媒体来源后，此字段将更改为 true。

    AmbientDevice 响应包含一个 pollingConfig，其中包含一个 pollInterval，您应将其用作轮询频率的指南。

  6. 检索媒体项：当 mediaSourcesSet 返回 true 时，应用可以开始提取用户选择的媒体项。

    调用 ListMediaItems 方法，并提供 deviceId。该 API 将返回一个 ListMediaItemsResponse，其中包含 AmbientMediaItem 对象列表。每个 AmbientMediaItem 都包含详细信息，例如 id、createTime 和包含其他元数据的 MediaFile 对象。MediaFile 包含一个 baseUrl，您可以使用它来提取媒体项的实际字节。如需详细了解其他 baseUrl 参数，请参阅列出和检索媒体项指南。

  7. 显示媒体项：使用 MediaFile 中的 baseUrl 下载媒体内容并在环境设备上显示。

重要注意事项

设备限制和管理：

  • 设备限制：请注意，每个应用用户最多只能使用 100 台设备。
  • 设备活动和令牌：您需要管理设备和用户授权令牌的生命周期。请考虑设备保持活跃状态的时间，以及在设备变为不活跃状态或令牌过期时，您将如何处理令牌刷新或重新授权。

如需了解更多详情，请参阅创建和管理设备指南。

处理媒体项：

  • 媒体内容项使用情况：了解如何使用 baseUrl 正确提取和处理媒体内容项内容，包括任何必要的身份验证或参数。
  • 错误处理：为 API 调用实现可靠的错误处理，包括设备为 NOT_FOUND 的情况、未设置媒体源时的 FAILED_PRECONDITION 以及达到设备限制时的 RESOURCE_EXHAUSTED 等场景。

列出和检索媒体内容指南包含更多详细信息，包括有关内容政策和过滤的信息。

后续步骤