配置配额

OpenAPI | gRPC

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

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

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

前提条件

首先，本页假定您已完成以下操作：

配置了 Cloud Endpoints
部署了 Endpoints 配置。
部署 API 后端。
将 API 配置为使用 API 密钥。要使 Endpoints 可以确定与调用应用关联的 Google Cloud 项目，则必须执行此操作。如需了解详情，请参阅共享受 API 密钥保护的 API。

向您的 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 配额，请执行以下操作：

在文本编辑器中打开项目的 openapi.yaml 文件。
如果您还没有添加 x-google-management 扩展程序，请将该扩展程序添加到文件的根位置（不缩进或嵌套），位于定义路径部分的前面。
在 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。
在与 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 项目关联的应用在一分钟内可发出的请求数。
（可选）定义额外的指标以及每个指标的限制。
在 openapi.yaml 文件的 paths 部分中，在每个要应用配额的方法下添加 x-google-quota 扩展程序（采用缩进格式）。
```
x-google-quota:
  metricCosts:
    YOUR_METRIC_NAME: YOUR_METRIC_COST
```
- 将 YOUR_METRIC_NAME 替换为先前定义的 metric.name。
- 将 YOUR_METRIC_COST 替换为一个整数。对于每个请求，指标的请求计数器都会根据您为该耗费指定的数值递增。
保存 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

要使配额生效，您必须完成以下操作：

将 openapi.yaml 文件部署到 Service Management，以更新 Endpoints 中的配置。
部署 ESP。部署 ESP 的步骤因部署 API 的后端而异。

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