할당량 구성

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 파일로 지칭하고 YAML 형식의 OpenAPI 확장 프로그램만 제공합니다.

다음 3개 섹션을 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 > 서비스 > 할당량 페이지에 표시된 텍스트로 바꿉니다.
- valueType 필드는 INT64여야 합니다.
- metricKind 필드는 DELTA여야 합니다.
quota 필드를 metrics와 같은 수준에 추가하고 limits 필드를 quota 섹션 내에 중첩해 추가합니다.
```
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 프로젝트에 연결된 애플리케이션에서 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: []

x-google-management 및 x-google-quota 확장 프로그램에 대한 그 밖의 예시와 자세한 설명은 OpenAPI 확장 프로그램을 참조하세요.

`openapi.yaml` 파일 및 ESP 배포

할당량을 적용하려면 다음과 같이 실시해야 합니다.

Endpoints에서 구성을 업데이트하는 Service Management에 openapi.yaml 파일을 배포합니다.
ESP를 배포합니다. ESP를 배포하는 단계는 API가 배포된 백엔드에 따라 달라집니다. ESP를 배포하는 단계는 API가 배포된 백엔드에 따라 달라집니다.

자세한 단계는 API 백엔드 배포를 참조하세요.