頻率限制

本頁說明如何使用服務基礎架構來為與 Service Management API 整合的管理化服務導入頻率限制。

管理化服務可供許多服務用戶使用。為保護系統容量及確保公平使用，受管理服務通常會使用頻率限制，在服務消費者之間分配容量。Service Management 和 Service Control API 可讓您管理及強制執行頻率限制。

配置頻率限制

如要使用頻率限制功能，請在服務供應商專案的服務設定中設定 _quota metrics_ 和 _quota limits_。

目前支援的頻率限制是每個服務消費者每分鐘的要求數，其中服務消費者是 Google Cloud 專案，可透過 API 金鑰、專案 ID 或專案號碼識別。對頻率限制設定而言，要求的概念是一種不透明概念。服務可以選擇將 HTTP 要求或負載位元組做為要求。頻率限制功能與要求的語意無關。

配額指標

指標是一種具備名稱的計數器，可用來測量一段時間內的特定值。舉例來說，某個服務收到的 HTTP 要求數就是一種指標。配額指標是一種用於配額和頻率限制設定的指標。服務發生活動時，一或多個配額指標的值可能會增加。當指標值達到預先定義的配額限制時，該服務就會拒絕活動並顯示 429 錯誤。

配額限制

配額限制代表可對配額指標施加的限制。舉例來說，每個服務用戶每分鐘的要求數是一種配額限制。目前唯一支援的配額限制類型是每位消費者每分鐘的限制，具體來說是 1/min/{project}。

一組 (服務、用戶) 配對的實際頻率限制由下列 3 種設定控管：

  • 管理化服務的指定預設限制。
  • 服務用戶的服務生產端覆寫設定。
  • 服務用戶的服務用戶覆寫設定。

有效的頻率限制如下：

  • 如果沒有任何覆寫設定，則採預設限制。
  • 如果有服務生產端覆寫設定，但沒有服務用戶覆寫設定，則採服務生產端覆寫設定。
  • 如果有服務用戶覆寫設定，但沒有服務生產端覆寫設定，則採 (服務用戶覆寫、預設限制) 組合中的最低值。
  • 如果有服務生產端和服務用戶覆寫設定，則採 (服務用戶覆寫、服務生產端覆寫) 組合中的最低值。

強制執行頻率限制設定

如要強制執行頻率限制，凡是屬於代管服務的伺服器都必須定期呼叫 Service Control API services.allocateQuota 方法。如果 services.allocateQuota 方法的回應指出用量超出限制，伺服器應拒絕連入要求，並傳回 429 錯誤。詳情請參閱 services.allocateQuota 方法的參考說明文件。

我們建議每個伺服器應使用批次、快取和預測邏輯，以增進系統效能和可靠性。一般而言，一個伺服器每秒只應針對相同的 (服務、用戶、指標) 組合呼叫 services.allocateQuota 方法一次。

以下範例示範如何呼叫 services.allocateQuota 方法來檢查頻率限制。必須正確設定的重要要求參數為服務名稱、用戶 ID、指標名稱和指標值。services.allocateQuota 方法會試著增加 (服務、用戶、指標) 組合指定數量的用量。如果提高的用量超過限制，則會傳回錯誤。下列範例使用 gcurl 指令來示範呼叫。如要瞭解相關設定方式，請參閱開始使用 Service Control API。

gcurl -d '{
  "allocateOperation": {
    "operationId": "123e4567-e89b-12d3-a456-426655440000",
    "methodName": "google.example.hello.v1.HelloService.GetHello",
    "consumerId": "project:endpointsapis-consumer",
    "quotaMetrics": [{
      "metricName": "endpointsapis.appspot.com/requests",
      "metricValues": [{
        "int64Value": 1
      }]
    }],
    "quotaMode": "NORMAL"
  }
}' https://servicecontrol.googleapis.com/v1/services/endpointsapis.appspot.com:allocateQuota
{
  "operationId": "123e4567-e89b-12d3-a456-426655440000",
  "quotaMetrics": [
    {
      "metricName": "serviceruntime.googleapis.com/api/consumer/quota_used_count",
      "metricValues": [
        {
          "labels": {
            "/quota_name": "endpointsapis.appspot.com/requests"
          },
          "int64Value": "1"
        }
      ]
    }
  ],
  "serviceConfigId": "2017-09-10r0"
}

處理錯誤

如果 HTTP 回應碼為 200，且回應包含 RESOURCE_EXHAUSTED QuotaError，伺服器應以 429 錯誤拒絕要求。如果回應中沒有任何配額錯誤，則您的伺服器應繼續服務連入要求。如果發生其他配額錯誤，伺服器應拒絕要求，並傳回 409 錯誤。基於安全性風險，對於納入錯誤訊息中的內容，您必須非常小心謹慎。

至於所有其他 HTTP 回應碼，可能是您的伺服器發生程式設計錯誤。我們建議在您偵錯問題的同時，伺服器可以繼續服務連入要求。如果 services.allocateQuota 方法傳回任何非預期的錯誤，伺服器應記錄錯誤並接受連入要求。您可以稍後對錯誤進行偵錯。

失效開放

頻率限制設定功能是用來保護管理化服務以免超載，以及將服務容量公平地分配給服務用戶。由於大多數服務消費者在正常運作期間不應達到頻率限制，因此如果頻率限制功能無法使用，受管理服務應接受所有傳入要求，這也稱為「失效開放」。這可避免服務可用性受到頻率限制系統的影響。

如果使用 services.allocateQuota 方法，服務必須忽略 500、503 和 504 錯誤，且不得重試。為了避免對頻率限制功能產生硬相依性，Service Control API 會定期發出數量有限的錯誤植入。