创建和管理会话

会话是 Picker API 的核心，可让用户以安全可控的方式从 Google 相册库中选择照片和视频。本指南概述了如何创建、管理和有效轮询会话，以便在应用中实现流畅的照片选择。

前期准备

  • 配置应用：启用 API 并设置身份验证。如需了解详细步骤，请参阅配置应用。
  • 了解流程：请参阅开始使用 Picker API，简要了解整个照片选择流程。
  • 查看所需的授权范围：如需使用会话，您需要拥有 photospicker.mediaitems.readonly 范围。如需详细了解范围，请参阅授权范围。

会话生命周期

Picker API 提供了用于创建、检索会话相关信息和删除会话的方法。对用户进行身份验证后，您可以使用会话来管理照片选择生命周期。

  1. 创建会话，以便用户选择媒体内容。
  2. 轮询会话，以检查用户何时完成选择媒体内容。
  3. 列出和检索媒体内容。
  4. 删除会话以清理会话。

创建会话

创建一个会话，以便用户可以直接从 Google 相册应用中安全地选择照片，并将其分享回您的应用。

sessions.create 会生成一个新会话，并返回一个唯一的 pickerUri，您可以将其呈现给用户。在用户成功选择媒体内容或会话超时之前，会话会保持活动状态。

会话次数限制

请注意会话限制。Picker API 会对您可以创建的会话数量施加限制，以确保负责任地使用并防止滥用。在正常情况下，您不太可能达到这些限制。不过，您应跟踪并主动清理会话，以免出现任何问题。

轮询和监控会话

创建会话后，请定期轮询 sessions.get 端点以获取会话状态。当用户完成选择后，响应中的 mediaItemsSet 属性会返回 true。

请务必使用高效的轮询。sessions.get 响应包含 pollingConfig 对象。使用以下字段有助于您避免不必要的调用并打造顺畅的用户体验：

  • pollInterval：最佳轮询间隔
  • timeoutIn：超时时长

如需了解详情，请参阅轮询流程示例。

删除和清理会话

sessions.delete 用于移除会话，通常用于在用户完成选择媒体后或会话超时时进行清理。

最佳实践是，在用户选择媒体内容并您的应用检索到媒体内容字节后删除会话。

轮询流程示例

以下是创建和轮询会话的示例。首次对用户进行身份验证后，创建一个新会话。

  1. 创建会话：调用 sessions.create 以启动新会话并获取 pickerUri。
  2. 向用户呈现 pickerUri：显示网址或生成二维码供用户扫描。阅读用户选择体验概览。
  3. 轮询会话：
    1. 使用 pollingConfig 中建议的 pollInterval。
    2. 检查 mediaItemsSet 是否为 true。
      1. 如果为 true，则继续列出所选媒体内容。
      2. 如果为 false，则继续轮询，直到达到 timeoutIn。
    3. 从容处理超时和取消。
GET https://photoslibrary.googleapis.com/v1/sessions/{sessionId}

以下是示例响应：

{
  "id": string,
  "pickerUri": string,
  "pollingConfig": {
    object (PollingConfig)
  },
  "mediaItemsSet": boolean
}

向用户显示 pickerUri，然后开始轮询会话。

检查响应是否包含以下内容：

  • mediaItemsSet：如果用户已完成选择媒体内容，则为 true
  • pollingConfig.pollInterval：建议在下次轮询之前等待的时间
  • pollingConfig.timeoutIn：在超时之前的等待总时间

如果 mediaItemsSet 为 false 且尚未达到 timeoutIn，请等待 pollInterval，然后重新轮询。

如果 mediaItemsSet 为 true，则继续列出所选媒体内容。

如果达到 timeoutIn，请妥善处理超时。