本頁面由 Cloud Translation API 翻譯而成。

設定配額

OpenAPI | gRPC

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

將配額相關資訊新增到您的 OpenAPI 設定檔。
部署您的 OpenAPI 設定檔。
部署可擴充服務 Proxy (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」 >「Services」 >「Quotas」頁面上顯示的文字，以識別指標。
- valueType 欄位必須為 INT64。
- metricKind 欄位必須為 DELTA。
在與 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 專案相關聯的應用程式可在一分鐘內發出的要求數量。
您也可視情況為各個指標定義其他指標和限制。
在 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 後端一文。