用量限制和配額

限制和配額可避免自動化程序以不當方式使用 Email Audit API，保護 Google 基礎架構。API 提出過多要求可能是因為無害的筆誤，也可能是因為系統設計效率不彰，導致不必要的 API 呼叫。無論原因為何，當特定來源的流量達到一定程度時，都必須封鎖該來源的流量，才能確保 Google Workspace 系統的整體健康狀態。限制可確保開發人員的行為不會對廣大社群造成負面影響。

萬一 API 要求失敗，您會收到 HTTP 狀態碼回應。狀態碼 403 包含輸入內容有誤的錯誤資訊，而 HTTP 狀態碼 503 則包含指出超出哪些 API 配額的錯誤資訊。自訂應用程式可透過這些回應偵測錯誤，並採取適當行動。

如果要求必須在固定時間內完成，請並行傳送要求，或在 Java 或 C# 應用程式中使用多個執行緒。舉例來說，與其同時新增或移除某位使用者的多封電子郵件，不如要求來自不同使用者的少量電子郵件。如果是執行緒，請先嘗試 10 個執行緒，每個使用者電子郵件地址對應一個執行緒。請注意，執行緒建議有其缺點，並非適用於所有 API 情況。如果要求次數過多，就會發生配額錯誤。另一個取捨範例是 Email Audit API 的配額，也就是整體郵件上傳速率上限。無論有多少個執行緒發出上傳要求，每位使用者每秒只能發出一個 API 要求。

對於所有以時間為準的錯誤 (每個執行緒每 N 秒最多 N 個項目)，尤其是 503 狀態碼錯誤，建議您的程式碼擷取例外狀況，並使用指數輪詢演算法，等待一小段時間後再重試失敗的呼叫。以一個執行緒的 Email Audit API 為例，就是等待 5 秒，然後重試失敗的呼叫。如果要求成功，請針對其他執行緒重複這個模式。如果第二次要求未成功，應用程式應減少要求頻率，直到呼叫成功為止。舉例來說，您可以將初始 5 秒的延遲時間增加至 10 秒，然後再次重試失敗的呼叫。此外，請決定重試次數上限。舉例來說，應用程式可以先以不同的延遲時間重試要求 5 到 7 次，再向使用者傳回錯誤。

下表列出 Email Audit API 的限制：

API 限制類別	限制
加密信箱檔案，建立	系統可能需要幾天時間準備加密的信箱檔案，實際時間取決於檔案大小。
加密信箱檔案、刪除時發生錯誤	如果刪除加密信箱時發生錯誤，要求會顯示 MARKED_DELETE 狀態。Google 會在 24 小時內再次自動刪除這些摘要和匯出檔案 (可能會有檔案殘留)。如果系統持續傳回 MARKED_DELETE 狀態，請嘗試採用指數輪詢策略。

下表列出 Email Audit API 的配額：

API 配額類別	配額
ClientLogin 驗證權杖	效期為 24 小時。錯誤訊息為「401 token expired」。
日期格式	使用 Email Audit API 前，請先將所有日期轉換為世界標準時間 (UTC) 格式。詳情請參閱 UTC 轉換器。
加密的信箱檔案、摘要和匯出檔案EXPIRED	Google 會將加密的信箱檔案保留 3 週。這段期限過後，系統就會刪除這些資料。網域管理員有責任在這段時間內下載這些信箱檔案。
加密信箱檔案 (格式)	加密信箱檔案的格式為 mbox。
加密信箱檔案、建立要求上限	網域中所有管理員每天最多可提出 100 個信箱匯出建立要求。
加密信箱檔案狀態、分頁	要求所有信箱要求的狀態時，回應可能會傳回大量資料。Email Audit API 會將這項資料分批處理成網頁，每個網頁最多包含 100 個項目，且 link rel='next' 標記中的 URI 會指向下一頁結果。開發用戶端應用程式時，程式碼必須管理這些額外結果。
電子郵件監控器	每日電子郵件監控要求數量上限為 1,500 個。這項限制適用於網域，且包含管理員當天提出的所有要求。
公開金鑰	Email Audit API 僅支援一個金鑰。 公開金鑰使用 GNU Privacy Guard (GPG) 軟體。這個檔案採用 PGP 格式，是經過 ASCII 編碼的 RSA 加密金鑰。上傳公開金鑰前，請先將其轉換為 Base64 編碼字串。公開金鑰檔案應以 US-ASCII 字元集讀取，(IANA 偏好的 ASCII 字元集名稱)。
搜尋中	searchQuery 和 includeDeleted 參數互斥，如果出現 includeDeleted="true"，就無法進行搜尋查詢。