配置配额

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

  1. 将关于配额的信息添加到您的 OpenAPI 配置文件。
  2. 部署您的 OpenAPI 配置文件。
  3. 部署可扩展服务代理 (ESP)。

要大致了解配额提供的功能,请参阅配额简介

前提条件

首先,本页假定您已完成以下操作:

向您的 OpenAPI 文档添加配额

以下过程介绍了如何将所需的扩展添加到您的 OpenAPI 文档以设置配额。为简单起见,本页将 OpenAPI 文档称为 openapi.yaml 文件,并仅以 YAML 格式提供 OpenAPI 扩展程序。

请将以下三个部分添加到 openapi.yaml 文件:

  • x-google-management.metrics:一个指定指标,用于计算向 API 发送的请求数。您需要提供一个描述计数器的名称。名称可以是类别,例如 read-requestswrite-requests。如果您要为特定方法定义配额,可能需要在其中包含方法的名称,例如:echo-api/echo_requests

  • x-google-management.quota.limits:表示对指定指标的单一强制性限制。您可以在此处为已定义的指标配置允许的请求数。目前仅支持每个项目每分钟限制。

  • x-google-quota.metricCostsmetricCosts 会将方法映射到指标(多对多)。对方法的请求将为每个映射的指标分配一个计数器。将方法与指标关联时,请务必指定请求的耗费。您可以单独配置每个方法的耗费,从而让不同的方法以不同的速率消耗同一个指定指标。如果没有复杂的配额要求,则可以将每个指标的耗费配置为 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 部分中的 quotalimits 字段:

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-managementx-google-quota 扩展程序的详细说明,请参阅 OpenAPI 扩展程序

部署 openapi.yaml 文件和 ESP

要使配额生效,您必须完成以下操作:

  1. openapi.yaml 文件部署到 Service Management,以更新 Endpoints 中的配置。
  2. 部署 ESP。部署 ESP 的步骤因要在其中部署您的 API 的后端而异。

如需了解详细步骤,请参阅部署 API 后端