用量限制和配額

限制和配額可保護 Google 基礎架構免受不當使用 Email Audit API 的自動化程序。來自 API 的過多要求可能是由無損的錯字所造成,或是因為設計不良的系統發出不必要的 API 呼叫。無論原因為何,當 Google Workspace 系統的整體健康狀態良好時,封鎖特定來源的流量仍須達到特定等級。設定限制可確保某個開發人員的動作不會因此對大型社群造成負面影響。

在極少數的 API 要求失敗的情況下,您會收到 HTTP 狀態碼回應。狀態碼 403 包含錯誤輸入錯誤資訊,而 503 的 HTTP 狀態碼出現錯誤資訊,指出已超過 API 配額。這些回應可讓您的自訂應用程式偵測這些錯誤並採取適當行動。

如果要求必須在固定時間內完成,請同時傳送要求,或在 Java 或 C# 應用程式中使用多個執行緒。平行要求的請求範例是要求來自不同使用者的少量電子郵件,而非同時新增或移除單一使用者的電子郵件。如果是執行緒,請先從 10 個執行緒開始 (每個使用者電子郵件一個執行緒)。請注意,執行緒建議有取捨,且不適用於所有 API 的情況。如果要求數量過高,就會發生配額錯誤。另一個取捨的例子是 Email Audit API 整體郵件上傳速率上限。上傳頻率為每位使用者每秒一次 API 要求,無論要求數量的執行緒數量為何。

對於所有以時間為準的錯誤 (每個執行緒 N 秒鐘,以 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
日期格式 將所有日期轉換為「世界標準時間」通用格式 (UTC) 格式並搭配電子郵件稽核 API 使用。詳情請參閱 UTC 轉換工具
加密信箱檔案、EXPIRED 摘要及匯出檔案 Google 會將已加密的信箱檔案保留 3 週。在這段期限過後,這些資料就會遭到刪除。 這段時間內,網域管理員必須下載這些信箱檔案。
加密信箱檔案,格式 加密信箱檔案採 mbox 格式。
加密信箱檔案、建立要求數量上限 系統每天為網域中所有管理員建立 100 項要求時,系統匯出信箱數量上限
加密信箱檔案狀態、分頁 要求所有信箱要求的狀態時,回應可能會傳回大量資料。Email Audit API 會將這項資料批次處理,其中每頁包含最多 100 個項目,而 link rel='next' 標記中有 URI 會指向下一頁的搜尋結果。開發用戶端應用程式時,您的程式碼需要管理這些額外結果。
電子郵件監控 每日電子郵件監控要求數量上限為 1500 個。這項限制適用於網域,且包含管理員在一天內提出的所有要求。
公開金鑰 Email Audit API 僅支援一個金鑰。

公開金鑰採用 GNU Privacy Guard (GPG) 軟體。採 PGP 格式,也是以 ASCII 編碼的 RSA 加密金鑰。上傳公開金鑰之前,您必須先將公開金鑰轉換為 Base64 編碼字串,公開金鑰檔案應使用字元集 US-ASCII (IANA 為 ASCII 偏好的字元集名稱) 讀取。

搜尋 searchQueryincludeDeleted 參數互斥。如果使用 includeDeleted="true",則無法進行搜尋查詢。