建立及管理工作階段

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

事前準備

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

工作階段生命週期

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

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

建立工作階段

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

sessions.create 會產生新的工作階段，傳回可向使用者顯示的不重複 pickerUri。在使用者成功選取媒體項目或工作階段逾時之前，工作階段都會保持有效。

注意： 基於安全考量，pickerUri 無法在 iframe 中開啟。

工作階段相關限制

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

注意： 在開發期間，如果您建立測試工作階段，但未儲存其 ID，就無法個別擷取或刪除這些工作階段。請留意這一點，以免建立未追蹤的工作階段。

輪詢及監控工作階段

建立工作階段後，請定期輪詢 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，請妥善處理逾時。