設定配額

本頁面說明如何設定您的 API 配額。整體來說,步驟大致如下:

  1. 將配額相關資訊新增到您的 gRPC API 設定檔中。
  2. 部署您的 gRPC API 設定檔。
  3. 部署可擴充服務 Proxy (ESP)。

如需配額功能總覽,請參閱關於配額一文。

先決條件

本頁假設您已經:

為您的 gRPC API 設定檔新增配額

以下過程說明如何將必要的設定新增至您的 gRPC API 設定檔,以設定配額。為求簡單明瞭,本網頁將 gRPC API 設定檔稱為 api_config.yaml 檔。

請將以下三個區段新增到 api_config.yaml 檔案中:

  • metrics:一種命名指標,計算對 API 的要求。您提供一個用來描述計數器的名稱。名稱可以是類別,例如 read-requestswrite-requests。或者,如果要為特定方法定義配額,則可能需納入方法名稱,例如:echo-api/echo_requests

  • quota.limits:代表可對命名指標施加的單一限制。您可以在此處為已定義的指標設定允許的要求數量。目前,僅支援每分鐘每個專案的限制。

  • quota.metric_rulesmetric_rule 將方法對應至指標 (多對多)。對方法提出要求時,會將計數器分配至每個對應的指標。當您建立方法與指標之間的關聯後,就能指定要求的成本。您可以為每個方法單獨設定其成本。這可將相同命名指標中的不同方法分別設為不同的使用頻率。若您沒有複雜的配額要求,則可以將每個指標的成本設定為 1。

在 API 上設定配額的方式:

  1. 在文字編輯器中開啟專案的 api_config.yaml 檔。
  2. 在檔案的頂層 (非縮排或巢狀) 新增 metrics 欄位,位置在 apis 欄位之後。`

    metrics:
      - name: "YOUR_METRIC_NAME"
        display_name: "YOUR_METRIC_DISPLAY_NAME"
            value_type: INT64
        metric_kind: DELTA`
    
    • YOUR_METRIC_NAME 改為描述 API 要求計數器的名稱。
    • YOUR_METRIC_DISPLAY_NAME 改為會在「Endpoints」 >「Services」 >「Quotas」頁面上顯示的文字,以識別指標。
    • value_type 欄位必須為 INT64
    • metric_kind 欄位必須為 DELTA
  3. 在與 metrics 相同層級中新增 quota 欄位,並在 quota 區段內以巢狀形式新增 limits 欄位。

    quota:
      limits:
        - name: "YOUR_LIMIT_NAME"
          metric: "YOUR_METRIC_NAME"
          unit: "1/min/{project}"
          values:
            STANDARD: VALUE_FOR_THE_LIMIT
    
    • YOUR_LIMIT_NAME 改成一個描述限制的名稱。
    • YOUR_METRIC_NAME 替換為先前定義的 metric.name
    • unit 欄位必須為 "1/min/{project}"。這是每個專案每分鐘上限的識別碼。
    • values 欄位必須包含 STANDARD
    • VALUE_FOR_THE_LIMIT 改為整數。這是與消費者的 Google Cloud 專案相關聯的應用程式可在一分鐘內發出的要求數量。
  4. 您也可視情況為各個指標定義其他指標和限制。

  5. quota 下方的 limits 區段之後以縮排形式新增 metric_rules 行。在 metric_rules 區段內,將先前定義的指標與方法建立關聯,如下所示:

    metric_rules:
      - metric_costs:
          YOUR_METRIC_NAME: YOUR_METRIC_COST
        selector: [METHODS]
    
    • YOUR_METRIC_NAME 替換為先前定義的 metric.name
    • YOUR_METRIC_COST 改為整數。針對每個要求,指標的要求計數器會按照您為成本指定的數字遞增。
    • 針對 selector 欄位,您可以指定下列其中一個選項:

      • 如要將所有 API 中的所有方法與 metric_cost 建立關聯,請使用 selector: "*"
      • 如要將 API 內的所有方法與 metric_cost 建立關聯,請使用 selector: YOUR_API_NAME.*
      • 如要將 API 中的特定方法與 metric_cost 建立關聯,請使用 selector: YOUR_API_NAME.YOUR_METHOD_NAME
  6. 儲存 api_config.yaml 檔案。

配額設定範例

以下三則範例說明如何在您的 API 上設定配額。

以下範例說明如何設定 metric 欄位:

metrics:
  # Define a metric for read requests.
  - name: "read-requests"
    display_name: "Read requests"
    value_type: INT64
    metric_kind: DELTA`

以下範例說明如何在 quota 區段內設定 quotalimits 欄位:

metrics:
  # Define a metric for read requests.
  - name: "read-requests"
    display_name: "Read requests"
    value_type: INT64
    metric_kind: DELTA
quota:
  limits:
    # Define the limit or the read-requests metric.
    - name: "read-limit"
      metric: "read-requests"
      unit: "1/min/{project}"
      values:
        STANDARD: 1000

以下範例說明如何在 limits 區段之後設定 metrics 行:

  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      display_name: "Read requests"
      value_type: INT64
      metric_kind: DELTA
  quota:
    limits:
      # Define the limit or the read-requests metric.
      - name: "read-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 1000
    metric_rules:
      - metric_costs:
          "read-requests": 1
        selector: *

部署 api_config.yaml 檔案和 ESP

如要使配額生效,您必須:

  1. api_config.yaml 檔案部署到 Service Management,這樣做會更新 Endpoints 中的設定。如需詳細步驟,請參閱「部署 Endpoints 設定」。
  2. 部署 ESP。詳細步驟請參閱部署 API 後端