Table of contents

節流指導方針 | Graph API 概念Throttling guidance | Graph API concepts

Pat Altimore|上次更新日期: 2018/6/19
2 貢獻者

我們強烈建議您使用 Microsoft Graph 來存取 Azure Active Directory 資源,而不是使用 Azure AD Graph API。We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources.我們目前致力於開發 Microsoft Graph,對於 Azure AD Graph API 則沒有進一步增強的計劃。Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API.Azure AD Graph API 仍適用於非常少數的案例;如需詳細資訊,請參閱 Office 開發人員中心的 Microsoft Graph 或 Azure AD Graph (英文) 部落格文章。There are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.

什麼是節流?What is throttling?

節流會限制針對服務的並行呼叫數目,以避免資源的過度使用。Throttling limits the number of concurrent calls to a service to prevent overuse of resources.Azure Active Directory (AD) Graph 是針對處理非常大量的要求而設計。Azure Active Directory (AD) Graph is designed to handle a very high volume of requests.在出現龐大要求數目的情況下,節流可以協助 Azure AD Graph 服務維持最佳化的效能和可靠性。In the event of an overwhelming number of requests, throttling helps maintain optimal performance and reliability of the Azure AD Graph service.

節流限制會根據案例而有所不同。Throttling limits vary based on the scenario.例如,相較於僅執行讀取,如果您正在針對租用戶執行大量的寫入,發生節流的機率將會較高。For example, if you are performing a large volume of writes to your tenant, the possibility for throttling is higher than if you are only performing reads.

發生節流時會發生什麼事?What happens when throttling occurs?

超過節流閥值時,Azure AD Graph 會在節流生效期間限制該用戶端所有進一步的要求。When a throttling threshold is exceeded, Azure AD Graph limits any further requests from that client while the throttle is in effect.節流時,Azure AD Graph 會傳回 HTTP 狀態碼 429 (「過多要求」),且要求將會失敗。When throttled, Azure AD Graph returns HTTP status code 429 ("Too many requests"), and the requests fail.節流行為可能會取決於要求的類型和數目。Throttling behavior can be dependent on the type and number of requests.例如,如果您有非常大量的要求,則會對所有要求類型進行節流。For example, if you have a very high volume of requests, all requests types are throttled.節流限制會根據要求類型而有所不同。Threshold limits vary based on the request type.因此,您可能會遇到針對寫入進行節流,但仍允許讀取的案例。Therefore, you could encounter a scenario where writes are throttled but reads are still permitted.

常見的節流案例Common throttling scenarios

造成針對用戶端進行節流的最常見案例包括:The most common causes of throttling of clients include:

  • 單一租用戶中的所有應用程式上皆出現大量的要求。A large number of requests across all applications in a tenant.
  • 所有租用戶上的特定應用程式出現大量的要求。A large number of requests from a particular application across all tenants.

處理節流的最佳做法Best practices to handle throttling

  • 減少每個要求的作業數目。Reduce the number of operations per request.
  • 減少呼叫的頻率。Reduce the frequency of calls.
  • 當要求失敗並顯示 HTTP 錯誤碼 429 時,請根據 Retry-After 回應標頭欄位中所指定的秒數等候一段時間,然後再重試該要求。When requests fail with a HTTP error code 429, wait the number of seconds specified in the Retry-After response header field and retry the request.

實作錯誤處理時,請使用 HTTP 錯誤碼 429 來偵測節流。When implementing error handling, use the HTTP error code 429 to detect throttling.失敗的回應在回應標頭中將會包含 Retry-After 欄位。The failed response will include the Retry-After field in the response header.

  1. 請根據 Retry-After 欄位中所指定的秒數等候一段時間。Wait the number of seconds specified in the Retry-After field.
  2. 重試要求。Retry the request.
  3. 如果要求再次失敗並顯示錯誤碼 429,便代表您仍然處於節流狀態,請繼續使用建議的 Retry-After 延遲並持續重試要求,直到成功為止。If the request fails again with a 429 error code, you are still being throttled, continue to use the recommended Retry-After delay and retry the request until it succeeds.

根據 Retry-After 延遲來暫停要求,是從節流中復原的最快方式,因為 AAD Graph 會在用戶端處於節流狀態時持續記錄資源使用量。Backing off requests using the Retry-After delay is the fastest way to recover from throttling because AAD Graph continues to log resource usage while a client is being throttled.您應該避免立即做出重試,因為所有的要求都會納入使用量限制的計算。You should avoid immediate retries since all requests accrue against your usage limits.

如需 Microsoft Cloud 上更廣泛的節流討論,請參閱節流模式 (英文)For a broader discussion of throttling on the Microsoft Cloud, see Throttling Pattern.

© 2018 Microsoft