OpenAPI 확장 프로그램

OpenAPI | gRPC

Cloud Endpoints는 Extensible Service Proxy(ESP), Extensible Service Proxy V2(ESPv2), Service Control의 동작을 구성하는 OpenAPI 사양에 대한 Google 관련 확장 프로그램을 허용합니다. 이 페이지에서는 OpenAPI 사양에 대한 Google 관련 확장 프로그램을 설명합니다.

아래 제공된 예는 YAML 형식이지만, JSON도 지원됩니다.

이름 지정 규칙

Google OpenAPI 확장 프로그램에는 x-google- 프리픽스로 시작하는 이름이 사용됩니다.

`x-google-allow`

x-google-allow: [configured | all]

이 확장 프로그램은 OpenAPI 사양의 최상위 수준에서 ESP를 통해 허용할 URL 경로를 나타내는 데 사용됩니다.

가능한 값은 configured 및 all입니다.

기본값은 configured이며, 이는 OpenAPI 사양에 나열한 API 메서드만이 ESP를 통해 제공됨을 나타냅니다.

all을 사용하면 API 키 또는 사용자 인증 유무에 관계없이 구성되지 않은 호출이 ESP를 통해 API로 전달됩니다.

ESP는 API 호출을 처리할 때 대소문자를 구분합니다. 예를 들어 /widgets와 /Widgets는 서로 다른 API 메서드로 간주됩니다.

all을 사용할 경우에는 다음 두 영역에서 특히 다음을 주의해야 합니다.

API 키 또는 인증 규칙
서비스의 백엔드 경로 라우팅

권장사항은 대소문자를 구분하는 경로 라우팅을 사용하도록 API를 구성하는 것입니다. 대소문자를 구분하는 라우팅을 사용하면 URL에 요청된 메서드가 OpenAPI 사양에 나열된 API 메서드 이름과 일치하지 않을 경우 API가 HTTP 상태 코드 404를 반환합니다. Node.js Express와 같은 웹 애플리케이션 프레임워크에서는 대소문자 구분 라우팅을 사용 설정하거나 사용 중지할 수 있습니다. 기본 동작은 사용 중인 프레임워크에 따라 달라집니다. 프레임워크의 설정을 검토해서 대소문자 구분 라우팅이 사용하도록 설정되었는지 확인하는 것이 좋습니다. '사양에 있는 모든 필드 이름은 대소문자를 구분합니다'와 같이 표시된 OpenAPI 사양 v2.0에서는 이러한 확인이 필요합니다.

예

다음과 같이 가정합니다.

x-google-allow가 all로 설정되어 있습니다.
API 메서드 widgets는 OpenAPI 사양에 나열되어 있지만 Widgets는 없습니다.
API 키가 필요하도록 OpenAPI 사양이 구성되어 있습니다.

OpenAPI 사양에 widgets가 있으므로 ESP는 API 키가 없는 다음 요청을 차단합니다.

https://my-project-id.appspot.com/widgets

Widgets가 OpenAPI 사양에 없으므로 ESP는 API 키가 없는 다음 요청을 서비스로 전달합니다.

https://my-project-id.appspot.com/Widgets/

API에 대소문자 구분 라우팅이 사용되며 'Widgets' 호출을 어떠한 코드로도 라우팅하지 않은 경우에는 API 백엔드가 404를 반환합니다. 그러나 대소문자를 구분하지 않는 라우팅을 사용하면 API 백엔드가 이 호출을 'widgets'로 라우팅합니다.

다른 언어 및 프레임워크에는 대소문자 구분 및 라우팅을 제어할 수 있는 여러 메서드가 있습니다. 자세한 내용은 프레임워크 문서를 참조하세요.

`x-google-backend`

x-google-backend 확장 프로그램은 로컬 또는 원격 백엔드로 요청을 라우팅하는 방법을 지정합니다. 확장 프로그램은 OpenAPI 사양의 최상위 수준 또는 작업 수준에서 지정할 수 있습니다.

기본적으로 ESP는 모든 트래픽을 단일 로컬 백엔드로 프록시하도록 구성됩니다. 로컬 백엔드 주소는 --backend 플래그로 지정됩니다(기본값은 http://127.0.0.1:8081). x-google-backend 확장 프로그램을 사용하여 이 기본 동작을 재정의하고 요청을 수신할 수 있는 하나 이상의 로컬 또는 원격 백엔드를 지정할 수 있습니다.

x-google-backend 확장 프로그램은 인증 및 제한 시간과 같은 로컬 및 원격 백엔드의 다른 설정을 구성할 수도 있습니다. 이러한 모든 구성은 작업별로 적용할 수 있습니다.

x-google-backend 확장 프로그램에는 다음 필드가 포함됩니다.

`address`

address: URL

선택사항. 대상 백엔드의 URL입니다. 주소 스키마는 http 또는 https여야 합니다.

원격 백엔드(서버리스)로 라우팅하는 경우 주소를 설정해야 하며 스키마 부분은 https여야 합니다.

작업이 x-google-backend를 사용하지만 address를 지정하지 않으면 ESPv2가 --backend 플래그로 지정된 로컬 백엔드로 요청을 라우팅합니다.

`jwt_audience | disable_auth`

이 두 속성 중 하나만 설정해야 합니다.

작업이 x-google-backend를 사용하지만 jwt_audience 또는 disable_auth를 지정하지 않으면 ESPv2가 자동으로 jwt_audience를 address에 일치하도록 기본 설정합니다. address가 설정되지 않으면 ESPv2가 자동으로 disable_auth를 true로 설정합니다.

`jwt_audience`

jwt_audience: string

선택사항. ESPv2가 인스턴스 ID 토큰을 가져올 때 지정된 JWT 잠재 사용자로, 이후에 대상 백엔드 요청을 실행할 때 사용됩니다.

서버리스용 Endpoints를 구성할 때 ESPv2의 트래픽만 허용하도록 원격 백엔드를 보호해야 합니다. ESPv2는 요청을 프록시할 때 인스턴스 ID 토큰을 Authorization 헤더에 연결합니다. 인스턴스 ID 토큰은 ESPv2를 배포하는 데 사용된 런타임 서비스 계정을 나타냅니다. 그러면 원격 백엔드가 이 연결된 토큰을 기반으로 ESPv2에서 보낸 요청인지 확인할 수 있습니다.

예를 들어 Cloud Run에 배포된 원격 백엔드는 IAM을 사용하여 다음을 수행할 수 있습니다.

특수 allUsers 주 구성원의 roles/run.invoker를 취소하여 인증되지 않은 호출을 제한합니다.
ESPv2 런타임 서비스 계정에 roles/run.invoker 역할을 부여하여 ESPv2만 백엔드를 호출하도록 허용합니다.

기본적으로 ESPv2는 address 필드와 일치하는 JWT 잠재 사용자를 사용하여 인스턴스 ID 토큰을 만듭니다. jwt_audience를 수동으로 지정하는 것은 대상 백엔드가 JWT 기반 인증을 사용하고 예상 잠재 사용자가 address 필드에 지정된 값과 다른 경우에만 필요합니다. App Engine 또는 IAP에 배포된 원격 백엔드의 경우 JWT 잠재 사용자를 재정의해야 합니다. App Engine 및 IAP는 예상 잠재 사용자로 OAuth 클라이언트 ID를 사용합니다.

이 기능을 사용 설정하면 ESPv2가 요청에서 헤더를 변형합니다. 요청에 이미 Authorization 헤더가 설정되어 있는 경우 ESPv2는 다음을 수행합니다.

원래 값을 새 헤더 X-Forwarded-Authorization에 복사합니다.
Authorization 헤더를 인스턴스 ID 토큰으로 재정의합니다.

따라서 API 클라이언트가 Authorization 헤더를 설정하는 경우 ESPv2 뒤에서 실행되는 백엔드는 X-Forwarded-Authorization 헤더를 사용하여 전체 JWT를 검색해야 합니다. 인증 방식이 구성되어 있지 않으면 ESPv2가 확인을 수행하지 않으므로 백엔드는 이 헤더에서 JWT를 확인해야 합니다.

`disable_auth`

disable_auth: bool

선택사항. 이 속성은 ESPv2가 인스턴스 ID 토큰 획득을 방지하고 요청에 첨부하지 못하도록 할지 결정합니다.

대상 백엔드를 구성할 때 다음 조건 중 하나라도 해당되는 경우 IAP 또는 IAM을 사용하여 ESPv2의 요청을 인증하지 않는 것이 좋습니다.

백엔드는 인증되지 않은 호출을 허용해야 합니다.
백엔드에 API 클라이언트의 원래 Authorization 헤더가 필요하며 X-Forwarded-Authorization(jwt_audience 섹션에서 설명)을 사용할 수 없습니다.

이 경우 이 필드를 true로 설정합니다.

`path_translation`

path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]

선택사항. 대상 백엔드로 요청을 프록시할 때 ESPv2에서 사용되는 경로 변환 전략을 설정합니다.

경로 변환에 대한 자세한 내용은 경로 변환 이해 섹션을 참조하세요.

OpenAPI 사양의 최상위 수준에서 x-google-backend가 사용되는 경우 path_translation의 기본값은 APPEND_PATH_TO_ADDRESS이고, OpenAPI 사양의 작업 수준에서 x-google-backend가 사용되는 경우 path_translation의 기본값은 CONSTANT_ADDRESS입니다. address 필드가 누락되면 path_translation은 지정되지 않은 상태로 유지되며 발생하지 않습니다.

`deadline`

deadline: double

선택사항. 요청에서 전체 응답을 기다리는 시간(초)입니다. 구성된 기한보다 시간이 더 오래 걸리는 응답은 타임아웃됩니다. 기본 기한은 15.0초입니다.

양수가 아닌 값은 적용되지 않습니다. 이러한 경우 ESPv2는 자동으로 기본값을 사용합니다.

기한은 사용 중지할 수 없지만 한 시간 동안 3600.0과 같이 큰 숫자로 설정할 수 있습니다.

`protocol`

protocol: [ http/1.1 | h2 ]

선택사항. 백엔드에 요청을 전송하는 데 사용되는 프로토콜입니다. 지원되는 값은 http/1.1 및 h2입니다.

HTTP 및 HTTPS 백엔드의 기본값은 http/1.1입니다.

HTTP/2를 지원하는 보안 HTTP 백엔드(https://)의 경우 이 필드를 h2로 설정하면 성능이 개선됩니다. 이 옵션은 Google Cloud 서버리스 백엔드에 권장되는 옵션입니다.

ESP에서 백엔드 지원 사용 설정

x-google-backend가 구성된 경우 ESPv2가 자동으로 감지합니다.

ESP에서 이 기능을 사용 설정하려면 수동으로 구성을 변경해야 합니다. ESP 컨테이너를 실행할 때 --enable_backend_routing 인수를 제공하여 ESP에서 x-google-backend 지원을 사용 설정합니다. ESP 컨테이너 옵션을 제어하지 않는 런타임의 경우에는 이 옵션이 이미 제공되어 있습니다. 다음은 GKE에 ESP 컨테이너를 배포할 때 x-google-backend 지원을 사용 설정하는 예시입니다. 이 예시는 GKE 가이드의 Endpoints 예시를 기반으로 합니다.

- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:1
  args: [
    "--http_port", "8081",
    "--service", "SERVICE_NAME",
    "--rollout_strategy", "managed",
    "--enable_backend_routing"
  ]

경로 변환 이해

ESP는 요청을 처리할 때 대상 백엔드에 대해 요청을 실행하기 전에 원래 요청 경로를 가져와 변환합니다. 이 변환이 수행되는 정확한 방식은 사용하는 경로 변환 전략에 따라 다릅니다. 경로 변환 전략에는 다음 2가지가 있습니다.

APPEND_PATH_TO_ADDRESS: x-google-backend 확장 프로그램의 address URL에 원래 요청 경로를 추가하여 대상 백엔드 요청 경로를 계산합니다.
CONSTANT_ADDRESS: 대상 요청 경로가 x-google-backend 확장 프로그램의 address URL에 의해 정의된 상수입니다. 해당 OpenAPI 경로에 매개변수가 있으면 매개변수의 이름과 값이 쿼리 매개변수가 됩니다.

예를 들면 다음과 같습니다.

APPEND_PATH_TO_ADDRESS
- address: https://my-project-id.appspot.com/BASE_PATH
- OpenAPI 경로 매개변수가 있는 경우
  - OpenAPI 경로: /hello/{name}
  - 요청 경로: /hello/world
  - 대상 요청 URL: https://my-project-id.appspot.com/BASE_PATH/hello/world
- OpenAPI 경로 매개변수가 없는 경우
  - OpenAPI 경로: /hello
  - 요청 경로: /hello
  - 대상 요청 URL: https://my-project-id.appspot.com/BASE_PATH/hello
CONSTANT_ADDRESS
- address: https://us-central1-my-project-id.cloudfunctions.net/helloGET
- OpenAPI 경로 매개변수가 있는 경우
  - OpenAPI 경로: /hello/{name}
  - 요청 경로: /hello/world
  - 대상 요청 URL: https://us-central1-my-project-id.cloudfunctions.net/helloGET?name=world
- OpenAPI 경로 매개변수가 없는 경우
  - OpenAPI 경로: /hello
  - 요청 경로: /hello
  - 대상 요청 URL: https://us-central1-my-project-id.cloudfunctions.net/helloGET

`x-google-endpoints`

이 섹션에서는 x-google-endpoints 확장 프로그램 사용 방법을 설명합니다.

`cloud.goog` 도메인에서 DNS 구성

애플리케이션을 Compute Engine 또는 Google Kubernetes Engine에 배포한 경우 OpenAPI 문서에 다음을 추가하여 cloud.goog 도메인에 Endpoints 서비스에 대한 DNS 항목을 만들 수 있습니다.

x-google-endpoints:
- name: "API_NAME.endpoints.PROJECT_ID.cloud.goog"
  target: "IP_ADDRESS"

들여쓰기가 적용되거나 중첩되지 않은 OpenAPI 문서의 최상위 수준에서 x-google-endpoints 확장 프로그램을 추가합니다. 도메인 이름은 .endpoints.PROJECT_ID.cloud.goog 형식으로 구성해야 합니다.

예를 들면 다음과 같습니다.

swagger: "2.0"
host: "my-cool-api.endpoints.my-project-id.cloud.goog"
x-google-endpoints:
- name: "my-cool-api.endpoints.my-project-id.cloud.goog"
  target: "192.0.2.1"

.cloud.goog 도메인은 Google에서 관리되고 Google Cloud 고객에 의해 공유됩니다. Google Cloud 프로젝트 ID는 전역에서 고유하므로 .endpoints.PROJECT_ID.cloud.goog 형식의 도메인 이름은 API의 고유 도메인 이름이 됩니다.

편의상 host 필드와 x-google-endpoints.name 필드를 동일하게 구성합니다. OpenAPI 문서를 배포하면 Service Management가 다음을 만듭니다.

host 필드에서 지정한 이름이 있는 관리형 서비스
x-google-endpoints 확장 프로그램에서 구성한 이름과 IP 주소를 사용하는 DNS A 레코드

App Engine 가변형 환경에서 호스팅되는 API에는 appspot.com 도메인을 사용할 수 있습니다. 자세한 내용은 Endpoints 구성을 참조하세요.

CORS 요청을 허용하도록 ESP 구성

다른 출처의 웹 애플리케이션에서 API를 호출하는 경우 API가 교차 출처 리소스 공유(CORS)를 지원해야 합니다. CORS를 지원하도록 ESP를 구성하는 방법은 ESP에 CORS 지원 추가를 참조하세요.

백엔드 코드에서 커스텀 CORS 지원을 구현해야 하는 경우에는 ESP가 모든 CORS 요청을 백엔드 코드로 전달하도록 allowCors: True를 설정합니다.

x-google-endpoints:
- name: "API_NAME.endpoints.PROJECT_ID.cloud.goog"
  allowCors: True

들여쓰기가 적용되거나 중첩되지 않은 OpenAPI 문서의 최상위 수준에서 x-google-endpoints 확장 프로그램을 추가합니다. 예를 들면 다음과 같습니다.

swagger: "2.0"
host: "my-cool-api.endpoints.my-project-id.cloud.goog"
x-google-endpoints:
- name: "my-cool-api.endpoints.my-project-id.cloud.goog"
  allowCors: True

`x-google-issuer`

x-google-issuer: URI | EMAIL_ADDRESS

이 확장 프로그램은 OpenAPI securityDefinitions 섹션에서 사용자 인증 정보 발급기관을 지정하는 데 사용됩니다. 값은 호스트 이름 또는 이메일 주소 형식일 수 있습니다.

`x-google-jwks_uri`

x-google-jwks_uri: URI

JSON 웹 토큰의 서명을 검증하도록 설정된 공급자의 공개 키 URI입니다.

ESP는 x-google-jwks_uri OpenAPI 확장 프로그램에서 정의한 다음 두 가지 비대칭 공개 키 형식을 지원합니다.

JWK 설정 형식 예를 들면 다음과 같습니다.

x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"

X509. 예를 들면 다음과 같습니다.

x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

대칭 키 형식을 사용하는 경우 x-google-jwks_uri를 base64url로 인코딩된 키 문자열이 포함된 파일의 URI로 설정합니다.

x-google-jwks_uri를 생략하면 ESP는 OpenID Connect 검색 프로토콜을 사용하여 지정된 OpenID 제공업체의 JWKS URI를 자동으로 검색합니다. ESP는 x-google-issuer/.well-known/openid-configuration에 요청하고 JSON 응답을 파싱하고 최상위 수준 jwks_uri 필드에서 JWKS URI를 읽습니다.

x-google-jwks_uri를 생략하면 시작 시 ESP가 원격 호출을 추가해야 하므로 콜드 스타트 시간이 길어집니다. 따라서 JWKS URI가 자주 변경되는 경우에만 이 필드를 생략하는 것이 좋습니다. 대부분의 인증 OpenID 제공업체(예: Google, Auth0, Okta)는 안정적인 JWKS URI를 보유합니다.

`x-google-jwt-locations`

기본적으로 JWT는 Authorization 헤더("Bearer "가 앞에 나옴), X-Goog-Iap-Jwt-Assertion 헤더 또는 access_token 쿼리 매개변수 중 하나에서 전달됩니다. JWT 전달에 대한 예시는 Endpoints API에 인증된 호출 실행을 참조하세요.

또는 OpenAPI securityDefinitions 섹션에서 x-google-jwt-locations 확장 프로그램을 사용하여 JWT 토큰을 추출할 맞춤 설정된 위치를 제공합니다.

x-google-jwt-locations 확장 프로그램은 JWT 위치 목록을 허용합니다. JWT 위치마다 다음 필드가 있습니다.

요소	설명
`header/query`	필수 항목. JWT가 포함된 헤더의 이름 또는 JWT가 포함된 쿼리 매개변수의 이름입니다.
`value_prefix`	선택사항. 헤더 전용입니다. `value_prefix`가 설정되면 해당 값은 JWT를 포함하는 헤더 값의 프리픽스와 일치해야 합니다.

예를 들면 다음과 같습니다.

x-google-jwt-locations:
  # Expect header "Authorization": "MyBearerToken <TOKEN>"
  - header: "Authorization"
    value_prefix: "MyBearerToken "
  # expect header "jwt-header-foo": "jwt-prefix-foo<TOKEN>"
  - header: "jwt-header-foo"
    value_prefix: "jwt-prefix-foo"
  # expect header "jwt-header-bar": "<TOKEN>"
  - header: "jwt-header-bar"
  # expect query parameter "jwt_query_bar=<TOKEN>"
  - query: "jwt_query_bar"

기본 JWT 위치의 하위 집합만 지원하려면 x-google-jwt-locations 확장 프로그램에 명시적으로 나열하세요. 예를 들어 "Bearer " 프리픽스가있는 Authorization 헤더만 지원하려면 다음과 같이 지정합니다.

  x-google-jwt-locations:
    # Support the default header "Authorization": "Bearer <TOKEN>"
    - header: "Authorization"
      value_prefix: "Bearer "

`x-google-audiences`

x-google-audiences: STRING

이 확장 프로그램은 OpenAPI securityDefinitions 섹션에서 JWT 인증 중에 JWT aud 필드가 일치해야 하는 대상의 목록을 제공하는 데 사용됩니다. 이 확장 프로그램은 쉼표로 구분된 값을 포함하는 단일 문자열을 사용합니다. 수신자 사이에는 공백이 허용되지 않습니다. 지정되지 않은 경우 JWT aud 필드는 플래그 --disable_jwt_audience_service_name_check가 사용되지 않는 한 OpenAPI 문서의 host 필드와 일치해야 합니다. 플래그가 사용되고 x-google-audiences가 지정되지 않으면 JWT aud 필드가 확인되지 않습니다.

securityDefinitions:
  google_id_token:
    type: oauth2
    authorizationUrl: ""
    flow: implicit
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v1/certs"
    x-google-audiences: "848149964201.apps.googleusercontent.com,841077041629.apps.googleusercontent.com"

`x-google-management`

x-google-management 확장 프로그램은 API 관리의 여러 측면을 제어하며 이 섹션에 설명된 필드를 포함합니다.

`metrics`

할당량 및 x-google-quota와 metrics를 함께 사용하여 API 할당량을 구성합니다. 할당량을 사용하면 애플리케이션이 API의 메서드를 호출하는 속도를 제어할 수 있습니다. 예를 들면 다음과 같습니다.

x-google-management:
  metrics:
    - name: read-requests
      displayName: Read requests
      valueType: INT64
      metricKind: DELTA

metrics 필드에는 다음과 같은 키-값 쌍이 있는 목록이 포함됩니다.

요소	설명
name	필수 항목. 이 측정항목의 이름입니다. 일반적으로 측정항목을 고유하게 식별하는 요청 유형입니다(예: 'read-requests' 또는 'write-requests').
displayName	선택사항이지만 권장됩니다. Google Cloud Console의 Endpoints > 서비스 페이지에 있는 할당량 탭에서 측정항목을 식별하도록 표시되는 텍스트입니다 이 텍스트는 IAM 및 관리자와 API 및 서비스의 할당량 페이지를 통해 API 소비자에게도 표시됩니다. 표시 이름은 최대 40자(영문 기준)여야 합니다. 가독성을 위해 연결된 할당량 한도 단위가 Google Cloud Console의 표시 이름에 자동으로 추가됩니다. 예를 들어 표시 이름에 'Read requests'를 지정하면 Google Cloud Console에 'Read requests per minute per project'가 표시됩니다. 지정하지 않으면 IAM 및 관리자와 API 및 서비스의 할당량 페이지에서 API 소비자에게 '라벨이 없는 할당량'이 표시됩니다. API 소비자가 보는 할당량 페이지에 나열되는 Google 서비스의 표시 이름과 일관성을 유지하기 위해 표시 이름에 대해 다음이 권장됩니다. 하나의 측정항목만 있을 때는 'Requests'를 사용합니다. 여러 측정항목이 있을 때는 각 측정항목이 요청의 유형을 설명하고 'requests'라는 단어를 포함해야 합니다(예: 'Read requests' 또는 'Write requests'). 측정항목과 연관된 비용이 1보다 크면 'requests' 대신 'quota units'를 사용합니다.
valueType	필수 항목. INT64여야 합니다.
metricKind	필수 항목. DELTA여야 합니다.

`quota`

quota 섹션에서 정의된 측정항목에 대해 할당량 한도를 지정합니다. 예를 들면 다음과 같습니다.

quota:
  limits:
    - name: read-requests-limit
      metric: read-requests
      unit: 1/min/{project}
      values:
        STANDARD: 5000

quota.limits 필드에는 다음과 같은 키:값 쌍이 있는 목록이 포함됩니다.

요소	설명
name	필수 항목. 서비스 내에서 고유해야 하는 제한 이름입니다. 이름에는 소문자 및 대문자, 숫자, `-`(대시 문자)를 사용할 수 있으며, 최대 길이는 64자여야 합니다.
측정항목	필수 항목. 이 제한이 적용되는 측정항목의 이름입니다. 이 이름은 측정항목 이름에 지정된 텍스트와 일치해야 합니다. 지정된 텍스트가 측정항목 이름과 일치하지 않으면 OpenAPI 문서를 배포할 때 오류가 발생합니다.
단위	필수 항목. 제한 단위입니다. 현재는 '1/min/{project}'만 지원됩니다. 즉, 제한이 프로젝트별로 적용되고 사용량이 1분마다 재설정됩니다.
값	필수 항목. 측정항목의 제한입니다. 이 값은 다음 형식의 키:값 쌍으로 지정해야 합니다. STANDARD: `YOUR-LIMIT-FOR-THE-METRIC` `YOUR-LIMIT-FOR-THE-METRIC`을 지정된 단위(현재는 분당, 프로젝트별)에 허용되는 최대 요청 수인 정수 값으로 바꿉니다. 예를 들면 다음과 같습니다. values: STANDARD: 5000

`x-google-quota`

x-google-quota 확장 프로그램은 OpenAPI paths 섹션에서 API의 메서드를 측정항목과 연결하는 데 사용됩니다. x-google-quota가 정의되지 않은 메서드에는 할당량 한도가 적용되지 않습니다. 예를 들면 다음과 같습니다.

x-google-quota:
  metricCosts:
    read-requests: 1

x-google-quota 확장 프로그램에는 다음 항목이 포함됩니다.

요소 설명

metricCosts

요소	설명
metricCosts	사용자 정의 키:값 쌍: `"YOUR-METRIC-NAME": METRIC-COST`. `"YOUR-METRIC-NAME":` `"YOUR-METRIC-NAME"`의 텍스트는 정의된 측정항목 이름과 일치해야 합니다. `METRIC-COST:` 각 요청의 비용을 정의하는 정수 값입니다. 요청이 발생하면 관련 측정항목이 지정된 비용만큼 증가합니다. 비용은 메서드가 동일 측정항목에서 서로 다른 속도로 소비할 수 있게 해줍니다. 예를 들어 측정항목의 할당량 한도가 1,000이고 비용이 1이면 호출 애플리케이션이 한도를 넘기 전까지 분당 1,000개의 요청을 수행할 수 있습니다. 같은 측정항목의 비용이 2가 되면 호출 애플리케이션이 한도를 넘기 전까지 분당 500개의 요청만 수행할 수 있습니다.

사용자 정의 키:값 쌍: "YOUR-METRIC-NAME": METRIC-COST.

"YOUR-METRIC-NAME": "YOUR-METRIC-NAME"의 텍스트는 정의된 측정항목 이름과 일치해야 합니다.
METRIC-COST: 각 요청의 비용을 정의하는 정수 값입니다. 요청이 발생하면 관련 측정항목이 지정된 비용만큼 증가합니다. 비용은 메서드가 동일 측정항목에서 서로 다른 속도로 소비할 수 있게 해줍니다. 예를 들어 측정항목의 할당량 한도가 1,000이고 비용이 1이면 호출 애플리케이션이 한도를 넘기 전까지 분당 1,000개의 요청을 수행할 수 있습니다. 같은 측정항목의 비용이 2가 되면 호출 애플리케이션이 한도를 넘기 전까지 분당 500개의 요청만 수행할 수 있습니다.

할당량 예

다음 예에서는 읽기 및 쓰기 요청에 대한 측정항목과 한도를 추가하는 방법을 보여줍니다.

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA
    # Define a metric for write requests.
    - name: "write-requests"
      displayName: "Write requests"
      valueType: INT64
      metricKind: DELTA
  quota:
    limits:
      # Rate limit for read requests.
      - name: "read-requests-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 5000
      # Rate limit for write requests.
      - name: "write-request-limit"
        metric: "write-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 5000

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-api-name`

서비스에 API가 하나만 포함된 경우 API 이름은 Endpoints 서비스 이름과 동일합니다. Endpoints는 OpenAPI 문서의 host 필드에 서비스 이름으로 지정된 이름을 사용합니다. 서비스에 API가 2개 이상 포함된 경우에는 OpenAPI 문서에 x-google-api-name 프로그램을 추가하여 API 이름을 지정합니다. x-google-api-name 확장 프로그램을 사용하면 개별 API 이름을 명시적으로 지정하고 각 API의 버전을 독립적으로 관리할 수 있습니다.

예를 들어 아래의 OpenAPI 문서 조각을 사용하여 API 두 개(producer와 consumer)가 있는 api.example.com이라는 서비스를 구성할 수 있습니다.

producer.yaml의 Producer API:

swagger: 2.0
host: api.example.com
x-google-api-name: producer
info:
  version: 1.0.3

consumer.yaml의 Consumer API:

swagger: 2.0
host: api.example.com
x-google-api-name: consumer
info:
  version: 1.1.0

다음 명령어로 OpenAPI 문서 두 개를 함께 배포할 수 있습니다.

gcloud endpoints services deploy producer.yaml consumer.yaml

OpenAPI 확장 프로그램

이름 지정 규칙

x-google-allow

예

x-google-backend

address

jwt_audience | disable_auth

jwt_audience

disable_auth

path_translation

deadline

protocol

ESP에서 백엔드 지원 사용 설정

경로 변환 이해

x-google-endpoints

cloud.goog 도메인에서 DNS 구성

CORS 요청을 허용하도록 ESP 구성

x-google-issuer

x-google-jwks_uri

x-google-jwt-locations

x-google-audiences

x-google-management

metrics

quota

x-google-quota

할당량 예

x-google-api-name

`x-google-allow`

`x-google-backend`

`address`

`jwt_audience | disable_auth`

`jwt_audience`

`disable_auth`

`path_translation`

`deadline`

`protocol`

`x-google-endpoints`

`cloud.goog` 도메인에서 DNS 구성

`x-google-issuer`

`x-google-jwks_uri`

`x-google-jwt-locations`

`x-google-audiences`

`x-google-management`

`metrics`

`quota`

`x-google-quota`

`x-google-api-name`