割り当ての構成

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

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

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

前提条件

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

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 で割り当てを構成するには次の手順に沿って操作します。

  1. テキスト エディタでプロジェクトの openapi.yaml ファイルを開きます。
  2. ファイルがない場合は、パスを定義するセクション前のファイルのルート（インデントやネストのないレベル）に x-google-management 拡張機能を追加します。

  3. 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 にする必要があります。

  4. 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 分間に行うことができるリクエストの数を表します。

  5. 必要に応じて、各指標に対して追加の指標と制限を定義します。

  6. openapi.yaml ファイルの paths セクションで、割り当ての対象となる各メソッドの下にインテンドされた x-google-quota 拡張機能を追加します。

    x-google-quota:
  metricCosts:
    YOUR_METRIC_NAME: YOUR_METRIC_COST
    • YOUR_METRIC_NAME は、以前に定義した metric.name に置き換えます。
    • YOUR_METRIC_COST は整数値で置き換えます。リクエストごとに、指標のリクエスト カウンタが、コストに指定した数だけインクリメントされます。

  7. 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 のデプロイ

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

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

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