Endpoints는 게이트웨이의 동작을 구성하는 OpenAPI 사양에 대한 Google 관련 확장 프로그램 집합을 허용합니다. 이러한 확장 프로그램을 사용하면 OpenAPI 문서 내에서 직접 API 관리 설정, 인증 방법, 할당량 한도, 백엔드 통합을 지정할 수 있습니다. 이러한 확장 프로그램을 이해하면 서비스 동작을 맞춤설정하고 엔드포인트 기능과 통합하는 데 도움이 됩니다.
이 페이지에서는 OpenAPI 사양 3.x에 대한 Google 관련 확장 프로그램을 설명합니다.
제공된 예는 YAML 형식이지만, JSON도 지원됩니다.
x-google-api-management
필수.
x-google-api-management 확장 프로그램은 서비스의 최상위 API 관리 설정을 정의합니다. OpenAPI 문서의 루트에 이 확장 프로그램을 배치합니다.
다음 표에서는 x-google-api-management의 필드를 설명합니다.
| 필드 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
metrics |
map[string]Metric |
아니요 | 비어 있음 | 할당량 한도를 적용하기 위한 측정항목을 정의합니다. |
quota |
map[string]Quota |
아니요 | 비어 있음 | 서비스의 할당량 한도를 지정합니다. |
backends |
map[string]Backend |
아니요 | 비어 있음 | 백엔드 서비스를 구성합니다. |
apiName |
string |
아니요 | 비어 있음 | OpenAPI 문서에 정의된 작업과 이름을 연결합니다. |
allowCors |
bool |
아니요 | False |
모든 CORS (OPTIONS) 요청을 백엔드로 전달합니다. |
Metric 객체
Metric 객체는 할당량 적용에 사용되는 측정항목을 정의합니다.
다음 표에서는 Metric의 필드를 설명합니다.
| 필드 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
displayName |
string |
아니요 | 비어 있음 | 측정항목의 표시 이름입니다. |
Quota 객체
Quota 객체는 할당량 한도를 정의합니다.
다음 표에서는 Quota의 필드를 설명합니다.
| 필드 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
limits |
map[string]QuotaLimit |
아니요 | 비어 있음 | 할당량 한도를 지정합니다. |
Quota Limit 객체
QuotaLimit 객체는 특정 할당량 한도를 정의합니다.
다음 표에서는 QuotaLimit의 필드를 설명합니다.
| 필드 | 유형 | 필수 | 설명 |
|---|---|---|---|
metric |
string |
예 | 이 OpenAPI 문서에 선언된 측정항목을 참조합니다. |
values |
int64 |
예 | 클라이언트 요청이 거부되기 전에 측정항목이 도달할 수 있는 최대값을 설정합니다. |
Backend 객체
Backend 객체는 백엔드 서비스를 구성합니다. jwtAudience 또는 disableAuth를 설정해야 합니다.
다음 표에서는 Backend의 필드를 설명합니다.
| 필드 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
address |
string |
아니요 | 비어 있음 | 백엔드의 URL을 지정합니다. |
jwtAudience |
string |
아니요 | 비어 있음 | 기본적으로 Endpoints는 주소 필드와 일치하는 JWT 잠재 사용자를 사용하여 인스턴스 ID 토큰을 만듭니다. jwt_audience를 수동으로 지정하는 것은 대상 백엔드가 JWT 기반 인증을 사용하고 예상 잠재 사용자가 주소 필드에 지정된 값과 다른 경우에만 필요합니다. App Engine 또는 IAP에 배포된 원격 백엔드의 경우 JWT 잠재 사용자를 재정의해야 합니다. App Engine 및 IAP는 예상 잠재 사용자로 OAuth 클라이언트 ID를 사용합니다. |
disableAuth |
bool |
아니요 | False |
데이터 플레인 프록시가 인스턴스 ID 토큰을 획득하여 요청에 첨부하지 못하도록 합니다. |
pathTranslation |
string |
아니요 | APPEND_PATH_TO_ADDRESS 또는 CONSTANT_ADDRESS |
대상 백엔드로 요청을 프록시할 때 경로 변환 전략을 설정합니다. x-google-backend이 최상위 수준에서 설정된 경우 기본 pathTranslation은 APPEND_PATH_TO_ADDRESS입니다. 작업에 x-google-backend이 설정되면 기본값은 CONSTANT_ADDRESS입니다. |
deadline |
double |
아니요 | 15.0 |
요청에서 전체 응답을 기다리는 시간(초)을 지정합니다. 이 기한을 초과하는 응답은 타임아웃됩니다. |
protocol |
string |
아니요 | http/1.1 |
백엔드에 요청을 전송하는 프로토콜을 설정합니다. 지원되는 값에는 http/1.1 및 h2이 포함됩니다. |
x-google-auth
선택사항.
x-google-auth 확장 프로그램은 보안 스킴 객체 내에서 인증 설정을 정의합니다.
다음 표에서는 x-google-auth의 필드를 설명합니다.
| 필드 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
issuer |
string |
아니요 | 비어 있음 | 사용자 인증 정보의 발급자를 지정합니다. 값은 호스트 이름 또는 이메일 주소일 수 있습니다. |
jwksUri |
string |
아니요 | 비어 있음 | JSON 웹 토큰 서명을 검증하도록 설정된 공급자의 공개 키 URI를 제공합니다. |
audiences |
[string] |
아니요 | 비어 있음 | JWT 인증 중에 JWT aud 필드가 일치해야 하는 대상을 나열합니다. |
jwtLocations |
[JwtLocations] |
아니요 | 비어 있음 | JWT 토큰의 위치를 맞춤설정합니다. 기본적으로 JWT는 Authorization 헤더('Bearer' 프리픽스 포함), X-Goog-Iap-Jwt-Assertion 헤더 또는 access_token 쿼리 매개변수로 전달됩니다. |
JwtLocations 객체
JwtLocations 객체는 JWT 토큰의 맞춤 위치를 제공합니다.
다음 표에서는 JwtLocations의 필드를 설명합니다.
| 필드 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
header | query |
string |
예 | 해당 사항 없음 | JWT가 포함된 헤더의 이름 또는 JWT가 포함된 쿼리 매개변수의 이름을 지정합니다. |
valuePrefix |
string |
아니요 | 비어 있음 | 헤더 전용입니다. 설정된 경우 해당 값은 JWT를 포함하는 헤더 값의 프리픽스와 일치해야 합니다. |
x-google-quota
선택사항.
x-google-quota 확장 프로그램은 할당량 한도를 정의합니다. 이 확장 프로그램은 OpenAPI 문서의 최상위 수준 또는 개별 작업에 대해 정의할 수 있습니다.
다음 표에서는 x-google-quota의 필드를 설명합니다.
| 필드 | 유형 | 필수 | 설명 |
|---|---|---|---|
self |
map[string]int64 |
예 | quota 객체 (self)는 객체 내에 정의된 측정항목을 참조합니다. 이 경우 측정항목 (예: read-requests)을 측정항목을 늘릴 금액에 매핑합니다. 측정항목 값이 할당량 한도에 도달하면 요청이 거부됩니다. |
x-google-backend
필수.
x-google-backend 확장 프로그램은 x-google-api-management에 정의된 백엔드를 참조합니다. 엔드포인트에 이 확장 프로그램을 설정해야 합니다. OpenAPI 문서의 최상위 수준 또는 개별 작업에 이 확장 프로그램을 정의할 수 있습니다.
다음 표에서는 x-google-backend의 필드를 설명합니다.
| 필드 | 유형 | 필수 | 설명 |
|---|---|---|---|
self |
string |
예 | x-google-api-management에 정의된 백엔드의 ID를 참조합니다. |
x-google-endpoint
필수.
x-google-endpoint 확장 프로그램은 OpenAPI 3.x 문서의 servers 배열에 정의된 서버의 속성을 구성하는 데 사용됩니다. OpenAPI 문서의 서버 항목 하나만 x-google-endpoint 확장 프로그램을 사용할 수 있습니다.
확장 프로그램은 다음을 비롯한 다른 백엔드 기능도 정의합니다.
- CORS:
allowCors속성을true로 설정하여 교차 출처 리소스 공유 (CORS)를 사용 설정할 수 있습니다. - 기본 경로:
x-google-endpoint로 서버에 설정된 기본 경로가 API에 사용됩니다. 예를 들어 다음 구성은v1을 기본 경로로 설정합니다.
servers:
- url: https://API_NAME.apigateway.PROJECT_ID.cloud.goog/v1
x-google-endpoint: {}
다음 표에서는 x-google-endpoint의 필드를 설명합니다.
| 필드 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
target |
string |
아니요 | 호스트가 확인되는 IP 주소를 지정합니다. | |
allowCors |
bool |
아니요 | false |
CORS 요청을 허용합니다. |
OpenAPI 확장 프로그램 제한사항 이해하기
이러한 OpenAPI 확장 프로그램에는 특정 제한사항이 있습니다. 자세한 내용은 OpenAPI 3.x 기능 제한사항을 참고하세요.
다음 단계
- OpenAPI 사양을 살펴봅니다.
- 특정 엔드포인트 또는 ESPv2 구성에 관한 Endpoints 문서를 검토하세요.