本頁面說明如何設定您的 API 配額。整體來說,步驟大致如下:
- 將配額相關資訊新增到您的 gRPC API 設定檔中。
- 部署您的 gRPC API 設定檔。
- 部署可擴充服務 Proxy (ESP)。
如需配額功能總覽,請參閱關於配額一文。
先決條件
本頁假設您已經:
- 設定好 Cloud Endpoints。
- 部署了 Endpoints 設定。
- 部署 API 後端。
- 已將您的 API 設定為使用 API 金鑰。注意,您需要執行這個步驟,以便 Endpoints 識別與呼叫應用程式相關聯的 Google Cloud 專案。詳情請參閱「共用受 API 金鑰保護的 API」一節。
為您的 gRPC API 設定檔新增配額
以下過程說明如何將必要的設定新增至您的 gRPC API 設定檔,以設定配額。為求簡單明瞭,本網頁將 gRPC API 設定檔稱為 api_config.yaml
檔。
請將以下三個區段新增到 api_config.yaml
檔案中:
metrics
:一種命名指標,計算對 API 的要求。您提供一個用來描述計數器的名稱。名稱可以是類別,例如read-requests
或write-requests
。或者,如果要為特定方法定義配額,則可能需納入方法名稱,例如:echo-api/echo_requests
。quota.limits
:代表可對命名指標施加的單一限制。您可以在此處為已定義的指標設定允許的要求數量。目前,僅支援每分鐘每個專案的限制。quota.metric_rules
:metric_rule
將方法對應至指標 (多對多)。對方法提出要求時,會將計數器分配至每個對應的指標。當您建立方法與指標之間的關聯後,就能指定要求的成本。您可以為每個方法單獨設定其成本。這可將相同命名指標中的不同方法分別設為不同的使用頻率。若您沒有複雜的配額要求,則可以將每個指標的成本設定為 1。
在 API 上設定配額的方式:
- 在文字編輯器中開啟專案的
api_config.yaml
檔。 在檔案的頂層 (非縮排或巢狀) 新增
metrics
欄位,位置在apis
欄位之後。`metrics: - name: "YOUR_METRIC_NAME" display_name: "YOUR_METRIC_DISPLAY_NAME" value_type: INT64 metric_kind: DELTA`
- 將
YOUR_METRIC_NAME
改為描述 API 要求計數器的名稱。 - 將
YOUR_METRIC_DISPLAY_NAME
改為會在「Endpoints」 >「Services」 >「Quotas」頁面上顯示的文字,以識別指標。 value_type
欄位必須為INT64
。metric_kind
欄位必須為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 專案相關聯的應用程式可在一分鐘內發出的要求數量。
- 將
您也可視情況為各個指標定義其他指標和限制。
在
quota
下方的limits
區段之後以縮排形式新增metric_rules
行。在metric_rules
區段內,將先前定義的指標與方法建立關聯,如下所示:metric_rules: - metric_costs: YOUR_METRIC_NAME: YOUR_METRIC_COST selector: [METHODS]
- 將
YOUR_METRIC_NAME
替換為先前定義的metric.name
。 - 將
YOUR_METRIC_COST
改為整數。針對每個要求,指標的要求計數器會按照您為成本指定的數字遞增。 針對
selector
欄位,您可以指定下列其中一個選項:- 如要將所有 API 中的所有方法與
metric_cost
建立關聯,請使用selector: "*"
- 如要將 API 內的所有方法與
metric_cost
建立關聯,請使用selector: YOUR_API_NAME.*
- 如要將 API 中的特定方法與
metric_cost
建立關聯,請使用selector: YOUR_API_NAME.YOUR_METHOD_NAME
- 如要將所有 API 中的所有方法與
- 將
儲存
api_config.yaml
檔案。
配額設定範例
以下三則範例說明如何在您的 API 上設定配額。
以下範例說明如何設定 metric
欄位:
metrics: # Define a metric for read requests. - name: "read-requests" display_name: "Read requests" value_type: INT64 metric_kind: DELTA`
以下範例說明如何在 quota
區段內設定 quota
和 limits
欄位:
metrics: # Define a metric for read requests. - name: "read-requests" display_name: "Read requests" value_type: INT64 metric_kind: DELTA quota: limits: # Define the limit or the read-requests metric. - name: "read-limit" metric: "read-requests" unit: "1/min/{project}" values: STANDARD: 1000
以下範例說明如何在 limits
區段之後設定 metrics
行:
metrics:
# Define a metric for read requests.
- name: "read-requests"
display_name: "Read requests"
value_type: INT64
metric_kind: DELTA
quota:
limits:
# Define the limit or the read-requests metric.
- name: "read-limit"
metric: "read-requests"
unit: "1/min/{project}"
values:
STANDARD: 1000
metric_rules:
- metric_costs:
"read-requests": 1
selector: *
部署 api_config.yaml
檔案和 ESP
如要使配額生效,您必須:
- 將
api_config.yaml
檔案部署到 Service Management,這樣做會更新 Endpoints 中的設定。如需詳細步驟,請參閱「部署 Endpoints 設定」。 - 部署 ESP。詳細步驟請參閱部署 API 後端。