割り当ての構成

OpenAPI | gRPC

このページでは、API の割り当てを構成する方法について説明します。全体的な手順は次のとおりです。

割り当てに関する情報を gRPC API 構成ファイルに追加する。
gRPC API 構成ファイルをデプロイする。
Extensible Service 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 ファイルに次の 3 つのセクションを追加します。

metrics: API に対するリクエスト数をカウントする名前付きの指標です。カウンタの内容を説明する名前を付けます。名前は、read-requests や write-requests などのカテゴリにすることもできます。特定のメソッドの割り当てを定義する場合は、メソッド名（例: echo-api/echo_requests）の指定が必要になることもあります。
quota.limits: 名前付き指標に適用可能な制限を表します。ここでは、定義した指標に許可するリクエスト数を構成します。現在、1 分ごとか、プロジェクトごとの制限がサポートされています。
quota.metric_rules: metric_rule はメソッドと指標をマッピングします（多対多）。メソッドへのリクエストが、マッピングされた指標ごとにカウンタを割り当てます。メソッドに指標を関連付ける場合は、常にリクエストのコストを指定します。メソッドごとに個別にコストを構成できます。これにより、異なるメソッドが同じ名前の指標を異なるレートで消費できます。複雑な割り当て要件がない場合は、各指標のコストを 1 に構成できます。

API で割り当てを構成するには:

テキストエディタでプロジェクトの api_config.yaml ファイルを開きます。
apis フィールドの後で、metrics フィールドをファイルのトップレベル（インデントやネストのないレベル）に追加します。
```
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 は、指標を表すテキストに置き換えます。このテキストは、[エンドポイント] > [サービス] > [割り当て] ページに表示されます。
- 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}" にする必要があります。これは、プロジェクトごとの 1 分あたりの制限であることを示します。
- values フィールドには STANDARD を含める必要があります。
- VALUE_FOR_THE_LIMIT は整数値に置き換えます。これはコンシューマの Google Cloud プロジェクトに関連付けられたアプリケーションが 1 分間に行うことができるリクエストの数を表します。
必要に応じて、各指標に対して追加の指標と制限を定義します。
limits セクションの後、quota の下にインデントした 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: "*" を使用します。
  - 1 つの API 内のすべてのメソッドを metric_cost に関連付ける場合: selector: YOUR_API_NAME.* を使用します。
  - 1 つの API 内の特定のメソッドを metric_cost に関連付ける場合: selector: YOUR_API_NAME.YOUR_METHOD_NAME を使用します。
api_config.yaml ファイルを保存します。

割り当ての構成例

次の 3 つの例は、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 構成をデプロイするをご覧ください。
ESP をデプロイします。詳細な手順については、API バックエンドのデプロイをご覧ください。