建立及管理工作階段

工作階段是 Picker API 的核心，提供安全無虞的受控 讓使用者從 Google 相簿相片庫中選取相片和相簿。本指南將概略說明如何建立、管理及有效地輪詢工作階段，以便在應用程式中提供無縫的相片選取功能。

事前準備

  • 設定應用程式：啟用 API 並設定驗證機制。詳情請見 詳請設定應用程式 100 萬步的訓練
  • 瞭解流程：請參閱「使用 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：顯示網址或產生 QR code，供使用者掃描。
  3. 意見調查活動：
    1. 使用 pollingConfig 中建議的輪詢間隔。
    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，請妥善處理逾時。