Ambient API 使用入门

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

Ambient API 工作流

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

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

  2. 启动 OAuth 2.0 授权：通过请求授权代码，开始适用于电视和输入受限设备的 OAuth 2.0 工作流。

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

    成功创建设备后，API 将返回一个 AmbientDevice 对象，其中包含 Google 分配的 deviceId。您的应用必须存储此 deviceId 并将其与用户关联。

  4. 显示 settingsUri：AmbientDevice 对象包含 settingsUri。向用户显示此 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。

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

后续步骤