配置配额

本页面介绍如何为您的 API 配置配额。概括来讲，步骤如下：

  1. 将关于配额的信息添加到您的 OpenAPI 配置文件。
  2. 部署您的 OpenAPI 配置文件。
  3. 部署可扩展服务代理 (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 > 服务 > 配额页面上显示的文本，以标识指标。
    • valueType 字段必须是 INT64。
    • metricKind 字段必须是 DELTA。

  4. 在与 metrics 相同的层级添加 quota 字段，并以嵌套格式将 limits 字段添加在 quota 部分中。

    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 后端。