Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

OpenAPI 3.x 기능 제한사항

이 문서에서는 API Gateway와 함께 OpenAPI 3.x를 사용할 때의 기능 제한사항을 설명합니다.

지원되는 OpenAPI 사양 버전에 대한 자세한 내용은 OpenAPI 개요를 참고하세요.

새로운 OpenAPI 3.x 제한사항

이 섹션에서는 OpenAPI 3.x의 새로운 기능에 대한 제한사항을 설명합니다.

서버

OpenAPI 3.x는 호스트와 기본 경로를 정의하는 여러 server 객체를 지원합니다. 하지만 API 게이트웨이는 x-google-endpoint 확장 프로그램으로 식별되는 단일 서버 객체를 사용하여 서비스를 구성합니다.

여러 서버를 정의할 수 있지만 API Gateway는 x-google-endpoint 확장 프로그램을 포함하는 서버만 고려하며 이러한 서버는 하나만 허용됩니다. API Gateway의 경우 서버 URL이 필요하지 않으므로 정의된 서버가 없거나 x-google-endpoint 확장 프로그램이 있는 서버가 하나 있을 수 있습니다.

예를 들어 API Gateway에서 다음 정의는 유효합니다.

servers:
  - url: https://example.com
    x-google-endpoint: {}

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com

다음 정의는 여러 x-google-endpoint 확장 프로그램을 포함하므로 유효하지 않습니다.

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com
    x-google-endpoint: {}

다음 정의는 API Gateway에서 유효하지만 API Gateway는 서버 객체를 무시합니다.

servers:
  - url: https://example.com

여러 파일에 걸친 서버

OpenAPI 파일을 여러 개 업로드하고 한 파일에 x-google-endpoint 확장자가 있는 서버가 포함된 경우 모든 파일에도 동일한 x-google-endpoint 확장자와 서버 URL의 동일한 호스트로 정의된 서버가 있어야 합니다. 기본 경로는 파일마다 다를 수 있습니다.

상대 URL

API Gateway의 경우 사양에 호스트 이름이 필요하지 않으므로 servers 객체의 상대 URL은 자체 기본 경로로 처리됩니다. 이는 OpenAPI 정의를 호스팅하는 서버에 대해 상대 URL을 확인하는 표준 OpenAPI 동작과 다릅니다. 예를 들어 API Gateway는 url: /v1을 기본 경로로 취급합니다.

베이스 경로는 '/'로 시작해야 합니다. API Gateway는 스키마가 없거나 베이스 경로를 나타내기 위해 '/'로 시작하는 URL을 거부합니다.

지원되지 않는 확장 프로그램

API Gateway는 OpenAPI 3.x의 x-google-allow 확장 프로그램을 지원하지 않습니다.

파일 크기 한도

API Gateway는 업로드된 OpenAPI 3.x 파일에 총 크기 제한 10MB와 파일 수 제한 50을 적용합니다.

MCP 제한사항

공개 미리보기 기간에는 모델 컨텍스트 프로토콜 (MCP) 지원에 다음과 같은 제한사항이 적용됩니다.

도구 수 제한: 고객은 게이트웨이당 최대 1,000개의 MCP 도구로 제한됩니다.
HTTP 메서드: GET, POST, PUT, PATCH, DELETE 작업만 MCP 도구로 노출할 수 있습니다. HEAD, OPTIONS, TRACE은 지원되지 않습니다.
스트리밍: 장기 실행 도구 호출의 서버 전송 이벤트 (SSE) 스트리밍은 지원되지 않습니다.
일괄 요청: JSON-RPC 일괄 배열이 거부됩니다.
멀티모달 페이로드: 도구 응답은 UTF-8 텍스트로 제한됩니다. 이진 응답은 지원되지 않습니다.
스테이트리스니스(Statelessness): 구현이 스테이트리스입니다. 세션 식별자(예: MCP-Session-Id)가 사용되거나 유지되지 않습니다.
지원되지 않는 MCP 메서드: resources/*, prompts/*, sampling/*, completion/*, ping, logging/*과 같은 특수 메서드는 지원되지 않으며 JSON-RPC 오류 코드 -32601을 반환합니다.
인증 제한: tools/list 메서드는 JWT 인증만 지원합니다. 이 메서드에는 API 키 인증이 지원되지 않습니다.
도구 주석 없음: destructiveHint 또는 readOnlyHint과 같은 힌트가 도구 선언에서 방출되지 않습니다.
CORS 프리플라이트: /mcp 경로의 자동 CORS 프리플라이트 처리 (OPTIONS 요청)는 게이트웨이에서 관리하지 않습니다.
모델 라우팅 상호 배제: 동일한 API 구성 내에서 MCP와 모델 라우팅을 모두 사용할 수 없습니다.
지원되지 않는 MCP 응답: 응답에서 빈 본문을 반환하는 작업(예: HTTP 204 응답)은 지원되지 않습니다.
스키마 검색: 알려진 구성 처리 제한으로 인해 OpenAPI 사양에서 파생된 복잡한 중첩 객체 스키마가 tools/list 검색 응답에서 완전히 또는 올바르게 렌더링되지 않을 수 있습니다.

기존 제한사항

이 섹션에서는 OpenAPI 2.0에서 가져온 제한사항 중 OpenAPI 3.x에도 적용되는 제한사항을 설명합니다.

무시하는 범위

API Gateway는 보안 스키마 객체에 범위가 정의된 OpenAPI 문서를 수락하지만 이러한 범위를 확인하거나 적용하지는 않습니다.

여러 보안 요구사항

API 키 요구사항: 스키마 중 하나가 API 키인 경우 API Gateway는 대체 (논리합) 보안 요구사항을 지원하지 않습니다. 하지만 API Gateway는 결합 (논리곱)을 지원하므로 API 키와 OAuth2 토큰을 모두 요구할 수 있습니다.
OAuth2 요구사항: API Gateway는 다양한 OAuth2 보안 스키마에 대한 대체 (논리합) 보안 요구사항을 지원합니다. 추가 보안 요구사항이 API 키가 아닌 경우 API Gateway는 결합 (논리곱)을 지원하지 않습니다.
선택적 보안: 빈 보안 요구사항 (- {})을 사용하여 API 키에 보안을 선택사항으로 설정할 수 있지만 API Gateway는 OAuth에 이를 지원하지 않습니다.

보안 정의 유효성 검사

API 게이트웨이는 securityDefinitions 섹션에 해당 정의가 없는 보안 요구사항을 사용하는 OpenAPI 3.x 사양을 거부합니다.

URL 경로 템플릿

API Gateway는 전체 경로 세그먼트를 나타내는 URL 경로 템플릿 매개변수(예: /items/{itemId})만 지원합니다. API Gateway는 부분 세그먼트에 해당하는 매개변수(예: /items/prefix_{id}_suffix)를 지원하지 않으며 거부합니다.

매개변수, 스키마, 요청 본문, 유형

API 게이트웨이는 다양한 매개변수 및 유형 정의 (예: required 매개변수 및 배열 형식)가 포함된 OpenAPI 문서를 허용하지만 이를 강제하지는 않습니다. API Gateway는 이러한 정의와 관계없이 수신 요청을 API로 전달합니다.

API Gateway는 요청 매개변수에서 기본 유형만 지원합니다.

외부 유형 참조

API Gateway는 제공된 OpenAPI 문서 외부의 유형에 대한 참조를 지원하지 않습니다. 예를 들어 API 게이트웨이는 외부 URL을 가리키는 $ref를 허용하지 않고 거부합니다.

호스트 주소의 커스텀 포트

API 게이트웨이는 OpenAPI 문서의 servers.url 필드에 커스텀 포트를 허용하지 않습니다.

YAML 별칭 제한사항

API Gateway에 제출된 OpenAPI 문서에는 YAML 별칭 노드가 최대 200개까지 있을 수 있습니다.