最佳做法

授權

所有傳送至 Google Photos Library API 的要求都必須獲得已驗證使用者的授權。

OAuth 2.0 授權程序的細節會因您編寫的應用程式類型而略有不同。以下一般程序適用於所有應用程式類型:

  1. 請按照下列步驟操作,準備授權程序:
    • 透過 Google API 控制台註冊應用程式。
    • 啟用 Library API 並擷取 OAuth 詳細資料,例如用戶端 ID 和用戶端密鑰。詳情請參閱「開始使用」一文。
  2. 為了存取使用者資料,應用程式會向 Google 發出特定存取範圍的要求。
  3. Google 會向使用者顯示同意畫面,要求他們授權應用程式要求部分資料。
  4. 如果使用者核准要求,Google 就會為應用程式提供會在一小段時間後到期的存取權杖。
  5. 應用程式針對使用者資料發出要求,並將存取權杖附加至要求。
  6. 如果 Google 判定要求和權杖有效,便會傳回要求的資料。

如要判斷應用程式適用的範圍,請參閱授權範圍

某些應用程式類型的程序包含額外的步驟,例如使用更新權杖取得新的存取權杖。如要進一步瞭解各種應用程式類型的流程,請參閱使用 OAuth 2.0 存取 Google API

快取

時時更新資料。

如果出於效能考量而需要暫時儲存媒體 (例如縮圖、相片或影片),請勿按照我們的使用指南快取超過 60 分鐘。

另外,也不應儲存 baseUrls,後者會在約 60 分鐘後失效。

媒體項目 ID 和相簿 ID 是專門用於識別使用者媒體庫內容的媒體項目 ID,不受快取限制的限制。您可以無限期儲存這些 ID (取決於應用程式的隱私權政策)。使用媒體項目 ID 和相簿 ID,透過適當的端點再次擷取可存取的網址和資料。詳情請參閱「取得媒體項目」或「列出專輯」。

如果您有多個媒體項目需要重新整理,則儲存傳回媒體項目的搜尋參數,並重新提交查詢以重新載入資料,可能是更有效率的做法。

SSL 存取

所有 Library API 網路服務要求都必須使用 HTTPS,且要求使用下列網址:

https://photoslibrary.googleapis.com/v1/service/output?parameters

透過 HTTP 發出的要求會遭到拒絕。

處理錯誤

如要瞭解如何處理 API 傳回的錯誤,請參閱 Cloud API 的處理錯誤

重試失敗的要求

指數輪詢所述,用戶端應在發生指數輪詢錯誤時重試 5xx。除非另有說明,否則最短延遲時間應為 1 s

如果是 429 錯誤,用戶端可能會重試,最短延遲 30s。如果是其他錯誤,則可能無法重試。請確認您的要求為冪等,且會看到錯誤訊息來取得指引。

指數輪詢

在極少數情況下,系統可能無法處理您的要求。您可能會收到 4XX5XX HTTP 回應代碼,或者 TCP 連線在用戶端和 Google 伺服器之間某處失敗。通常重試要求都值得。原始要求失敗時,後續追蹤要求可能會成功。不過,請勿循環發出要求,不要重複向 Google 的伺服器發出要求。這種循環行為可能會導致用戶端和 Google 之間的網路超載,並導致許多各方發生問題。

更好的方法,就是重試每次嘗試時增加延遲時間。一般來說,延遲時間會隨著每次嘗試的乘法因子而增加,這種方法稱為指數輪詢

您也必須留意,在應用程式呼叫鏈中,重試程式碼的位置不會超過導致快速連續要求重複要求的情況。

友善使用 Google API

設計不良的 API 用戶端可能會在網際網路和 Google 伺服器上超量負載,本節提供 API 用戶端的一些最佳做法。只要採用這些最佳做法,就能避免應用程式因為不慎濫用 API 而遭到封鎖。

同步要求

針對傳送至 Google API 的大量已同步要求,Google 基礎架構可能會受到分散式阻斷服務 (DDoS) 攻擊,並視情況加以處理。為避免這種情況,請確保在用戶端之間不會同步處理 API 要求。

例如,假設應用程式會以目前時區顯示時間。此應用程式可能會在用戶端作業系統中設定鬧鐘,並在一分鐘開始時喚醒,以便更新顯示的時間。應用程式不應在與鬧鐘相關聯的處理程序中進行任何 API 呼叫。

發出 API 呼叫以回應固定的鬧鐘,會帶來不良體驗,因為會導致 API 呼叫同步到幾分鐘的開始時間 (即使是在不同裝置之間),而不是隨著時間平均分配。設計不良的應用程式會在每分鐘開始時以正常程度的六十倍產生流量。

相反地,建議您將第二個鬧鐘設為隨機選擇的時間。當這第二次鬧鐘啟動時,應用程式會呼叫其所需的任何 API,並儲存結果。如要在一分鐘開始時更新畫面,應用程式會使用先前儲存的結果,而不是再次呼叫 API。使用這個方法時,API 呼叫會在時間中平均分配。此外,螢幕更新時,API 呼叫不會延遲轉譯。

除了一分鐘的開始外,您也應留意其他常見的同步處理時間,不要在 1 個小時的開始和每天午夜開始時。