建立及管理工作階段

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

事前準備

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

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

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

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

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

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

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

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

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

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

以下是建立及輪詢工作階段的範例。初次驗證使用者後，請建立新的工作階段。

建立工作階段：呼叫 sessions.create 以啟動新的工作階段，並取得 pickerUri。
向使用者呈現 pickerUri：顯示網址或產生 QR code，供使用者掃描。請參閱使用者選擇體驗總覽。
輪詢工作階段：
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 為 false，且尚未達到 timeoutIn，請等待 pollInterval，然後再輪詢一次。

如果 mediaItemsSet 為 true，請繼續列出所選媒體項目。

如果已達 timeoutIn，請妥善處理逾時情況。