割り当ての構成

OpenAPI | gRPC

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

割り当てに関する情報を OpenAPI 構成ファイルに追加する。
OpenAPI 構成ファイルをデプロイする。
Extensible Service Proxy（ESP）をデプロイする。

割り当てによって提供される機能の概要については、割り当てについてをご覧ください。

前提条件

このページの説明は、次のことを前提としています。

Cloud Endpoints が構成されていること。
Endpoints 構成をデプロイ済みであること。
API バックエンドをデプロイ済みであること。
API キーを使用するように API を構成している。これは、Endpoints が、呼び出し側のアプリケーションが関連付けられている Google Cloud プロジェクトを識別するために必要です。詳しくは、API キーにより保護されている API を共有するをご覧ください。

OpenAPI ドキュメントに割り当てを追加する

以下の手順では、必要な拡張機能を OpenAPI ドキュメントに追加して、割り当てを設定する方法について説明します。わかりやすくするため、このページでは OpenAPI ドキュメントを openapi.yaml ファイルと表記しており、OpenAPI の拡張を YAML 形式でのみ提供しています。

openapi.yaml ファイルに次の 3 つのセクションを追加します。

x-google-management.metrics: API に対するリクエスト数をカウントする名前付きの指標です。カウンタの内容を説明する名前を入力します。名前は read-requests や write-requests などのカテゴリになります。特定のメソッドの割り当てを定義する場合、メソッド名（例: echo-api/echo_requests）の指定が必要になることもあります。
x-google-management.quota.limits: 名前付き指標に適用可能な上限を表します。ここでは、定義した指標に許可するリクエスト数を構成します。現在、1 分ごとか、プロジェクトごとの上限がサポートされています。
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 フィールドを追加し、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 分間に行えるリクエストの数を表します。
必要に応じて、各指標に対して追加の指標と上限を定義します。
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 ファイルを保存します。

割り当ての構成例

次の 3 つの例は、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: []

OpenAPI 拡張機能には、拡張機能 x-google-management と x-google-quota に関するその他の例と詳しい説明があります。

`openapi.yaml` ファイルと ESP のデプロイ

割り当てを有効にするには、以下を実行する必要があります。

openapi.yaml ファイルを Service Management にデプロイします。これにより、エンドポイントの構成が更新されます。
ESP をデプロイします。ESP をデプロイする手順は、API がデプロイされているバックエンドによって異なります。

詳細な手順については、API バックエンドをデプロイするをご覧ください。