設定配額

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

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

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

先決條件

本頁面假設您已經：

於 OpenAPI 文件新增配額

以下過程說明如何於 OpenAPI 文件新增所需的擴充項目以設定配額。為求簡潔，本頁面將 OpenAPI 文件稱為 openapi.yaml 檔案，並僅提供 YAML 格式的 OpenAPI 擴充功能。

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

  • x-google-management.metrics：一種命名指標，用於計算對 API 的要求。您提供描述計數器的名稱。名稱可以是類別，例如 read-requests 或 write-requests。但如果要為特定方法定義配額，則可能需包括方法名稱，例如：echo-api/echo_requests

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

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

在 API 上設定配額的方式：

  1. 在文字編輯器中開啟專案的 openapi.yaml 檔。
  2. 如果您還沒有這個檔案，請在檔案的最上層 (非縮排或巢狀部分) 新增 x-google-management 擴充功能，位置在定義路徑的區段之前。

  3. 在 x-google-management 下方以縮排形式新增 metrics 定義。

    x-google-management:
  metrics:
    - name: "YOUR_METRIC_NAME"
      displayName: "YOUR_METRIC-DISPLAY_NAME"
      valueType: INT64
      metricKind: DELTA
    • 將 YOUR_METRIC_NAME 改為描述 API 要求計數器的名稱。
    • 將 YOUR_METRIC_DISPLAY_NAME 改為「Endpoints」 >「Services」(服務) >「Quotas」(配額) 頁面中顯示的文字，以識別指標。
    • valueType 欄位必須為 INT64。
    • metricKind 欄位必須為 DELTA。

  4. 在與 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 專案相關聯的應用程式可在一分鐘內發出的要求數量。

  5. 您也可視情況為各個指標定義其他指標和限制。

  6. 在 openapi.yaml 檔案的 paths 區段中，在您要套用配額的每個方法下方以縮排形式新增 x-google-quota 擴充功能。

    x-google-quota:
  metricCosts:
    YOUR_METRIC_NAME: YOUR_METRIC_COST
    • 將 YOUR_METRIC_NAME 換成先前定義的 metric.name。
    • 將 YOUR_METRIC_COST 改為整數。針對每個要求，指標的要求計數器會按照您為成本指定的數字遞增。

  7. 儲存 openapi.yaml 檔案。

配額設定範例

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

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

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA

以下範例說明如何在 quota 區段內設定 quota 和 limits 欄位：

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA
  quota:
    limits:
      # Define the limit or the read-requests metric.
      - name: "read-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 1000

以下範例說明如何在 paths 區段中設定 x-google-quota 擴充功能：

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA
  quota:
    limits:
      # Define the limit or the read-requests metric.
      - name: "read-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 1000
paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      x-google-quota:
        metricCosts:
          "read-requests": 1
      security:
      - api_key: []

如需 x-google-management 和 x-google-quota 擴充功能的範例和詳細說明，請參閱 OpenAPI 擴充功能一文。

部署 openapi.yaml 檔案和 ESP

如要使配額生效，您必須：

  1. 將 openapi.yaml 檔案部署到 Service Management，這樣做會更新 Endpoints 中的設定。
  2. 部署 ESP。部署 ESP 的步驟會依 API 所部署的後端而異。

如需詳細步驟，請參閱部署 API 後端一文。