建立及管理工作階段

工作階段是 Picker API 的核心，可讓使用者安全地從 Google 相簿庫選取相片和影片。本指南說明如何建立、管理及有效輪詢工作階段，以便在應用程式中順暢選取相片。

事前準備

  • 設定應用程式：啟用 API 並設定驗證。如需詳細步驟，請參閱「設定應用程式」。
  • 瞭解流程：請參閱「開始使用 Picker API」，瞭解整個相片選取流程。
  • 查看必要授權範圍：如要使用工作階段，必須具備 photospicker.mediaitems.readonly 範圍。如要進一步瞭解範圍，請參閱授權範圍。

工作階段生命週期

Picker API 提供建立、擷取工作階段相關資訊及刪除工作階段的方法。驗證使用者身分後，您可以使用工作階段管理相片挑選生命週期。

  1. 建立工作階段，讓使用者選取媒體項目。
  2. 輪詢工作階段，檢查使用者何時完成選取媒體項目。
  3. 列出及擷取媒體項目。
  4. 刪除工作階段，清除所用資源。

建立工作階段

建立工作階段，讓使用者直接從 Google 相簿應用程式安全地挑選相片，然後分享回您的應用程式。

sessions.create 會產生新的工作階段，並傳回專屬的 pickerUri，您可以向使用者顯示。工作階段會持續有效，直到使用者成功選取媒體項目或工作階段逾時為止。如果是網頁應用程式，您可以在 pickerUri 中附加 /autoclose，讓使用者完成選取後，系統自動關閉 Google 相簿視窗或分頁標籤，詳情請參閱「相片挑選：使用者看到的內容」。

工作階段相關限制

請注意工作階段限制。為確保合理使用並防止濫用，Picker API 會限制可建立的工作階段數量。在一般情況下，您不太可能達到這些限制。不過，您應主動追蹤及清除工作階段，以免發生任何問題。

輪詢及監控工作階段

建立工作階段後，請定期輪詢 sessions.get 端點，以取得工作階段狀態。使用者完成選取後，回應中的 mediaItemsSet 屬性會傳回 true。

請務必使用有效率的輪詢方式。sessions.get 回應包含 pollingConfig 物件。請使用下列欄位，避免不必要的呼叫，並打造流暢的使用者體驗：

  • pollInterval：最佳輪詢間隔
  • timeoutIn：逾時時間長度

詳情請參閱輪詢流程範例。

刪除及清除工作階段

sessions.delete 會移除工作階段，通常用於在使用者選取完媒體後或工作階段逾時時進行清理。

最佳做法是，使用者選取媒體項目且應用程式已擷取媒體項目位元組後，就刪除工作階段。

輪詢流程範例

以下範例說明如何建立及輪詢工作階段。首次驗證使用者後，請建立新的工作階段。

  1. 建立工作階段：呼叫 sessions.create 啟動新工作階段，並取得 pickerUri。
  2. 向使用者提供 pickerUri：顯示網址或產生 QR code，供使用者掃描。閱讀使用者揀貨體驗總覽。
  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，請妥善處理逾時問題。