共用方式為

依金鑰限制呼叫頻率

  • 發行項

適用於：開發人員 |基本 |基本 v2 |標準 |標準 v2 |Premium |進階 v2

rate-limit-by-key 原則藉由將指定時間週期內的呼叫頻率限制為指定次數，以防止每個金鑰的 API 使用量暴增。 金鑰可以具有任意字串值，而且通常會使用原則運算式來提供。 可以新增選擇性增量條件，以指定哪些要求應該計入限制。 達到此速率限制時，呼叫端會收到 429 Too Many Requests 回應狀態碼。

若要瞭解速率限制和配額之間的差異，請參閱速率限制和配額。

警告

由於節流架構的分散本質，速率限制永遠不會完全精確。 已設定的允許要求數目，與實際允許的要求數目之間的差異，取決於要求的數量和速率、後端延遲和其他因素。

注意

請依照原則陳述式中提供的順序，來設定原則的元素和子元素。 為了協助您設定此原則，入口網站會提供引導式表單型編輯器。 深入了解如何設定或編輯 APIM 原則。

原則陳述式

<rate-limit-by-key calls="number"
                   renewal-period="seconds"
                   increment-condition="condition"
                   increment-count="number"
                   counter-key="key value" 
                   retry-after-header-name="custom header name, replaces default 'Retry-After'" 
                   retry-after-variable-name="policy expression variable name"
                   remaining-calls-header-name="header name"  
                   remaining-calls-variable-name="policy expression variable name"
                   total-calls-header-name="header name"/>

屬性

屬性 描述 是必要欄位 預設
通話 在 renewal-period 中指定的時間週期內索引鍵值允許的呼叫總數上限。 允許使用原則運算式。 Yes N/A
counter-key 用於頻率限制原則的金鑰。 針對每個索引鍵值，會針對原則設定的所有範圍使用單一計數器。 允許使用原則運算式。 Yes N/A
increment-condition 此布林運算式指定要求是否應該計入頻率 (true)。 允許使用原則運算式。 No N/A
increment-count 依每個要求增加的計數器數目。 允許使用原則運算式。 No 1
renewal-period 滑動視窗的長度，其中允許的要求數目不應超過 calls 中指定的值。 允許的最大值：300 秒。 允許使用原則運算式。 Yes N/A
retry-after-header-name 自訂回應標頭的名稱，其值是超過索引鍵值的指定呼叫率之後，以秒為單位的建議重試間隔。 不允許使用原則運算式。 No Retry-After
retry-after-variable-name 超過索引鍵值的指定呼叫率之後，以秒為單位儲存建議重試間隔的原則運算式變數名稱。 不允許使用原則運算式。 No N/A
remaining-calls-header-name 回應標頭的名稱，每個原則執行之後的值都是對於在 renewal-period 中指定的時間間隔內索引鍵值允許的剩餘呼叫次數。 不允許使用原則運算式。 No N/A
remaining-calls-variable-name 原則運算式變數的名稱，每個原則執行之後的變數都是對於在 renewal-period 中指定的時間間隔內索引鍵值允許的剩餘呼叫次數。 不允許使用原則運算式。 No N/A
total-calls-header-name 回應標頭的名稱，其值為 中指定的 calls 值。 不允許使用原則運算式。 No N/A

使用方式

使用注意事項

  • API 管理會針對您在原則中指定的每個 counter-key 值使用單一計數器。 計數器會在使用該索引鍵值設定原則的所有範圍內更新。。 如果您想要在不同的範圍設定不同的計數器 (例如特定 API 或產品)，請在不同的範圍指定不同的索引鍵值。 例如，將識別範圍的字串附加至運算式的值。
  • 自我裝載閘道中的頻率限制計數可以設定為在本機同步 (在叢集節點中的閘道執行個體之間)，例如，透過適用於 Kubernetes 的 Helm 圖表部署或使用 Azure 入口網站部署範本。 不過，頻率限制計數不會與 APIM 執行個體中設定的其他閘道資源 (包括雲端中的受控閘道) 同步。 深入了解

範例

在下列範例中，每 60 秒 10 次呼叫的頻率限制是依呼叫端 IP 位址鍵入。 在每個原則執行之後，時間週期內該呼叫者 IP 位址允許的其餘呼叫會儲存在變數 remainingCallsPerIP 中。

<policies>
    <inbound>
        <base />
        <rate-limit-by-key calls="10"
              renewal-period="60"
              increment-condition="@(context.Response.StatusCode == 200)"
              counter-key="@(context.Request.IpAddress)"
              remaining-calls-variable-name="remainingCallsPerIP"/>
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

如需此原則範例的詳細資訊，請參閱以 Azure API 管理進行進階要求節流。

相關內容

如需使用原則的詳細資訊，請參閱：