Cloud Endpoints는 Extensible Service Proxy(ESP)와 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 경로 매개변수가 없는 경우
- OpenAPI 경로:
/hello
- 요청 경로:
/hello
- 대상 요청 URL:
https://my-project-id.appspot.com/BASE_PATH/hello
- OpenAPI 경로:
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 경로 매개변수가 없는 경우
- OpenAPI 경로:
/hello
- 요청 경로:
/hello
- 대상 요청 URL:
https://us-central1-my-project-id.cloudfunctions.net/helloGET
- OpenAPI 경로:
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 서비스의 표시 이름과 일관성을 유지하기 위해 표시 이름에 대해 다음이 권장됩니다.
|
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자여야 합니다. |
metric | 필수. 이 제한이 적용되는 측정항목의 이름입니다. 이 이름은 측정항목 이름에 지정된 텍스트와 일치해야 합니다. 지정된 텍스트가 측정항목 이름과 일치하지 않으면 OpenAPI 문서를 배포할 때 오류가 발생합니다. |
unit | 필수. 제한 단위입니다. 현재는 '1/min/{project}'만 지원됩니다. 즉, 제한이 프로젝트별로 적용되고 사용량이 1분마다 재설정됩니다. |
values | 필수. 측정항목의 제한입니다. 이 값은 다음 형식의 키:값 쌍으로 지정해야 합니다. 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 | 사용자 정의 키:값 쌍: "YOUR-METRIC-NAME": METRIC-COST .
|
할당량 예
다음 예에서는 읽기 및 쓰기 요청에 대한 측정항목과 한도를 추가하는 방법을 보여줍니다.
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